@intentic/sandbox-contract 1.311.0 → 1.313.0

package/src/documents/read.ts

@@ -0,0 +1,114 @@
+import type { ManifestProblem } from "../schemas/system.js";
+import { type Conversion, convertDocument, type Granularity } from "./conversions.js";
+import { carryUnknown, type IdKeys, reemitQuarantined } from "./passthrough.js";
+
+// The one reading of a stored document, shared by every store that keeps a file across versions: the daemon's
+// jsonFile, jsonEntries and jsonDir, and an extension's sandboxDocument. The bytes as JSON, then the document's
+// conversions, then this build's parse; what it could not read is named by a `reason` a reader matches on, never by its
+// wording; and a change to what it read comes back through `carry`, which keeps what this build's parse dropped.
+
+// What a reader needs of a document: the conversions its shape has had, and where they apply.
+export interface DocumentShape {
+    readonly history: readonly Conversion[];
+    readonly granularity: Granularity;
+}
+
+type Report = (problem: ManifestProblem) => void;
+
+export type DocumentParse<T> =
+    // The whole file as one value, undefined for one this build cannot read; `report` flags a problem within a valid one.
+    | { readonly kind: "whole"; readonly parse: (raw: unknown, report: Report) => T | undefined }
+    // A top-level array read one entry at a time: an entry this build cannot read, or whose conversion fails, is
+    // reported and quarantined (kept as written on the next save), never the file. `idKeys` pair a rebuilt entry with
+    // the one it replaces.
+    | {
+          readonly kind: "entries";
+          readonly entry: (raw: unknown, report: Report) => (T extends readonly (infer E)[] ? E : never) | undefined;
+          readonly idKeys?: IdKeys;
+      };
+
+export interface DocumentRead<T> {
+    // Undefined when the file as a whole is unreadable; `problems` then leads with why.
+    readonly value: T | undefined;
+    // The bytes a change to `value` writes: the change, plus what the file held that this build does not know.
+    readonly carry: (updated: T) => unknown;
+    readonly problems: readonly ManifestProblem[];
+}
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+const unreadable = <T>(reason: NonNullable<ManifestProblem["reason"]>, detail: string): DocumentRead<T> => ({
+    value: undefined,
+    carry: (updated) => updated,
+    problems: [{ kind: "unreadable", reason, detail }],
+});
+
+// `checkSettles` is the daemon's development-build check (conversions.ts), off for an extension.
+export const readDocument = <T>(text: string, shape: DocumentShape, how: DocumentParse<T>, checkSettles = false): DocumentRead<T> => {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(text);
+    } catch {
+        return unreadable("not-json", "the file is not valid JSON");
+    }
+    const problems: ManifestProblem[] = [];
+    const report: Report = (problem) => problems.push(problem);
+    if (how.kind === "entries") {
+        if (!Array.isArray(raw)) {
+            return unreadable("rejected", "the file does not match what this build expects");
+        }
+        const perEntry = shape.granularity === "entries";
+        const entries: unknown[] = [];
+        const aligned: unknown[] = [];
+        const quarantined: { index: number; entry: unknown }[] = [];
+        let whole: readonly unknown[] = raw;
+        if (!perEntry && shape.history.length > 0) {
+            try {
+                const converted = convertDocument(shape.history, shape.granularity, raw, checkSettles).value;
+                whole = Array.isArray(converted) ? converted : [];
+            } catch (error) {
+                return unreadable("conversion-failed", `a conversion to this build's shape failed (${message(error)})`);
+            }
+        }
+        whole.forEach((written, index) => {
+            let candidates: readonly unknown[];
+            try {
+                const value = perEntry ? convertDocument(shape.history, "entries", [written], checkSettles).value : [written];
+                candidates = Array.isArray(value) ? value : [value];
+            } catch (error) {
+                quarantined.push({ index, entry: written });
+                report({
+                    kind: "invalidEntry",
+                    reason: "conversion-failed",
+                    detail: `entry ${index} could not be converted to this build's shape (${message(error)}); it is kept as written`,
+                });
+                return;
+            }
+            for (const candidate of candidates) {
+                const parsed = how.entry(candidate, report);
+                if (parsed === undefined) {
+                    quarantined.push({ index, entry: candidate });
+                    report({ kind: "invalidEntry", reason: "rejected", detail: `entry ${index} is not one this build can read; it is kept as written` });
+                    continue;
+                }
+                entries.push(parsed);
+                aligned.push(candidate);
+            }
+        });
+        return {
+            value: entries as T,
+            carry: (updated) => reemitQuarantined(carryUnknown(aligned, entries, updated, how.idKeys) as readonly unknown[], quarantined, how.idKeys),
+            problems,
+        };
+    }
+    try {
+        raw = convertDocument(shape.history, shape.granularity, raw, checkSettles).value;
+    } catch (error) {
+        return unreadable("conversion-failed", `a conversion to this build's shape failed (${message(error)})`);
+    }
+    const value = how.parse(raw, report);
+    if (value === undefined) {
+        return unreadable("rejected", "the file does not match what this build expects");
+    }
+    return { value, carry: (updated) => carryUnknown(raw, value, updated), problems };
+};

