@intentic/sandbox-contract 1.166.0 → 1.168.0

package/src/events.ts

@@ -6,6 +6,8 @@ import {
     LandConflictSchema,
     PermissionModeSchema,
     RateLimitInfoSchema,
+    SubagentKindSchema,
+    SubagentStatusSchema,
     UsageWindowSchema,
 } from "./schemas.js";
 
@@ -125,19 +127,36 @@ export type ToolCallContent = z.infer<typeof ToolCallContentSchema>;
 // tool_use/tool_result blocks, so a restored card carries everything the live `tool_call` frame did except
 // the streaming-only correlation fields.
 //
-// One restored tool card. Subagent (Task) calls do NOT nest here: the SDK stores a delegation's own calls in a
-// separate per-subagent file, so a Task card restores as a leaf and its children stay collapsed — the live
-// stream still nests them (see ChatTool.children).
-export const RestoredToolCallSchema = z.object({
-    id: z.string(),
-    name: z.string(),
-    category: ToolKindSchema,
-    status: ToolCallStatusSchema,
-    target: z.string().optional(),
-    locations: z.array(ToolCallLocationSchema).optional(),
-    content: z.array(ToolCallContentSchema).optional(),
-});
-export type RestoredToolCall = z.infer<typeof RestoredToolCallSchema>;
+// One restored tool card. A subagent's own calls and its thinking nest under the Agent card that spawned them,
+// the same two fields (and the same recursion) the live ChatTool carries — so a reopened chat redraws the
+// delegation it was showing instead of a leaf card with the whole child collapsed into its result text.
+// z.lazy because the shape refers to itself: a subagent that delegates nests one level deeper.
+export const RestoredToolCallSchema: z.ZodType<RestoredToolCall> = z.lazy(() =>
+    z.object({
+        id: z.string(),
+        name: z.string(),
+        category: ToolKindSchema,
+        status: ToolCallStatusSchema,
+        target: z.string().optional(),
+        locations: z.array(ToolCallLocationSchema).optional(),
+        content: z.array(ToolCallContentSchema).optional(),
+        children: z.array(RestoredToolCallSchema).optional(),
+        thinking: z.string().optional(),
+    }),
+);
+// Mutable, unlike most of this file: both builders settle a card IN PLACE when its result arrives turns later
+// (restoredTurn's `cards` map, readWorkspaceSession's `awaiting`), which is what saves them a second pass.
+export interface RestoredToolCall {
+    id: string;
+    name: string;
+    category: ToolKind;
+    status: ToolCallStatus;
+    target?: string | undefined;
+    locations?: ToolCallLocation[] | undefined;
+    content?: ToolCallContent[] | undefined;
+    children?: RestoredToolCall[] | undefined;
+    thinking?: string | undefined;
+}
 
 // One restored bubble. Each stored assistant message becomes its own, which is what reproduces the live
 // interleaving — prose, the tool cards that prose introduced, then the next block of prose — rather than
