Schemas

Per-user onboarding state. Stores draft user input + wizard progress. Step "completion" is derived from real product state, not stored here. No secrets — vault tokens stay in AppSettings.vaultProviders.

Construct a type with a set of properties K of type T

How the browser-tab red "done" dot behaves after a TODO finishes.

Disabled

Construct a type with a set of properties K of type T

Enabled model-mention aliases (e.g. 'claude', 'gpt') for

Show accept/reject chunk controls in the diff (merge) view. Off by default — with auto-apply the diff is just a record of what got applied, so the controls are unnecessary noise.

Show the selected agent's name (with an expand chevron) on the collapsed composer trigger instead of the plain settings cog icon.

Show the Auto-Done toggle in the message toolbar. When the toggle is on, the next run's successful completion lands the todo in DONE instead of READY.

Show the JSON export button in the agent settings modal header.

Show the workspace bar on the built-in Cloud device card. Hidden by default — the cloud workspace is always /root and virtually nobody should change it.

Show the project picker at the top of the todo sidebar. Only ever visible on the team plan; defaults to on there, this lets team users hide it.

Tool-block display density, resolved per viewport. collapsed keeps non-essential tool blocks collapsed (one-line summary, click to expand). normal opens them by default. debug additionally surfaces internal fields (pid, timeout, …) on shell/bash blocks. Desktop defaults to normal, mobile to collapsed.

Collapse consecutive tool-only assistant messages into a single group row. Backend defaults to true (the recommended workflow); set false to render each tool block individually. Independent of verbose tool display.

Construct a type with a set of properties K of type T

Tile identity.key (e.g. "filesystem", "gh") or widget id (e.g. "widget:activity").

Column span (default 1).

Row span (default 1).

Discriminates render path. Defaults to 'tile' when omitted.

id === userId

Schema version for future migrations

Last server-side write timestamp (last-write-wins)

Construct a type with a set of properties K of type T

Construct a type with a set of properties K of type T

Construct a type with a set of properties K of type T

