Persistence
This page lists every table and column of the one SQLite file an app environment keeps its state in, and explains the schema check at startup, the open settings, how secrets are encrypted, and the files kept beside the database.

An app environment keeps its state in one SQLite file. This page lists every table in it, with the exact column names, so you can query the file or read a backup.

The first thing to check: the schema is in apps/src/sqlite-schema.sql, and that file is the source of every name here. The code that opens the database and runs migrations is apps/src/sqlite.ts.

What an agent publishes does not live here. It goes to the HM server as signed blobs. This database holds only the server's own working state. The ideas behind the tables are explained under agents, and each table below links its concept page.

Files on disk

By default the database is ./data/agents.sqlite and the data directory is ./data, both relative to the working directory. You set them with SEED_APPS_DB_PATH and SEED_APPS_DATA_DIR, or with --db-path and --data-dir; see configuration. The Docker image sets them to /data/agents.sqlite and /data. A server started from apps/ keeps:

apps/data/agents.sqlite apps/data/agents.sqlite-shm apps/data/agents.sqlite-wal apps/data/agents/<agentId>/

The database is the record of everything except the files on disk:

    agents/<agentId>/ is one agent's state directory. The server creates it with the agent and removes it with the agent. It holds the agent's memory/ files, which are the ~/memory/ half of its Space, and the attachments that are private to a session.

    server-id holds the stable id that health reports as serverId.

    exec-probe/ is a work directory for the exec canary; see the code execution backend.

    Uploads that arrive in chunks are staged under the data directory until they are committed or expire.

Each session's durable store is in the database, not in these directories.

A backup is the database file together with the data directory.

Schema gate

The server never runs on a database whose schema it does not know. When it starts, sqlite.open() does one of three things:

    It creates a new database from sqlite-schema.sql and stamps it with desiredVersion.

    It opens a database at or behind the wanted version and applies the migrations that are missing.

    It rejects the database. This happens when the version is unknown, cannot be parsed, or is newer than this binary. It also happens when the database is from before versions were tracked: it has the older schema_version key, or no server_config table at all.

When the database is rejected, main.ts answers 500 on every route and logs both versions. Troubleshooting says what to do.

Migrations live in the migrations array in sqlite.ts. The rules for people who add one:

    The array is prepend-only. A new migration goes at the top of the literal, and the code reverses the array. So the index order is the order they are applied in, and desiredVersion is migrations.length.

    Each migration runs inside its own savepoint, and all of them run in one transaction. If one fails, the whole batch is rolled back.

    sqlite-schema.sql is what a new install gets. It must stay equal to the baseline plus every migration.

Tables

server_config

Holds values that belong to this server alone. Columns: key, value.

The keys:

    secret_encryption_key_v1: the AES-GCM key for encrypted secrets.

    schema_migration_version: the number the schema gate reads.

    retention.durable.watermark and retention.journal.watermark: where the retention task left off.

The encrypted secrets and their key sit in the same database. That is better than plain text in API responses or logs. It is weaker than a key kept in a key management service or a system keychain. See security.

accounts

Holds the account IDs this server knows. Columns: id, created_at, updated_at.

The server adds or updates a row when it writes something an account owns. An account id is the principal of a Seed account.

account_authorizations

Holds the keys that may sign for an account on this server. The primary key is (account_id, signer).

Columns: account_id, signer, role, created_at, and, when a capability blob proves the delegation, capability and capability_cid. The capability page lists that blob's fields. Accepted roles:

    OWNER

    AGENT

auth.isAuthorizedSigner() reads this table. The server writes a row with role AGENT when the capability in a signed request checks out; see the signed API. This is how a key in a browser or on a device acts for an account kept in the vault.

model_providers

Holds each account's model provider settings.

Columns, besides id, created_at and updated_at:

    account_id

    name

    type

    config_cbor

config_cbor encodes ModelProviderConfig:

type ModelProviderConfig = { type: string modelDefaults?: Record<string, unknown> secretRefs?: Record<string, string> baseUrl?: string authMode?: 'api-key' | 'subscription' }

The (account_id, name) pair is unique. See model providers.

secrets

Holds each account's secret values, encrypted. The (account_id, name) pair is unique.

Columns, besides id, created_at and updated_at:

    account_id

    name

    ciphertext

    metadata_cbor

The API never returns a secret in plain text. The secrets are provider keys, sign-in credentials, MCP header values and the agents' signing keys; see identity and security.

agents

Holds one row per agent.

