@intentic/sandbox-contract 1.312.0 → 1.313.0

package/src/events/child-run.ts

@@ -0,0 +1,73 @@
+import type { ChildAgentAsk, ChildRun } from "./requests.js";
+import type { AgentReply } from "../schemas/providers/plan-limits.js";
+
+// How a child agent's run is compared and replaced, stated once: the card deciding whether the owner changed anything,
+// the settle rule recording what started, and the daemon starting it all replace the same fields in the same way.
+
+/** A child's run alone, off anything that carries one; absent fields stay absent rather than arriving as undefined. */
+export const childRunOf = (from: ChildRun): ChildRun => {
+    const run: ChildRun = { provider: from.provider, model: from.model };
+    if (from.harness !== undefined) {
+        run.harness = from.harness;
+    }
+    if (from.account !== undefined) {
+        run.account = from.account;
+    }
+    if (from.effort !== undefined) {
+        run.effort = from.effort;
+    }
+    if (from.thinking !== undefined) {
+        run.thinking = from.thinking;
+    }
+    if (from.fast !== undefined) {
+        run.fast = from.fast;
+    }
+    return run;
+};
+
+/**
+ * Whether two runs would start the same child. An absent harness is the provider's own loop, as a named `native` is,
+ * and an absent speed is the standard one. An absent effort or thinking setting is the model's own default, which is
+ * not the same as naming one.
+ */
+export const sameChildRun = (left: ChildRun, right: ChildRun): boolean =>
+    left.provider === right.provider &&
+    left.model === right.model &&
+    (left.harness ?? "native") === (right.harness ?? "native") &&
+    left.account === right.account &&
+    left.effort === right.effort &&
+    left.thinking === right.thinking &&
+    (left.fast ?? false) === (right.fast ?? false);
+
+/**
+ * The request as it reads once the owner started the child on `run`: the run replaced whole, with what the agent asked
+ * for kept as `proposed`. The same request, unchanged, when `run` is what the agent asked for anyway.
+ */
+export const repointedChild = (ask: ChildAgentAsk, run: ChildRun): ChildAgentAsk => {
+    if (sameChildRun(ask, run)) {
+        return ask;
+    }
+    const {
+        provider: _provider,
+        model: _model,
+        harness: _harness,
+        account: _account,
+        effort: _effort,
+        thinking: _thinking,
+        fast: _fast,
+        ...about
+    } = ask;
+    return { ...about, ...childRunOf(run), proposed: childRunOf(ask) };
+};
+
+/**
+ * A permission card as a reply leaves its child: a start the owner allowed on a run of their own reads what actually
+ * started, so a settled card never names the model that didn't. Anything else, a no included, keeps the card as asked.
+ */
+export const startedChildCard = <P extends { readonly child?: ChildAgentAsk | undefined }>(card: P, reply: AgentReply | undefined): P => {
+    const ask = card.child;
+    if (ask?.move !== "spawn" || reply?.kind !== "permission" || reply.decision === "deny" || reply.child === undefined) {
+        return card;
+    }
+    return { ...card, child: repointedChild(ask, reply.child) };
+};

package/src/events/errands.test.ts

@@ -0,0 +1,22 @@
+import { errandOfPrompt, errandOfRow } from "./errands.js";
+import { landBreakagePrompt, landFixPrompt } from "./land-breakage.js";
+import { LAND_CONFLICT_OPENING } from "./land-conflict.js";
+import { verifyNudgePrompt } from "./verify-nudge.js";
+
+// A row says what it is for since rows carry `errand`; one written before is still read by its opening.
+
+describe(`which errand a message is`, () => {
+    test(`is what the row says it is, whatever its words`, () => {
+        expect(errandOfRow({ role: `user`, text: `Carry on from where you left off.`, errand: `land-fix-nudge` })).toBe(`land-fix-nudge`);
+    });
+
+    test(`is read by its opening on a row written before rows said, and on nothing but a message`, () => {
+        expect(errandOfPrompt(landBreakagePrompt([`- a failure`]))).toBe(`land-breakage`);
+        expect(errandOfPrompt(landFixPrompt([`- a failure`]))).toBe(`land-fix`);
+        expect(errandOfPrompt(verifyNudgePrompt([`x`]))).toBe(`verify-nudge`);
+        expect(errandOfPrompt(`${LAND_CONFLICT_OPENING}\n\nthe files`)).toBe(`land-conflict`);
+        expect(errandOfPrompt(`Please fix the parser`)).toBeUndefined();
+        expect(errandOfRow({ role: `assistant`, text: landFixPrompt([]) })).toBeUndefined();
+        expect(errandOfRow({ role: `user`, text: `hello` })).toBeUndefined();
+    });
+});

