Request:

Response:

Lists agents owned by the verified account plus agents on which it is an accepted reader or writer, ordered by update time descending. Each AgentInfo.accessRole is owner, reader, or writer. An agent read through public access reports reader, or chatter when public chat is on. Pending invitations are not returned here, on purpose.

ListAgentInvites {} returns pending AgentInviteInfo rows for the signed account. An invite shows only the agent id and name, owner account, role, and timestamps. Agent contents stay hidden until the invite is accepted.

ListAgentCollaborators {agentId} returns the owner and accepted members plus the agent's publicRead and publicChat flags. The owner also sees pending invitations.

InviteAgentCollaborator {agentId, accountId, role} creates an invitation (reader or writer) or updates an existing member's role. Owner-only.

RemoveAgentCollaborator {agentId, accountId} revokes an accepted member or cancels a pending invitation. Owner-only.

AcceptAgentInvite {agentId} accepts the signed account's pending invitation and returns the now-accessible agent.

DeclineAgentInvite {agentId} deletes the signed account's pending invitation.

SetAgentPublicRead {agentId, publicRead} turns public read access on or off. Owner-only. While on, every signed account that knows the agent id is treated as a reader (the same view an invited reader gets, including live subscriptions). The agent is still never returned from ListAgents or account-wide ListSessions for accounts that are not owner or collaborator. AgentInfo.publicRead reports the flag. Turning it off also clears publicChat.

SetAgentPublicChat {agentId, publicChat} turns public chat on or off. Owner-only, and enabling requires publicRead to already be on (400 otherwise). While on, every signed account that reads the agent publicly is a chatter: it may CreateSession, MessageSession, UploadSessionAttachment (and the chunked-upload actions targeting a session), StopSession, and RetrySession on any of the agent's sessions. It still cannot do anything writer-level: UpdateAgent, memory, tool, or trigger writes, UpdateSession, DeleteSession, InvokeSessionTool, CancelRun, SignalRun. AgentInfo.publicChat reports the flag. Public chat is narrower than inviting a writer on purpose. Anyone can talk to the agent, and nobody but writers can change it.

Readers can inspect all agent-scoped state. Chatters (public chat only, and not a role you can invite) can also create, message, and stop sessions. Writers can also create, update, and delete agent-scoped resources, rename and delete sessions, control runs, and run session tools. Managing collaborators and deleting the agent stay owner-only. An agent collaboration never grants account-scoped provider or secret changes. Agent settings may list the owner's redacted providers and signing identities through optional agentId fields. These agent roles are separate from Hypermedia roles on documents.

Request:

Creates a new agent. Checks that the referenced provider exists for the account. Creates a per-agent state directory.

When the definition's primary signingKey resolves to an hm-account-key secret, the server also creates a default enabled activity trigger, "Mentions, replies, and comments for <name>", for that signing identity's account uid: a user-mention, a comment-reply, and a document-author-comment condition (prompt: "Respond to the mention, reply, or comment on your document, performing any action requested."). Mentioning the agent's account, replying to one of its comments, or commenting on a document it authored then starts one session in which it responds. This is best-effort and never blocks agent creation. Agents without a signing key get no default trigger.

Idempotent when clientRequestId is supplied.

Request:

Response:

Returns provider metadata only. Config and secret refs are redacted. See model providers.

Request:

Response:

Looks up one configured provider for the verified account, decrypts its referenced API key in memory, and calls the provider's model-list endpoint. Plain secrets and provider config are not returned.

Request:

Response:

Lists account-scoped secrets whose metadata has kind: 'hm-account-key'. Plain secret material is never returned, and only keys uploaded by the signed account are visible. With agentId, the request resolves against the owning account of a shared agent. The owner sees every identity. Collaborators (reader or writer) see only the identities granted to that agent, and the owner's other keys stay private to the owner. Changing the granted set itself (definition.signingKeys via UpdateAgent) is owner-only. A writer's UpdateAgent must carry the grant set unchanged, or it is rejected with 403.

Request:

Response:

Generates a new server-side Ed25519 HM account key, publishes a profile blob with the supplied label to the configured HM server, encrypts the raw seed as an account-scoped secret tagged kind: 'hm-account-key', and returns redacted identity metadata. clientRequestId makes repeated creates idempotent.

Request:

Republishes the server-side account's profile blob with the new display name and updates redacted metadata.

Request:

Deletes the encrypted server-side account key secret for the signed account. Published profile blobs are append-only and stay in HM storage.

Request:

