The RPC contract

The RPCs by which the UI, the Web and the Agent talk to tsugumid, generated from the doc comments of protocol/tsugumi.fbs.

Format: one message is one FlatBuffer (root Tsugumi.RPC.Message, file identifier TSG1). The WebSocket subprotocol is tsugumi.rpc.v1; on a Unix socket, a 4-byte length (little endian) is followed by the body.
Failure: any request may be answered with Failure.
Requests that change something: carry an op_id, and a resend with the same op_id is applied only once. If a response is lost, check with OperationGet.
The Agent’s tools: made from the same schema (tsugumi.bfbs) (Features).

There are 50 requests.

Connection

Request	Response	Description
`SessionHello`	HelloResult	token is required on WebSocket. Project mismatch is permission_denied. Must be the first request, within 5 s of connecting. `protocol` is the newest version the client speaks and `min_protocol` the oldest (default: protocol); the server answers with the newest version both speak (HelloResult.protocol), or protocol_mismatch.

SessionHello

Field	Type	Required	Description
`protocol`	`uint32`
`client_id`	`string`	yes
`expected_project_id`	`string`
`token`	`string`
`min_protocol`	`uint32`
`language`	`string`		The client’s language (“ja” or “en”; anything else is Japanese). What tsugumid writes into the project’s git for the runs this connection starts (the commit message, the run’s note) is in it.

Projects and saving

Request	Response	Description
`ProjectOpen`	OpenResult	Creates (or replaces) the connection’s subscription.
`ProjectClose`	Ack	Ends only the given subscription. Unknown ids are acknowledged.
`ProjectInspect`	ProjectSnapshot	No subscription, build or reload.
`CardId`	CardIdResult	Reserves a permanent identifier for a new Card without changing the document revision. Supply its human name; use the returned id in the canvas, definition paths and wires, and name in _meta.json.name. Each call reserves a fresh id; save the definition and canvas with project_save.
`ProjectSave`	SaveResult	Apply all changes in one transaction at base_rev.
`ProjectReload`	SaveResult	Takes external edits of the allowed area into the document. Every permission widening requires explicit approval, regardless of origin.
`ProjectValidate`	ProjectValidateResult	targets = [] means everything; mode = executable.
`ProjectShell`	ProjectShellResult	Runs in the project VM as the project user, with the project directory as cwd. Available only when the isolated project launcher enables it. timeout_ms defaults to 10000 and must be between 1 and 30000. Each output stream is capped at 262144 bytes. Disconnecting cancels the process group. An operation ID is never executed twice, even after an interrupted daemon. Agent use requires explicit Shell access in addition to Read, Write and Run. With origin “agent”, project files are read-only, using bubblewrap on Linux and Seatbelt on macOS; only diagnostic temporary files are writable. Isolation unavailable means the request is refused. Shell commands are for diagnosis and reads. Analysis runs in Cards; Agent edits go through ProjectSave. A person’s UI terminal is a separate writable path.
`ProjectCacheClear`	ProjectCacheClearResult	Only while no run or SDK job is active.
`ProjectCacheUsage`		Cached shared-store measurement; never triggers a store traversal on the RPC lane.
`RunScratchDelete`	RunScratchDeleteResult	Deletes only the listed scratch folders from the usage report. Refuses active runs, pending remote results and the latest run.
`OperationGet`	OperationResult

ProjectOpen

Field	Type	Required	Description
`view_id`	`string`

ProjectClose

Field	Type	Required	Description
`subscription_id`	`string`	yes

ProjectInspect

No fields.

CardId

Field	Type	Required	Description
`name`	`string`	yes
`project_path`	`string`		Project-relative directory: empty for the root, or externals//, repeated for nesting. May name a project being created in the same draft.

ProjectSave

Field	Type	Required	Description
`base_rev`	`uint64`
`op_id`	`string`	yes
`origin`	`string`	yes
`changes`	`[DocumentChange]`	yes
`approved_permissions`	`[string]`		The Card permissions this save widens that the user approved, each as an `approval_required` failure names it. Set by the client after asking the user, never by a model; a save from a model (origin “agent”) is rejected unless every widening is listed.

ProjectReload

Field	Type	Required	Description
`base_rev`	`uint64`
`op_id`	`string`	yes
`origin`	`string`	yes
`approved_permissions`	`[string]`		The widenings named by approval_required that the user approved. Set by the client after asking the user, never by a model.