package/src/events/errands.ts

@@ -0,0 +1,27 @@
+import type { TurnErrand } from "../schemas/speaker.js";
+import type { TranscriptRow } from "./transcript.js";
+import { isLandBreakage, isLandFix } from "./land-breakage.js";
+import { LAND_CONFLICT_OPENING } from "./land-conflict.js";
+import { withoutResumeNote } from "./resume.js";
+import { isVerifyNudge } from "./verify-nudge.js";
+
+// Which errand a composed prompt is, read the old way: by its opening paragraph, for the rows and turns written before
+// they carried `errand`. The openings are anchored on here, so each must stay byte-identical forever. A prompt the
+// daemon restarted carries its resume note first, so it is read past.
+export const errandOfPrompt = (prompt: string): TurnErrand | undefined => {
+    const text = withoutResumeNote(prompt.trim());
+    if (text.startsWith(LAND_CONFLICT_OPENING)) {
+        return "land-conflict";
+    }
+    if (isVerifyNudge(text)) {
+        return "verify-nudge";
+    }
+    if (isLandBreakage(text)) {
+        return "land-breakage";
+    }
+    return isLandFix(text) ? "land-fix" : undefined;
+};
+
+/** A message row's errand: what the row says, else what its opening names; none for anything but a message. */
+export const errandOfRow = (row: Pick<TranscriptRow, "role" | "text" | "errand">): TurnErrand | undefined =>
+    row.role !== "user" ? undefined : (row.errand ?? errandOfPrompt(row.text));

package/src/events/requests.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AgentProviderSchema } from "../schemas/agent.js";
+import { AgentHarnessSchema, AgentProviderSchema } from "../schemas/agent.js";
 import { CredentialGateKindSchema, CredentialGateScopeSchema, CredentialLaneSchema } from "../schemas/secrets.js";
 
 // Requests a turn raises to ask the person something mid-turn; each pauses the turn until `POST /agent/reply` answers it.
@@ -40,6 +40,42 @@ export const ProgramAskSchema = z.object({
 });
 export type ProgramAsk = z.infer<typeof ProgramAskSchema>;
 