Upserts provider config by account and name. ModelProviderConfig.authMode selects how requests authenticate: api-key (default, uses the secretRefs.apiKey secret) or subscription (uses OAuth credentials in the secretRefs.oauth secret).

Request:

Deletes the named provider record for the account, plus every secret it referenced that no remaining provider still references. Subscription providers of the same type share one OAuth secret, so a shared credential survives the deletion of one of its providers. 404 when the account has no provider by that name. Response: {_: 'DeleteModelProviderResponse'; name}.

Subscription-authenticated providers use a four-action login flow in place of a pasted API key. The flow is offered only when the server runs with SEED_AGENTS_SUBSCRIPTION_AUTH enabled (shown as subscriptionAuth on /api/health). Otherwise StartProviderOAuth returns 403. Implementation lives in agents/src/provider-oauth.ts.

StartProviderOAuth {providerType} → {_: 'StartProviderOAuthResponse'; loginId; authUrl; expiresAt}. Only openai is supported. Starting a new login cancels the account's previous pending one.

GetProviderOAuthStatus {loginId} → {_: 'ProviderOAuthStatusResponse'; loginId; status: 'pending' | 'completed' | 'failed'; secretName?; error?}. On completed, secretName is the stored credentials secret to reference as secretRefs.oauth.

SubmitProviderOAuthCode {loginId, code} → {_: 'SubmitProviderOAuthCodeResponse'}. For deployments where the provider's localhost redirect cannot reach the server, the client pastes the code (or the full redirect URL).

CancelProviderOAuth {loginId} → {_: 'CancelProviderOAuthResponse'; loginId}.

RedactedModelProvider.authStatus reports subscription health afterwards: ok, or needs-login when credentials are missing or a token refresh failed.

Account-scoped, like model providers. Full behavior is in MCP servers.

SetMcpServer validates the name (slug), URL (http/https), transport, and header maps (valid header names, at most 16 each, values ≤ 4 KiB), saves, then connects to discover the server's tools. The response reports status and tools either way, and a failed discovery still saves. RefreshMcpServer discovers again. DeleteMcpServer deletes the record and the mcp-<name>-… secrets it owns, removes the name from every agent's definition.mcpServers, and drops their projected mcp tool documents. Writes emit account-change with reason mcp-servers-changed, plus agent-tools-changed per re-projected agent.

AgentDefinition.mcpServers?: string[] (≤ 16 names) is the per-agent grant, accepted by CreateAgent and UpdateAgent.

Request:

Encrypts and upserts a secret. The response is redacted and never includes the secret value.

Request:

Response:

Requires owner, reader, or writer access to the agent.

Request:

Updates the definition for the owner or an accepted writer after validating the owning account's provider and signing identities.

Request:

Response:

Deletes the agent after validating ownership, including its triggers, sessions, session events, trigger firings, drafts, and per-agent state directory. Live runs of the agent are canceled first, cascading through their trees. Run history survives, detached: runs.agent_id, runs.session_id, and runs.trigger_firing_id are nulled inside the delete transaction. They are enforced foreign keys, and without the detach any agent that had ever executed a run could not be deleted. Sub-sessions of other agents hanging off this agent's sessions promote to top level.

The trigger API supports signed CRUD for agent-scoped triggers. The ActivityFeed monitor processes HM activity triggers, and the schedule monitor processes schedule triggers.

Trigger source shape:

Trigger prompts accept the same rich Seed block format as agent system prompts. Legacy string input is parsed as markdown. Trigger prompt blocks are converted to resolved markdown before starting the triggered session.

A user-mention source watches a list of accounts. A legacy singular mentionedAccount on input is still normalized into mentionedAccounts, and an empty list is rejected. A comment-reply source matches a comment replying directly to a comment by one of repliedToAccounts, never an account's reply to itself. A document-author-comment source matches a comment on a document authored by one of documentAuthors (the feed's targetAuthorUids), never an author's own comment.

