@intentic/sandbox-contract 1.126.0 → 1.133.0

package/src/contracts/codex.contract.ts

@@ -0,0 +1,23 @@
+import { oc } from "@orpc/contract";
+import {
+    AccountIdSchema,
+    CodexDevicePollSchema,
+    CodexDeviceStartSchema,
+    CodexPollResultSchema,
+    ModelsSchema,
+    OauthAccountListSchema,
+    OkSchema,
+} from "../schemas.js";
+
+// ChatGPT (Codex) OAuth — OpenAI's device-code flow. `start` requests a one-time code + verification URL; the
+// browser signs in and enters the code, while the UI polls `poll` (pending:true until sign-in completes, then
+// the created account). The sandbox owns the credential (Codex's native auth.json, one dir per account).
+// `accounts` lists the connected accounts; `disconnect` clears the one named by id.
+export const codexContract = {
+    start: oc.route({ method: "POST", path: "/codex/oauth/start" }).output(CodexDeviceStartSchema),
+    poll: oc.route({ method: "POST", path: "/codex/oauth/poll" }).input(CodexDevicePollSchema).output(CodexPollResultSchema),
+    // OpenAI/Codex's live models for the model picker — the source of valid ids (see codex-models.ts).
+    models: oc.route({ method: "GET", path: "/codex/models" }).output(ModelsSchema),
+    accounts: oc.route({ method: "GET", path: "/codex/accounts" }).output(OauthAccountListSchema),
+    disconnect: oc.route({ method: "POST", path: "/codex/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
+};

package/src/contracts/drafts.contract.ts

@@ -0,0 +1,11 @@
+import { oc } from "@orpc/contract";
+import { DraftIdParamSchema, DraftsListSchema, DraftSummarySchema, OkSchema } from "../schemas.js";
+
+// The sandbox's post-drafts queue (agent-proposed posts awaiting approval). The agent creates draft files
+// directly — these routes are the OWNER's side: `list` is the approval inbox, `upsert` covers approve / edit /
+// retry (all a plain re-post with a field changed, like the automations enabled toggle), `remove` is reject.
+export const draftsContract = {
+    list: oc.route({ method: "GET", path: "/drafts" }).output(DraftsListSchema),
+    upsert: oc.route({ method: "POST", path: "/drafts" }).input(DraftSummarySchema).output(OkSchema),
+    remove: oc.route({ method: "DELETE", path: "/drafts/{id}" }).input(DraftIdParamSchema).output(OkSchema),
+};

package/src/contracts/extensions.contract.ts

@@ -0,0 +1,28 @@
+import { oc } from "@orpc/contract";
+import {
+    CapabilityIdParamSchema,
+    ExtensionProcessParamSchema,
+    ExtensionProcessStatusSchema,
+    ExtensionSettingsInputSchema,
+    ExtensionSettingsSchema,
+    ExtensionsListSchema,
+    OkSchema,
+} from "../schemas.js";
+
+// Installed extensions resolved to their approved manifests — what the web extension host boots from. The
+// bundle itself is a plain Hono route (GET /extensions/{id}/bundle): raw ESM bytes are not an oRPC payload.
+// `settings`/`setSettings` carry the extension's own contributes.settings values; keys the manifest never
+// declared are refused, the same honesty rule the host applies to runtime view/command registrations.
+export const extensionsContract = {
+    list: oc.route({ method: "GET", path: "/extensions" }).output(ExtensionsListSchema),
+    settings: oc.route({ method: "GET", path: "/extensions/{id}/settings" }).input(CapabilityIdParamSchema).output(ExtensionSettingsSchema),
+    setSettings: oc.route({ method: "POST", path: "/extensions/{id}/settings" }).input(ExtensionSettingsInputSchema).output(OkSchema),
+    // Declared background processes (contributes.processes): tmux-managed through the panel machinery
+    // (session `panel-ext-<id>-<name>`, PORT-assigned, optional tunneled preview route).
+    processStatus: oc
+        .route({ method: "GET", path: "/extensions/{id}/processes/{name}" })
+        .input(ExtensionProcessParamSchema)
+        .output(ExtensionProcessStatusSchema),
+    processStart: oc.route({ method: "POST", path: "/extensions/{id}/processes/{name}/start" }).input(ExtensionProcessParamSchema).output(OkSchema),
+    processStop: oc.route({ method: "POST", path: "/extensions/{id}/processes/{name}/stop" }).input(ExtensionProcessParamSchema).output(OkSchema),
+};

package/src/contracts/git.contract.ts

@@ -0,0 +1,64 @@
+import { oc } from "@orpc/contract";
+import {
+    CommitResultSchema,
+    CommitSchema,
+    DiscardSchema,
+    FileDiffSchema,
+    GitActionResultSchema,
+    GitBranchCreateSchema,
+    GitChangesSchema,
+    GitCheckoutSchema,
+    GitCommitActionSchema,
+    GitCommitDiffQuerySchema,
+    GitCommitDiffSchema,
+    GitCommitFileDiffQuerySchema,
+    GitFileDiffQuerySchema,
+    GitFileQuerySchema,
+    GitFileSchema,
+    GitFilesSchema,
+    GitFileWriteSchema,
+    GitLogQuerySchema,
+    GitLogSchema,
+    GitReposSchema,
+    GitResetSchema,
+    GitStatusSchema,
+    GitTagCreateSchema,
+    OkSchema,
+    PushSchema,
+    RepoParamSchema,
+} from "../schemas.js";
+
+// Per-repo git ops over the workspace repos: "root" (the /work repo) plus every discovered repo under /work
+// ({repo} is the repo's root-relative dir, URL-encoded). An unknown {repo} is a handler-thrown
+// NOT_FOUND; a path that escapes the repo is a BAD_REQUEST. `changes` is the workspace-wide review set the
+// 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),
+    // 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).
+    repos: oc.route({ method: "GET", path: "/git/repos" }).output(GitReposSchema),
+    log: oc.route({ method: "GET", path: "/git/{repo}/log" }).input(GitLogQuerySchema).output(GitLogSchema),
+    commitDiff: oc.route({ method: "GET", path: "/git/{repo}/commit-diff" }).input(GitCommitDiffQuerySchema).output(GitCommitDiffSchema),
+    commitFileDiff: oc.route({ method: "GET", path: "/git/{repo}/commit-file-diff" }).input(GitCommitFileDiffQuerySchema).output(FileDiffSchema),
+    // 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.
+    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),
+    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),
+    drop: oc.route({ method: "POST", path: "/git/{repo}/drop" }).input(GitCommitActionSchema).output(GitActionResultSchema),
+    merge: oc.route({ method: "POST", path: "/git/{repo}/merge" }).input(GitCommitActionSchema).output(GitActionResultSchema),
+    rebase: oc.route({ method: "POST", path: "/git/{repo}/rebase" }).input(GitCommitActionSchema).output(GitActionResultSchema),
+    reset: oc.route({ method: "POST", path: "/git/{repo}/reset" }).input(GitResetSchema).output(GitActionResultSchema),
+    fileDiff: oc.route({ method: "GET", path: "/git/{repo}/file-diff" }).input(GitFileDiffQuerySchema).output(FileDiffSchema),
+    status: oc.route({ method: "GET", path: "/git/{repo}/status" }).input(RepoParamSchema).output(GitStatusSchema),
+    commit: oc.route({ method: "POST", path: "/git/{repo}/commit" }).input(CommitSchema).output(CommitResultSchema),
+    discard: oc.route({ method: "POST", path: "/git/{repo}/discard" }).input(DiscardSchema).output(OkSchema),
+    push: oc.route({ method: "POST", path: "/git/{repo}/push" }).input(PushSchema).output(OkSchema),
+    files: oc.route({ method: "GET", path: "/git/{repo}/files" }).input(RepoParamSchema).output(GitFilesSchema),
+    readFile: oc.route({ method: "GET", path: "/git/{repo}/file" }).input(GitFileQuerySchema).output(GitFileSchema),
+    writeFile: oc.route({ method: "PUT", path: "/git/{repo}/file" }).input(GitFileWriteSchema).output(OkSchema),
+};