Columns, besides id, created_at, updated_at and the activity columns described below:

    account_id

    definition_cbor

    state_dir

    public_read, public_chat: whether any signed account may read, or chat with, the agent

    status

definition_cbor encodes AgentDefinition.

state_dir is the path of the agent's directory under the data directory. Its memory/ subdirectory holds the agent's memory files (see apps/src/agent-memory.ts), the ~/memory/ half of its Space. The agent reaches them through the read and write verbs. Its owner reaches them through the signed agent-memory actions. The files are on disk, not in SQLite. The server removes them with the rest of state_dir when the agent is deleted.

Current agent statuses:

    idle

    running

    stopped

    error

The activity columns are activity_at, activity_kind, message_at, message_from and activity_session_id. They hold the latest activity across all of the agent's sessions, and they are NULL until the first event. The server writes them every time it adds a session event:

    A tool call, a spawn, a tool result, or any event of a delegated child session moves only activity_at and activity_kind.

    A message from a person, a trigger or the agent in a top-level session also moves message_at, message_from and activity_session_id.

The API returns these as AgentInfo.activity, with a busy flag that comes from the live runs. So a client can show unread marks from the list of agents, without reading every session.

Most work happens in sessions, and the runs table holds what is executing.

agent_id_aliases

Maps an alias to an agent_id, so an agent stays reachable under an id it had before. Rows are removed with the agent.

agent_collaborators

Holds the invitations to an agent and the access people have accepted. The primary key is (agent_id, account_id). Here account_id is the invited account. The owner of the agent stays in agents.account_id, and everything the agent holds is still stored under that owner.

The other columns:

    role: reader or writer;

    status: pending or accepted;

    accepted_at: acceptance time, NULL while pending;

    created_at, updated_at.

agent_triggers

Holds the triggers this server runs: activity, schedule, webhook and run-completed triggers. A trigger belongs to an agent or to an app, so a row has agent_id or app_id, and the table refuses a row with neither. Triggers is the reference for what a trigger can do.

Columns, besides id, created_at and updated_at:

    account_id

    agent_id: the agent the trigger belongs to, or NULL for an app's trigger

    app_id: the app the trigger belongs to, or NULL for an agent's trigger

    document_id, document_version: the trigger document this row was made from and its version. document_id is NULL for a trigger stored only on this server, and it is unique

    author: the account whose trigger it is

    name

    enabled

    source_cbor

    prompt

    continuation_cbor

    last_checked_at

    last_fired_at

    last_error

    merged_into, cooldown_ms: described below

source_cbor holds an AgentTriggerSource. The kinds are document-comment, user-mention, comment-reply, document-author-comment, site-update, activity, schedule, webhook and run-completed.

    An activity source holds a list of one or more {id, source} alternatives, limited to the activity filters. Older rows with a single source stay valid as they are.

    A schedule trigger keeps its interval, its weekly days and time, or its one-time run inside this value. There is no separate schedule table.

merged_into marks a trigger that was combined into another one. Such a row is disabled and cannot be changed, and it keeps its own firing history. The trigger that survives gets the combined conditions and the chosen action in one transaction.

continuation_cbor holds what a firing does: {kind: 'newThread', โ€ฆ}, {kind: 'wake', signal, runId?, payload?}, {kind: 'tool', tool, input?, onFailure?}, or {kind: 'script', script, input?, onFailure?}. NULL means start a new thread. See triggers.

Three things write rows:

    the signed create, update and delete actions;

    the agent itself, through write ~/triggers/<name> (writeTriggerAddress), which keeps enabled as the agent wrote it;

    the trigger document task, which turns a trigger document under an agent or an app on this server into a row.

An agent manages its own triggers directly; see security.

Nothing reads or writes cooldown_ms. No protocol field sets it and no monitor looks at it.

trigger_event_claims

Makes sure one activity event is let in only once per trigger. Columns: account_id, trigger_id, activity_key, which together are the primary key.

When two triggers are combined, the survivor gets the claims of both. Deleting one of the old triggers does not delete the claims the survivor already got. The old firing rows keep their IDs and their trigger, even when both old triggers handled the same event.

sessions

Holds one row per session, which is one conversation with an agent.

Columns, besides id, created_at, updated_at and the message columns described below:

    account_id

    agent_id

    title

    title_source (system, agent, or user)

    status

    parent_session_id: set when another session started this one. That covers model children of delegate, the children a script starts with ctx.delegate, and sessions an agent starts. A client passes includeChildren: false to ListSessions to leave rows with a parent out of the top-level list

    run_id: the run this session is the transcript of, for sessions created as run children

    plan_cbor: the live checklist written by the plan verb (a RunPlan)

    model_override_cbor: the session's quick-switched provider and model, when it differs from the agent's

    description: the live status the agent maintains with the status verb

    thoroughness: the session's delegation preset override (quick, normal, or deep)