Document fields (resource, resourcePrefix) must name an account or document (hm://<account uid>[/path]); a bare hm:// or a wildcard is rejected rather than treated as "everything". site-update eventTypes must be one of doc-update, comment, citation, capability, contact (or the legacy aliases document-update, change, ref).

Agents writing ~/triggers/<name> can pass dryRun: true to validate the trigger and replay about 100 recent activity events through it without saving. An agent's edit cannot change the kind of source that starts a trigger unless it passes replaceSource: true, and interval schedules under 5 minutes need frequentSchedule: true; both are meant only for explicit user requests.

An activity source matches any of its 1–32 conditions. Condition IDs must be unique and remain stable when edited; the server assigns an ID if omitted on input. Nested groups and schedule/webhook/run-completed conditions are rejected. One comment matching both a document filter and a mention filter admits only one firing, including sibling feed events arriving in separate polls. Distinct triggers remain independent.

CombineAgentTriggers {triggerId, otherTriggerId, expectedUpdatedAt, otherExpectedUpdatedAt, useOtherAction?} combines two activity triggers of the same agent and returns UpdateAgentTriggerResponse. The first survives, retaining its name and enabled state. Its action stays unless useOtherAction is true. The other becomes disabled with mergedInto and cannot be edited or enabled again. Both original histories remain available; previously handled events remain deduplicated. UpdateAgentTrigger also accepts optional expectedUpdatedAt to reject stale edits with HTTP 409.

Compound-source operations require protocol 3. Older clients receive a typed update-required response rather than an incomplete rule. Existing single-source operations and session attribution remain compatible.

continuation says what a firing does. See trigger continuations. Omitted (or newThread), it starts a fresh thread from the trigger's prompt, which is what every trigger did before continuations existed. wake delivers a signal to a run parked on ctx.waitForEvent instead, through the same delivery path as SignalRun. Without runId, the server searches the account's parked runs for one the signal satisfies.

run-completed lets automations chain: it fires when a run of this account reaches a terminal status. Chains are loop-guarded. A firing whose ancestry already contains the same trigger within 8 hops is skipped (TRIGGER_CHAIN_MAX_HOPS in api-service.ts).

The agent_triggers table carries a cooldown_ms column, but no protocol field writes it and no monitor reads it. It is vestigial. Do not document a cooldown feature until one exists.

Actions:

ListAgentTriggers {agentId} returns {_: 'ListAgentTriggersResponse'; triggers: AgentTriggerInfo[]}.

GetAgentTrigger {triggerId} returns {_: 'GetAgentTriggerResponse'; trigger: AgentTriggerInfo; sessions: SessionInfo[]}.

CreateAgentTrigger {agentId, trigger, clientRequestId?} returns {_: 'CreateAgentTriggerResponse'; trigger}.

UpdateAgentTrigger {triggerId, patch} returns {_: 'UpdateAgentTriggerResponse'; trigger}.

DeleteAgentTrigger {triggerId} returns {_: 'DeleteAgentTriggerResponse'; triggerId}.

All trigger actions verify account ownership through the owning agent and trigger rows. CreateAgentTrigger supports the same clientRequestId idempotency pattern as other create actions.

Each agent owns a private memory filesystem at <stateDir>/memory. It is the ~/memory/ half of its Space. The agent reaches it through the read and write verbs, and its owner sees it on the desktop Memory tab. All actions validate agent ownership for the signed account. Every path is a sandboxed relative path: no absolute paths, no .., symlinks refused. Files can be UTF-8 text or binary.

Actions:

ListAgentMemory {agentId} returns {_: 'ListAgentMemoryResponse'; agentId; entries: AgentMemoryEntry[]; totalBytes} with every file and directory sorted by path.

ReadAgentMemoryFile {agentId, path} returns {_: 'ReadAgentMemoryFileResponse'; agentId; file: AgentMemoryFile}. Small clean-UTF-8 files come back as text. Everything else comes back as raw bytes for preview and download in the Memory tab.

WriteAgentMemoryFile {agentId, path, content} returns {_: 'WriteAgentMemoryFileResponse'; agentId; entry} after writing the full file content, creating parent directories as needed. content may be a string (UTF-8 text) or Uint8Array bytes (e.g. a local file uploaded from the Memory tab). Writes, downloads, and deletes emit an account-change event with reason agent-memory-changed, which is also fanned out to agents/<agentId> WebSocket subscribers so open Memory tabs refresh.

DeleteAgentMemoryFile {agentId, path} removes a file, or a directory recursively, and returns {_: 'DeleteAgentMemoryFileResponse'; agentId; path; deleted}. deleted is false when nothing existed.

DownloadAgentMemoryFile {agentId, url, path?} server-side fetches a public http(s) URL into memory (streamed, with a 60-second idle timeout) and returns {_: 'DownloadAgentMemoryFileResponse'; agentId; entry; finalUrl; contentType?}. Omitting path stores the file under downloads/, named from the URL. Extension-less paths gain an extension from the response content type.

UploadAgentMemoryFileToIpfs {agentId, path} chunks the file as UnixFS and publishes its blocks through the typed HM API's PublishBlobs action, then returns {_: 'UploadAgentMemoryFileToIpfsResponse'; agentId; path; cid; url; size; mimeType?}, where url is the ipfs://<cid> URL usable from Hypermedia content. Publishing makes the file publicly retrievable.

Path limits (agents/src/agent-memory.ts): 512 bytes per normalized relative path, 16 levels of nesting. Memory itself has no per-file, per-agent, or entry-count size cap. The server accepts uploads of any size (main.ts raises Bun's request-body limit for this). The 256 KiB MAX_WRITE_CONTENT_BYTES bound in api-service.ts applies only to hypermedia content the write verb publishes. It does not apply to memory files.

Request:

Response:

Lists every tool document in the agent's ~/tools, builtin bindings and authored lambdas alike, from the tool_documents table. It rebuilds the builtin rows first if the registry contract has changed. This is the owner's view of the same documents the agent sees when it reads ~/tools/. See tools.

Request:

Creates an idle session for an account-owned agent.

Idempotent when clientRequestId is supplied.

Request:

Lists the signed account's sessions newest-first across every agent on the server, or a single agent's sessions when agentId is set. Response:

agents contains only the agents referenced by sessions, so a client rendering a cross-agent session list can label each row without a follow-up GetAgent per session. This exists because the desktop assistant sidebar shows one merged list spanning every agent on every configured server; without it the client would have to walk ListAgents and then GetAgent per agent just to enumerate sessions.

limit defaults to 50 and is clamped to 200.

Pagination is keyset on the composite (updatedAt, id). Sessions often share an updatedAt millisecond, because one trigger firing over a batch of activity events creates several at once. A timestamp-only cursor would silently drop every tied row past a page boundary. Pass nextCursor back verbatim as cursor. When it is absent, the list is exhausted.

Child sessions (spawned by delegate, a script's ctx.delegate, or an agent starting a session) are included by default. An absent includeChildren returns every session, because older deployed clients cannot send the field, and hiding agent-started sessions from them would be a silent regression. Lineage-aware clients (the current desktop) pass includeChildren: false to get top-level rows only. Parents carry childSessionCount. These clients fetch children per parent with parentSessionId, which ignores includeChildren.

Request:

Updates editable session metadata for an account-owned session. The server trims and bounds the title, marks the title as user-authored, updates updatedAt, emits session-change, and fans out an account change with reason session-updated. A title saved this way is marked title_source = 'user', which the server's automatic session titling refuses to overwrite.

Response:

Request:

Deletes an account-owned session and its durable events. Every live run rooted at the session is canceled first, including descendants (spawned sub-sessions and workflows). A parked parent is never stranded waiting because its session disappeared, and no executor streams into deleted rows. Run history survives, detached (runs.session_id nulled). Child sessions promote to top level (parent_session_id nulled). A creating trigger firing is kept but detached. The server emits an account change with reason session-deleted.

Response:

Request:

Returns session metadata, durable events with seq > afterSeq if provided, and systemPromptMarkdown, the current markdown system prompt that would be used to continue the session.

Request:

context parts carry ambient client state. The desktop sidebar sends the current window (open document, view, focused block) so "this document" resolves for the model. All context lines in a request collapse onto its first user message as contextLines. They reach the model appended to that message inside a <window_context> block, and never appear in the transcript content. At least one text part is required.

attachment parts reference files already staged with UploadSessionAttachment (or a committed chunked upload). They are session-private attachments. They live with the session, the agent reaches them through read attachment:<id>, and they are deleted with the session.

Flow:

Verify that the signed account has write access to the session's agent.

Append the durable user message immediately, with content and rawMarkdown, optional rich blocks, and meta.accountId plus the exact cryptographic meta.signerId from the verified envelope.

Enqueue a durable run for that message.

Claim it inline when no other turn owns the session. Otherwise leave it queued behind the current turn.

Run the model loop with one model turn at a time per session.

Emit live partials over WebSocket.

Append tool events and the final assistant or error event.

Start the next queued collaborator turn, if any.

So several writers may submit to one session at once. Their messages are saved and broadcast in append order, and nobody gets a 409 while the agent is streaming. Model turns stay serialized. A queued turn gets an in-memory handoff that names the exact message events that arrived during the preceding response. Later assistant events from that preceding turn are then not mistaken for answers to the newly queued messages.

Internally each turn is a durable run row in the dispatch queue (agents/src/runs.ts). MessageSessionResponse.assistantEventId is an empty string when the request returned before a final assistant event existed. That happens for concurrent and background enqueues (including triggers and agent-started sessions), and for turns that parked on children spawned with delegate. The rest of the turn streams over WebSocket.

Idempotent through clientMessageId. It avoids one long SQLite transaction around network calls, on purpose.

Request:

Response:

Runs one verb as the user against the session's shared Log. The log is a shared workspace. The same read, write, and call implementations the agent uses execute here. Both the call and its result append as durable events stamped actor: 'user', so the agent reads them on its next turn as ground truth. There is no side channel. The desktop composer's wrench palette sends this action.

Only those three verbs are accepted. delegate and plan cannot be invoked by the user, on purpose. Delegation is a conversational ask, and any path that reaches session-spawning from a user verb rejects with "Delegation is a conversational ask; message the agent instead".

Execution failures are log entries too, because the user's failed attempt is context. They come back in error, with no HTTP error. Only pre-execution problems reject the request outright: an unknown verb (400), an unowned session (404), and a session with a live run (409, "The agent is working in this thread right now").

UploadSessionAttachment {sessionId, name, mimeType?, content} → {_: 'UploadSessionAttachmentResponse'; attachment: SessionAttachmentInfo}. The attachment id is the SHA-256 hex of the bytes, so re-uploading the same file returns the same id. Caps: 100 MiB per attachment and 200 attachments per session (agents/src/session-attachments.ts), stored under <stateDir>/session-attachments/<sessionId>/.

ReadSessionAttachment {sessionId, attachmentId} → {_: 'ReadSessionAttachmentResponse'; attachment; data} for rendering an attachment back in the thread.

Large files upload in bounded chunks, so each signed action stays small and clients can show progress:

BeginFileUpload {target, size} → {_: 'BeginFileUploadResponse'; uploadId; maxChunkBytes}. target is {kind: 'memory', agentId, path} or {kind: 'session-attachment', sessionId, name, mimeType?}, validated up front so a long upload cannot fail at the very end. maxChunkBytes is 8 MiB.

AppendFileUploadChunk {uploadId, offset, content} → {_: 'AppendFileUploadChunkResponse'; uploadId; received}. Chunks must arrive in order: offset must equal the bytes already staged. Oversized chunks return 413.

CommitFileUpload {uploadId} → {_: 'CommitFileUploadResponse'; entry?; attachment?}: entry for a memory target, attachment for a session attachment. The staged byte count must equal the declared size.

AbortFileUpload {uploadId} → {_: 'AbortFileUploadResponse'; uploadId}. Staged uploads also expire after an hour.

Request:

Response:

Stops the in-flight Pi agent turn for the signed account and session when one is active, and cancels every live run rooted at the session including descendants (delegated model children and script children). stopped is false when the session is already idle.

Request:

Response:

Re-runs a session whose latest run failed, without appending a new user message. The turn re-enters from the durable transcript, and error events are not replayed to the provider. Rejected when a run is live or the latest run did not fail. assistantEventId is an empty string when the retried turn parked (the rest streams over WebSocket), exactly like MessageSession.

{_: 'GetRun', runId} → {_: 'GetRunResponse', run: RunInfo}. 404 when the run does not belong to the account.

Exactly one selector is required. Response: {_: 'ListRunsResponse', runs: RunInfo[]}.

{_: 'CancelRun', runId} → {_: 'CancelRunResponse', runId, canceled}. Cancels the run and every non-terminal descendant: queued runs never start, waiting runs never wake, executing runs are aborted (Pi abort for agent runs, VM interrupt for script runs). canceled is false when everything was already terminal.

Response: {_: 'SignalRunResponse', runId, delivered}.

Delivers a named signal to a run parked on ctx.waitForEvent, and wakes it with the payload. A person or another system uses this to answer a workflow that waits for something the activity feed cannot express: an approval, a webhook, a human decision. The run card's Answer button sends the run's RunWaitInfo.answerWith signal. Signalling a run that is not listening for this signal is not an error. delivered is false. See wake source. A trigger with a wake continuation rides this same delivery path.

{_: 'GetRunJournal', runId, afterSeq?} → {_: 'GetRunJournalResponse', runId, entries}. It returns a script (workflow) run's durable journal entries ({runId, seq, entry, createdAt}). It is empty for agent runs, and replayable with afterSeq like session events.

Request:

Used over /agents/ws. See WebSocket subscriptions.