Contains Agent, Session, Executor and WorkHub wire declarations, plus the Agent configuration schema. Native services and SDK generation share these definitions. Use this crate when a consumer needs the public contract without pulling in the Agent execution engine.
Independent Desktop clients consume the same persisted Agent service through the Root-bound public Host client; they do not open Agent storage or embed its execution engine. Agent contracts and interaction contracts are the source of field definitions and schemas.
Read history pages under one fixed through fence and resume watch from its last nextAfter; watch also publishes queue and pending-interaction updates. send admits work and returns its identity; stop names that exact invocation. Use pendingInteractions, interaction and respond to reconstruct and answer the original request after reconnecting. Mutations retain their original operation receipts: a lost response does not authorize another send. See native acceptance and transport ownership and exit modes.
History row references use position: { sourceSequence, itemIndex }, ordered by the original emitting event and then its row ordinal. Cursors, source reads, prompt anchors and tool-image references share this position. through and { kind: "event", sequence } still address raw events; a model completion publishes all of its rows at that completion’s event.
search scans the selected Session’s history with a literal query and explicit caseSensitive and wholeWord options. Case-insensitive matching uses Unicode simple case folding without normalization; whole-word matches require no adjacent Unicode word character (letters, marks, decimal digits, connector punctuation or join controls). Start with after: null. Keep the query, options and through fence fixed while advancing nextAfter, including pages with no hits; null ends the scan. Each hit identifies the exact original field for source reads. Open a hit in history with { kind: "row", position: hit.position, field: hit.field === "thinking" ? "thinking" : "body" } and that same fence; this includes empty tool rows and reveals an explicitly targeted internal tool without exposing subsequent hidden rows. Byte continuation cursors remain exclusive of already-read content.
Executor execute receives immutable files through one optional binary resource named attachments. Its metadata is an ordered array of { name, mimeType, bytes, digest }; the resource contains the original file bytes concatenated in that order, with each offset determined by preceding lengths. Read through the actual request resource, which retains Host byte-budget and cleanup custody; metadata alone grants no access.
fork starts a side conversation from a complete Turn or all current history, guarded by the source revision. Included work must be settled; an earlier complete Turn can still be forked while a later Turn runs. The new Session retains that history and its attachments, shares the verified workspace, and starts with narrowed permissions and no active work. Its branch identifies the source. Recover a lost response with the original operation reference; forkReceipt can locate a published fork even when the Host outcome remains unknown. A null result does not prove that nothing happened or authorize a replacement fork. See the fork declarations.
diagnostics reads bounded, newest-first pages of execution, model-step and automatic-title failures under a fixed through fence. watchDiagnostics emits the current diagnostic revision on subscription and after changes; reconnect by reading the latest page again. These session-scoped operational records retain original invocation/event identities and safe typed causes. They exclude provider bodies and failures belonging to copied source sessions. Their revision is independent of conversation history, so a late title failure remains discoverable after the answer finishes.
context reports the latest Main request prepared by the selected Session, including requests still running or interrupted. It groups the original Host input by message role and tool schemas; token counts are estimates, while provider-reported input usage is separate. Pin through to reread the same result after reconnecting. Missing requests or measurements remain null, and copied history does not count as a request executed by the new Session. See the context declarations.
gitStatus and gitDiff read the selected Session's repository through the same Agent service, including WorkHub coordinator sessions. Status separates staged, worktree and untracked changes; a path can appear in both staged and worktree areas. Diff compares HEAD to the index, the index to the working file, or an empty file to an untracked file, respectively. An unborn repository has a null head; a workspace without a repository returns null. Paths use exact Git pathname bytes encoded as bytesBase64, and renames appear as deletion plus addition.
These are fresh, read-only observations, not repository snapshots. Status returns the complete list of staged, worktree and untracked entries. Per-file diff reads complete inputs and returns text, binary, unchanged or unsupported; text patches are returned in full. Repository metadata, control files, status entries, diff inputs and patches are buffered in memory. Cancellation is cooperative; these queries do not promise bounded memory or a fixed execution time. The workspace must be the repository root. Unsupported repository features fail explicitly, including external filters, sparse checkout and submodules; configured commands are never executed. A changed workspace or comparison base requires a fresh query. Git declarations define the wire types; snapshotPatch captures an immutable completed-work patch after workspace writers settle. Capture reads complete source images and buffers the complete patch before publication; readPatch returns recoverable pages from that original artifact, including after later executions and Host restarts.
listFiles lists direct children of the selected Session workspace; watchFiles reports when that directory needs rereading. Both also work for WorkHub coordinator sessions. Use null path for the workspace root, or a WorkspacePath carrying exact relative pathname bytes as bytesBase64. Symlinks are leaf entries; .git, the workspace marker and private Host state/control directories are excluded, including in unrestricted model workspaces. Only the Session’s validated managed worktree is readable inside private state. Pages contain at most 128 entries with a soft 512 KiB byte target; one complete first entry can always advance. Paths preserve complete relative bytes. Unsupported platform filenames fail explicitly instead of being converted lossily.
readFile is an ordinary UI subscription for one current regular file at an exact WorkspacePath under the same Session authority. It captures complete UTF-8 text or original supported image bytes, with no-follow directory/file handles and checks of workspace, permission boundary and file identity before publication. It emits begin, Base64 chunk items of at most 32 KiB original bytes, then an explicit end item; the subscription final value is null. Text chunks end at UTF-8 boundaries. Consumers must check contiguous byte offsets, the matching version/size/digest in End, and the complete SHA-256 digest before accepting the content. Missing End means incomplete delivery. Absent, changed, binary and unsupported file kinds are explicit; permission, invalid-path and IO errors remain failures. Empty files are valid text.
The version binds original bytes, physical file/parent identity and pathname; optional expectedVersion is a reread precondition, never permission. All chunks of one read come from the same complete native buffer, so replacing the path during delivery cannot mix versions. No durable artifact or atomic filesystem snapshot under concurrent writes is promised. A new read reauthorizes the Session and captures current content; historical toolImage keeps its separate immutable source authority. Drain through successful subscription completion and cleanup before accepting a preview; close the subscription to cancel, then await its original cleanup.
Start the watch, wait for ready, then read the first list page and compare its directoryIdentity with ready. Follow next for further pages; a changed notification means discard the cursor and reread from the beginning. Pages are live observations, so concurrent edits can change pagination. Notifications can coalesce and are not a replayable event history: reconnect with a new watch and fresh listing. Detected deletion or replacement of a selected subdirectory ends the watch with unavailable; invalid Session/workspace authority or filesystem observation failures end it with an error. Close the subscription when leaving the directory.
On macOS, active watches also compare direct-child metadata. Each scan is followed by a pause of at least one second, extended to nine times the scan duration for expensive directories; this targets a 10% scanning duty cycle per subscription, rather than a fixed delivery deadline or total CPU limit. This detects persistent changes even when native notifications arrive late; unchanged scans emit nothing. Scans do not read file contents, follow symlinks or descend into child directories. ready waits for the initial scan; large directories or slow storage can delay readiness and later notifications. Closing a subscription waits for its active filesystem work to settle.