package/src/contracts/grok.contract.ts

@@ -0,0 +1,16 @@
+import { oc } from "@orpc/contract";
+import { AccountIdSchema, DeviceStartSchema, ModelsSchema, 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
+// URL + instructions (which carry the one-time code the user enters at x.ai); OpenCode then polls to completion
+// — 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.
+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/history.contract.ts

@@ -0,0 +1,12 @@
+import { oc } from "@orpc/contract";
+import { FileDiffSchema, OkSchema, SnapshotDiffSchema, SnapshotFileDiffQuerySchema, SnapshotIdSchema, SnapshotsListSchema } from "../schemas.js";
+
+// Workspace history: daemon-owned snapshots of /work with diff + restore. `diff` compares a checkpoint against
+// the previous visible checkpoint (everything that happened since it, hidden interval captures included); an
+// unknown id is a handler-thrown NOT_FOUND.
+export const historyContract = {
+    list: oc.route({ method: "GET", path: "/history/snapshots" }).output(SnapshotsListSchema),
+    diff: oc.route({ method: "GET", path: "/history/diff" }).input(SnapshotIdSchema).output(SnapshotDiffSchema),
+    fileDiff: oc.route({ method: "GET", path: "/history/file-diff" }).input(SnapshotFileDiffQuerySchema).output(FileDiffSchema),
+    restore: oc.route({ method: "POST", path: "/history/restore" }).input(SnapshotIdSchema).output(OkSchema),
+};

package/src/contracts/intentic.contract.ts

@@ -0,0 +1,17 @@
+import { eventIterator, oc } from "@orpc/contract";
+import { IntenticLineSchema } from "../events.js";
+import { IntenticRunSchema, OkSchema } from "../schemas.js";
+
+// Run the in-sandbox intentic CLI (resolve/plan/apply/deployments/…) and stream its ndjson lines as they
+// arrive, so the UI sees live progress. A non-zero exit surfaces as a thrown error once the stream ends.
+export const intenticContract = {
+    run: oc.route({ method: "POST", path: "/intentic" }).input(IntenticRunSchema).output(eventIterator(IntenticLineSchema)),
+    // Launch the minutes-long apply → adopt reconcile as a one-shot tmux job (session panel-infra-apply) and
+    // return immediately — progress is followed by attaching the terminal, not by holding this request open.
+    apply: oc.route({ method: "POST", path: "/intentic/apply" }).output(OkSchema),
+    // Tail the running (or just-finished) apply's structured event stream — the same ndjson lines the tmux pane
+    // renders as text, persisted to a durable file so the UI shows per-resource progress that survives a page
+    // refresh. Replays from the run's {kind:"start"} then follows live, closing on {kind:"exit"}. GET, like
+    // /events, because it takes no input; reuses the loose IntenticLine shape so no new schema is needed.
+    applyEvents: oc.route({ method: "GET", path: "/intentic/apply/events" }).output(eventIterator(IntenticLineSchema)),
+};

package/src/contracts/inventory.contract.ts

@@ -0,0 +1,11 @@
+import { oc } from "@orpc/contract";
+import { AddInventoryInputSchema, InventoryListSchema, InventoryNameParamSchema } from "../schemas.js";
+
+// The i.have.* / i.want.service entries in deploy.config.ts's managed region. add/remove rewrite the region and
+// commit it (mirroring an agent edit) and return the full updated list so the UI re-renders from one response.
+// Deploy-target hosts self-register out-of-band via the daemon's plain /enroll route (connect-host script).
+export const inventoryContract = {
+    list: oc.route({ method: "GET", path: "/inventory" }).output(InventoryListSchema),
+    add: oc.route({ method: "POST", path: "/inventory" }).input(AddInventoryInputSchema).output(InventoryListSchema),
+    remove: oc.route({ method: "DELETE", path: "/inventory/{name}" }).input(InventoryNameParamSchema).output(InventoryListSchema),
+};

package/src/contracts/logs.contract.ts

@@ -0,0 +1,9 @@
+import { oc } from "@orpc/contract";
+import { LogReadQuerySchema, LogReadSchema, LogsListSchema } from "../schemas.js";
+
+// Daemon-owned debug logs (historyRoot/logs): terminal pipe-pane captures, intentic CLI run logs, daemon.log.
+// Read-only by design — the files are written by the daemon/tmux only, so the record stays trustworthy.
+export const logsContract = {
+    list: oc.route({ method: "GET", path: "/logs" }).output(LogsListSchema),
+    read: oc.route({ method: "GET", path: "/logs/file" }).input(LogReadQuerySchema).output(LogReadSchema),
+};

package/src/contracts/panels.contract.ts

@@ -0,0 +1,12 @@
+import { oc } from "@orpc/contract";
+import { OkSchema, PanelRepoParamSchema, PanelsListSchema } from "../schemas.js";
+
+// Per-repository dev servers + the content facts the web app's extensions detect on. `list` enumerates every
+// repo with its runtime status + facts; `start`/`stop` drive the repo's dev server. Their tmux sessions list
+// on the global GET /system/terminals (the web app's one terminal panel); the interactive I/O is the
+// /system/terminal WebSocket.
+export const panelsContract = {
+    list: oc.route({ method: "GET", path: "/panels" }).output(PanelsListSchema),
+    start: oc.route({ method: "POST", path: "/panels/{repo}/start" }).input(PanelRepoParamSchema).output(OkSchema),
+    stop: oc.route({ method: "POST", path: "/panels/{repo}/stop" }).input(PanelRepoParamSchema).output(OkSchema),
+};

package/src/contracts/ports.contract.ts

@@ -0,0 +1,11 @@
+import { oc } from "@orpc/contract";
+import { OkSchema, PortForwardResultSchema, PortParamSchema, PortsListSchema } from "../schemas.js";
+
+// Listening TCP ports in the sandbox + explicit forwarding through the preview proxy (see the ports section in
+// schemas.ts). `forward` is idempotent — re-forwarding a port returns its existing slot's URL; `unforward`
+// frees the slot immediately (the hostname keeps resolving, the proxy just stops mapping it).
+export const portsContract = {
+    list: oc.route({ method: "GET", path: "/ports" }).output(PortsListSchema),
+    forward: oc.route({ method: "POST", path: "/ports/forward" }).input(PortParamSchema).output(PortForwardResultSchema),
+    unforward: oc.route({ method: "POST", path: "/ports/unforward" }).input(PortParamSchema).output(OkSchema),
+};

package/src/contracts/secrets.contract.ts

@@ -0,0 +1,15 @@
+import { oc } from "@orpc/contract";
+import { OkSchema, SecretInventorySchema, SecretKeyParamSchema, SecretKeysSchema, SecretRevealSchema, SecretSetSchema } from "../schemas.js";
+
+// User-supplied env-var secrets, written to the sandbox's gitignored desired-state/.env (which
+// `apply` reloads each run — no restart). `set` upserts one KEY=value, `remove` deletes it; `list` returns the
+// keys present. `inventory` aggregates every secret store into one view (keys + status + provenance, never
+// values). `reveal` is the single value-returning route — owner-only, POST so the key never sits in a URL.
+// set/remove/list/reveal refuse until DevOps has scaffolded the desired-state repo; inventory always answers.
+export const secretsContract = {
+    set: oc.route({ method: "POST", path: "/secrets" }).input(SecretSetSchema).output(OkSchema),
+    list: oc.route({ method: "GET", path: "/secrets" }).output(SecretKeysSchema),
+    remove: oc.route({ method: "DELETE", path: "/secrets/{key}" }).input(SecretKeyParamSchema).output(OkSchema),
+    inventory: oc.route({ method: "GET", path: "/secrets/inventory" }).output(SecretInventorySchema),
+    reveal: oc.route({ method: "POST", path: "/secrets/reveal" }).input(SecretKeyParamSchema).output(SecretRevealSchema),
+};

package/src/contracts/sessions.contract.ts

@@ -0,0 +1,14 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { SessionIdParamSchema, SessionsListSchema, SessionTranscriptSchema } from "../schemas.js";
+
+// Past conversations in this workspace (the SDK-native session store, keyed on the workspace dir). `list`
+// returns summaries for the history menu (filtered by `query` when the search box is used); `get` restores one
+// transcript for display.
+export const sessionsContract = {
+    list: oc
+        .route({ method: "GET", path: "/sessions" })
+        .input(z.object({ query: z.string().optional() }))
+        .output(SessionsListSchema),
+    get: oc.route({ method: "GET", path: "/sessions/{id}" }).input(SessionIdParamSchema).output(SessionTranscriptSchema),
+};

package/src/contracts/settings.contract.ts

@@ -0,0 +1,11 @@
+import { oc } from "@orpc/contract";
+import { CleanerSavingsSchema, OkSchema, SandboxSettingsSchema } from "../schemas.js";
+
+// Per-sandbox agent settings (.intentic/settings.json). `get` returns the current flags with defaults applied
+// when the file is absent; `set` overwrites them. `savings` reports the output-cleaner token savings aggregated
+// from the live filter-stats ledger (the rtk-`gain` surface — read-only, so a UI card can show what's working).
+export const settingsContract = {
+    get: oc.route({ method: "GET", path: "/settings" }).output(SandboxSettingsSchema),
+    set: oc.route({ method: "POST", path: "/settings" }).input(SandboxSettingsSchema).output(OkSchema),
+    savings: oc.route({ method: "GET", path: "/settings/savings" }).output(CleanerSavingsSchema),
+};

package/src/contracts/system.contract.ts

@@ -0,0 +1,37 @@
+import { eventIterator, oc } from "@orpc/contract";
+import { z } from "zod";
+import { SystemEventSchema } from "../events.js";
+import {
+    HostTunnelInputSchema,
+    HostTunnelSchema,
+    InfoSchema,
+    OkSchema,
+    PresenceReportSchema,
+    TerminalNameParamSchema,
+    TerminalsListSchema,
+    UsageSummarySchema,
+} from "../schemas.js";
+
+// Sandbox status + identity, the long-lived liveness stream, and the connect-token-relayed host tunnel.
+// `events` interleaves heartbeat frames (browser holds it open to detect the sandbox dying instantly) with
+// workspaceChanged batches (live file tree/viewer refresh) and presence roster snapshots until the request
+// aborts. `clientId` is the tab's per-connection presence key; absent (an older web client) means the
+// connection simply never joins the roster.
+export const systemContract = {
+    info: oc.route({ method: "GET", path: "/info" }).output(InfoSchema),
+    events: oc
+        .route({ method: "GET", path: "/events" })
+        .input(z.object({ clientId: z.string().optional() }))
+        .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
+    // per name on load/reload); `killTerminal` destroys one when its tab's close button is clicked. The live I/O
+    // is the separate /system/terminal WebSocket — these are just the control plane. Bearer-authed like the rest
+    // (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),
+};

package/src/contracts/translator.contract.ts

@@ -0,0 +1,20 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { DeviceStartSchema, KeyedProviderSchema, OkSchema, TranslatorAccountsSchema } from "../schemas.js";
+
+// Routed-provider subscriptions (Sandbox ▸ Agent). The bundled translator (CLIProxyAPI) runs a non-Claude model
+// UNDER the Claude Code harness on the user's SUBSCRIPTION, so each provider connects via a device-code OAuth
+// login (no API key). `accounts` reports which subscriptions are connected; `connect` starts a device login and
+// returns the verification URL + one-time code (the translator polls to completion in the background, so the UI
+// polls `accounts` until connected — there is no paste-back); `disconnect` clears a provider's tokens.
+export const translatorContract = {
+    accounts: oc.route({ method: "GET", path: "/translator/accounts" }).output(TranslatorAccountsSchema),
+    connect: oc
+        .route({ method: "POST", path: "/translator/{provider}/connect" })
+        .input(z.object({ provider: KeyedProviderSchema }))
+        .output(DeviceStartSchema),
+    disconnect: oc
+        .route({ method: "POST", path: "/translator/{provider}/disconnect" })
+        .input(z.object({ provider: KeyedProviderSchema }))
+        .output(OkSchema),
+};

package/src/contracts/workspace.contract.ts

@@ -0,0 +1,74 @@
+import { oc } from "@orpc/contract";
+import {
+    AddAppsSchema,
+    AppParamSchema,
+    AppsListSchema,
+    CloneRepoSchema,
+    CloneResultSchema,
+    WorkspaceSearchResultSchema,
+    WorkspaceSearchQuerySchema,
+    OkSchema,
+    RepoAppsParamSchema,
+    ReposListSchema,
+    RunTestsSchema,
+    TemplatesListSchema,
+    WorkspaceChildrenQuerySchema,
+    WorkspaceChildrenSchema,
+    WorkspaceClassificationSchema,
+    WorkspaceDirSchema,
+    WorkspaceFileQuerySchema,
+    WorkspaceFileSchema,
+    WorkspaceGraphSchema,
+    WorkspaceMoveSchema,
+    WorkspaceSyncSchema,
+    WorkspaceTreeSchema,
+} from "../schemas.js";
+
+// The full /work view + extra-repo cloning. The binary preview (/workspace/raw) is intentionally NOT here — it
+// 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),
+    // 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),
+    file: oc.route({ method: "GET", path: "/workspace/file" }).input(WorkspaceFileQuerySchema).output(WorkspaceFileSchema),
+    // Ranked groups, match-reason tags, freshness, resumable cursor. `mode` narrows to one verb; default is
+    // auto-mode fusion. (Implementation detail: the daemon backs this with a resident in-process iq engine.)
+    search: oc.route({ method: "GET", path: "/workspace/search" }).input(WorkspaceSearchQuerySchema).output(WorkspaceSearchResultSchema),
+    // Deterministic, no-LLM classification of the dropped workspace into coarse buckets (repositories / documents
+    // / media / archives / other). Read-only proposal: the browser renders it and applies accepted moves via the
+    // existing /workspace/move route — this route never touches the tree.
+    classify: oc.route({ method: "GET", path: "/workspace/classify" }).output(WorkspaceClassificationSchema),
+    // Direct file management the browser drives against the /work tree (byte writes go through POST
+    // /workspace/upload). oRPC's OpenAPI codec reads non-GET input from the JSON body, so delete sends {path}
+    // in the body too (not the query) — same as the POST routes.
+    mkdir: oc.route({ method: "POST", path: "/workspace/dir" }).input(WorkspaceDirSchema).output(OkSchema),
+    delete: oc.route({ method: "DELETE", path: "/workspace/entry" }).input(WorkspaceFileQuerySchema).output(OkSchema),
+    move: oc.route({ method: "POST", path: "/workspace/move" }).input(WorkspaceMoveSchema).output(OkSchema),
+    copy: oc.route({ method: "POST", path: "/workspace/copy" }).input(WorkspaceMoveSchema).output(OkSchema),
+    repos: oc.route({ method: "GET", path: "/workspace/repos" }).output(ReposListSchema),
+    addRepo: oc.route({ method: "POST", path: "/workspace/repos" }).input(CloneRepoSchema).output(CloneResultSchema),
+    // Force-fetch + guarded fast-forward every repo with a remote (mutates the tree ⇒ POST). The turn hook syncs
+    // automatically each turn; this is the on-demand refresh (and how you re-sync a dirty/diverged repo after committing).
+    sync: oc.route({ method: "POST", path: "/workspace/sync" }).output(WorkspaceSyncSchema),
+    // The addable app types the configured source repo offers (its templates.json) — drives the apps
+    // extension's Add-app picker.
+    templates: oc.route({ method: "GET", path: "/workspace/templates" }).output(TemplatesListSchema),
+    // Per-monorepo apps, driven by the web app's apps extension (owner-authed; {repo} is validated in the
+    // handler): add one or more apps into an existing monorepo, list them with per-app preview URL + status,
+    // and start/stop each app's preview dev server. `addApps` kicks off a one-shot tmux job (session
+    // panel-<repo>--add_apps) that runs `intentic add-app` — the attachable terminal is the progress/error
+    // surface; the extension polls the session's `running` for completion. It returns immediately (an ack).
+    addApps: oc.route({ method: "POST", path: "/workspace/repos/{repo}/apps" }).input(AddAppsSchema).output(OkSchema),
+    appsList: oc.route({ method: "GET", path: "/workspace/repos/{repo}/apps" }).input(RepoAppsParamSchema).output(AppsListSchema),
+    // The monorepo's workspace package dependency graph (pnpm-workspace.yaml globs + per-package package.json
+    // workspace deps) — drives the apps extension's Dependencies view.
+    packageGraph: oc.route({ method: "GET", path: "/workspace/repos/{repo}/graph" }).input(RepoAppsParamSchema).output(WorkspaceGraphSchema),
+    startApp: oc.route({ method: "POST", path: "/workspace/repos/{repo}/apps/{app}/start" }).input(AppParamSchema).output(OkSchema),
+    stopApp: oc.route({ method: "POST", path: "/workspace/repos/{repo}/apps/{app}/stop" }).input(AppParamSchema).output(OkSchema),
+    // Run vitest for the given repo-relative project dirs in a one-shot tmux panel session
+    // (panel-<repo>--<session>) — drives the apps extension's per-app / per-package / library Run-tests actions.
+    // Mirrors addApps: it returns an ack; the attachable terminal is the result surface.
+    runTests: oc.route({ method: "POST", path: "/workspace/repos/{repo}/tests" }).input(RunTestsSchema).output(OkSchema),
+};