title_source protects a title a person typed. A row starts as system. UpdateSession writes user. The value becomes agent when the agent or the automatic namer titles the session. Nothing automatic changes the title of a user row. See session.

plan_cbor carries RunPlan: {title?, steps: [{id, label, status, resolvedBy?}], settledAt?}. resolvedBy and settledAt come from the runtime and never from the model. See plan and step.

Current session statuses:

    idle

    streaming

    stopped

    error

The server never sets stopped on a session. The type allows it, and that is all.

status is a copy of the state of the session's runs. The runs table holds the truth, so a crash can never leave a session stuck in streaming:

    streaming if, and only if, an agent run that has not ended points at the session;

    error when the session's latest run failed;

    idle in every other case, including after a canceled run.

Deleting a session does not delete the rows that point at it. Its runs keep their history with session_id set to NULL. Its child sessions become top-level sessions, with parent_session_id set to NULL.

message_at and message_from hold the session's latest message. The server writes them for every message from a person, a trigger or the agent in a top-level session. Tool activity and child sessions never move them. The API returns them as SessionInfo.activity, so a list of sessions can mark the ones with something unread.

runs

Holds one row for every piece of work the server executes: an interactive turn, a trigger firing, a session an agent started, a delegated model child, a script child. See runs. The table is also the queue the server takes work from (see apps/src/runs.ts). Runs form a tree through parent_run_id. Each row also carries root_run_id, so one WebSocket subscription covers a whole tree.