ProjectValidate

Field	Type	Description
`at_rev`	`uint64`	Omitted: the latest revision.
`targets`	`[CardPath]`
`mode`	`ValidateMode`
`changes`	`[DocumentChange]`	Proposed changes (as in project_save): the document as it would be after them is checked and nothing is saved. For the apps’ editors; the model is not offered this field (it saves, then checks).

ProjectShell

Field	Type	Required
`op_id`	`string`	yes
`command`	`string`	yes
`timeout_ms`	`uint32`
`origin`	`string`	yes

ProjectCacheClear

Field	Type	Required	Description
`op_id`	`string`	yes

ProjectCacheUsage

No fields.

RunScratchDelete

Field	Type	Required	Description
`op_id`	`string`	yes
`paths`	`[string]`	yes

OperationGet

Field	Type	Required	Description
`op_id`	`string`	yes

Files

Request	Response	Description
`ProjectFileList`	SourcePage	depth = 0 (0..8), include_directories = false, limit = 100.
`ProjectFileStat`	SourceInfo
`ProjectFileRead`	FileContent	offset = 0, limit_bytes = 262144 (1..1 MiB).
`ProjectFileFormat`	ProjectFileFormatResult	Never changes the document.
`AttachedFolderRead`	FileContent	Reads a folder of the Mac attached to a chat (read-only, shared with this project only): a file’s bytes, or for a folder its entries as text, one per line (folders end with “/”). `folder` is the attached folder’s path on the Mac; `path` is relative to it (“” = itself).

ProjectFileList

Field	Type	Required	Description
`path`	`string`	yes	Relative to the project; “” or “.” is the project folder.
`at_rev`	`uint64`		Omitted: the latest revision.
`depth`	`uint32`
`include_directories`	`bool`
`cursor`	`string`
`limit`	`uint32`

ProjectFileStat

Field	Type	Required	Description
`path`	`string`	yes
`at_rev`	`uint64`

ProjectFileRead

Field	Type	Required	Description
`path`	`string`	yes
`at_rev`	`uint64`		Omitted: the latest revision.
`if_hash`	`string`
`offset`	`uint64`
`limit_bytes`	`uint32`

ProjectFileFormat

Field	Type	Required
`path`	`string`	yes
`text`	`string`	yes
`language`	`FormatLanguage`

AttachedFolderRead

Field	Type	Required
`folder`	`string`	yes
`path`	`string`	yes
`offset`	`uint64`
`limit_bytes`	`uint32`

Card SDKs and types