One-paragraph description of the voice (tone, formality, quirks, do/don't).

0–100 how well the final draft matches the target style.

Where the voice was learned from:

• 'answers' the user's own answers were usable and drove the profile
• 'company' the answers were too thin, so the profile is inferred from company info
• 'social' inferred from a (mock) connected social account

The refinement passes, oldest → newest, so the UI can show the loop converging.

When source==='company': a short note explaining why the answers weren't used.

Optional label of the mock social channel this came from (source==='social').

Construct a type with a set of properties K of type T

Sample line rewritten in the learned voice for this pass.

0–100 self-assessed match to the target style after this pass.

What changed / what was still off this pass (one short sentence).

Construct a type with a set of properties K of type T

A project organizes todos.

Count of todos in the DONE stage — O(1) ZCARD, kept accurate independent of what the paginated todo list has loaded. Todo count = todoIds.length - doneCount.

User IDs with read access

User IDs with write access

AI AgentSettings configuration including model, system prompt, and MCP tools.

Construct a type with a set of properties K of type T

Visible in the project's default todo list. Defaults to true; subagent runs (tfa-*) pass false. Hidden todos are still accessible by id.

When true, successful completion lands in DONE (strikethrough/terminal) instead of READY. For plumbing todos that don't need user ack.

Per-edge config bag. Mostly serverId → ServerSettings, but also carries edge-level metadata (deviceType, installedTools) used by the agent runtime. TODO: rename to EdgeConfig — see plan/edge-config-rename.md

Custom system prompt for the agent

LLM model identifier (e.g., 'claude-3-opus')

'default_coder' uses built-in coding prompt, 'custom_w_tools' uses systemMessage + auto-injected capability sections, 'raw' uses systemMessage verbatim (no global prepend, no tool/routing/workspace sections).

Auto-enhance system prompt based on context

Template this agent was created from

Hex color (e.g. '#10b981') used to tint todos assigned to this agent

Edge device type — used by the Julia agent for capability checks (e.g. has_shell).

Construct a type with a set of properties K of type T

Per-agent edge on/off. false removes this edge from the agent's tool spec at run time (filtered in AgentSettingsService.prepareForAgent). Undefined/true = on.

Edge identity surfaced at submit time (enrichWithOnlineEdges) so the agent can use it for the tool-alias suffix (bash_) and the ### <name> heading in ## Available Machines. TODO: revisit — questionable whether this belongs here. (1) For real edges name is an auto-generated junk label (e.g. "PC_8814" = {deviceType}_{rand}), which gives the agent no useful alias/heading; only bridge devices have a meaningful user-given name. (2) name/metadata duplicate Edge.* and bloat every per-agent record. Consider passing identity out-of-band instead of stuffing it into edgesMcpConfigs.

Construct a type with a set of properties K of type T

Whether the binary is found on PATH

Output of versionCmd (e.g. "v1.2.3"), undefined if not run or no versionCmd

Output of statusCmd (e.g. logged-in user), undefined if not run or no statusCmd

Whether statusCmd exited 0 (authenticated/ready)

Per-agent device state. For ordinary devices, false disables and every other value enables. The hosted cloud VM additionally supports: false → Off. 'auto' → use only when no local desktop is online. 'on' → explicitly always on (overrides global Auto/Off). true / undefined → enabled, inheriting the per-user global cloud mode. true remains the inherited state for compatibility with existing agent records, where it was written before explicit cloud modes existed.

Device type — used by the agent for capability checks (e.g. has_shell vs has_cdp). Surfaced at submit time by enrichWithOnlineDevices.

Device identity surfaced at submit time so the agent can render the device in ## Available Machines (name heading, tool-alias suffix).

Construct a type with a set of properties K of type T

Construct a type with a set of properties K of type T

Tools/patterns that auto-execute without approval

Tools that require user approval (default if not in any list)

Tools/patterns blocked from execution

Resource URI - always required. Format: "todoforai:todos/{todoId}/{id}"

In bytes

Last modified time (mtime), milliseconds epoch

Unix permission bits (e.g. 0o644 = 420 decimal)

Block ID that produced this attachment (for mapping tool results back to tool_calls)

LLM tool_call ID — for stamping results back to the originating tool call

Construct a type with a set of properties K of type T

0 if immediate

Domain-specific knowledge context

User-checked blocks

Blocks with code, commands, etc.

Star/favorite timestamp; absent/0 = not starred

For optimistic concurrency

Construct a type with a set of properties K of type T

Visible in default project listings; defaults to true.

Publicly viewable (read-only) by anyone with the link, no login required.

True when messages holds only the newest page — older ones via todo.getMessages.

'user', 'assistant', or 'system'

Stop sequence that ended AI response, if any

Parsed content blocks (code, tool calls, text)

0 if sent immediately

Project the todo belongs to (denormalized for search; absent on legacy messages).

Token usage, model info, etc.

System prompt used for this assistant message (dev mode)

If set, this message belongs to a sub-agent spawned by the given block

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

OS PID of the persistent shell inside the bridge PTY. Surfaced on RUN_STARTED so the UI can address the session for stdin / force-kill. SIGINT is delivered as \x03 through the regular stdin path — the kernel TTY line discipline forwards it to the foreground process group, so no separate fg pid is needed on the block.

Bridge reported STEP_AWAITING_INPUT — foreground command parked in n_tty_read, waiting on stdin. The shell itself is alive.

Only meaningful when awaitingInput === true: PTY slave has ECHO disabled (sudo / getpass / ssh / git credential). UI should mask input.

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Bare HTML fragment authored by the LLM (no doctype/html/head/body).

Short label shown in the block header.

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

A directly-openable URL. For a remote target it's the http(s) URL the agent was given; for a tunnel it's https://.preview.todofor.ai once the frontend has lazily minted a session.

Direct URL (http://127.0.0.1:) for an edge-local target. The frontend probes it first and, only if unreachable, mints a tunnel session (see edgeId/port) via POST /preview/session.

Edge + port backing localUrl — the frontend needs them to lazily mint a tunnel session when the direct URL isn't reachable.

Short label shown in the block header.

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

Pre-formatted user response (set by backend on approval).

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval

BlockStatus - lifecycle states

First page to load (the tool's url arg).

agent-browser CDP connect URL of the enrolled resource (set on approval → tool result).

Generalized permission pattern for "remember" feature (e.g., "BASH(cmd: npm *)")

LLM API tool_call id — durable mapping from block to the tool_call that created it

Parent block ID — present on sub-agent child blocks (e.g., read blocks inside explore)

Device that executed this tool call. Edges and bridges both map to a device id. Stamped from internal routing context, not provided by the LLM.

Read-time schema issue: set by the tRPC soft-output validator when this block failed output validation (e.g. legacy/malformed data). Derived on every read from the failing typia path — NEVER persisted to Redis.

Edge approval context — present when edge requests tool install approval