package/src/events/agent-events.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { PermissionModeSchema } from "../schemas/agent.js";
+import { TurnErrandSchema } from "../schemas/speaker.js";
 import { LandConflictSchema } from "../schemas/agents.js";
 import { ContextTrimSchema } from "../schemas/context-trim.js";
 import { RateLimitInfoSchema } from "../schemas/providers/claude-gate.js";
@@ -65,6 +66,8 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         sentAt: z.number(),
         attachments: z.array(z.string()).optional(),
         voice: z.enum(["sandbox", "agent"]).optional(),
+        // What a composed message is for, stamped on the row it becomes (TranscriptRow.errand).
+        errand: TurnErrandSchema.optional(),
         // The message's own id, stamped on the row it becomes (TranscriptRow.messageId).
         messageId: z.string().optional(),
     }),
@@ -271,6 +274,8 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
             .optional(),
         // rate_limit only: epoch seconds when the exhausted window reopens; absent when the reset instant is unknown.
         resetsAt: z.number().optional(),
+        // The daemon's word, never the window's guess: which account a reconnect badge or a spent pool belongs to.
+        account: z.string().optional().describe("Which of the provider's accounts served (or was refused for) the turn, where the sandbox holds it."),
         // Gated codes only: "scheduled" if this conversation arms the resume, "available" if one exists but isn't.
         autoResume: z.enum(["scheduled", "available"]).optional(),
         // "scheduled" only: epoch seconds the booked send actually fires. Distinct from `resetsAt` (the provider's fact

package/src/events/child-run.test.ts

