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

Preferred column count used by the automatic preview-window layout. Defaults to 3.

Opt-in: board cards show which of my other frontends (tab / desktop app / phone) have the todo open. Off = this frontend neither reports nor tracks presence.

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

What opening a TODO from the board does: a floating preview window over the board (default, the advanced workspace) or the full-page chat.

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 agent's system prompt (and its diffs) inline in chat. Also makes the backend ask the agent for it: the prompt is only attached to a finished message when this is on (or an x-tfa-debug turn), since it is tens of KB per message.

Developer mode: reveals the Developer group in View settings (debug-only toggles). Purely cosmetic — it gates no capability, every toggle inside works on its own. Staff-granted: adminUser.setDeveloperMode is the only writer — updateUserSettings drops the key, so no client can reveal the group for itself.

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

How much of the machine layer the UI exposes — see SurfaceMode. Unset means basic for accounts with no paired machine and advanced once one exists, so existing users never lose their cards.

Paint each device card with that machine's real desktop wallpaper, captured by the bridge when it reconnects. Off keeps every card on the built-in OS-themed gradient. Individual devices can still opt out on their own via Device.metadata.wallpaper.mode. Default off — the wallpaper is a personal image, so uploading it is opt-in.

Project picker at the top of the todo sidebar (team plan only). off hides it, auto shows it only when you have more than one project, always keeps it pinned. Defaults to auto.

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.

Which finished reasoning ("Thinking") blocks stay in chat. Default 'last'; hidden reason blocks render nothing, which also lets more consecutive tool messages collapse into a single group.

Show the files a shell command touched (edge/bridge git tracking) under Shell blocks. Default off: the heuristic can pick up unrelated concurrent edits. When on, each diff still renders collapsed.

Per-host desktop layout, keyed by host id (device/edge id, or "cloud"). An ordered list of items; array index IS the order. Items absent from a host's list are appended (in the host's default order) on render, and items whose key no longer exists are dropped.

Per-project people filter for the todo list, keyed by project id: user ids whose todos are shown. Absent key = everyone.

When the user agreed that their content is sent to the provider of the AI model they pick.

Read-only: set from Stripe, never accepted from the client.

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)

The board's setup todo (ONBOARDING_AGENT); kept (DONE) after finishing, '' on restart.

Stepper step id the user is on

Personal board (no brand UI) or business board (brand card, analyzer, voice).

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

Todos started this day. Missing on records from before the counter existed.

Tool blocks completed this day. Missing on records from before the counter existed.

Team to act on, identified by its owner's user id.

Inclusive day range actually covered, ms timestamps at day start.

Sum of members[].spent — what the team pool paid out in the window.

Role of a user within a team (IAM). owner: billing + full control; admin: manage members; member: belongs only.

Spend funded by the team pool in the window, in $.

Spent from the pool while on the team, but no longer a member.

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.

Todos the board list (todo.list) can actually page: shared, visible, not dismissed — any status. Optional for older backends.

Runtime server capability, response-only (never persisted): this backend enforces MY_PRIVATE_GROUP privacy. Clients MUST fail closed — hide the private lane when absent — so a new frontend against an old backend can't create shared "private" todos.

User IDs with read access

User IDs with write access

The team this project belongs to, identified by its owner's user id. Set = a shared team project: every member of that team holds write access, and AI spend inside it is billed to that team's pool. This is the switch that decides WHOSE quota a member burns, so a project belongs to at most one team (enforced atomically in setTeamProjectAtomic).

Being replaced by organizationId: the migration writes both, and once every reader is on organizationId this field goes away.

The organization (better-auth organization plugin) this project belongs to. Same semantics as teamOwnerId — members get write access, spend bills to the org owner's pool — but keyed by the org's own id, so an org can outlive / change its owner. At most one per project.

The project IS the brand: this is the attachment id of its brand page (markdown). Absent = a personal board (no brand card, analyzer or voice).

The latch that applies TO THE CALLER, projected per request: the project-wide one if the owner pressed it, otherwise this user's own. A teammate's personal latch is never visible here — it stops their runs, not the board.

user: by's own runs, latched in by's own slot — invisible to teammates, released by by. project: everyone's runs (owner presses and releases).

Latch tripped by the running limit rather than by a person.

Avatar attachment id (same as the profile picture).

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

Group slug. Empty/absent means ungrouped. MY_PRIVATE_GROUP creates a private todo owned by the authenticated creator (no separate visibility input).

Optional display name to upsert for groupTag. Ignored for MY_PRIVATE_GROUP.

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.

Todo whose agent shell spawned this one (tfa-cli reads $TODOFORAI_TODO_ID).

'orchestrator' forces visible:false and manual start (no agent run).

How the first message was produced (orchestrator threads).

Edge device MCP configurations by edgeId

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

Put the user's file memory (todoforai:memory/: index + pinned files) in the system prompt. Default on.

Reference files (PDF, images, text/office docs) pinned to every conversation of this agent: sent natively as the first user message (PDF/image as document/image blocks), prompt-cached. Metadata only — the agent fetches bytes by attachment id.

Bridge device workspace + cwd config by deviceId. Parallel to edgesMcpConfigs.

