@intentic/sandbox-contract 1.307.0 → 1.308.2

package/src/contracts/skills.contract.ts

@@ -1,4 +1,4 @@
-import { oc } from "@orpc/contract";
+import { procedure } from "../protocol/route-meta.js";
 import { SkillBodySchema, SkillDraftSchema, SkillIdSchema, SkillRemoveSchema, SkillsListSchema, SkillSwitchSchema } from "../schemas/settings.js";
 import { OkSchema } from "../schemas/shared.js";
 
@@ -8,7 +8,7 @@ import { OkSchema } from "../schemas/shared.js";
 // together with the text. `read` takes the id in the query, since an id can name an owner and won't fit a path
 // template.
 export const skillsContract = {
-    list: oc
+    list: procedure
         .route({
             method: "GET",
             path: "/skills",
@@ -17,7 +17,7 @@ export const skillsContract = {
                 "Every skill available here and whether it is switched on, joined from all the places they come from: the owner's own, the settings, plugins a connection installed, folders inside extensions, and persona kits.",
         })
         .output(SkillsListSchema),
-    read: oc
+    read: procedure
         .route({
             method: "GET",
             path: "/skills/read",
@@ -29,7 +29,7 @@ export const skillsContract = {
         .output(SkillBodySchema),
     // Upsert by name; renaming saves under a new name and deletes the old. A new skill starts on; rewriting keeps its
     // switch as it was.
-    save: oc
+    save: procedure
         .route({
             method: "POST",
             path: "/skills",
@@ -39,7 +39,7 @@ export const skillsContract = {
         })
         .input(SkillDraftSchema)
         .output(OkSchema),
-    switch: oc
+    switch: procedure
         .route({
             method: "POST",
             path: "/skills/switch",
@@ -49,7 +49,7 @@ export const skillsContract = {
         })
         .input(SkillSwitchSchema)
         .output(OkSchema),
-    remove: oc
+    remove: procedure
         .route({
             method: "POST",
             path: "/skills/remove",

package/src/contracts/system.contract.ts

@@ -1,4 +1,4 @@
-import { oc } from "@orpc/contract";
+import { procedure } from "../protocol/route-meta.js";
 import { streamOf } from "../protocol/routes.js";
 import { z } from "zod";
 import { SessionTranscriptSchema } from "../events/transcript.js";
@@ -27,11 +27,14 @@ import {
 } from "../schemas/terminal.js";
 import { UsageSummarySchema } from "../schemas/providers/usage.js";
 
+// The box itself (terminals, devices, sessions, spend), which no control token reaches whatever the floor.
+const systemRoute = procedure.meta({ control: "never" });
+
 // Sandbox status/identity, the long-lived liveness stream, and the connect-token-relayed host tunnel. `events`
 // interleaves heartbeats, workspaceChanged batches and presence snapshots until the request aborts. `clientId` is this
 // tab's presence key; omitting it means never joining the roster.
 export const systemContract = {
-    info: oc
+    info: procedure
         .route({
             method: "GET",
             path: "/info",
@@ -39,9 +42,10 @@ export const systemContract = {
             description:
                 "The sandbox's own identity and state: which workspace it holds, which image it runs, what it is called, and the list of calls it actually implements. Start here, because a browser is routinely newer than the sandbox it is talking to and this is how it finds out what is there.",
         })
+        .meta({ guest: true })
         .output(InfoSchema),
     // Own route, not a field on /info: it goes stale on a manifest changing on disk, not on identity changing.
-    manifestProblems: oc
+    manifestProblems: systemRoute
         .route({
             method: "GET",
             path: "/system/manifest-problems",
@@ -51,7 +55,7 @@ export const systemContract = {
         })
         .output(ManifestProblemsSchema),
     // Removes or renames only a key, never a value; writes queue through the owning store, not racing a live save.
-    repairManifest: oc
+    repairManifest: systemRoute
         .route({
             method: "POST",
             path: "/system/manifest-problems/repair",
@@ -62,7 +66,7 @@ export const systemContract = {
         .input(ManifestRepairSchema)
         .output(OkSchema),
     // Trades a verified bearer or unexpired session for a fresh daemon session; calling it again renews it.
-    session: oc
+    session: systemRoute
         .route({
             method: "POST",
             path: "/system/session",
@@ -70,8 +74,10 @@ export const systemContract = {
             description:
                 "Exchanges a verified sign-in, or a session that has not expired yet, for a fresh session the daemon minted. That session is the credential every other call carries, and calling this again with a live one renews it.",
         })
+        // Staying signed in and on the roster is identity, not power, and needs nothing the boot chain builds.
+        .meta({ beforeBoot: true, floor: "viewer", guest: true })
         .output(DaemonSessionSchema),
-    events: oc
+    events: procedure
         .route({
             method: "GET",
             path: "/events",
@@ -79,10 +85,11 @@ export const systemContract = {
             description:
                 "A stream held open for as long as you want it, carrying heartbeats so a caller notices the sandbox dying at once, batches of file changes so a tree or an editor can refresh itself, and the roster of who else is looking. Give it an id for this connection to appear in that roster; leave it out and you watch without being seen.",
         })
+        .meta({ beforeBoot: true, stream: true, guest: true })
         .input(z.object({ clientId: z.string().optional() }))
         .output(streamOf(SystemEventSchema)),
     // A tab's activity self-report (view/session/file/idle), fanned back out to every member on /events.
-    presence: oc
+    presence: systemRoute
         .route({
             method: "POST",
             path: "/system/presence",
@@ -90,19 +97,22 @@ export const systemContract = {
             description:
                 "Reports which view, conversation or file this connection is on, or that it has gone idle. The daemon fans it back out on the event stream so everyone else's roster updates.",
         })
+        .meta({ beforeBoot: true, floor: "viewer", guest: true })
         .input(PresenceReportSchema)
         .output(OkSchema),
     // Per-account token/cost totals, aggregated from the activity log's turn.completed events.
-    usage: oc
+    usage: systemRoute
         .route({
             method: "GET",
             path: "/system/usage",
             summary: "What has been spent",
             description: "Token and cost totals per account, added up from the record of every finished turn.",
         })
+        // Spend is the operator's reading, not the audience's.
+        .meta({ floor: "maintainer" })
         .output(UsageSummarySchema),
     // Measured per request and never in the background: a sandbox nobody is asking pays nothing for this route.
-    metrics: oc
+    metrics: systemRoute
         .route({
             method: "GET",
             path: "/system/metrics",
@@ -112,7 +122,7 @@ export const systemContract = {
         })
         .output(SandboxMetricsSchema),
     // Control plane only; live I/O is /system/terminal WebSocket, exempt from the Bearer auth these routes take.
-    terminals: oc
+    terminals: systemRoute
         .route({
             method: "GET",
             path: "/system/terminals",
@@ -120,8 +130,10 @@ export const systemContract = {
             description:
                 "The terminal sessions this sandbox is holding, which is what a terminal panel rebuilds its tabs from after a reload. The live typing and output run over a separate socket; this is the list.",
         })
+        // Lists tmux and the supervisor, neither built by the boot chain, for a surface on screen meanwhile.
+        .meta({ beforeBoot: true })
         .output(TerminalsListSchema),
-    killTerminal: oc
+    killTerminal: systemRoute
         .route({
             method: "DELETE",
             path: "/system/terminals/{name}",
@@ -131,7 +143,7 @@ export const systemContract = {
         .input(TerminalNameParamSchema)
         .output(OkSchema),
     // Scrollback as selectable text; the live view is a tmux alternate screen, with nothing in the page to select.
-    terminalScrollback: oc
+    terminalScrollback: systemRoute
         .route({
             method: "GET",
             path: "/system/terminals/{name}/scrollback",
@@ -142,7 +154,7 @@ export const systemContract = {
         .input(TerminalScrollbackQuerySchema)
         .output(TerminalScrollbackSchema),
     // Control plane like `terminals`; frames stream separately. `closeBrowser` fails the next call as crashed.
-    browsers: oc
+    browsers: systemRoute
         .route({
             method: "GET",
             path: "/system/browsers",
@@ -151,7 +163,7 @@ export const systemContract = {
                 "Every browser a conversation currently has running and the pages inside each one. The picture of what they are showing comes over a separate socket; this is the roster.",
         })
         .output(BrowsersListSchema),
-    closeBrowser: oc
+    closeBrowser: systemRoute
         .route({
             method: "DELETE",
             path: "/system/browsers/{name}",
@@ -162,7 +174,7 @@ export const systemContract = {
         .input(BrowserNameParamSchema)
         .output(OkSchema),
     // SDK subagents and delegated runs alike; watched via transcript, not a socket, live then from stored history.
-    subagents: oc
+    subagents: systemRoute
         .route({
             method: "GET",
             path: "/system/subagents",
@@ -171,7 +183,7 @@ export const systemContract = {
                 "Every subagent and child agent this sandbox's conversations have delegated work to, whichever tool started it, with what each one is doing.",
         })
         .output(SubagentsListSchema),
-    subagentTranscript: oc
+    subagentTranscript: systemRoute
         .route({
             method: "GET",
             path: "/system/subagents/{id}/transcript",
@@ -184,7 +196,7 @@ export const systemContract = {
     // On the contract, not a hand-written route beside it: this payload is what every "do it out there" button is
     // gated on, so its shape has to be fingerprinted like any other, or a daemon older than the app disagrees about
     // it silently and the buttons just stop being drawn.
-    devices: oc
+    devices: systemRoute
         .route({
             method: "GET",
             path: "/system/devices",
@@ -194,7 +206,7 @@ export const systemContract = {
         })
         .output(DevicesListSchema),
     // One stream for every op; the daemon adds no judgment, a refusal is the machine's own `error` line.
-    manageDeviceSandbox: oc
+    manageDeviceSandbox: systemRoute
         .route({
             method: "POST",
             path: "/system/devices/{id}/sandboxes/{slug}",
@@ -205,7 +217,7 @@ export const systemContract = {
         .input(DeviceSandboxFlowInputSchema)
         .output(streamOf(DeviceFlowLineSchema)),
     // Closed set of actions; the daemon builds the command line, not the caller. One sentence is the whole answer.
-    runDeviceCommand: oc
+    runDeviceCommand: systemRoute
         .route({
             method: "POST",
             path: "/system/devices/{id}/commands/{command}",
@@ -216,7 +228,7 @@ export const systemContract = {
         .input(DeviceCommandInputSchema)
         .output(DeviceCommandResultSchema),
     // The stream usually ends without a frame; a bare stop means success, the device's version confirms it later.
-    runDeviceAgentFlow: oc
+    runDeviceAgentFlow: systemRoute
         .route({
             method: "POST",
             path: "/system/devices/{id}/agent/{op}",

package/src/contracts/translator.contract.ts

@@ -1,4 +1,4 @@
-import { oc } from "@orpc/contract";
+import { procedure } from "../protocol/route-meta.js";
 import { z } from "zod";
 import { TranslatorAccountsSchema } from "../schemas/providers/plan-limits.js";
 import { TranslatorCompleteSchema, TranslatorStartSchema, TranslatorStatusSchema } from "../schemas/providers/provider-oauth.js";
@@ -15,7 +15,7 @@ import { OkSchema } from "../schemas/shared.js";
 // URL this sandbox can't receive, so `complete` hands the landing URL to the translator. `connect.flow` tells the
 // card which mechanic it received without inferring it from whether an optional device code happened to exist.
 export const translatorContract = {
-    accounts: oc
+    accounts: procedure
         .route({
             method: "GET",
             path: "/translator/accounts",
@@ -24,7 +24,7 @@ export const translatorContract = {
                 "What is signed in per provider. Each provider can hold several accounts at once, and the translator spreads work across them.",
         })
         .output(TranslatorAccountsSchema),
-    connect: oc
+    connect: procedure
         .route({
             method: "POST",
             path: "/translator/{provider}/connect",
@@ -34,7 +34,7 @@ export const translatorContract = {
         })
         .input(z.object({ provider: KeyedProviderSchema }))
         .output(TranslatorStartSchema),
-    status: oc
+    status: procedure
         .route({
             method: "GET",
             path: "/translator/{provider}/connect",
@@ -44,7 +44,7 @@ export const translatorContract = {
         })
         .input(z.object({ provider: KeyedProviderSchema, state: z.string().min(1) }))
         .output(TranslatorStatusSchema),
-    complete: oc
+    complete: procedure
         .route({
             method: "POST",
             path: "/translator/{provider}/complete",
@@ -54,7 +54,7 @@ export const translatorContract = {
         })
         .input(TranslatorCompleteSchema)
         .output(OkSchema),
-    disconnect: oc
+    disconnect: procedure
         .route({
             method: "POST",
             path: "/translator/{provider}/disconnect",

package/src/contracts/usage.contract.ts

@@ -1,4 +1,4 @@
-import { oc } from "@orpc/contract";
+import { procedure } from "../protocol/route-meta.js";
 import { z } from "zod";
 import { LimitResetClaimSchema, LimitResetStatusSchema } from "../schemas/providers/plan-limits.js";
 import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas/providers/usage.js";
@@ -28,7 +28,7 @@ export type PlanLimitsHeld = PlanLimitsRefreshed["held"][number];
 // Durable spend ledger, read-only over the wire; rows are appended daemon-side at turn end.
 // `rollup` groups by day, provider, account and model, so every cost panel re-projects from this one answer.
 export const usageContract = {
-    rollup: oc
+    rollup: procedure
         .route({
             method: "GET",
             path: "/usage/rollup",
@@ -39,7 +39,7 @@ export const usageContract = {
         .input(DayWindowQuerySchema)
         .output(UsageRollupSchema),
     // Re-measures every account's plan limits on request; readings also arrive via /events and account lists otherwise.
-    refreshPlanLimits: oc
+    refreshPlanLimits: procedure
         .route({
             method: "POST",
             path: "/usage/plan-limits/refresh",
@@ -52,7 +52,7 @@ export const usageContract = {
     // Asked, not polled: the provider only evaluates this when told the account is at the wall, and the answer isn't
     // cached.
     // Answers `available: false` rather than failing when the account has no such mechanism.
-    limitReset: oc
+    limitReset: procedure
         .route({
             method: "GET",
             path: "/usage/limit-reset/{account}",
@@ -62,7 +62,7 @@ export const usageContract = {
         })
         .input(z.object({ account: z.string().min(1).describe("Which account.") }))
         .output(LimitResetStatusSchema),
-    claimLimitReset: oc
+    claimLimitReset: procedure
         .route({
             method: "POST",
             path: "/usage/limit-reset/{account}/claim",

package/src/contracts/vpn.contract.ts

@@ -1,16 +1,19 @@
-import { oc } from "@orpc/contract";
+import { procedure } from "../protocol/route-meta.js";
 import { streamOf } from "../protocol/routes.js";
 import { IntenticLineSchema } from "../events/system-events.js";
 import { OkSchema } from "../schemas/shared.js";
 import { ForticlientImportInputSchema, ForticlientImportSchema, VpnConnectInputSchema, VpnIdParamSchema, VpnListSchema } from "../schemas/vpn.js";
 
+// The agent's `vpn` CLI dials and drops these on the agent token; a control token never reaches them.
+const vpnRoute = procedure.meta({ agent: true, control: "never" });
+
 // A VPN is added as a `vpn` capability; connecting and dropping it happen through the routes here, called by both the
 // operator UI and the agent's `vpn` CLI.
 // Every route reads tunnel state from the OS, not daemon memory, so a shell-dropped tunnel and a UI-dropped one are the
 // same event across a restart.
 export const vpnContract = {
     // Every configured VPN with its live link state; feeds the VPN card, rail indicator, and `vpn list`.
-    list: oc
+    list: vpnRoute
         .route({
             method: "GET",
             path: "/vpn",
@@ -20,7 +23,7 @@ export const vpnContract = {
         })
         .output(VpnListSchema),
     // Dials a stored VPN, streaming auth and routing progress; idempotent, an already-up tunnel is just reported.
-    connect: oc
+    connect: vpnRoute
         .route({
             method: "POST",
             path: "/vpn/{id}/connect",
@@ -31,7 +34,7 @@ export const vpnContract = {
         .input(VpnConnectInputSchema)
         .output(streamOf(IntenticLineSchema)),
     // Drops a tunnel; tolerates one already down, since the contract is "not up," not "it was up."
-    disconnect: oc
+    disconnect: vpnRoute
         .route({
             method: "POST",
             path: "/vpn/{id}/disconnect",
@@ -41,7 +44,7 @@ export const vpnContract = {
         .input(VpnIdParamSchema)
         .output(OkSchema),
     // Parses an exported FortiClient config into addable connections a user can pick instead of retyping.
-    importForticlient: oc
+    importForticlient: vpnRoute
         .route({
             method: "POST",
             path: "/vpn/import-forticlient",

package/src/contracts/workflows.contract.ts

@@ -1,4 +1,4 @@
-import { oc } from "@orpc/contract";
+import { procedure } from "../protocol/route-meta.js";
 import { DoorTokenSchema, OkSchema } from "../schemas/shared.js";
 import {
     WorkflowIdParamSchema,
@@ -17,7 +17,7 @@ import {
 // `run` acks with the run as recorded and executes detached, the same contract every turn-starting route here keeps.
 export const workflowsContract = {
     // Every saved workflow with its run history, newest first; a never-run workflow isn't an error case.
-    list: oc
+    list: procedure
         .route({
             method: "GET",
             path: "/workflows",
@@ -29,7 +29,7 @@ export const workflowsContract = {
     // Create or replace, with the operation explicit so an id collision can't turn a create into an overwrite.
     // Refuses a graph that can't run (a cycle, an unmet `needs`, a step with no completion signal), in the same words
     // the design-time validator (workflowFaults) uses.
-    save: oc
+    save: procedure
         .route({
             method: "POST",
             path: "/workflows",
@@ -40,7 +40,7 @@ export const workflowsContract = {
         .input(WorkflowSaveSchema)
         .output(WorkflowSavedSchema),
     // Mints a new gate credential; every pipeline holding the old URL stops working the moment this answers.
-    rotateGateToken: oc
+    rotateGateToken: procedure
         .route({
             method: "POST",
             path: "/workflows/{id}/gate/rotate",
@@ -51,7 +51,7 @@ export const workflowsContract = {
         .input(WorkflowIdParamSchema)
         .output(DoorTokenSchema),
     // Deleting a workflow doesn't stop or erase an in-flight run: a run snapshots its definition at start.
-    remove: oc
+    remove: procedure
         .route({
             method: "DELETE",
             path: "/workflows/{id}",
@@ -64,7 +64,7 @@ export const workflowsContract = {
     // Starts a run, optionally with a request appended to every step's own prompt; each step is recorded `pending` up
     // front so the graph is complete from the first frame.
     // Multiple runs of one workflow can be in flight at once; each derives its own conversation ids, so none collide.
-    run: oc
+    run: procedure
         .route({
             method: "POST",
             path: "/workflows/{id}/run",
@@ -75,7 +75,7 @@ export const workflowsContract = {
         .input(WorkflowRunStartSchema)
         .output(WorkflowRunSchema),
     // Every run across every workflow, newest first; the only place a deleted workflow's runs are still reachable.
-    runs: oc
+    runs: procedure
         .route({
             method: "GET",
             path: "/workflows/runs",
@@ -87,7 +87,7 @@ export const workflowsContract = {
     // Cuts off in-flight steps where they stand, aborting their turns like /agent/stop; not the graceful
     // finish-the-iteration stop a loop performs, since a step is a whole agent turn.
     // Always ends the run, including one left `running` by a daemon that was replaced mid-flight.
-    stopRun: oc
+    stopRun: procedure
         .route({
             method: "POST",
             path: "/workflows/runs/{runId}/stop",
@@ -100,7 +100,7 @@ export const workflowsContract = {
     // Ends a run's board presence, the run's half of `agents.archive`: nothing is lost, checkouts are reclaimed, and
     // `unarchiveRun` reverses it. Refused while the run is going.
     // Archives every step that ran along with it, since a step has no card of its own; the run's row stands for it.
-    archiveRun: oc
+    archiveRun: procedure
         .route({
             method: "POST",
             path: "/workflows/runs/{runId}/archive",
@@ -111,7 +111,7 @@ export const workflowsContract = {
         .input(WorkflowRunIdParamSchema)
         .output(OkSchema),
     // Inverse of archiveRun: puts an archived run and its sessions back on the board.
-    unarchiveRun: oc
+    unarchiveRun: procedure
         .route({
             method: "POST",
             path: "/workflows/runs/{runId}/unarchive",