@@ -0,0 +1,81 @@
+import type { ChildAgentAsk } from "./requests.js";
+import type { TranscriptPermission } from "./transcript.js";
+import { childRunOf, repointedChild, sameChildRun } from "./child-run.js";
+import { settledRequests } from "../policy/request-status.js";
+
+// A child's run is replaced whole when the owner re-points it on the card: an effort or an account chosen for one model
+// means nothing on another, so nothing of the agent's own pick may leak into the owner's.
+
+const asked: ChildAgentAsk = {
+    move: "spawn",
+    task: "Port the parser to zig",
+    provider: "claude",
+    model: "claude-opus-4-6",
+    effort: "max",
+    account: "work",
+    on: "rog",
+};
+
+describe("sameChildRun", () => {
+    test("the provider's own loop is the same run whether it is named or left out", () => {
+        expect(sameChildRun({ provider: "claude", model: "m" }, { provider: "claude", model: "m", harness: "native" })).toBe(true);
+        expect(sameChildRun({ provider: "claude", model: "m" }, { provider: "claude", model: "m", harness: "claude-code" })).toBe(false);
+    });
+
+    test("standard speed is the same run whether it is named or left out", () => {
+        expect(sameChildRun({ provider: "claude", model: "m" }, { provider: "claude", model: "m", fast: false })).toBe(true);
+    });
+
+    test("naming an effort is a different run from leaving it to the model", () => {
+        expect(sameChildRun({ provider: "claude", model: "m" }, { provider: "claude", model: "m", effort: "high" })).toBe(false);
+    });
+});
+
+describe("repointedChild", () => {
+    test("replaces the run whole and keeps what the agent asked for", () => {
+        const started = repointedChild(asked, { provider: "codex", model: "gpt-5.5" });
+        expect(started).toEqual({
+            move: "spawn",
+            task: "Port the parser to zig",
+            on: "rog",
+            provider: "codex",
+            model: "gpt-5.5",
+            proposed: { provider: "claude", model: "claude-opus-4-6", effort: "max", account: "work" },
+        });
+    });
+
+    test("leaves the request alone when the owner kept the agent's pick", () => {
+        expect(repointedChild(asked, childRunOf(asked))).toBe(asked);
+    });
+});
+
+describe("a settled child-agent request", () => {
+    const card: TranscriptPermission = { requestId: "r1", toolName: "agents.spawn", status: "pending", child: asked };
+
+    test("reads what actually started when the owner re-pointed it", () => {
+        const settled = settledRequests(
+            { permission: card },
+            { kind: "permission", requestId: "r1", decision: "once", child: { provider: "claude", model: "claude-sonnet-4-6" } },
+        );
+        expect(settled.permission?.status).toBe("allowed");
+        expect(settled.permission?.child).toMatchObject({ model: "claude-sonnet-4-6", proposed: { model: "claude-opus-4-6" } });
+        expect(settled.permission?.child).not.toHaveProperty("effort");
+    });
+
+    test("a no starts nothing, so it keeps what was asked", () => {
+        const settled = settledRequests(
+            { permission: card },
+            { kind: "permission", requestId: "r1", decision: "deny", child: { provider: "claude", model: "claude-sonnet-4-6" } },
+        );
+        expect(settled.permission?.child).toEqual(asked);
+    });
+
+    test("only a start can be re-pointed: a message to a child already running keeps its run", () => {
+        const sent: TranscriptPermission = { ...card, child: { ...asked, move: "send", child: "sub-1" } };
+        const settled = settledRequests(
+            { permission: sent },
+            { kind: "permission", requestId: "r1", decision: "once", child: { provider: "codex", model: "gpt-5.5" } },
+        );
+        expect(settled.permission?.child?.model).toBe("claude-opus-4-6");
+    });
+});

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/land-breakage.ts