+// What a child agent runs on: who serves it and how. The child-agent gate's request shows it, and the owner's allow may
+// carry a replacement (the permission reply's `child`, plan-limits.ts).
+export const ChildRunSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves it."),
+    model: z.string().min(1).describe("Which of that provider's models."),
+    harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Absent is the provider's own."),
+    account: z
+        .string()
+        .optional()
+        .describe("Which of that provider's connected accounts pays for it. Absent is whichever has the most room when it starts."),
+    effort: z.string().optional().describe("How hard it thinks, where the model offers a choice. Absent is the model's own default."),
+    thinking: z.boolean().optional().describe("Whether it reasons before it answers, where the model offers the choice."),
+    fast: z.boolean().optional().describe("Whether it asks for the faster rate, at the higher price."),
+});
+export type ChildRun = z.infer<typeof ChildRunSchema>;
+
+// A move a parent makes on a child agent that the owner's rules may hold for a yes.
+export const ChildMoveSchema = z.enum(["spawn", "send", "answer"]);
+export type ChildMove = z.infer<typeof ChildMoveSchema>;
+
+// The child a held request is about, as the daemon's own record of the call has it, never as the agent describes it.
+export const ChildAgentAskSchema = ChildRunSchema.extend({
+    move: ChildMoveSchema.describe("What the parent asks to do: start a new child, say something to one it started, or answer one's question."),
+    child: z.string().optional().describe("The child's id, for one that already exists."),
+    task: z.string().optional().describe("What the child is for, in a line."),
+    message: z
+        .string()
+        .optional()
+        .describe("What the parent would say to it: the message it sends, or the answers it gives. Clipped for the request."),
+    on: z.string().optional().describe('Which machine it runs on, when one is named: a runner, or "here" for this sandbox.'),
+    proposed: ChildRunSchema.optional().describe(
+        "What the agent asked to start it on, when the owner started it on something else instead. Present only once the request has settled that way.",
+    ),
+});
+export type ChildAgentAsk = z.infer<typeof ChildAgentAskSchema>;
+
 // One per-tool permission prompt (SDK's canUseTool, surfaced as a request); the daemon passes the bridge's own rendered
 // strings through unchanged. `alwaysLabel` is present only when the SDK offered a rule to persist.
 export const PermissionAskSchema = z.object({
@@ -62,6 +98,9 @@ export const PermissionAskSchema = z.object({
     program: ProgramAskSchema.optional().describe(
         "The program this request is holding, when the request is about one. Present on a command gate's request and absent on every other permission ask.",
     ),
+    child: ChildAgentAskSchema.optional().describe(
+        "The child agent this request would start or reach, and what it runs on. Present on the child-agent gate's request and absent on every other permission ask.",
+    ),
     // The judge's own sentence, present only when the title can't say it; never written by the agent being gated.
     explain: z
         .string()

package/src/events/transcript.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { AgentHarnessSchema, AgentProviderSchema } from "../schemas/agent.js";
 import { ShareDetailSchema } from "../schemas/share.js";
+import { TurnErrandSchema, TurnSpeakerSchema } from "../schemas/speaker.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
 import { RetryLadderSchema } from "../schemas/turn-break.js";
 import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind} from "./requests.js";
@@ -245,6 +246,13 @@ export const TranscriptRowSchema = z.object({
         .describe(
             "What the sandbox added to this message before the model saw it. Carried on the message rather than as rows of their own, because they genuinely were part of what was sent.",
         ),
+    // Who spoke a message row, as the sandbox verified it (schemas/speaker.ts), and what a composed one is for: a reader
+    // shows the sandbox's own words as the sandbox's, never as the owner's. Absent on rows written before rows said so,
+    // which are read by their opening (events/errands.ts).
+    speaker: TurnSpeakerSchema.optional().describe("Who sent this message, as the sandbox verified it. Absent where it does not say."),
+    errand: TurnErrandSchema.optional().describe(
+        "What this message is for, when the sandbox or the app composed it rather than a person typing it. Absent on a person's own words.",
+    ),
     // The user wrote this as the agent, no turn behind it; marked for a human reader, never surfaced to the agent.
     placed: z
         .boolean()

package/src/front/browser-wire.ts

@@ -0,0 +1,20 @@
+// Everything a browser sees of a sandbox's front and of the edge in front of it, outside the daemon's oRPC contract. The
+// Rust crates are the definition (`browser-wire`, and `tunnel` for what the edge declares): their types arrive as
+// TypeScript in generated/, and every value here is held to the manifest they write beside it (wire-manifests.test.ts),
+// which contract.lock.json pins.
+
+export type { EdgeVerdict, TerminalClientMessage, TerminalServerMessage } from "./generated/browser-wire.js";
+
+// Where a terminal socket opens on a sandbox's address. It is a WebSocket whichever way its bytes ride: over TCP, or on a
+// stream of the edge's WebTransport session, where the editor speaks the same protocol itself.
+export const TERMINAL_PATH = "/system/terminal";
+
+// Where a browser opens its WebTransport session, on the address of the sandbox the session's streams reach; the edge
+// answers it, never the sandbox.
+export const WEBTRANSPORT_PATH = "/system/transport";
+
+// What an edge may declare it serves beyond HTTPS over TCP (the tunnel crate's `Transport`), each only because its own
+// configuration binds it. Undeclared means not served: an editor opens WebTransport only where `webtransport` is named.
+export type EdgeTransport = "quic" | "h3" | "webtransport";
+
+export const EDGE_TRANSPORTS: readonly EdgeTransport[] = ["quic", "h3", "webtransport"];

package/src/front/front-wire.ts

@@ -0,0 +1,15 @@
+// The control socket between intentic-front and the daemon. The Rust crate `front-wire` is the definition: its types
+// arrive as TypeScript in generated/, and every value here is held to the manifest it writes beside it
+// (wire-manifests.test.ts), which contract.lock.json pins.
+
+export type * from "./generated/wire.js";
+
+// Set by intentic-front on the daemon it spawns: where to dial the control socket, and where to serve HTTP.
+export const FRONT_SOCKET_ENV = "INTENTIC_FRONT_SOCKET";
+export const NODE_SOCKET_ENV = "INTENTIC_NODE_SOCKET";
+
+// How long either side waits for the answer to a question it asked before giving up on it.
+export const ASK_PATIENCE_MS = 5000;
+
+// A frame is this many bytes of big-endian length, then that many bytes of JSON.
+export const FRAME_LENGTH_BYTES = 4;

package/src/front/generated/browser-wire.json

@@ -0,0 +1,138 @@
+{
+  "edge": {
+    "verdictHeader": "x-intentic-edge",
+    "verdicts": {
+      "description": "The edge's verdicts, the only values [`VERDICT_HEADER`] carries.",
+      "oneOf": [
+        {
+          "const": "no-tunnel",
+          "description": "No tunnel is registered: the box is off, and one that comes back redials within seconds.",
+          "type": "string"
+        },
+        {
+          "const": "unknown-sandbox",
+          "description": "The platform has no such sandbox, and no tunnel for it will be accepted again.",
+          "type": "string"
+        },
+        {
+          "const": "dropped",
+          "description": "A tunnel was held and the forward failed mid-flight.",
+          "type": "string"
+        }
+      ],
+      "title": "EdgeVerdict"
+    }
+  },
+  "terminal": {
+    "client": {
+      "description": "What the browser sends on a terminal socket, each a JSON text message.",
+      "oneOf": [
+        {
+          "description": "Keystrokes, a paste or a mouse report, written into the pane as their UTF-8 bytes.",
+          "properties": {
+            "data": {
+              "type": "string"
+            },
+            "type": {
+              "const": "input",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type",
+            "data"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "cols": {
+              "format": "uint16",
+              "maximum": 65535,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "rows": {
+              "format": "uint16",
+              "maximum": 65535,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "type": {
+              "const": "resize",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type",
+            "cols",
+            "rows"
+          ],
+          "type": "object"
+        },
+        {
+          "description": "The client's liveness, the socket's only one: the editor sends one every 30 s and calls the socket stale after\n90 s without a frame. The front answers `pong`, sends a WebSocket ping only to a client silent for 45 s, and closes\none silent for 90.",
+          "properties": {
+            "type": {
+              "const": "ping",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "type": "object"
+        }
+      ],
+      "title": "TerminalClientMessage"
+    },
+    "path": "/system/terminal",
+    "server": {
+      "description": "What a terminal socket sends as JSON text; the pane's own bytes travel as binary messages.",
+      "oneOf": [
+        {
+          "description": "The session is over, and the browser must not reconnect; `reason` is tmux's own words when it had any.",
+          "properties": {
+            "code": {
+              "format": "int32",
+              "type": "integer"
+            },
+            "reason": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "const": "exit",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type",
+            "code"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "type": {
+              "const": "pong",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "type": "object"
+        }
+      ],
+      "title": "TerminalServerMessage"
+    },
+    "upgrade": "websocket"
+  },
+  "webTransport": {
+    "alpn": "h3",
+    "path": "/system/transport"
+  }
+}

package/src/front/generated/browser-wire.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The edge's verdicts, the only values [`VERDICT_HEADER`] carries.
+ */
+export type EdgeVerdict = "no-tunnel" | "unknown-sandbox" | "dropped";
+
+/**
+ * What the browser sends on a terminal socket, each a JSON text message.
+ */
+export type TerminalClientMessage = { "type": "input", data: string, } | { "type": "resize", cols: number, rows: number, } | { "type": "ping" };
+
+/**
+ * What a terminal socket sends as JSON text; the pane's own bytes travel as binary messages.
+ */
+export type TerminalServerMessage = { "type": "exit", code: number, reason?: string, } | { "type": "pong" };