@intentic/sandbox-contract 1.176.3 → 1.209.0

package/src/contracts/git.contract.ts

@@ -1,7 +1,5 @@
 import { oc } from "@orpc/contract";
 import {
-    CommitMessageDraftSchema,
-    CommitMessageSchema,
     CommitResultSchema,
     CommitSchema,
     DiscardSchema,
@@ -24,15 +22,25 @@ import {
     GitFileWriteSchema,
     GitLogQuerySchema,
     GitLogSchema,
+    GitOperationStateSchema,
+    GitUndoSchema,
+    GitUndoStateSchema,
     GitRemoteStateSchema,
     GitReposSchema,
     GitResetSchema,
     GitStageSchema,
     GitStatusSchema,
     GitTagCreateSchema,
+    GitTagDeleteSchema,
+    GitTagPushSchema,
     OkSchema,
     PushSchema,
     RepoParamSchema,
+    StashApplySchema,
+    StashDiffQuerySchema,
+    StashListSchema,
+    StashPushSchema,
+    StashRefParamSchema,
 } from "../schemas.js";
 
 // Per-repo git ops over the workspace repos: "root" (the /work repo) plus every discovered repo under /work
@@ -41,10 +49,6 @@ import {
 // Changes panel renders; commit/discard take optional `paths` for per-file actions.
 export const gitContract = {
     changes: oc.route({ method: "GET", path: "/git/changes" }).output(GitChangesSchema),
-    // Drafts a commit message for what the commit box is about to record, on the sandbox's quick model (the
-    // cheap rung — see quick-model.ts). Workspace-wide like `changes` and for the same reason: one commit box,
-    // one message, every staged repo. POST because it spends a model call, not because it writes anything.
-    commitMessage: oc.route({ method: "POST", path: "/git/commit-message" }).input(CommitMessageDraftSchema).output(CommitMessageSchema),
     // The git-history graph over one repo's real commits: the repo list (for the tree affordance + switcher),
     // one repo's commit log, and lazy per-commit detail (changed files, then a file's before/after AT the
     // commit). Read-only — commit/discard on the working tree stay the write path (above).
@@ -55,8 +59,31 @@ export const gitContract = {
     // Write actions from the graph's commit context menu (VSCode "Git Graph" parity). Non-destructive refs
     // (branch/tag) return Ok and let git's errors propagate; the sequence + HEAD-moving ops return a
     // GitActionResult so a conflict/clean-apply failure is a value, not a 500. Read routes above.
+    /* The halted-operation pair. `operation` is a READ every git surface can use to explain a worktree it cannot
+     * otherwise act on; `abort` is the single way out, and it is git's own `--abort` rather than anything
+     * clever. Neither is reachable from the daemon's own verbs — those abort themselves — so this exists purely
+     * for what a terminal left behind. */
+    operation: oc.route({ method: "GET", path: "/git/{repo}/operation" }).input(RepoParamSchema).output(GitOperationStateSchema),
+    abort: oc.route({ method: "POST", path: "/git/{repo}/abort" }).input(RepoParamSchema).output(GitActionResultSchema),
+    /* Walk the current branch back to where it was before its last action, off the branch's own reflog. The
+     * complement to the Checkpoints timeline, not a duplicate of it: a checkpoint restores the working tree,
+     * this moves the ref. The read carries `previousSha`, which the write sends back as a concurrency token —
+     * an undo prepared against a stale view is refused rather than landing somewhere unlooked-at. */
+    undoable: oc.route({ method: "GET", path: "/git/{repo}/undo" }).input(RepoParamSchema).output(GitUndoStateSchema),
+    undo: oc.route({ method: "POST", path: "/git/{repo}/undo" }).input(GitUndoSchema).output(GitActionResultSchema),
+    /* The stash. Read as a list plus a per-entry diff, mirroring the commit log and commit-diff pair above,
+     * because a stash entry is a commit and the graph renders it as one. The writes are git's own four verbs;
+     * only `drop` is unrecoverable, and the route checkpoints before it. */
+    stashes: oc.route({ method: "GET", path: "/git/{repo}/stashes" }).input(RepoParamSchema).output(StashListSchema),
+    stashDiff: oc.route({ method: "GET", path: "/git/{repo}/stash-diff" }).input(StashDiffQuerySchema).output(GitCommitDiffSchema),
+    stashPush: oc.route({ method: "POST", path: "/git/{repo}/stash" }).input(StashPushSchema).output(GitActionResultSchema),
+    stashApply: oc.route({ method: "POST", path: "/git/{repo}/stash/apply" }).input(StashApplySchema).output(GitActionResultSchema),
+    stashDrop: oc.route({ method: "POST", path: "/git/{repo}/stash/drop" }).input(StashRefParamSchema).output(OkSchema),
     createBranch: oc.route({ method: "POST", path: "/git/{repo}/branch" }).input(GitBranchCreateSchema).output(OkSchema),
     createTag: oc.route({ method: "POST", path: "/git/{repo}/tag" }).input(GitTagCreateSchema).output(OkSchema),
+    // The other two things one does with a tag, so the graph's tag pills are not a create-only affordance.
+    deleteTag: oc.route({ method: "POST", path: "/git/{repo}/tag/delete" }).input(GitTagDeleteSchema).output(OkSchema),
+    pushTag: oc.route({ method: "POST", path: "/git/{repo}/tag/push" }).input(GitTagPushSchema).output(GitActionResultSchema),
     checkout: oc.route({ method: "POST", path: "/git/{repo}/checkout" }).input(GitCheckoutSchema).output(GitActionResultSchema),
     cherryPick: oc.route({ method: "POST", path: "/git/{repo}/cherry-pick" }).input(GitCommitActionSchema).output(GitActionResultSchema),
     revert: oc.route({ method: "POST", path: "/git/{repo}/revert" }).input(GitCommitActionSchema).output(GitActionResultSchema),

package/src/contracts/grok.contract.ts

@@ -1,5 +1,5 @@
 import { oc } from "@orpc/contract";
-import { AccountIdSchema, DeviceStartSchema, ModelsSchema, OauthAccountListSchema, OkSchema } from "../schemas.js";
+import { AccountIdSchema, DeviceStartSchema, OauthAccountListSchema, OkSchema } from "../schemas.js";
 
 // xAI Grok (via OpenCode) uses subscription OAuth — the sandbox owns the credential (OpenCode persists the
 // tokens and refreshes them). `start` authorizes xAI's headless device-code method and returns the verification
@@ -7,10 +7,11 @@ import { AccountIdSchema, DeviceStartSchema, ModelsSchema, OauthAccountListSchem
 // — there is no paste-back — and the UI polls `accounts` until connected. `disconnect` clears the tokens.
 // ponytail: OpenCode holds one xAI auth per data dir, so `accounts` is 0 or 1 — the list shape matches the
 // other providers without paying for per-account OpenCode servers yet.
+//
+// Like Claude's, this contract is now the account handshake alone — the model catalog answers on the shared
+// /providers/{provider}/models route (providers.contract.ts).
 export const grokContract = {
     start: oc.route({ method: "POST", path: "/grok/oauth/start" }).output(DeviceStartSchema),
-    // xAI's live models (via OpenCode) for the model picker — the source of truth for valid model ids.
-    models: oc.route({ method: "GET", path: "/grok/models" }).output(ModelsSchema),
     accounts: oc.route({ method: "GET", path: "/grok/accounts" }).output(OauthAccountListSchema),
     disconnect: oc.route({ method: "POST", path: "/grok/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
 };

package/src/contracts/host.contract.ts

@@ -1,6 +1,6 @@
-import { oc } from "@orpc/contract";
+import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
-import { HostFactsSchema, HostScopesSchema, OkSchema } from "../schemas.js";
+import { HostFactsSchema, HostScopesSchema, MachineFlowLineSchema, MachineSandboxFlowSchema, OkSchema } from "../schemas.js";
 
 /* What a connected computer can be ASKED, over the socket it opened to this sandbox.
  *
@@ -30,4 +30,15 @@ export const hostContract = {
     ping: oc.output(OkSchema),
     // One MCP JSON-RPC message in, its answer out — forwarded verbatim in both directions. See above.
     mcp: oc.input(z.unknown()).output(z.unknown()),
+    /* One operation on one of this machine's sandboxes, narrated as it happens.
+     *
+     * TYPED, unlike `mcp`, and the difference is who is on the other end. `mcp`'s reader is a model, which has
+     * nothing to do with a line as it arrives and everything to gain from the machine learning tools without a
+     * daemon release. This reader is a PERSON watching a progress log: an update pulls an image and recreates a
+     * container, which is minutes of silence unless the lines travel while they are produced. A stream is what
+     * the browser needs, and a stream is the one thing an MCP tool result cannot be.
+     *
+     * The scope is still checked here, on the machine, by the same functions the MCP tools call — this adds a
+     * way of WATCHING an operation, never a way of skipping the switch that permits it. */
+    runSandboxFlow: oc.input(MachineSandboxFlowSchema).output(eventIterator(MachineFlowLineSchema)),
 };

package/src/contracts/loops.contract.ts

@@ -0,0 +1,62 @@
+import { oc } from "@orpc/contract";
+import {
+    LoopDesignIdParamSchema,
+    LoopDesignSaveSchema,
+    LoopDesignSchema,
+    LoopDesignsListSchema,
+    LoopIdParamSchema,
+    LoopRecordSchema,
+    LoopSchema,
+    LoopsListSchema,
+    OkSchema,
+} from "../schemas.js";
+
+/* The loop routes — "run this conversation again until the goal is met".
+ *
+ * TWO HALVES THAT LOOK LIKE ONE FEATURE AND ARE NOT, which is why they share a file and share nothing else.
+ *
+ * A RUNNING LOOP has no editor. It is started against a conversation, it converges or it gives up, and then it
+ * is history: `start`, `stop`, and a `list` of what has run. No upsert, no enabled toggle, no id of its own —
+ * the conversation IS the id.
+ *
+ * A SAVED LOOP is a manifest entry like a workflow, and gets the manifest treatment: list, save, remove. It is
+ * the loop's MACHINERY without its goal (LoopDesignSchema says why at length), so it is authored once and
+ * pointed at a different job every time. It has no `run` route of its own on purpose — running one is `start`
+ * with the design's fields and the composer's sentence, so there is exactly one way a loop begins and exactly
+ * one place that can refuse it.
+ *
+ * `start` acks immediately with the loop as recorded and runs detached, the same contract POST /agent keeps: the
+ * first iteration alone can take minutes, and every surface that would render progress is already attached to
+ * the conversation. What comes back is the record, not an outcome — the outcome arrives on the fleet card.
+ */
+export const loopsContract = {
+    // Every loop this workspace has run, newest first — the record is kept after the loop ends, because "why did
+    // it stop at iteration 4" is the question a loop is read for, and the answer is its iteration history.
+    list: oc.route({ method: "GET", path: "/loops" }).output(LoopsListSchema),
+    /* Start looping a conversation. Rejects when that conversation is already looping — a second loop on one
+     * agent would have two pumps racing the same worktree and the same turn mutex, and the loser would spend a
+     * turn to discover it.
+     *
+     * The conversation need not exist yet: a loop against a fresh id opens it, exactly as a first chat turn
+     * does, which is what lets "run this until it's green" be the FIRST thing said to a new agent. */
+    start: oc.route({ method: "POST", path: "/loops" }).input(LoopSchema).output(LoopRecordSchema),
+    /* Stop the loop, leaving the turn in flight alone.
+     *
+     * The split is deliberate and it is the one thing about this route that has to be right: stopping a LOOP
+     * means "do not start another iteration", not "kill what is running". A user watching iteration 6 do good
+     * work should be able to say "this is the last one" without throwing that work away. Killing the turn is
+     * what /agent/stop is for, and pressing both is the ordinary way to abandon a loop outright. */
+    stop: oc.route({ method: "POST", path: "/loops/{conversationId}/stop" }).input(LoopIdParamSchema).output(OkSchema),
+
+    // Every saved loop. A literal path segment under /loops rather than a surface of its own, because a saved
+    // loop is not a different feature — it is the same loop with its goal left blank until somebody types one.
+    designs: oc.route({ method: "GET", path: "/loops/designs" }).output(LoopDesignsListSchema),
+    /* Create or replace a saved loop, with the operation explicit so a name collision cannot turn a create into
+     * a replacement. Refuses a design that could never finish — nothing to produce and nothing to check — with
+     * the same sentence `start` refuses an ad-hoc loop for, because it is the same mistake made earlier and
+     * catching it at save time is the whole advantage of saving. */
+    saveDesign: oc.route({ method: "POST", path: "/loops/designs" }).input(LoopDesignSaveSchema).output(LoopDesignSchema),
+    // Deleting a saved loop does NOT stop a loop running from it: a running loop copied the fields it needed
+    // when it started, so it converges or gives up on its own terms, and its record stays readable.
+    removeDesign: oc.route({ method: "DELETE", path: "/loops/designs/{id}" }).input(LoopDesignIdParamSchema).output(OkSchema),
+};

package/src/contracts/personas.contract.ts

@@ -0,0 +1,56 @@
+import { oc } from "@orpc/contract";
+import {
+    OkSchema,
+    PersonaIdParamSchema,
+    PersonaKitSchema,
+    PersonaPromptSchema,
+    PersonaSchema,
+    PersonasListSchema,
+    PersonaSkillBodySchema,
+    PersonaSkillNameSchema,
+    PersonaSkillSchema,
+} from "../schemas.js";
+
+/* The sandbox's named personas (PersonaSchema): which connected accounts each one speaks for, what a session
+ * wearing it may do, where it works, and what it is told. The card half is a plain three-verb CRUD with no apply
+ * step, because a card provisions NOTHING — unlike a capability, saving one connects nothing, installs nothing
+ * and spends nothing. It records a decision about accounts that already exist.
+ *
+ * The file behind it is committed workspace config (personas/personas-store.ts), so these routes are one of
+ * two equally supported ways to edit them: this, and opening the file in the editor like any other project
+ * config. Neither is the "real" one — which is why `save` is a whole-card upsert rather than a field patch, so
+ * a round trip through the UI leaves a diff a reviewer would recognise.
+ *
+ * THE KIT ROUTES BELOW EDIT FILES, not the card, and they are here rather than on the skills contract because
+ * what they write belongs to one persona: its prompt, and the skills only its turns can reach
+ * (personas/persona-kit.ts). The sandbox's `skills` domain answers "what does the agent know" for every chat;
+ * this answers "what does this card carry", and the two lists are different questions with different answers.
+ *
+ * Per-verb routes rather than one whole-kit PUT: a kit is a directory of files somebody edits one at a time, and
+ * a save that shipped the whole folder would make an edit to one skill capable of deleting another. */
+export const personasContract = {
+    list: oc.route({ method: "GET", path: "/personas" }).output(PersonasListSchema),
+    // Upsert by id — re-saving the same id edits that card.
+    save: oc.route({ method: "POST", path: "/personas" }).input(PersonaSchema).output(OkSchema),
+    /* Removing a card takes away a persona, never an account: the login it named stays connected and reachable from
+     * every other surface. What it CAN do is orphan a reference — an automation pinned to this id now names a
+     * card that no longer exists — and the resolver reads that as "no accounts at all" rather than "all of
+     * them", so the automation goes quiet instead of posting as somebody unintended. */
+    /* Removing a card takes away a persona, never an account: the login it named stays connected and reachable from
+     * every other surface. It DOES take the card's kit with it — a folder no card can reach is a folder no list
+     * shows, and leaving the owner's prompt and skills orphaned on disk is worse than deleting what they just
+     * asked to delete. */
+    remove: oc.route({ method: "DELETE", path: "/personas/{id}" }).input(PersonaIdParamSchema).output(OkSchema),
+
+    // ---- the kit: what this card is told, and the skills only it reaches ----
+
+    kit: oc.route({ method: "GET", path: "/personas/{id}/kit" }).input(PersonaIdParamSchema).output(PersonaKitSchema),
+    // An empty prompt DELETES the file rather than storing a blank one, so "custom with nothing written" is one
+    // state instead of two — the resolver falls back to the sandbox's prompt for it (personas.ts personaPrompt).
+    savePrompt: oc.route({ method: "POST", path: "/personas/{id}/prompt" }).input(PersonaPromptSchema).output(OkSchema),
+    readSkill: oc.route({ method: "GET", path: "/personas/{id}/skills/read" }).input(PersonaSkillNameSchema).output(PersonaSkillBodySchema),
+    // Upsert by name, like the sandbox's own skills — and with no enabled list to write, because a kit skill is
+    // on exactly when its persona is worn. That is what "specific to that persona" has to mean.
+    saveSkill: oc.route({ method: "POST", path: "/personas/{id}/skills" }).input(PersonaSkillSchema).output(OkSchema),
+    removeSkill: oc.route({ method: "POST", path: "/personas/{id}/skills/remove" }).input(PersonaSkillNameSchema).output(OkSchema),
+};

package/src/contracts/prepush.contract.ts

@@ -6,9 +6,10 @@ import { OkSchema, PrepushRunSchema } from "../schemas.js";
 // main working tree, of which there is exactly one, so nothing here is addressed by id.
 //
 // `run` starts the check and returns immediately — a suite takes minutes, and an oRPC call held open for one
-// would die on the first proxy timeout with the work still going. The dialog that started it polls `state`,
-// which carries the live output tail while `status` is `running`. `cancel` kills the child's whole process
-// group; the run settles as `cancelled` and the push it was gating does not go.
+// would die on the first proxy timeout with the work still going. The dialog that started it polls `state` for
+// the verdict, and opens the terminals panel on the `session` the first answer names: the suite runs in a real
+// tmux window, so watching it is the terminal's job. `cancel` kills that window; the run settles as `cancelled`
+// and the push it was gating does not go.
 export const prepushContract = {
     state: oc.route({ method: "GET", path: "/prepush/state" }).output(PrepushRunSchema),
     run: oc.route({ method: "POST", path: "/prepush/run" }).output(OkSchema),

package/src/contracts/providers.contract.ts

@@ -0,0 +1,23 @@
+import { oc } from "@orpc/contract";
+import { ModelsSchema, NativeProviderParamSchema } from "../schemas.js";
+
+// EVERY NATIVE PROVIDER'S PICKER CATALOG, ON ONE ROUTE.
+//
+// There were five of these — /claude/models, /codex/models, /grok/models, /kimi/models, /gemini/models — one per
+// provider, each a contract entry, a route factory and a service field wired separately. They differed in
+// nothing: same method, same output schema, same "the daemon's catalog for this provider, never empty". Three of
+// the five route files were the same fifteen lines with a name swapped, and the daemon paid for that shape twice
+// more in the branch chains that had to fan back out over the providers to ask them all the same question.
+//
+// So the provider is a PARAMETER, not five routes. Adding one is a row in the daemon's catalog registry — the
+// same discipline the adapter registry already applies to serving a turn — rather than a vertical slice through
+// the contract, the router, the service container and every test double.
+//
+// Endpoints keep their own route (endpoints.contract.ts) and should: they are user-created and unbounded, their
+// id names a capability that may not exist, and a missing one is a NOT_FOUND rather than an empty catalog. That
+// is a different question with a different failure, not a sixth provider.
+export const providersContract = {
+    // One provider's models (+ its default id), never empty — live discovery with a persisted/seed floor behind
+    // it. Order is the provider's own preference order and is not re-ranked here; see ModelsSchema.
+    models: oc.route({ method: "GET", path: "/providers/{provider}/models" }).input(NativeProviderParamSchema).output(ModelsSchema),
+};

package/src/contracts/public.contract.ts

@@ -0,0 +1,14 @@
+import { oc } from "@orpc/contract";
+import { OkSchema, PublicListSchema, PublishResultSchema, PublishSchema, UnpublishSchema } from "../schemas.js";
+
+// The workspace outbox — what `public/` currently holds and its address (see the public section in schemas.ts).
+// `publish` copies a workspace file or directory in, creating the outbox if this is the first one; `unpublish`
+// withdraws one and removes the outbox behind the last, so the directory's presence always means exactly "there
+// is something published". There is no route to READ a published file: that is the whole point of the
+// unauthenticated `public-<slot>` hostname, and a second, authenticated way in would just be the workspace file
+// API with extra steps.
+export const publicContract = {
+    list: oc.route({ method: "GET", path: "/public" }).output(PublicListSchema),
+    publish: oc.route({ method: "POST", path: "/public/publish" }).input(PublishSchema).output(PublishResultSchema),
+    unpublish: oc.route({ method: "POST", path: "/public/unpublish" }).input(UnpublishSchema).output(OkSchema),
+};

package/src/contracts/sessions.contract.ts

@@ -7,10 +7,14 @@ import { SessionIdParamSchema, SessionsListSchema } from "../schemas.js";
 // repo covers its linked worktrees too, so an isolated conversation's transcript is reachable from the
 // workspace root). `list` returns summaries for the history menu (filtered by `query` when the search box is
 // used); `get` restores one transcript for display.
+//
+// `caseSensitive` is the filter's Aa switch, on the same terms as the fleet search's — off means the letters do
+// not matter, and the two routes answer one query together (the board lists these rows under its own cards), so
+// a switch either of them ignored would show as one field returning two different match sets.
 export const sessionsContract = {
     list: oc
         .route({ method: "GET", path: "/sessions" })
-        .input(z.object({ query: z.string().optional() }))
+        .input(z.object({ query: z.string().optional(), caseSensitive: z.stringbool().optional() }))
         .output(SessionsListSchema),
     get: oc.route({ method: "GET", path: "/sessions/{id}" }).input(SessionIdParamSchema).output(SessionTranscriptSchema),
 };

package/src/contracts/settings.contract.ts

@@ -4,6 +4,7 @@ import {
     BuiltinPromptTextSchema,
     DayWindowQuerySchema,
     OkSchema,
+    RuleFiringsSchema,
     SandboxSettingsSchema,
     SavingsReportSchema,
 } from "../schemas.js";
@@ -20,4 +21,8 @@ export const settingsContract = {
     set: oc.route({ method: "POST", path: "/settings" }).input(SandboxSettingsSchema).output(OkSchema),
     savings: oc.route({ method: "GET", path: "/settings/savings" }).input(DayWindowQuerySchema).output(SavingsReportSchema),
     builtinPrompt: oc.route({ method: "GET", path: "/settings/system-prompt/{base}" }).input(BuiltinPromptSchema).output(BuiltinPromptTextSchema),
+    // When each rule last did something, keyed by rule id. Its own route rather than a field on the settings
+    // object because a firing is not an edit: folding it in would make every push a settings write, and would
+    // put a value that changes on its own inside the object the screen optimistically patches.
+    firings: oc.route({ method: "GET", path: "/settings/rule-firings" }).output(RuleFiringsSchema),
 };

package/src/contracts/share.contract.ts

@@ -0,0 +1,20 @@
+import { oc } from "@orpc/contract";
+import { OkSchema, ShareCreateSchema, ShareListSchema, ShareRemoveSchema, ShareUpdateSchema, SharedConversationSchema } from "../schemas.js";
+
+/* Conversations published as read-only pages (see the share section in schemas.ts).
+ *
+ * Its own group rather than two more routes on `public`, because the two speak different path spaces and mean
+ * different things by "publish". The outbox's routes take a path in the workspace and copy the bytes at it; a
+ * share takes a CONVERSATION ID and renders something that did not exist as a file until it was asked for.
+ * Folding them together would have `publish` accept two unrelated kinds of input distinguished by a flag.
+ *
+ * There is no route to read a share back. The page is the read — it answers on the unauthenticated
+ * `public-<slot>` hostname like every other published file, which is the point of having made one. */
+export const shareContract = {
+    list: oc.route({ method: "GET", path: "/share" }).output(ShareListSchema),
+    // Answers with the row it just wrote, link included, so the dialog can show the address without re-listing.
+    create: oc.route({ method: "POST", path: "/share" }).input(ShareCreateSchema).output(SharedConversationSchema),
+    // Re-render an existing share from the conversation as it stands now. Same id, same link, new snapshot.
+    update: oc.route({ method: "POST", path: "/share/update" }).input(ShareUpdateSchema).output(SharedConversationSchema),
+    remove: oc.route({ method: "POST", path: "/share/remove" }).input(ShareRemoveSchema).output(OkSchema),
+};

package/src/contracts/skills.contract.ts

@@ -0,0 +1,24 @@
+import { oc } from "@orpc/contract";
+import { OkSchema, SkillBodySchema, SkillDraftSchema, SkillIdSchema, SkillRemoveSchema, SkillsListSchema } from "../schemas.js";
+
+/* WHAT THE AGENT KNOWS RIGHT NOW, and which half of it the owner controls.
+ *
+ * Its own domain rather than three more routes on `settings`, because only one of the four sources it reads is
+ * the settings file: the rest are the owner's own skill store, the plugin checkouts a capability cloned, and the
+ * skills folders inside installed extensions. `list` is the join of all four (skill-inventory.ts).
+ *
+ * The ENABLED half still rides the settings object's `skills` array — that array is what the reconciler
+ * converges and what the boot path already reads, so a switch on this list is an ordinary settings write and
+ * there is exactly one place that decides which skills exist on disk. `save` and `remove` write the text AND
+ * that array together, which is why they are here rather than being two calls a screen has to sequence.
+ *
+ * `read` is a GET with the id in the query rather than in the path: an id can name an owner
+ * (`extension:intentic.knowledge:knowledge`), and a path template cannot carry those segments. */
+export const skillsContract = {
+    list: oc.route({ method: "GET", path: "/skills" }).output(SkillsListSchema),
+    read: oc.route({ method: "GET", path: "/skills/read" }).input(SkillIdSchema).output(SkillBodySchema),
+    // Upsert by name: saving over an existing skill rewrites it, which is also how one is renamed (the old name
+    // is a different skill and is deleted on its own). A saved skill is switched ON — you wrote it to use it.
+    save: oc.route({ method: "POST", path: "/skills" }).input(SkillDraftSchema).output(OkSchema),
+    remove: oc.route({ method: "POST", path: "/skills/remove" }).input(SkillRemoveSchema).output(OkSchema),
+};

package/src/contracts/system.contract.ts

@@ -5,14 +5,17 @@ import {
     BrowserNameParamSchema,
     BrowsersListSchema,
     DaemonSessionSchema,
-    HostTunnelInputSchema,
-    HostTunnelSchema,
     InfoSchema,
+    ManifestProblemsSchema,
+    MachineFlowLineSchema,
+    MachineSandboxFlowInputSchema,
     OkSchema,
     PresenceReportSchema,
     SubagentIdParamSchema,
     SubagentsListSchema,
     TerminalNameParamSchema,
+    TerminalScrollbackQuerySchema,
+    TerminalScrollbackSchema,
     TerminalsListSchema,
     UsageSummarySchema,
 } from "../schemas.js";
@@ -24,6 +27,10 @@ import {
 // connection simply never joins the roster.
 export const systemContract = {
     info: oc.route({ method: "GET", path: "/info" }).output(InfoSchema),
+    // What the daemon could not read in its own `.intentic/` manifests — a file it fell back on, a key it did
+    // not recognise, an entry it skipped. Its own route rather than a field on /info because it is invalidated
+    // by a different thing: a manifest changing on disk, which the workspace-state table already broadcasts.
+    manifestProblems: oc.route({ method: "GET", path: "/system/manifest-problems" }).output(ManifestProblemsSchema),
     // Exchange the request's verified bearer (a Google ID token — or a still-valid session, which makes this
     // route sliding renewal) for a daemon-minted session, the credential every steady-state call presents.
     session: oc.route({ method: "POST", path: "/system/session" }).output(DaemonSessionSchema),
@@ -33,7 +40,6 @@ export const systemContract = {
         .output(eventIterator(SystemEventSchema)),
     // A tab's activity self-report (view/session/file/idle), fanned back out to every member on /events.
     presence: oc.route({ method: "POST", path: "/system/presence" }).input(PresenceReportSchema).output(OkSchema),
-    hostTunnel: oc.route({ method: "POST", path: "/system/host-tunnel" }).input(HostTunnelInputSchema).output(HostTunnelSchema),
     // Per-account token/cost totals, aggregated from the activity log's turn.completed events.
     usage: oc.route({ method: "GET", path: "/system/usage" }).output(UsageSummarySchema),
     // The web-owned tmux sessions behind the terminal tabs. `terminals` enumerates them (the panel rebuilds a tab
@@ -42,6 +48,13 @@ export const systemContract = {
     // (browser fetch sends the header), unlike the header-less WS route which app.ts exempts.
     terminals: oc.route({ method: "GET", path: "/system/terminals" }).output(TerminalsListSchema),
     killTerminal: oc.route({ method: "DELETE", path: "/system/terminals/{name}" }).input(TerminalNameParamSchema).output(OkSchema),
+    // One session's pane history as selectable text — the answer to "scroll back and copy that" in a surface
+    // whose live view is a tmux client on the alternate screen, where the scrollback is on the far side of the
+    // socket and the page has nothing to select. See TerminalScrollbackSchema.
+    terminalScrollback: oc
+        .route({ method: "GET", path: "/system/terminals/{name}/scrollback" })
+        .input(TerminalScrollbackQuerySchema)
+        .output(TerminalScrollbackSchema),
     // The agent's live Chromiums and the pages each has open — the Browsers view's roster, polled while it is on
     // screen and by the rail so its tile can appear the moment a turn starts browsing. The frames are the
     // separate /system/browser-view WebSocket; this is the control plane, exactly as `terminals` is for tmux.
@@ -61,4 +74,15 @@ export const systemContract = {
         .route({ method: "GET", path: "/system/subagents/{id}/transcript" })
         .input(SubagentIdParamSchema)
         .output(SessionTranscriptSchema),
+    /* Start, stop, restart, update, rebuild, roll back or remove a sandbox on one of the user's own computers —
+     * the Computers view's buttons, relayed to the machine over the socket it holds open to us.
+     *
+     * Streamed because the slowest of these takes minutes, and it is the same stream whatever the op: one door
+     * for one decision, so the view has one shape to render rather than one per duration. The daemon adds no
+     * judgement — the machine enforces its own switches and its refusal arrives as the terminal `error` line,
+     * in its own words, naming the control to flip. */
+    manageMachineSandbox: oc
+        .route({ method: "POST", path: "/system/computers/{id}/sandboxes/{slug}" })
+        .input(MachineSandboxFlowInputSchema)
+        .output(eventIterator(MachineFlowLineSchema)),
 };

package/src/contracts/workflows.contract.ts

@@ -0,0 +1,78 @@
+import { oc } from "@orpc/contract";
+import {
+    OkSchema,
+    WorkflowIdParamSchema,
+    WorkflowRunIdParamSchema,
+    WorkflowRunSchema,
+    WorkflowRunsListSchema,
+    WorkflowRunStartSchema,
+    WorkflowSaveSchema,
+    WorkflowSchema,
+    WorkflowsListSchema,
+} from "../schemas.js";
+
+/* The workflow routes — "run these sessions, in this order, each handing its result to the next".
+ *
+ * SPLIT LIKE AUTOMATIONS, NOT LIKE LOOPS, and the split says what a workflow is. A loop has no editor because
+ * it is started against a conversation and then it is history; a workflow is a DESIGN — a thing the user
+ * authors once, keeps, edits, and runs repeatedly — so it gets the manifest treatment: create/update, delete,
+ * list. What it does not get is an `enabled` toggle, because nothing fires it on its own: a workflow runs when
+ * somebody (or an automation's prompt) says run it.
+ *
+ * `run` acks with the run as recorded and executes detached, the contract every turn-starting route here
+ * keeps. The first step alone can take minutes and the run may take hours; the run view is where it is watched,
+ * and the fleet board shows its steps as the ordinary agents they are.
+ */
+export const workflowsContract = {
+    // Every saved workflow with its run history, newest run first. One route rather than two because the list
+    // page shows both and a workflow with no runs is the interesting case, not an error.
+    list: oc.route({ method: "GET", path: "/workflows" }).output(WorkflowsListSchema),
+    /* Create or replace a workflow, with the operation made explicit so an accidental id collision cannot turn
+     * a create into replacement. Refuses a graph that cannot run — a cycle, a `needs` naming a step
+     * that is not there, a step with no way to know it is finished — with the same sentences the designer shows
+     * while you type (see workflowFaults). Validation lives in the contract precisely so those two can never
+     * disagree about what is legal. */
+    save: oc.route({ method: "POST", path: "/workflows" }).input(WorkflowSaveSchema).output(WorkflowSchema),
+    // Deleting a workflow does NOT stop a run of it that is in flight, and does not delete its history: the run
+    // snapshotted its definition when it started, so it stays readable and stays stoppable.
+    remove: oc.route({ method: "DELETE", path: "/workflows/{id}" }).input(WorkflowIdParamSchema).output(OkSchema),
+    /* Start a run, optionally pointed at a request — the sentence the user typed in the composer, which every
+     * step is handed on top of its own prompt. Every step is recorded `pending` up front, so the graph is
+     * complete from the first frame and a missing node never has to mean two things. Several runs of one
+     * workflow may be in flight at once — they derive different conversation ids, so nothing is shared and
+     * nothing can collide, which is what makes "run this design again on a different question" free. */
+    run: oc.route({ method: "POST", path: "/workflows/{id}/run" }).input(WorkflowRunStartSchema).output(WorkflowRunSchema),
+    // Every run across every workflow, newest first — the history the run view opens onto, and the only place a
+    // deleted workflow's runs are still reachable.
+    runs: oc.route({ method: "GET", path: "/workflows/runs" }).output(WorkflowRunsListSchema),
+    /* Stop a run: nothing that has not started will start, and the steps in flight are CUT OFF where they
+     * are — their turns aborted exactly as /agent/stop aborts one, so whatever they had written stays on
+     * their branches and the step settles as stopped.
+     *
+     * Not the graceful "finish the iteration you are on" a LOOP's stop performs, and the difference is the
+     * unit: a loop's iteration is a round somebody is watching, a workflow step's is an entire agent turn.
+     * Waiting for one meant a stopped run kept working, kept spending and kept asking questions for minutes
+     * after the press, which is indistinguishable from a button that does nothing.
+     *
+     * IT ALWAYS ENDS THE RUN, including one no scheduler is behind — a record left `running` by a daemon that
+     * was replaced mid-flight. That case used to be refused, which made the stuck run permanent: a Stop that
+     * could not work, a step count that would never move, and no way off the board.
+     */
+    stopRun: oc.route({ method: "POST", path: "/workflows/runs/{runId}/stop" }).input(WorkflowRunIdParamSchema).output(OkSchema),
+    /* Take an ENDED run off the board — the run's half of `agents.archive`, and the same bargain: nothing is
+     * lost, the checkouts are reclaimed, and `unarchiveRun` puts it all back. It needs an exit of its own
+     * because nothing about a run transitions once it is over, so a failed one would sit in Attention until
+     * fifty more had rolled it off the ledger. Refused while the run is going.
+     *
+     * IT ARCHIVES THE STEPS WITH THE RUN, which is what makes it an archive rather than a dismissal. A step
+     * has no card of its own — the run's row stands for it — so merely dropping the record released the run's
+     * conversations onto the board as loose cards at the exact moment the user said they were done with the
+     * job. Every step that ran is archived, on the same terms as pointing `agents.archive` at those ids: that
+     * route archives what the user named without re-litigating whether each one was ready to go, and a run the
+     * user has archived is exactly that gesture made once for the whole graph.
+     */
+    archiveRun: oc.route({ method: "POST", path: "/workflows/runs/{runId}/archive" }).input(WorkflowRunIdParamSchema).output(OkSchema),
+    // Put an archived run and its sessions back on the board, the inverse of the above and the run's half of
+    // `agents.unarchive`.
+    unarchiveRun: oc.route({ method: "POST", path: "/workflows/runs/{runId}/unarchive" }).input(WorkflowRunIdParamSchema).output(OkSchema),
+};

package/src/contracts/workspace.contract.ts

@@ -24,11 +24,13 @@ import {
     WorkspaceHealthSchema,
     WorkspaceInstallResultSchema,
     WorkspaceInstallSchema,
+    WorkspaceMediaTicketQuerySchema,
     WorkspaceMediaTicketSchema,
     WorkspaceModulesSchema,
     WorkspaceMoveSchema,
     WorkspaceResolveQuerySchema,
     WorkspaceResolveSchema,
+    WorkspaceScopeSchema,
     WorkspaceSetupSchema,
     WorkspaceSyncSchema,
     WorkspaceTreeSchema,
@@ -38,7 +40,10 @@ import {
 // stays a plain Hono route serving raw bytes with a Content-Type header (oRPC's request/response shape doesn't
 // fit a streamed binary body). External MCP tools moved to the unified capabilities manifest (mcp kind).
 export const workspaceContract = {
-    tree: oc.route({ method: "GET", path: "/workspace/tree" }).output(WorkspaceTreeSchema),
+    // `agent` names whose copy of the workspace to read (WorkspaceScopeSchema); omitted is the shared /work
+    // tree. Every read route below takes it, so a link into a conversation's own checkout browses as one tree
+    // rather than as one openable file surrounded by the shared one.
+    tree: oc.route({ method: "GET", path: "/workspace/tree" }).input(WorkspaceScopeSchema).output(WorkspaceTreeSchema),
     // Lazy-load one directory's children — the tree returns ignored dirs (node_modules, .git, …) without children,
     // and the client fetches them here on expand so a giant node_modules can't blow the tree walk's entry budget.
     children: oc.route({ method: "GET", path: "/workspace/children" }).input(WorkspaceChildrenQuerySchema).output(WorkspaceChildrenSchema),
@@ -49,7 +54,10 @@ export const workspaceContract = {
      * it answers a streamed byte RANGE, which oRPC has no shape for). Minting is here rather than beside it so
      * it rides the bearer middleware and the contract's route advertisement: a browser can tell whether the
      * sandbox in front of it can stream video at all, instead of learning it from a 404 mid-playback. */
-    mediaTicket: oc.route({ method: "POST", path: "/workspace/media-ticket" }).input(WorkspaceFileQuerySchema).output(WorkspaceMediaTicketSchema),
+    mediaTicket: oc
+        .route({ method: "POST", path: "/workspace/media-ticket" })
+        .input(WorkspaceMediaTicketQuerySchema)
+        .output(WorkspaceMediaTicketSchema),
     // Which file a NAMED reference means — the lookup behind every clickable path in the UI. A path an agent
     // wrote in prose is often only a suffix of the real one, so it is matched against the workspace tree rather
     // than trusted as root-relative.

package/src/conversation-ids.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "vitest";
+import { newConversationId } from "./conversation-ids.js";
+import { ConversationIdSchema } from "./schemas.js";
+
+// The one property that is not a matter of taste: this string becomes a git branch and a filesystem path, and
+// the id guard is what stands between those and an injection. Held over a large sample rather than one draw,
+// because the generator picks from three independent spaces and any of them could produce the bad character.
+test("every generated id passes the conversation-id guard", () => {
+    for (let index = 0; index < 2_000; index += 1) {
+        expect(ConversationIdSchema.safeParse(newConversationId()).success).toBe(true);
+    }
+});
+
+test("an id reads as a word pair with a short tail, and stays short", () => {
+    const id = newConversationId();
+    expect(id).toMatch(/^[a-z]+-[a-z]+-[0-9a-z]{4}$/);
+    // Comfortably under a UUID's 36, which is the whole reason this exists.
+    expect(id.length).toBeLessThan(24);
+});
+
+// The tail is what makes the readable half safe to repeat: names may rhyme, ids may not.
+test("ids are unique across a burst", () => {
+    const ids = new Set(Array.from({ length: 5_000 }, newConversationId));
+    expect(ids.size).toBe(5_000);
+});