@@ -9,3 +9,15 @@ export const landBreakagePrompt = (parts: readonly string[]): string => [LAND_BR
 
 // Whether a stored prompt is one.
 export const isLandBreakage = (prompt: string): boolean => prompt.startsWith(LAND_BREAKAGE_OPENING);
+
+// The opening of a FRESH conversation the daemon starts on a red main-line check that the conversation that landed the
+// work could not take: nobody could be named, several could, or the one named had gone cold or run out of room.
+// Anchored on by the chat like the follow-up above, so it must stay unique and stable across releases.
+export const LAND_FIX_OPENING =
+    "The main tree's own check went red after work landed, and no conversation still holding that work could take it, so this one was started to fix it. The failures, the lands they arrived with and where to read those conversations are below. Fix them in this isolated worktree and check the fix as you would any change; your work lands like any other turn.";
+
+// The prompt a fresh fix-up is started with: its opening, then the evidence, each part already worded for the model.
+export const landFixPrompt = (parts: readonly string[]): string => [LAND_FIX_OPENING, ...parts].join("\n\n");
+
+// Whether a stored prompt is one.
+export const isLandFix = (prompt: string): boolean => prompt.startsWith(LAND_FIX_OPENING);

package/src/events/land-conflict.ts

@@ -0,0 +1,12 @@
+import { withoutResumeNote } from "./resume.js";
+
+// The turn the app sends a conversation whose land refused, asking it to rebase and resolve, recognised by its opening.
+// Composed by the editor, but lives here because the fold must recognise it as well: that turn's own rebase notice
+// would otherwise tell the reader the thing the turn was sent to fix.
+
+// Anchored on by the chat and the fold, so it must stay unique and stable across releases.
+export const LAND_CONFLICT_OPENING =
+    "Landing your work hit a merge conflict, none of it reached the user's workspace; it is all still on your branch. Rebase onto the main line and resolve the conflicts yourself. In each repo below (`root` is your working directory, any other name that subdirectory of it):";
+
+// Whether a stored prompt is one. A turn the daemon re-ran carries the same prompt after its resume note.
+export const isLandConflict = (prompt: string): boolean => withoutResumeNote(prompt.trim()).startsWith(LAND_CONFLICT_OPENING);

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/system-events.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { AgentSummarySchema } from "../schemas/agents.js";
 import { AccountUsageSchema, ProviderRefusalSchema } from "../schemas/providers/plan-limits.js";
 import { MemberRoleSchema } from "../schemas/shared.js";
-import { SidecarStatusSchema } from "../schemas/workspace/workspace-tree.js";
+import { SidecarStatusSchema, WorkspaceTreeDeltaSchema } from "../schemas/workspace/workspace-tree.js";
 
 // Frames about the sandbox rather than a turn: liveness, boot progress, what moved (repos, refs, running processes,
 // presence, the fleet), and account headroom. One stream carries them all.
@@ -128,13 +128,19 @@ export type AccountUsageChanged = z.infer<typeof AccountUsageChangedSchema>;
 export const ProviderRefusalChangedSchema = z.object({ kind: z.literal("providerRefusal"), provider: z.string(), refusal: ProviderRefusalSchema.optional() });
 export type ProviderRefusalChanged = z.infer<typeof ProviderRefusalChangedSchema>;
 
-// The /events stream union: hello, heartbeats, boot progress, workspace/repo/ref/runtime/shadow changes, presence and
-// fleet rosters, account headroom and refusal changes. oRPC validates every frame against this.
+// What moved in the shared tree, once the daemon's resident copy re-listed a batch: a tab holding the generation it
+// counts from patches its tree, and one holding any other fetches it afresh.
+export const TreeChangedSchema = WorkspaceTreeDeltaSchema.extend({ kind: z.literal("treeChanged") });
+export type TreeChanged = z.infer<typeof TreeChangedSchema>;
+
+// The /events stream union: hello, heartbeats, boot progress, workspace/repo/ref/runtime/shadow/tree changes, presence
+// and fleet rosters, account headroom and refusal changes. oRPC validates every frame against this.
 export const SystemEventSchema = z.discriminatedUnion("kind", [
     HelloSchema,
     HeartbeatSchema,
     BootSchema,
     WorkspaceChangedSchema,
+    TreeChangedSchema,
     DerivedChangedSchema,
     ReposChangedSchema,
     RefsChangedSchema,

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/events/verify-nudge.ts

@@ -1,6 +1,7 @@
-// The follow-up the daemon sends when a turn ended with work it could not confirm: the runtimes with no Stop hook get
-// their turn.ending asks this way (verify-nudge.ts), as an ordinary prompt. Its opening lives on the wire because the
-// chat has to recognise it coming back: a prompt nobody typed must not reach a reader as their own words.
+// The follow-up the daemon USED to send when a turn ended with work it could not confirm. Nothing sends it any more:
+// checks run after work lands, never inside a conversation (schemas/workspace/mainline.ts). It stays on the wire because
+// records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not reach a reader as
+// their own words.
 
 // Anchored on by the reader, so it must stay unique and stable across releases — a reworded opening un-recognises every
 // nudge already in a record, and they read as the user's own typing again.

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;