@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/protocol/runner-protocol.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import { NeedsActionSchema } from "../policy/needs-action.js";
+
+// The runner link's edges: the /system/runners/connect handshake, boot env, and turn placement (procedures live in
+// contracts/runner.contract.ts). A runner is a sandbox image in runner mode, no browser owner or tunnel, that dials its
+// parent over one outbound socket authenticating in its first frame.
+
+// Boot env for a runner container: who to dial, and the single-use pairing token to enroll with.
+export const RUNNER_PARENT_URL_ENV = "RUNNER_PARENT_URL";
+export const RUNNER_PAIR_TOKEN_ENV = "RUNNER_PAIR_TOKEN";
+
+// First frame on /system/runners/connect: plain JSON, not oRPC, since a socket must prove whose it is before a typed
+// link exists. Token rides the frame, never the URL.
+export const RunnerHelloSchema = z.object({
+    type: z.literal("runner-hello"),
+    // The runner's durable token, redeemed once from the pairing over /system/runners/enroll.
+    token: z.string(),
+    // The daemon build the runner runs, so an old image is visible rather than mysteriously wrong.
+    version: z.string(),
+    // Compared against what the parent runs to report parity (outdated → rebuild action); an outdated runner still runs
+    // turns rather than being refused.
+    image: z.string(),
+    channel: z.string().optional(),
+    overlayHash: z.string().optional(),
+    // Runner's declared settings-only sandbox.toml (definition.ts), diffed against the parent's to itemize drift;
+    // absent on an old image.
+    definitionToml: z.string().optional(),
+});
+export type RunnerHello = z.infer<typeof RunnerHelloSchema>;
+
+// The URL a runner dials, given its parent's public URL. One builder, so `ic`, the Fly provisioner and the
+// daemon route cannot disagree about where the door is (hostConnectUrl's rule).
+/* HOW OFTEN THE PARENT PINGS A CONNECTED RUNNER, read by both sides of the socket: the parent's hub pings on
+ * it (runners/runner-peer.ts) and the runner presumes the link dead after a few of them pass in silence
+ * (peer-dial.ts's peerLinkSilenceMs). One number, because the two sides disagreeing about it is a runner either
+ * dropped while healthy or believed alive for as long as its socket happens to stay open. */
+export const RUNNER_HEARTBEAT_MS = 30_000;
+
+export const runnerConnectUrl = (parentUrl: string): string => `${parentUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/runners/connect`;
+
+// Where a runner redeems its pairing for a durable token, once, over plain HTTPS.
+export const runnerEnrollUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/enroll`;
+
+// The parent's git door for one repo: stock git fetch/push against its smart-HTTP git dirs, authenticated by the
+// runner's own token as bearer.
+export const runnerGitUrl = (parentUrl: string, repo: string): string =>
+    `${parentUrl.replace(/\/$/, "")}/system/runners/git/${encodeURIComponent(repo)}`;
+
+// Where a runner's push lands; never refs/heads/agent/<id> directly since git refuses updating a checked-out ref. The
+// parent advances that branch by hard-resetting its mirror worktree to this ref.
+export const runnerIncomingRef = (conversationId: string): string => `refs/runner-incoming/${conversationId}`;
+
+// Container name for a runner on its host machine; the `ic`-prefix (runner.rs SLUG_PREFIX) must match exactly, or
+// updates target a container that doesn't exist.
+export const runnerSlug = (name: string): string => `runner-${name}`;
+
+// Credential doors: a runner's turns spend the origin sandbox's model providers, never accounts of its own. The parent
+// answers with the least that travels (a minted token or a route); refresh tokens never leave it.
+export const runnerCredentialsUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/credentials`;
+export const runnerCredentialRefreshUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/credentials/refresh`;
+
+// Re-serves the parent's model translator to runners: subscription-routed turns dial this authenticated proxy instead
+// of syncing auth files, and the parent forwards to its own loopback translator.
+export const runnerTranslatorPath = "/system/runners/translator";
+export const runnerTranslatorUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}${runnerTranslatorPath}`;
+
+export const RunnerCredentialRequestSchema = z.object({
+    // Provider as the turn names it (absent = claude); an open vocabulary, including endpoint/<id>.
+    agent: z.string().optional(),
+    account: z.string().optional(),
+    model: z.string().optional(),
+});
+export type RunnerCredentialRequest = z.infer<typeof RunnerCredentialRequestSchema>;
+
+// What travels back, by kind:
+// oauth: a native-Claude access token minted for this turn; `account` set for a stored account, absent for the
+// container-env fallback
+// parent-translator: runs against the parent's translator through the proxy; the runner supplies its own token as
+// bearer
+// endpoint: a foreign endpoint capability the runner dials directly, with its own bearer
+// A refusal uses the same codes as local resolution, so a remote refusal reads like a local one.
+export const RunnerCredentialSchema = z.union([
+    z.object({ ok: z.literal(true), kind: z.literal("oauth"), accessToken: z.string(), account: z.string().optional() }),
+    z.object({ ok: z.literal(true), kind: z.literal("parent-translator"), model: z.string(), trial: z.boolean().optional() }),
+    z.object({
+        ok: z.literal(true),
+        kind: z.literal("endpoint"),
+        baseUrl: z.string(),
+        authToken: z.string(),
+        model: z.string(),
+        trial: z.boolean().optional(),
+    }),
+    z.object({
+        ok: z.literal(false),
+        code: z.enum(["subscription-required", "claude-reauth", "trial-unavailable"]).optional(),
+        message: z.string(),
+    }),
+]);
+export type RunnerCredential = z.infer<typeof RunnerCredentialSchema>;
+
+export const RunnerCredentialRefreshRequestSchema = z.object({
+    account: z.string().min(1),
+    // Token the harness was refused with; rotation supersedes exactly that one, never a token already rotated.
+    rejected: z.string().min(1),
+});
+export type RunnerCredentialRefreshRequest = z.infer<typeof RunnerCredentialRefreshRequestSchema>;
+
+// Absent `accessToken` means the parent couldn't re-mint (a revoked account); the harness gives up as it would locally.
+export const RunnerCredentialRefreshSchema = z.object({ accessToken: z.string().optional() });
+export type RunnerCredentialRefresh = z.infer<typeof RunnerCredentialRefreshSchema>;
+
+// What a runner is, hardware-wise: what the placement picker shows and a future scheduler would weigh.
+export const RunnerFactsSchema = z.object({
+    cpus: z.number().int().positive(),
+    memoryMb: z.number().int().positive(),
+    freeDiskMb: z.number().int().nonnegative(),
+    // 0..1 over the last minute; a coarse busy signal for a picker, not a metrics feed.
+    load: z.number().nonnegative(),
+});
+export type RunnerFacts = z.infer<typeof RunnerFactsSchema>;
+
+// Whether a runner matches this sandbox's image, channel and approved overlay: `current`, `outdated` (gets an update
+// button), or `unknown` (never connected, or a parent that can't name its own image). Reported, never enforced.
+export const RunnerParitySchema = z.enum(["current", "outdated", "unknown"]);
+export type RunnerParity = z.infer<typeof RunnerParitySchema>;
+
+// One runner as the owner's list shows it: enrolled state plus whatever the hub currently knows — HostSummary's shape,
+// retold with parity instead of platform/scopes.
+export const RunnerSummarySchema = z.object({
+    id: z.string(),
+    // The connected device that requested it (Devices view); absent for one started by hand on a machine.
+    host: z.string().optional(),
+    online: z.boolean(),
+    version: z.string().optional(),
+    image: z.string().optional(),
+    channel: z.string().optional(),
+    overlayHash: z.string().optional(),
+    facts: RunnerFactsSchema.optional(),
+    lastSeen: z.number().optional(),
+    // Computed once by the daemon (runners/runner-parity.ts), so every surface shows the same badge.
+    parity: RunnerParitySchema,
+    // Where the runner's environment differs from this sandbox's, one line per difference; absent if never reported,
+    // empty if they agree. A Setting line is fixable live; an overlay line needs a rebuild.
+    drift: z.array(NeedsActionSchema).optional(),
+});
+export type RunnerSummary = z.infer<typeof RunnerSummarySchema>;
+
+// A workspace sync, narrated line by line as it happens (first contact clones whole repos). `op`: `pull` brings the
+// runner's checkout current before a turn, `push` returns the branch after; `repos` is the parent's own record, since
+// the runner's mirror could be stale.
+export const RunnerSyncSchema = z.object({
+    op: z.enum(["pull", "push"]),
+    conversationId: z.string().min(1),
+    branch: z.string().min(1),
+    repos: z.array(
+        z.object({
+            repo: z.string().min(1),
+            // "" for the workspace root itself; every other repo sits at its root-relative dir.
+            dir: z.string(),
+            mainBranch: z.string().min(1),
+        }),
+    ),
+});
+export type RunnerSync = z.infer<typeof RunnerSyncSchema>;
+
+export const RunnerSyncLineSchema = z.union([
+    z.object({ kind: z.literal("line"), text: z.string() }),
+    z.object({ kind: z.literal("done"), ok: z.boolean(), detail: z.string().optional() }),
+]);
+export type RunnerSyncLine = z.infer<typeof RunnerSyncLineSchema>;
+
+// One dispatched turn, not AgentTurnSchema: that's the browser's request full of fields the parent resolves first. This
+// is the residue after resolution, plus attachments inline, since the runner has no route to the parent's attachment
+// store.
+export const RunnerTurnSchema = z.object({
+    conversationId: z.string().min(1),
+    branch: z.string().min(1),
+    prompt: z.string(),
+    provider: z.string(),
+    harness: z.string(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+    thinking: z.boolean().optional(),
+    fast: z.boolean().optional(),
+    // Which origin-sandbox account pays; credentials resolve against the parent, naming an account there.
+    account: z.string().optional(),
+    sessionId: z.string().optional(),
+    // Base64 since frames are JSON and attachment count is capped; `path` is the workspace-relative path the prompt
+    // already names.
+    attachments: z.array(z.object({ path: z.string().min(1), bytesBase64: z.string() })).optional(),
+});
+export type RunnerTurn = z.infer<typeof RunnerTurnSchema>;
+
+// Where a conversation runs, fixed on its first turn like `isolated` placement: later turns follow the registry, not
+// the sender. `runner` implies isolation since a remote conversation is branch-anchored; absent means local.
+export const AgentPlacementSchema = z.union([z.object({ kind: z.literal("local") }), z.object({ kind: z.literal("runner"), id: z.string().min(1) })]);
+export type AgentPlacement = z.infer<typeof AgentPlacementSchema>;

package/src/protocol/terminal-protocol.ts

@@ -0,0 +1,13 @@
+// The /system/terminal WebSocket wire protocol, shared by the daemon and browser terminal so the two can't drift. Plain
+// types, not zod, since this is a per-keystroke hot path nothing validates. Pane bytes travel as raw binary frames (so
+// a split UTF-8 char decodes whole); everything else is JSON.
+
+// `ping` is the client's 30s keepalive against tunnel idle-reaping; `pong` answers it, so silence beyond the interval
+// means half-open.
+export type TerminalClientMessage =
+    | { readonly type: "input"; readonly data: string }
+    | { readonly type: "resize"; readonly cols: number; readonly rows: number }
+    | { readonly type: "ping" };
+
+// `exit` is terminal (no reconnect) when the tmux client ends; `reason` is tmux's own words, if any, for the dead pane.
+export type TerminalServerMessage = { readonly type: "exit"; readonly code: number; readonly reason?: string } | { readonly type: "pong" };

package/src/protocol/webext-links.ts

@@ -0,0 +1,50 @@
+// Zod-free half of the browser connector's wire: URL builders, pairing code format, message names. Split from
+// webext-protocol.ts since a content script only needs two constants and importing the barrel pulls in all of zod. No
+// imports allowed here, ever.
+
+// URL the extension dials, from the sandbox's public URL; carries no credential, the token rides the hello frame.
+export const webextConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/webext/connect`;
+
+// Where the extension POSTs a site's session when the owner connects it, bearer-authenticated. A separate door from the
+// socket, since the socket's answers land in the agent's context and cookies must never reach a model.
+export const webextSessionUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/session`;
+
+// The reverse direction: lends a sandbox account's session to this browser for a step only it can do (passkey, 2FA,
+// SSO). Separate from webextSessionUrl since the two have distinct refusals; cookies return on this request, never as
+// an MCP result.
+export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/lend`;
+
+// One pasteable code, not two fields: base64url of {url, token}, since a popup gets one paste, not two boxes. `token`
+// is single-use and expires in ten minutes; the prefix versions the format.
+const PAIRING_PREFIX = "ixb1_";
+
+const base64url = (value: string): string => btoa(value).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+
+export const webextPairingCode = (pairing: { readonly url: string; readonly token: string }): string =>
+    `${PAIRING_PREFIX}${base64url(JSON.stringify({ url: pairing.url, token: pairing.token }))}`;
+
+// The extension's side; undefined for anything not one of ours, so a bad paste is reported rather than attempted.
+export const parseWebextPairingCode = (code: string): { readonly url: string; readonly token: string } | undefined => {
+    const trimmed = code.trim();
+    if (!trimmed.startsWith(PAIRING_PREFIX)) {
+        return undefined;
+    }
+    try {
+        const decoded = JSON.parse(atob(trimmed.slice(PAIRING_PREFIX.length).replaceAll("-", "+").replaceAll("_", "/"))) as {
+            url?: unknown;
+            token?: unknown;
+        };
+        // Checked here (http(s) URL, non-empty token) rather than left to the WebSocket constructor to throw.
+        if (typeof decoded.url !== "string" || typeof decoded.token !== "string" || decoded.token === "" || !/^https?:\/\//.test(decoded.url)) {
+            return undefined;
+        }
+        return { url: decoded.url, token: decoded.token };
+    } catch {
+        return undefined;
+    }
+};
+
+// Window message the sandbox's page posts for its content script to pick up, not chrome.runtime.sendMessage, which
+// would need the extension's store id baked into the web app.
+export const WEBEXT_PAIR_MESSAGE = "intentic:webext:pair";
+export const WEBEXT_PAIRED_MESSAGE = "intentic:webext:paired";

package/src/protocol/webext-protocol.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+// Handshake on /system/webext/connect, the one message on that socket that isn't oRPC, same two-phase shape as
+// host-protocol.ts. A separate protocol from host's, since the extension has no shell or filesystem, only tabs and
+// origins the person granted one at a time.
+
+/* HOW OFTEN THIS DOOR PINGS A CONNECTED BROWSER, read by both sides of the socket: the daemon's hub pings on
+ * it (webext/webext-peer.ts) and the extension presumes a link dead after a few of them pass in silence
+ * (peer-dial.ts's peerLinkSilenceMs). Tighter than the machine door's and the number is not a taste: an MV3
+ * service worker is killed after 30 seconds of inactivity and WebSocket traffic is what counts as activity, so
+ * a heartbeat at or above Chrome's own limit would race the browser into shutting the extension down between
+ * beats. One number, because the two sides disagreeing about it is either a browser dropped while healthy or
+ * one believed alive for as long as its socket happens to stay open. */
+export const WEBEXT_HEARTBEAT_MS = 20_000;
+
+export const WebExtHelloSchema = z.object({
+    type: z.literal("hello"),
+    // Enrollment token, in the first frame, never the URL: a WebSocket has no headers, and `?token=` would leak into
+    // proxy logs.
+    token: z.string(),
+    // Extension build per connection, so an outdated one is visible rather than mysteriously missing a tool.
+    version: z.string(),
+});
+export type WebExtHello = z.infer<typeof WebExtHelloSchema>;

package/src/schemas/activity.ts

@@ -1,9 +1,8 @@
-// activity: the activity audit log (historyRoot/activity.jsonl)
+// Activity audit log schemas (historyRoot/activity.jsonl).
 import { z } from "zod";
 import { AgentOriginSchema } from "./agent.js";
-// One provider-agnostic event per agent↔provider interaction, appended by the daemon only (never the agent,
-// the log lives under historyRoot, outside /work, so the agent can't read or rewrite its own trail). Discord
-// is the first source; other cli providers reuse the same shape.
+// One provider-agnostic event per agent↔provider interaction, appended only by the daemon; the log lives outside /work,
+// so an agent can't read or rewrite its own trail.
 
 export const ActivityEventSchema = z.object({
     id: z.string().describe("The entry's own id."),
@@ -11,21 +10,17 @@ export const ActivityEventSchema = z.object({
     at: z.number().describe("When it happened, in milliseconds. Also what you page by."),
     // "discord", …; absent on provider-less system events (a cron automation.run).
     provider: z.string().optional().describe("Which outside service, when one was involved. Absent for the sandbox's own events."),
-    // Which provider account handled the turn, the attribution key for per-account usage totals. Absent on
-    // provider-less events and turns that ran on the provider's default account.
+    // Which provider account handled it; attribution key for per-account usage, absent on provider-less or
+    // default-account turns.
     account: z
         .string()
         .optional()
         .describe("Which account handled it. Absent for the sandbox's own events and for work run on a provider's default."),
     direction: z.enum(["in", "out", "system"]).describe("Whether something arrived, something went out, or the sandbox did it to itself."),
-    // in: message.received | voice_utterance.received | voice_transcript.received
-    // out: message.send | reaction.add | messages.read | api.call (unclassified provider endpoint)
-    // system: gateway.login_failed | dispatch.failed | voice.session_started | voice.session_ended | automation.run
-    //         | turn.started | turn.plan | turn.error | turn.completed (agent turn lifecycle; provider = claude/codex)
-    //         | rule.blocked_push | rule.held_work | rule.continued_turn (a rule DID something, see RuleSchema.
-    //           Only the three outcomes a person would otherwise have no explanation for: a push that did not
-    //           go, work that did not arrive, a turn that did not end. A rule that ran and passed says nothing,
-    //           because a feed that logs every green check is one the eye learns to skip.)
+    // in: message.received, voice_utterance.received, voice_transcript.received
+    // out: message.send, reaction.add, messages.read, api.call (unclassified endpoint)
+    // system: gateway.login_failed, dispatch.failed, voice.session_started, voice.session_ended, automation.run,
+    // turn.started, turn.plan, turn.error, turn.completed, rule.blocked_push, rule.held_work, rule.continued_turn
     type: z
         .string()
         .describe(
@@ -34,42 +29,41 @@ export const ActivityEventSchema = z.object({
     channelId: z.string().optional().describe("Which channel or thread it happened in."),
     // Inbound author display name.
     author: z.string().optional().describe("Who sent it, for something that arrived."),
+    // Distinct from `author` (the relayed sender) and `account` (who served it); absent for an unasked wake.
+    actor: z
+        .string()
+        .optional()
+        .describe("Who asked for the turn, as the sandbox verified it: a member's email, or token:<label> for a program's control token. Absent for a wake nothing asked for."),
     // Full message text (inbound) or sent payload content (outbound).
     content: z.string().optional().describe("The message, in full, whichever direction it went."),
-    // Outbound HTTP method + endpoint path (tokens ride headers, never URLs).
+    // HTTP method and endpoint path of an outgoing call; credentials ride headers, never the URL.
     method: z.string().optional().describe("The verb of an outgoing call."),
     endpoint: z.string().optional().describe("The address of an outgoing call. Credentials travel in headers, so they are never here."),
     // The agent turn that made/handled it, the join key between an inbound wake and its outbound calls.
     sessionId: z.string().optional().describe("The provider session behind it."),
-    /* ONE TURN'S EVENTS, TIED TOGETHER. A turn writes four lifecycle events plus one per outbound provider call,
-     * and read as five rows they say one thing five times, so the feed groups on this instead. It cannot be
-     * sessionId: the runtime does not mint one until the stream's first frame, which is AFTER turn.started, so
-     * the very event carrying the prompt is the one that could never be joined. Minted by the turn itself. */
+    // Ties one turn's events together; not sessionId, minted only after turn.started, too late for that event.
     turnId: z
         .string()
         .optional()
         .describe(
             "Ties one turn's entries together. A turn writes several, and read as separate rows they say one thing several times, so a feed groups on this.",
         ),
-    // The stable conversation the turn belongs to. Outlives sessionId, which a provider/account/harness switch
-    // retires mid-conversation, so this, not sessionId, is what "the same agent" means across a feed.
+    // Outlives sessionId, retired by a provider switch; this is what "same agent" means across a feed.
     conversationId: z
         .string()
         .optional()
         .describe(
             "Which conversation. This, rather than the provider session, is what the same agent means across a feed, because a session is retired whenever the model changes.",
         ),
-    // The conversation's display title as it stood when the event was written. Denormalised on purpose: the
-    // registry entry it came from is prunable and renameable, and an audit row must still read as words years
-    // later. Absent on the first event of a fresh conversation, the auto-namer has not run yet.
+    // Denormalized title at write time, since the registry entry is prunable/renameable; absent before the auto-namer
+    // runs.
     title: z
         .string()
         .optional()
         .describe(
             "What that conversation was called at the time. Copied in rather than looked up, because an audit entry must still read as words years later, after the conversation has been renamed or pruned.",
         ),
-    // What woke the conversation from outside, when something did (see AgentOriginSchema), the feed's "who
-    // called me" attribution, and how a turn is filed under Discord rather than under the runtime that served it.
+    // Files a turn under what caused it (e.g. Discord), not under the runtime that served it.
     origin: AgentOriginSchema.optional().describe(
         "What woke the conversation from outside, when something did. It is how a turn gets filed under the chat service that caused it rather than under the model that served it.",
     ),
@@ -91,10 +85,8 @@ export const ActivityQuerySchema = z.object({
 });
 export type ActivityQuery = z.infer<typeof ActivityQuerySchema>;
 export const ActivityListSchema = z.object({ events: z.array(ActivityEventSchema).describe("The audit entries, newest first.") });
-// Live connection health, probed per provider capability (not stored): gateway state from the client pool
-// (idle = the gateway is up but has no enabled listener automation to connect for, distinct from a
-// connection that should be up but isn't; pairing = the socket is up but the credential is a ceremony nobody
-// has finished, which no amount of waiting fixes), lastError from the newest system-error event in the log.
+// Live connection health, probed per capability, not stored; `gateway` from the client pool, `lastError` from the
+// newest system-error event in the log.
 export const ActivityConnectionSchema = z.object({
     capabilityId: z.string().describe("Which connection."),
     provider: z.string().describe("Which service it is."),