Tool permission allowlist

Spec this agent was created from

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

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

Agent → backend only: small text results travel inline here instead of a separate binary frame. Consumed at registration; never persisted.

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

Catalog tool states injected by the backend at submit time.

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)

The user explicitly asked for this tool on this device (Connect / Add). Hosts with a preinstalled catalog (cloud VMs) list only requested or connected tools — the rest is clutter — and a requested tool that later lost its credentials stays visible as "Not linked" so it can be fixed. Sticky across rescans; cleared by the forget tool op.

User description override from the edge's ~/.todoforai/custom_tools.json, folded into the scan result edge-side. Takes precedence over the catalog description in the agent's bash tool CLI list, and lets non-catalog binaries (found on PATH) be advertised. Deliberately ONE field for both audiences, unlike the catalog's summary/description pair: the user writes this line themselves, in their own words, about their own binary — asking them for two takes of the same sentence buys less than it costs. It is shown as-is in the tile and sent as-is to the agent.

User label override (custom_tools.json), same mechanism as description.

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

Catalog tool states injected by the backend at submit time.

Tools/patterns that auto-execute without approval

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

Tools/patterns blocked from execution

0 if immediate

Project-scoped group slug.

Set (server-side, from the creator) when the todo lives in MY_PRIVATE_GROUP: only this user may read or modify it. Never accepted from clients.

Todo whose agent shell spawned this one (via tfa-cli).

'orchestrator': a per-tab orchestrator thread — the tab runs the agent loop itself and authors the assistant turns over the frontend socket. Always created with visible:false (off the board); listed via todo.listOrchestrators.

User-checked blocks

Blocks with code, commands, etc.

When the proposal was dismissed — bounds the analyzer's feedback window.

Star/favorite timestamp; absent/0 = not starred

Users who sent messages into the todo, in order of first appearance ([0] = creator).

For optimistic concurrency

Visible in default project listings; defaults to true.

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

Signed-in non-members may comment on a public todo. Members can always comment.

Pre-finished: the user checked it while the agent was still working, so the run's READY lands as DONE. Cleared once the todo reaches a terminal status.

Per-todo transition counter at status — travels WITH it, so a client knows which transition it holds.

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

Set on todos created by todo.importSession — the external session they mirror.

'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).

Who this turn belongs to: the submitter for a user message, the submitter of the turn being answered for an assistant/tool message. Together with agentSettingsId this is the run's identity — continuations (flushToolMessage) MUST resolve from here, never from todo.agentSettingsId, which is last-writer-wins and gets overwritten when a second user joins the todo. Absent on legacy messages (pre multi-user attribution) — callers fall back to the project owner.

Sent into an already-running turn, so it sits in the agent's internal queue until the turn drains it. While true the user can still retract it (Front2Agent.TODO_QUEUE_CANCEL); cleared on Agent2Server.TODO_MSG_DEQUEUED.

Token usage, model info, etc.

System prompt used for this assistant message (dev mode / debug-dump turns)

Debug-dump turns (x-tfa-debug): native tool schemas of the LLM request that produced this assistant message, JSON-stringified.

Predicted next user message (ghost text), computed once per finished assistant turn by reusing the warm prompt cache. Set only on assistant messages; throwaway, never fed back.

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

Orchestrator (JARVIS) tools: the result text the model read.

Orchestrator tools whose text is a bulk payload: the one-line transcript chip.

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

Files changed by this command (edge git tracking; overwritten on re-run).

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.

Only meaningful when awaitingInput === true: the bridge parked the run because the step deadline hit, not because it saw a stdin wait (Windows/ConPTY has no such signal). The command may just be slow.

Sub-agent runs spawned by the command as real (hidden) todos — tfa-* CLIs stamp these via POST /todos/{id}/blocks/{id}/subtodo. One command can spawn several (a & b & wait), so each gets its own nested trace in the UI, in link order.

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

What happened to the file (resolved from git pre/post state).

Why content is null even though the file exists on that side.

Bytes of the post-command file (pre-command size when deleted).

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

Original filename, shown in the block header.

Short label shown in the block header, overriding filename.

Stable short address within the todo (<todoId>:<alias>), for later update/lookup.

Mimetype of the shown bytes — decides how the block renders.

Live target for todoforai-cli open <url> (rendered as a preview instead of bytes).

Name of a project-scoped card (reusable HTML renderer) to render the shown bytes through (todoforai-cli show data.json --card <name>). Resolved live per-project at render time, so updating the card updates every instance. tfa/<name> is a BUILT-IN card instead: a first-party React renderer with no shown bytes (POST /resources/cards), e.g. the onboarding cards.

Presentation hint: 'link' renders a compact file chip (name + size + download) instead of inline content; click expands to the normal render. Absent = render inline by mimetype as usual (todoforai-cli show --link).

Every version this block has shown (attachment ids, oldest first; the current one is results[0]). A re-shown alias appends.

Set while publicly shared (show share): show.todofor.ai/<token> serves the latest version, /<token>/<version> a frozen one. Absent = private to whoever can read the todo. Unshare drops it; a re-share mints a new token.

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