@@ -162,7 +181,8 @@ export const AgentTranscriptSchema = SessionTranscriptSchema.extend({ sessionId:
 // without a UI mapping is dropped. `plan`/`question`/`permission` pause the turn until the user answers on the
 // `POST /agent/reply` side channel, and `resolved` releases the one it names; `mode` reports the live
 // permission posture as the agent changes it.
-// `parentToolUseId` tags frames produced inside a subagent (Task tool).
+// `parentToolUseId` tags frames produced inside a subagent (Task tool); `subagent`/`subagent_update` report the
+// subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("session"), sessionId: z.string() }),
     /* First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
@@ -229,6 +249,40 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // `browser-<id>` session, and the client surfaces it in the same panel as the terminals. One per turn, for
     // the same reason: one browser serves every browser call the turn makes.
     z.object({ kind: z.literal("browser"), session: z.string() }),
+    /* THE AGENT STARTED ANOTHER AGENT — an Agent/Task subagent, or a Codex/Grok CLI it drove from its own Bash
+     * (see SubagentSessionSchema). One `subagent` frame per child, then `subagent_update` as it works: the same
+     * call/update pair `tool_call`/`tool_call_update` uses, and for the same reason — the fields that move
+     * (status, spend, what it is doing) arrive many times and must REPLACE, while the fields that identify it are
+     * said once.
+     *
+     * `id` is the SPAWNING TOOL CALL's id — the same id the client already nests the child's inner frames under
+     * (`parentToolUseId`), so both frames land on the card that spawned the child by the lookup that is already
+     * there (mapToolAnywhere). No second correlation, and nothing to get wrong.
+     *
+     * These exist because the SDK's task messages were dropped. A BACKGROUNDED child (the Agent tool's default)
+     * emits its tool_use and then nothing until its result lands, which for a long child is minutes of a spinner
+     * that cannot say whether anything is happening. */
+    z.object({
+        kind: z.literal("subagent"),
+        id: z.string(),
+        subagentKind: SubagentKindSchema,
+        agentType: z.string().optional(),
+        description: z.string().optional(),
+        model: z.string().optional(),
+        background: z.boolean().optional(),
+        // A delegation's tmux session — the one live view a subagent doesn't have (SubagentSessionSchema).
+        terminal: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal("subagent_update"),
+        id: z.string(),
+        status: SubagentStatusSchema.optional(),
+        tokens: z.number().optional(),
+        toolUses: z.number().optional(),
+        lastTool: z.string().optional(),
+        summary: z.string().optional(),
+        error: z.string().optional(),
+    }),
     z.object({ kind: z.literal("todos"), items: z.array(TodoItemSchema) }),
     // The provider's own slash commands (ACP available_commands_update), replaced whole each time — the
     // composer's `/` popover lists them; invoking one is plain `/name …` prompt text (the ACP convention).
@@ -322,9 +376,11 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 "claude-reauth",
                 // The API refused this turn's token MID-FLIGHT — nearly always one superseded by a rotation,
                 // which Anthropic retires the moment its successor is minted. Distinct from claude-reauth: the
-                // account is fine and the daemon re-mints on the spot, so this frame is a notice about a turn
-                // that resumed itself, not a request for the user to do anything. It only reaches the client
-                // when the resume could NOT start, which is when reconnecting really is the fix.
+                // account is fine and the daemon re-mints on the spot, so this is usually a notice about a turn
+                // that is coming back rather than a request for the user to do anything. `autoResume` says
+                // which of the two: "scheduled" means the re-mint-and-re-run is armed, and its absence means
+                // nothing is coming (the turn was already a resume, or it ran on a credential with nothing to
+                // re-mint from) — that is the case where reconnecting really is the fix.
                 "claude-token-refused",
                 // The model provider itself failed transiently — 500/502/503, a 529 at capacity, a dropped
                 // socket — and the harness's own in-turn retries did not outlast it. Nothing about the workspace
@@ -346,11 +402,12 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         // rate_limit_event or the account's persisted usage windows). Absent when the reset instant is unknown
         // (nothing to schedule against).
         resetsAt: z.number().optional(),
-        // Where the daemon's resume of THIS turn stands — the same two states for a spent allowance and for a
-        // provider outage, because the client's reading of them is the same: "scheduled" = the resume is armed
-        // and this turn comes back by itself; "available" = the daemon remembered the failed turn and turning
-        // the setting on (autoResumeOnLimit / resumeAfterOutage) arms that same resume, which is what the
-        // chat's offer banner hangs off. Absent ⇒ there is nothing to resume.
+        // Where the daemon's resume of THIS turn stands, for the two codes that have one (provider-outage,
+        // claude-token-refused). "scheduled" = the resume is armed and this turn comes back by itself;
+        // "available" = the daemon remembered the failed turn and turning resumeAfterOutage on arms that same
+        // resume, which is what the chat's offer banner hangs off — outage only, since a renewal is never gated
+        // on a setting. Absent means there is nothing automatic to resume: a spent usage limit never has one,
+        // and a refused credential has none once re-minting it has already been tried and failed.
         autoResume: z.enum(["scheduled", "available"]).optional(),
         /* provider-outage only: the shape of the wait. `retryAt` (epoch seconds) is when the next attempt is
          * due — not a fixed cadence, because an outage has no reset instant to aim at and hammering a provider
@@ -361,10 +418,6 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
          * on-by-default retry that gives no account of how long it will keep going is the kind users switch off
          * defensively; one that says "attempt 2 of 6" is one they leave on. */
         outage: z.object({ retryAt: z.number(), attempt: z.number(), maxAttempts: z.number() }).optional(),
-        // rate_limit only: the account whose allowance is spent, as the DAEMON resolved it (the client's own
-        // selection can be empty, which means "the provider's first"). It is what lets the chat offer the
-        // provider's OTHER accounts as a resume-now instead of a wait — see /agent/resume-limit.
-        account: z.string().optional(),
     }),
     z.object({ kind: z.literal("done") }),
 ]);
@@ -383,6 +436,32 @@ export const AttachFrameSchema = z.discriminatedUnion("kind", [
 ]);
 export type AttachFrame = z.infer<typeof AttachFrameSchema>;
 