Request	Response	Description
`CardSDKPrepare`	CardSDKPrepareResult	Accepted asynchronously.
`CardSDKStatus`	CardSDKPrepareResult or Failure
`OutputTypes`	OutputTypesResult	Compiles an _outputs.fbs text (nothing is saved): its reflection schema (bfbs), from which a client lists the types. With port and type_name, also the text with that port’s type and kind set (File / Directory: the tsugumi attribute).
`NixSourceResolve`	NixSourceResolved	Looks a flake up for nixSources (nothing is saved): its current commit and hash, and the packages it has for this system. To customize an approved package, save nixSources[].overrides = {“packageName”:{“override”:{“argument”:“value”},“overrideAttrs”:{“pname”:“custom”}}}. Both maps contain JSON values, not Nix functions. A value {“fetchurl”:{“url”:“https://…”,“sha256”:“…”}} fetches a hash-pinned source or patch in the external evaluator. Modifying these overrides needs user approval. Cards consume inputs.sources..packages., with the system already selected. Unsupported override/overrideAttrs functions return an actionable evaluation error. Slow the first time: it evaluates them, fetching what they need.

CardSDKPrepare

Field	Type	Required
`card`	`CardPath`	yes
`at_rev`	`uint64`
`op_id`	`string`	yes

CardSDKStatus

Field	Type	Required	Description
`op_id`	`string`	yes

OutputTypes

Field	Type	Required
`text`	`string`	yes
`port`	`string`
`type_name`	`string`
`kind`	`PortKind`

NixSourceResolve

Field	Type	Required	Description
`ref`	`string`	yes

Running

Request	Response	Description
`RunPlan`	RunPlanResult	propagate = true.
`Run`	RunAccepted	propagate = true, max_concurrency = 4 (1..64), nix_jobs = 1, nix_cores = 1.
`RunCancel`	RunStatus	Idempotent. Unknown id is not_found.
`RunStatus`	RunStatus	Omitted run_id: the active run, else the latest locally started run, else idle. partial_run marks debugging with saved inputs; uses_partial_result marks values derived from a partial run, within this run or through saved inputs. Both flags persist in RunSummary.status in history/comparison replies and run events, including runs with recorded values and retained artifacts.

RunPlan

Field	Type	Required
`at_rev`	`uint64`
`card`	`CardPath`	yes
`propagate`	`bool`

Run

Field	Type	Required
`base_rev`	`uint64`
`op_id`	`string`	yes
`origin`	`string`	yes
`card`	`CardPath`	yes
`propagate`	`bool`
`max_concurrency`	`uint32`
`nix_jobs`	`uint32`
`nix_cores`	`uint32`

RunCancel

Field	Type	Required	Description
`run_id`	`string`	yes

RunStatus

Field	Type	Required	Description
`run_id`	`string`

History and artifacts

Request	Response	Description
`RunHistory`	RunPage, newest accepted first
`RunInvocations`	InvocationPage, ascending invocation number
`RunLatestInvocations`	InvocationPage	Each Card’s latest invocation of a run, for a client that opens the project after the run: it did not get RunCardChanged for them.
`RunRecord`	RecordResult	invocation and follow_latest = true are exclusive.
`RunValueRead`	FileContent	offset = 0, limit_bytes = 1048576.
`RunHistoryDelete`	RunHistoryDeleteResult	Deletes finished runs (all, or those that ended before ended_before, Unix ms) with their records, values, logs and files, here and in the project’s copy. Only while no run is active. Approvals must set restrict_to_run_ids and pass the exact run_ids shown to the person (an empty set deletes nothing). Without that flag, run_ids must be empty and the UI’s all-runs or date scope applies. The separate flag distinguishes an empty selection from object APIs’ default empty vectors.
`ArtifactList`	ArtifactPage	invocation requires card.
`ArtifactRead`	FileContent	member only for Directory artifacts.
`LogRange`	LogSlice	limit_bytes = 65536 (4..256 KiB). tail with offset != 0 is rejected. invocation requires card.
`RunEnvironments`	BuildEnvironmentPage	Recorded environments, in first-use order; no Nix evaluation. offset defaults to 0; limit defaults to 100 (maximum 500).
`RunEnvironmentPaths`	EnvironmentPathPage	Runtime closure, including the manifest, in store-path order. These are runtime references, not the full set of build-time dependencies.

RunHistory

Field	Type	Required	Description
`card`	`CardPath`
`artifacts_only`	`bool`
`cursor`	`string`
`limit`	`uint32`

RunInvocations

Field	Type	Required
`run_id`	`string`	yes
`card`	`CardPath`	yes
`cursor`	`string`
`limit`	`uint32`

RunLatestInvocations

Field	Type	Required	Description
`run_id`	`string`	yes

RunRecord

Field	Type	Required
`run_id`	`string`	yes
`card`	`CardPath`	yes
`invocation`	`uint64`
`follow_latest`	`bool`

RunValueRead

Field	Type	Required
`run_id`	`string`	yes
`card`	`CardPath`	yes
`invocation`	`uint64`
`side`	`ValueSide`
`port`	`string`	yes
`offset`	`uint64`
`limit_bytes`	`uint32`

RunHistoryDelete

Field	Type	Required
`op_id`	`string`	yes
`ended_before`	`int64`
`run_ids`	`[string]`
`restrict_to_run_ids`	`bool`

ArtifactList

Field	Type	Required
`run_id`	`string`	yes
`card`	`CardPath`
`invocation`	`uint64`
`cursor`	`string`
`limit`	`uint32`

ArtifactRead

Field	Type	Required
`artifact_id`	`string`	yes
`member`	`string`
`offset`	`uint64`
`limit_bytes`	`uint32`

LogRange

Field	Type	Required
`run_id`	`string`	yes
`card`	`CardPath`
`invocation`	`uint64`
`stream`	`LogStream`
`offset`	`uint64`
`tail`	`bool`
`limit_bytes`	`uint32`

RunEnvironments

Field	Type	Required
`run_id`	`string`	yes
`offset`	`uint64`
`limit`	`uint32`

RunEnvironmentPaths

Field	Type	Required	Description
`run_id`	`string`	yes
`environment_id`	`string`	yes
`offset`	`uint64`
`limit`	`uint32`
`query`	`string`		Case-insensitive literal substring search. Offset and total refer to matching paths.

Views

Request	Response	Description
`ViewSetVisible`	Ack	Replaces the subscription’s Display targets. enabled = true.
`ViewSave`	ViewSaveResult	CAS on view_rev only.
`ModuleRead`	FileContent	Reads immutable module source in bounded pages. For a Wasm view, the core assembles the shared index.js template and local view.wasm. Only canonical /nix/store/- directories with index.js qualify.
`LayoutArrange`	LayoutProposal	Places the scope’s Cards, output frames and notes, then gives ports the order that crosses fewer wires and places the Cards once more for it. The bars are taken to follow the Cards again. Nothing is saved.
`LayoutUntangle`	LayoutProposal (port_orders only)	Reorders ports where the wires then cross less; no Card moves. With `around` (the Cards a drag just moved) only they and the Cards wired to them may change. Nothing is saved.

ViewSetVisible

Field	Type	Required
`subscription_id`	`string`	yes
`cards`	`[CardPath]`	yes
`enabled`	`bool`

ViewSave

Field	Type	Required
`view_id`	`string`	yes
`base_view_rev`	`uint64`
`view`	`ViewState`	yes

ModuleRead

Field	Type	Required
`module`	`string`	yes
`offset`	`uint64`
`limit_bytes`	`uint32`

LayoutArrange

Field	Type	Required	Description
`scene`	`LayoutScene`	yes

LayoutUntangle

Field	Type	Required	Description
`scene`	`LayoutScene`	yes
`around`	`[string]`

Versions

Request	Response	Description
`VersionInit`	VersionResult	Makes the project a git repository: a first commit of what is saved (a demo’s history file becomes its versions). Nothing happens when it already is one.
`VersionMark`	VersionResult	Names the current version: what is saved is committed (when it changed) and gets an annotated tag `name` with `message`.
`VersionCheckout`	SaveResult	Starts from a version: what is saved now is committed, then the project’s files become those of `commit` and the document is read again (like ProjectReload). Only while no run is active.
`VersionGraph`	VersionGraph, newest first
`VersionCanvas`	VersionCanvas: the Cards of a version and how they connect (a minimap)
`VersionDiff`	VersionDiff: what a version changed from another version (its first parent by default), in the text a summary is written from	Only code and settings: never data files.
`VersionNote`	VersionNote	Core-generated mechanical record and the saved Agent note. The host Agent service chooses which to return to the UI. Mechanical records are kept in refs/notes/tsugumi-record-{ja,en}.
`VersionNoteStore`	VersionResult	The host Agent service stores the generated note in refs/notes/tsugumi-summary. Clients request notes from agentd.

VersionInit

Field	Type	Required	Description
`op_id`	`string`	yes
`origin`	`string`	yes

VersionMark

Field	Type	Required
`op_id`	`string`	yes
`origin`	`string`	yes
`name`	`string`	yes
`message`	`string`

VersionCheckout

Field	Type	Required
`base_rev`	`uint64`
`op_id`	`string`	yes
`origin`	`string`	yes
`commit`	`string`	yes

VersionGraph

Field	Type	Required	Description
`limit`	`uint32`

VersionCanvas

Field	Type	Required	Description
`commit`	`string`	yes

VersionDiff

Field	Type	Required	Description
`commit`	`string`	yes
`from_commit`	`string`		Compare from this version; absent means the first parent of commit.

VersionNote

Field	Type	Required	Description
`commit`	`string`	yes
`language`	`string`	yes

VersionNoteStore

Field	Type	Required
`op_id`	`string`	yes
`origin`	`string`	yes
`commit`	`string`	yes
`summary`	`string`	yes

Notifications

Sent from tsugumid to connected clients.

DocPatched
RunEvent
DisplayUpdated
LogAvailable

Run events

The value inside a RunEvent has one of these types.

RunAcceptedEvent
RunStatusChanged
RunCardChanged
RunTimeline
RunFinished
RunBatchChanged