package/src/effects.test.ts

@@ -0,0 +1,132 @@
+import type { ConnectorContribution, ExtensionManifest } from "@intentic/extension-api";
+import { describe, expect, it } from "vitest";
+import { capabilityEffects } from "./effects.js";
+import { CapabilityKindSchema } from "./schemas.js";
+
+const connector = (overrides?: Partial<ConnectorContribution>): ConnectorContribution => ({
+    provider: "github",
+    kind: "cli",
+    catalog: { name: "GitHub", description: "Issues and PRs.", category: "code" },
+    fields: [{ key: "token", label: "Token", secret: true }],
+    env: { GITHUB_TOKEN: "${token}" },
+    skill: "skills/github/SKILL.md",
+    ...overrides,
+});
+
+const manifest = (contributes: ExtensionManifest["contributes"]): ExtensionManifest => ({
+    publisher: "acme",
+    name: "tools",
+    version: "1.0.0",
+    engines: { intentic: "^0.2.0" },
+    contributes,
+});
+
+describe("capabilityEffects", () => {
+    // Pins the CapabilityKind union to the deriver: a 13th kind must declare its effects to pass.
+    it("yields at least one effect for every kind", () => {
+        for (const kind of CapabilityKindSchema.options) {
+            expect(capabilityEffects({ kind, config: {} }).length).toBeGreaterThan(0);
+        }
+    });
+
+    it("interpolates the plugin clone url and token from form state and from the echo", () => {
+        expect(capabilityEffects({ kind: "plugin", config: {} })).toEqual([{ kind: "clone", url: undefined }]);
+        expect(capabilityEffects({ kind: "plugin", config: { url: "https://github.com/o/p", token: "t" } })).toEqual([
+            { kind: "clone", url: "https://github.com/o/p" },
+            { kind: "secret", exposure: "disk" },
+        ]);
+        expect(capabilityEffects({ kind: "plugin", config: { url: "https://github.com/o/p", hasToken: true } })).toContainEqual({
+            kind: "secret",
+            exposure: "disk",
+        });
+    });
+
+    it("stores an mcp token only when one is present", () => {
+        expect(capabilityEffects({ kind: "mcp", config: { url: "https://mcp.example.com" } })).toEqual([{ kind: "mcp" }]);
+        expect(capabilityEffects({ kind: "mcp", config: { url: "https://mcp.example.com", token: "t" } })).toContainEqual({
+            kind: "secret",
+            exposure: "disk",
+        });
+    });
+
+    it("always stores an ssh credential on disk, for both auth modes", () => {
+        for (const auth of ["key", "password"]) {
+            expect(capabilityEffects({ kind: "ssh", config: { auth } })).toEqual([
+                { kind: "secret", exposure: "disk" },
+                { kind: "skill", name: "ssh" },
+            ]);
+        }
+    });
+
+    it("scaffolds the monorepo under the instance name", () => {
+        expect(capabilityEffects({ kind: "monorepo", id: "shop", config: {} })).toEqual([{ kind: "scaffold", repos: ["shop"] }]);
+        expect(capabilityEffects({ kind: "monorepo", config: {} })).toEqual([{ kind: "scaffold", repos: [] }]);
+    });
+
+    it("derives cli secret and image from the connector spec", () => {
+        const github = capabilityEffects({ kind: "cli", id: "github", config: { provider: "github" }, connector: connector() });
+        expect(github).toEqual([
+            { kind: "skill", name: "github" },
+            { kind: "secret", exposure: "agent-env" },
+        ]);
+        const postgres = capabilityEffects({
+            kind: "cli",
+            id: "db",
+            config: { provider: "postgres" },
+            connector: connector({ provider: "postgres", fragment: "env/postgres.Dockerfile" }),
+        });
+        expect(postgres).toContainEqual({ kind: "image" });
+        // Discord's whisper fragment is connector spec data like any other — the image effect derives from it.
+        const discord = capabilityEffects({
+            kind: "cli",
+            id: "discord",
+            config: { provider: "discord" },
+            connector: connector({ provider: "discord", fragment: "env/whisper.Dockerfile" }),
+        });
+        expect(discord).toContainEqual({ kind: "image" });
+    });
+
+    it("falls back to the echoed hasSecret when no connector spec is at hand", () => {
+        expect(capabilityEffects({ kind: "cli", id: "github", config: { provider: "github", hasSecret: true } })).toContainEqual({
+            kind: "secret",
+            exposure: "agent-env",
+        });
+        expect(capabilityEffects({ kind: "cli", id: "github", config: { provider: "github" } })).toEqual([{ kind: "skill", name: "github" }]);
+    });
+
+    it("derives extension process and image effects from the installed manifest", () => {
+        const bare = capabilityEffects({ kind: "extension", config: { url: "https://github.com/o/e" } });
+        expect(bare).toEqual([{ kind: "trusted-code" }, { kind: "clone", url: "https://github.com/o/e" }]);
+        const full = capabilityEffects({
+            kind: "extension",
+            config: { url: "https://github.com/o/e", hasToken: true },
+            manifest: manifest({
+                processes: [{ name: "gateway", command: "node gateway.js" }],
+                environment: { fragment: "env/tools.Dockerfile" },
+            }),
+        });
+        expect(full).toContainEqual({ kind: "secret", exposure: "disk" });
+        expect(full).toContainEqual({ kind: "image" });
+        expect(full).toContainEqual({ kind: "process", names: ["gateway"] });
+    });
+
+    it("marks vpn as a privileged-runtime image change", () => {
+        expect(capabilityEffects({ kind: "vpn", config: {} })).toContainEqual({ kind: "runtime", level: "net-admin" });
+    });
+
+    it("marks docker as a fully privileged runtime rebuild running dockerd", () => {
+        expect(capabilityEffects({ kind: "docker", config: {} })).toEqual([
+            { kind: "image" },
+            { kind: "runtime", level: "privileged" },
+            { kind: "process", names: ["dockerd"] },
+        ]);
+    });
+
+    it("keeps a browser profile per platform", () => {
+        expect(capabilityEffects({ kind: "browser", id: "reddit", config: { platform: "reddit" } })).toEqual([
+            { kind: "skill", name: "reddit" },
+            { kind: "image" },
+            { kind: "profile", platform: "reddit" },
+        ]);
+    });
+});