+/* WHAT A RESUMED TURN'S PROMPT SAYS IT IS. The daemon re-runs a turn something underneath it killed (turn-resume.ts)
+ * by sending the original prompt again behind one of these sentences, so the model knows what interrupted it.
+ *
+ * They live on the wire rather than in the daemon because the CLIENT has to recognise them too: an attach head
+ * carries the run's prompt verbatim, and a window joining a resumed run would otherwise render the note as a
+ * message the USER wrote — the same words the user already said one run up, with a machine's preamble on them.
+ * Recognising the prefix is what lets that window reuse the bubble that is already there instead. */
+export const RESUME_NOTES = {
+    auth: "The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically.",
+    outage: "The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically.",
+    restart: "The sandbox restarted while this turn was running, which stopped it, and this turn resumed automatically once it came back.",
+} as const;
+
+// The prompt a resume actually sends: the note, then why the words below are being repeated, then them.
+export const withResumeNote = (prompt: string, note: string): string =>
+    Object.values(RESUME_NOTES).some((known) => prompt.startsWith(known))
+        ? prompt
+        : `${note} The interrupted request is repeated below — where part of it was already completed in this session, continue from that point instead of starting over.\n\n${prompt}`;
+
+// The user's own words inside a resumed prompt — the note and its explanation stripped back off. Returns the
+// prompt unchanged when it is not a resume, so a caller can hand every attach head through it.
+export const withoutResumeNote = (prompt: string): string => {
+    const note = Object.values(RESUME_NOTES).find((known) => prompt.startsWith(known));
+    return note === undefined ? prompt : prompt.slice(prompt.indexOf("\n\n") + 2);
+};
+
 // One parsed line from `intentic … --output ndjson` (engine events, provider `log`, the terminal `result`).
 // Open-ended by design — the sandbox consumes the wire shape, not @intentic/engine's types — so a string
 // `kind` plus arbitrary extra fields pass through. The apply-events tail (intentic.contract `applyEvents`) rides

package/src/index.ts

@@ -67,6 +67,7 @@ export * from "./effects.js";
 export * from "./events.js";
 export * from "./sse.js";
 export * from "./routes.js";
+export * from "./workspace-state.js";
 export * from "./agent-catalog.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";

package/src/model-order.ts

@@ -3,7 +3,7 @@
  *
  * Anthropic's REST /v1/models answers newest-first: that IS a provider opinion, and Claude's catalog rides it
  * (claude-models.ts). Every other provider here is read through an OpenAI-compatible /v1/models — Codex and
- * Gemini via the bundled translator, Kimi via Moonshot — or out of xAI's "Did you mean" rejection, and those
+ * Gemini and Kimi via the bundled translator — or out of xAI's "Did you mean" rejection, and those
  * endpoints publish a SET, not a ranking: they hand the ids back in whatever order their registry iterates,
  * which in practice is alphabetical. Reading that as a preference is what put "GPT 5.4 Mini" at the head of the
  * Codex group with GPT 5.6 below it, and what made a fresh Codex conversation start on whichever id happened to

package/src/quick-model.test.ts

@@ -31,7 +31,7 @@ test("puts tier ahead of cost — a free frontier model is still the wrong tool
     expect(resolveQuickModel([CLAUDE, proOnly], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
 });
 
-test("prefers a subscription to a metered key at equal tier, since only one of them charges per click", () => {
+test("uses stable provider order when two subscriptions offer the same tier", () => {
     const kimiCheap: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-mini`] };
     const claudeCheap: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-haiku-4-5`] };
 

package/src/schemas.test.ts

@@ -21,13 +21,14 @@ test("a payload from a build that predates a toggle parses, with the new toggle
     expect(SandboxSettingsSchema.parse(older)).toEqual({
         ...older,
         terseHoldout: 0,
+        iqContext: false,
+        iqContextHoldout: 0,
         filterBackend: "native",
         systemPromptMode: "intentic",
         systemPrompt: "",
         quickModel: "",
         agentRetentionDays: 3,
         autoLand: true,
-        autoResumeOnLimit: false,
         resumeAfterOutage: true,
         autoResumeOnRestart: true,
         gateCommand: "",
@@ -46,6 +47,10 @@ test("an empty object is the full default settings object", () => {
         // Off: the steer's turn-level control spends the tokens it measures, so measuring is opt-in.
         terseHoldout: 0,
         iqSearch: false,
+        // Off, and its holdout with it: pre-injection spends input tokens on every eligible turn, and the
+        // control that would tell you whether they paid for themselves costs the turns it measures.
+        iqContext: false,
+        iqContextHoldout: 0,
         outputCleaners: "off",
         outputHoldout: 0,
         filterBackend: "native",
@@ -62,9 +67,8 @@ test("an empty object is the full default settings object", () => {
         // On because it is the historical behaviour — defaulting off would silently hold every existing
         // sandbox's finished work on branches nobody is watching.
         autoLand: true,
-        autoResumeOnLimit: false,
-        // On, unlike the limit resume beside it: an outage resume spends nothing the dead turn hadn't already
-        // committed, and the turns it saves are the unattended ones nobody is watching to restart by hand.
+        // On, where a spent usage limit re-runs nothing: an outage resume spends nothing the dead turn hadn't
+        // already committed, and the turns it saves are the unattended ones nobody is watching to restart by hand.
         resumeAfterOutage: true,
         // On: a daemon restart is usually intentic's own doing (an image update, an approved environment
         // change), not the user's decision, so the turn it interrupted resumes rather than staying stuck.