Columns:

    id, account_id, root_run_id, parent_run_id, depth

    parent_tool_call_id: the parent's delegate call that spawned this run. It is also in the run's input payload, but only a column can be read back without decoding every run. The column lets a delegate row in a transcript find its child while that child is still working, before any result exists.

    continued_from_run_id: the run this one continues. ctx.continueAsNew ends a run and starts a successor that carries only the state it declared, so a day-scale loop never grows an unbounded journal. The two rows are one piece of work.

    kind: agent (a model turn, with a transcript session) or workflow (a script child in the QuickJS engine)

    agent_id, session_id (transcript session for agent runs; NULL for script runs), trigger_firing_id

    origin: user, trigger, agent, or workflow (system is in the type but nothing enqueues it)

    title, model

    source_cid, source_text: for script runs, the JS module and its sha256: digest

    input_cbor, output_cbor, error_cbor ({code, message, retryable?, httpStatus?, stack?, tool?, callSeq?, detail?, unmetObligations?}; tool and callSeq join a script's failure to the journaled call, and stack frames of workflow.js:LINE index into source_text)

    status: queued, claimed, running, waiting, succeeded, failed, canceled

    wait_cbor: why a run is parked, one of four reasons: children (spawned children, with toolCallIds), timer (wakeAt), event (ctx.waitForEvent, with timeoutAt), budget-pause (it stopped before spending more, with a note). See park and wake source. The wire shape RunWaitInfo differs a little: it carries pendingChildren (a count) instead of the ids, maps an event wait's timeoutAt to wakeAt and a budget pause's note to label, and answerWith names the signal that would answer the wait by hand, when one can.

    attempt, max_attempts, not_before (backoff or timer wake), queue (interactive or background)

    lease_owner, lease_expires_at: written on claim (the queue instance, and sixty seconds out) and cleared on park or requeue. The expiry is recorded but never read: with one service process, the boot sweep simply requeues every row the previous process left claimed or running

    budget_cbor, usage_cbor (persisted per turn boundary, child usage rolled up into the parent on finalize)

    plan_cbor: a workflow's own ctx.step and ctx.plan snapshot, or the immutable copy of a session plan written onto its owning agent run when that plan settles. The copy keeps completed checklist history after the session starts a new mutable plan

    created_at, started_at, finished_at, updated_at

A run's output_cbor or error_cbor may also carry unmetObligations: what the run committed to and had not delivered when it ended. That is an undelivered typed result ({kind: 'typed-result'}), or plan steps left neither finished nor written off ({kind: 'plan', steps}). See runs.

Deleting a trigger detaches its runs (trigger_firing_id nulled) before deleting firings.

run_event_waits

One row per outstanding ctx.waitForEvent: (run_id, wait_id) primary key plus account_id, match_cbor (the wait criteria: a {signal} for a person or system answering, or {eventType, resource, author} for the activity feed), timeout_at, and created_at, indexed by (account_id, created_at).

A wait is transient run state, not configuration, so it has its own table and is not a marker on agent_triggers. A running script creates the row, and it is deleted the moment the wait is delivered, times out, or its run dies. See park and wake source.

mcp_servers

One row per remote MCP server an account has connected, unique on (account_id, name): id, config_cbor ({url, transport?, headers?, secretRefs?}; secret header values live in secrets under the mcp-<name>-<header> convention and are referenced by name), tools_cbor (the McpToolInfo[] from the last successful discovery, kept across a later failed refresh), status_cbor ({state, error?, checkedAt?}), timestamps. Agents reference servers by name from definition.mcpServers. Deleting a server scrubs those references, the projected documents, and its owned secrets. See mcp.md.

tool_documents

Every tool an agent holds is a content-addressed tool document, one row per (account_id, agent_id, name): kind (builtin, lambda, or mcp), cid, doc_cbor, enabled, timestamps.

doc_cbor is the canonical DAG-CBOR encoding of a ToolDocument (apps/src/tool-documents.ts): {name, kind, summary, description, input, output?, source?, runtime?, binding?, server?, remoteName?}. cid is the CIDv1 over exactly those bytes, the same encoding the hypermedia network uses for blobs. The CID is the tool's version. It changes on every edit.

Builtin rows are materialized (and refreshed when the shipped registry contract changes, detected by CID mismatch) by ensureBuiltinToolDocuments, which runs whenever the Space index or a ~/tools listing is built and on ListAgentTools. Builtins carry a binding (the runtime executor id) and no source. lambda rows hold authored source from an earlier design: nothing in the service creates them, and the server moves an agent's lambdas into its memory under tools/<name>/ and removes the rows. Builtins cannot be deleted. They are withheld through the agent's grants instead.

mcp rows are projections of mcp_servers.tools_cbor filtered by the agent's definition.mcpServers, named <server>__<tool> and carrying server and remoteName. syncMcpToolDocuments reconciles them (rewrite on CID change, delete when the server is disabled or gone) eagerly on agent and server writes and opportunistically on every listing and run start. They cannot be deleted or replaced by a lambda. A lambda that already holds the name wins.

agent_drafts

Holds the document drafts an agent keeps before it publishes them. An agent makes one with write hm://โ€ฆ and options.action: 'draft.create', and changes it with the other draft actions.

Columns: id, account_id, agent_id, signer_secret_name (the secret that holds the key the draft will be signed with), title, content_format and content_cbor (the draft's content), metadata_cbor, edit_target and location_target (the document the draft changes and the place it will be published), path_name, visibility, status, created_at, updated_at, and, once published, published_at, published_id and published_version. The table is indexed by account and updated_at, by agent, and by status.

run_journal

Append-only journal for script (workflow) runs. It makes replay-from-top resume safe. Rows are (run_id, seq, entry_cbor, created_at) with seq monotonic per run (the count of the run's entries plus one at append). Each entry carries a callSeq that ties together the entries of one ctx call (call and result, timer and fired, wait and event; the (run_id, seq) primary key cannot repeat). The first entry of each group also carries a key, the effect's deterministic content key (tool|name|inputJSON, agent|specJSON, sleep|ms, โ€ฆ), which replay matches on; the journal page explains replay. Entry kinds: call, result, timer, fired, wait, event, now, log, step, plan (see WorkflowJournalEntry in apps/src/workflow-host.ts). A call entry may carry a description, display metadata that stays out of the key. Caps: 5,000 entries or 8 MiB per run, after which the run fails journal-cap. Retention cuts the large payloads of finished runs to previews. Entries are streamed to runs/<rootRunId> subscribers as append events and replayed on subscribe.

session_continuations

One row per continuation edge created by continue_session: the predecessor and successor sessions, the origin session of the chain, the tool call and initiating event, the reason, and manifest_cbor, the successor's exact starting point (handoff, cited sources, what was loaded and what was left cold). A successor has exactly one row, and (predecessor_session_id, tool_call_id) is unique so a retried call cannot create a second successor. The session continuation page describes the manifest.

webhook_trigger_credentials

One row per webhook trigger: secret_hash, which delivery requests are checked against, and secret_ciphertext, the encrypted secret that GetAgentTrigger returns to editors. The secret is created with the trigger. See triggers.

trigger_firings

Holds one row each time a trigger fires: an activity event or a scheduled time that matched a trigger, and the session that came from it. The monitors use this table to make sure a trigger fires once per event, and it is the history of a trigger's sessions.

Columns, besides id and created_at:

    account_id

    agent_id: NULL for an app's trigger

    app_id: the app, for an app's trigger

    trigger_id

    activity_key

    session_id

    run_id: the headless run a tool or script continuation started

    tool_call_id: the tool call this firing made, when it made one

    activity_cbor

    context_cbor: the snapshot of the trigger's name, prompt, and matched conditions at admission. Session attribution reads that snapshot instead of the current configuration; a firing without one falls back to the trigger's current view

    body_digest: a webhook body's digest, so a reused Idempotency-Key with a different body is refused

    status

    error

(account_id, trigger_id, activity_key) is unique. So a retry by the feed or by the schedule monitor cannot make a second firing for the same trigger. An activity firing first passes through trigger_event_claims (above). Schedule, webhook and run-completed firings rely on this row alone. The keys have fixed forms:

    a schedule trigger uses schedule:<triggerId>:<scheduledAt>;

    a webhook uses webhook:<Idempotency-Key>, or a random key when the sender sends none.

activity_watermarks

Holds how far the activity monitor has read each account's activity feed. The primary key is (account_id, server_url).

Columns:

    account_id

    server_url

    cursor_cbor

    last_poll_at

    last_success_at

    last_error

session_events

Holds every event of every session. Rows are only ever added.

Columns, besides id:

    session_id

    seq

    event_cbor

    created_at

    pi_entry_id: the entry of the session's durable store this event was projected from, or NULL for an event anything else wrote

seq only grows within a session, and (session_id, seq) is unique. A new event gets the session's highest seq plus one. This is safe because only one server process writes the database. GetSession returns the events, and a session's WebSocket subscription replays them. Both take afterSeq and return the events after it; see the signed API.

This table is the Log. Every entry has an actor that says who did it. Only user and system are ever written on a row. The agent's own messages and tool calls carry no actor, and a reader works out agent from their shape. A message that a trigger started is a user message.

The event payloads:

type SessionActor = 'user' | 'agent' | 'system' | 'trigger' type SessionEventMeta = { accountId?: string // Seed account that originated a user message signerId?: string // exact cryptographic signer from its verified action envelope model?: string // model that produced the message provider?: string // provider it ran on usage?: AgentRunUsage // this turn's tokens, not the run's cumulative total durationMs?: number // wall time for this message or tool call reasoningLevel?: ReasoningLevel | 'off' | 'default' } type SessionEventPayload = | { type: 'message' role: 'user' | 'assistant' | 'tool' content: string toolCallId?: string rawMarkdown?: string blocks?: AgentMessageBlock[] contextLines?: string[] // client `context` parts; fed to the model, never part of `content` attachments?: SessionAttachmentInfo[] actor?: SessionActor meta?: SessionEventMeta } | {type: 'tool_call'; id: string; name: string; input: unknown; actor?: SessionActor} | { type: 'tool_spawn' toolCallId: string name: string runId: string sessionId?: string title: string actor?: SessionActor } | { type: 'tool_result' toolCallId: string name: string output?: unknown error?: string actor?: SessionActor meta?: SessionEventMeta } | {type: 'error'; message: string; actor?: SessionActor} | Record<string, unknown>

delegate adds a tool_spawn event the moment its child exists. The event names the child run, and the session when the child is a model. The model is never shown this event, and it never takes the place of the tool_result. See delegate.

actor and meta are both optional. Never write code that needs either:

    The agent's own events never carry an actor, and some stored rows carry neither field.

    sessionEventActor() in the protocol package works out the actor of an event that has none: a message with the user role is user, an error is system, everything else is agent.

    trigger is in the type and is never written.

    meta is detail for display. A signed user message carries both the accountId that acted and the exact signerId. The two differ when the account signs with an authorized device or delegate key.

A change to a plan is not an event. The plan verb writes sessions.plan_cbor in place, so the plan carries its own settledAt time.

The partial text of a reply that is still streaming is not stored here.

session_durable_files

Each session has a Pi Durable store, kept in the session_durable_files table. Its columns are session_id, file, seq, and data. The store is Pi Durable's own set of append-only JSONL files, and each file is the data of its rows read in seq order. An append inserts one row. A file that has collected many rows is rewritten as one row the next time it is read, which is once per turn. The rows reference sessions with ON DELETE CASCADE.

The log in session_events stays the canonical record, and a store that is missing is rebuilt from it on the session's next turn. The two are tied together by session_events.pi_entry_id on one side and the store's seed.sync document on the other. Durable sessions says what the store holds, and retention when an idle session's store is dropped.

Deleting a session deletes its store. A backup of the database includes every store.

transcript_privacy

Reader privacy per transcript, keyed by (kind, id) where kind is session or run. private is set once any event or journal entry up to scanned_seq carried browser or private-memory data. sessions_json and runs_json list the sessions and runs the scanned entries read from, whose privacy the transcript inherits.

action_idempotency

Lets a client send the same request twice without doing the work twice. Columns: account_id, action, client_request_id, which together are the primary key, then request_cbor, response_cbor and created_at.

These fields fill client_request_id:

    CreateAgent.clientRequestId

    CreateAgentTrigger.clientRequestId

    CreateSigningIdentity.clientRequestId

    CreateSession.clientRequestId

    MessageSession.clientMessageId

The same client ID with the same request bytes gets the stored response again. The same client ID with different request bytes gets 409.

effect_outbox

Records what each tool call set out to do and what came of it, for every call that changes something outside the conversation. See the effect outbox. There is one row per call.

Columns:

    id: <session_id>:<tool_call_id>

    account_id

    session_id: the row is deleted with the session

    run_id, tool_call_id, tool

    kind: publish, memory-write, execute, delegate, call:<name>, and so on

    input_digest: the SHA-256 of the call's arguments

    status: running, succeeded, failed or interrupted

    lease_owner: the process running it

    response_cbor: the receipt, which is the text and details the tool returned

    error

    created_at, updated_at, completed_at

The server inserts and commits the row before the effect begins, and settles it when the effect ends. At startup the boot sweep marks every running row interrupted. Settled rows are removed after two days.

app_runs

One row per app running on this server: app_id, space_uid, started_by (the account that started it), private_config_ciphertext (its private config, encrypted), created_at, updated_at.

app_tool_calls

Every call of a running app's tools: id, app_id, tool_id, caller, tool_version, input_json, output_json, error, duration_ms, created_at, indexed by (tool_id, created_at). The server serves these rows, with inputs and outputs, without an access check. See tool.

Open settings and planner statistics

Every time the server opens the database it sets journal_mode=WAL, synchronous=NORMAL and temp_store=MEMORY. It also applies three sizes from configuration:

    the page cache: SEED_APPS_SQLITE_CACHE_MIB, 256 MiB by default;

    memory-mapped reads: SEED_APPS_SQLITE_MMAP_MIB, 1024 MiB by default, and never more than the maximum SQLite was built with;

    the size the WAL file is cut back to after a checkpoint: SEED_APPS_SQLITE_WAL_LIMIT_MIB, 64 MiB by default.

The startup log prints the values in use, on the line [agents/sqlite] connection settings. Every SQLite statement runs on the server's only thread. So a read that misses the cache makes everything else wait. The cache and the mapping keep the common reads in memory.

Every open also runs ANALYZE on the small tables the query planner needs numbers for (PLANNER_STATISTICS_TABLES: accounts, agents, collaborators, triggers, runs, sessions, continuations and firings). It leaves out session_events and run_journal on purpose. Without these numbers the planner treats every index alike, and it can pick the account-wide index to look up the runs of one session. The busiest queries also name their index with INDEXED BY. Nothing runs VACUUM; see database retention.

Secret encryption

The code is encryptSecret() and decryptSecret() in api-service.ts.

The scheme:

    AES-GCM;

    32-byte server-local key;

    12-byte random nonce per write;

    stored ciphertext is nonce || encryptedBytes || tag, with the 16-byte GCM authentication tag last (aes-256-gcm).

The key is the secret_encryption_key_v1 row of server_config. A secret carries no version and no record of key rotation. The key cannot be kept in a key management service or a system keychain. Security covers what this protects against.

Transaction policy

This rule is for people who change the code: never hold a write transaction open during a network call to a provider or a tool.

    CreateAgent and CreateSession may use short transactions that are safe to repeat.

    MessageSession must not hold a long SQLite transaction, because it does model and network work.

    When several people write to one session at once, the single server process adds each event at once and then queues each run on its own.

    The run queue runs one model turn per session at a time. It does not delay the storing of events.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Connections0
Linked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkLinked document ยท Outgoing linkPersistencePersistence
Citations 0Children & links 50

Loading child documentsโ€ฆ

Connections show where other documents or comments link to this document.

Related documents

Loading connectionsโ€ฆ