@intentic/sandbox-contract 1.308.2 → 1.309.0

package/src/schemas/providers/plan-limits.ts

@@ -214,6 +214,14 @@ export const SteerSchema = z
     .object({
         conversationId: z.string().min(1).describe("Which running conversation to interrupt."),
         text: z.string().max(20_000).describe("What to say to it. It arrives mid-turn without stopping the turn."),
+        messageId: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe(
+                "Your id for this message. Sending again under an id the sandbox already took is answered with what it did with it the first time, never a second delivery. Leave it out and the sandbox names the message itself.",
+            ),
         attachments: z
             .array(z.string().min(1))
             .max(20)
@@ -233,8 +241,42 @@ export const SteerSchema = z
     .refine((steer) => steer.text.trim().length > 0 || (steer.attachments?.length ?? 0) > 0, {
         message: "text or attachments required",
     });
-// True cancel, aborted daemon-side; unlike closing the /agent fetch, which sends no cancel frame.
-export const StopTurnSchema = z.object({ conversationId: z.string().min(1).describe("Which conversation's running turn to cancel.") });
+// True cancel, aborted daemon-side; unlike closing the /agent fetch, which sends no cancel frame. A stop names the run
+// it means, so one arriving after that run settled cannot cancel whatever the conversation started next.
+export const StopTurnSchema = z.union([
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        run: z
+            .string()
+            .min(1)
+            .describe(
+                "The run you mean to cancel, as starting or attaching to it named it. If another turn has started since, nothing is cancelled and the answer names the one running instead.",
+            ),
+    }),
+    // A send not yet answered has no run to name, only the id it gave its message.
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        messageId: z
+            .string()
+            .min(1)
+            .describe(
+                "The message you sent, while its run is not named yet: cancels the turn it is in. If none is, nothing is cancelled: the message has not become a turn, or its turn has already ended.",
+            ),
+    }),
+    // Only for a turn nobody can name: one the sandbox runs with no run to attach to (a scheduled automation's).
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        live: z
+            .literal(true)
+            .describe("Cancel whatever turn is running now, whichever that is. Only for a turn you cannot name: one that has no run to attach to."),
+    }),
+]);
+export type StopTurn = z.infer<typeof StopTurnSchema>;
+export const StopResultSchema = z.object({
+    stopped: z.boolean().describe("Whether a turn was cancelled."),
+    running: z.string().optional().describe("The run that is live instead of the one you named, left running. Absent when nothing else runs."),
+});
+export type StopResult = z.infer<typeof StopResultSchema>;
 // The press carries WHO serves the re-run; the daemon keeps WHAT the turn is (prompt, attachments, worktree) from its
 // own record, since re-deriving from a stripped client transcript would replay a different turn.
 export const ResumeRoutingSchema = z.object({
@@ -261,3 +303,26 @@ export const ResumeTurnSchema = z.object({
         "Who serves the re-run, when the conversation has been re-pointed since it was refused. Leave it out to run it on whatever the turn carried.",
     ),
 });
+// Names one queued message as it was read, so a change made against an older copy is refused rather than written over
+// somebody else's.
+export const QueuedMessageRefSchema = z.object({
+    conversationId: z.string().min(1).describe("Whose queue."),
+    id: z.string().min(1).describe("Which waiting message."),
+    revision: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("The message's revision as you read it. If it has been changed since, from this window or another, nothing happens."),
+});
+export type QueuedMessageRef = z.infer<typeof QueuedMessageRefSchema>;
+export const QueueEditSchema = QueuedMessageRefSchema.extend({
+    text: z.string().describe("What the message should say instead. It keeps its place in the queue."),
+});
+export type QueueEdit = z.infer<typeof QueueEditSchema>;
+export const QueueResumeSchema = z.object({
+    conversationId: z.string().min(1).describe("Whose queue to let go."),
+    routing: ResumeRoutingSchema.optional().describe(
+        "Who serves the turn the waiting messages start, when the conversation has been re-pointed since they were queued: the usual answer to a refusal that held them. Leave it out to send them as they were queued.",
+    ),
+});
+export type QueueResume = z.infer<typeof QueueResumeSchema>;

package/src/schemas/providers/usage.ts

@@ -72,6 +72,9 @@ export const UsageTurnSchema = z.object({
     // Hash of the brief that was sent, recorded on control turns too. Load-bearing rather than decorative: the file is
     // rewritten monthly, so a 30-day window holds two different treatments and pooling them would measure neither.
     notesCohort: z.string().optional(),
+    // Arm of the lean-guidance experiment, stable per conversation; true is the short form. The cohort hashes both forms.
+    guidanceArm: z.boolean().optional(),
+    guidanceCohort: z.string().optional(),
     // What became of pre-turn retrieval on this turn, and how long it took. Assignment and DELIVERY are different
     // facts: the first version of this mechanism was assigned to every eligible turn and reached four in five of them,
     // which is the difference between a null result and a mechanism that never ran. Absent means the flag was off, so

package/src/schemas/settings.ts

@@ -254,6 +254,21 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control.",
         ),
+    // Measured by the `guidance` experiment against the full set; the full set stays the default until that says otherwise.
+    leanGuidance: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Send this product's own guidance in its short form: only what the agent cannot find out by looking, instead of a paragraph for every habit it was once caught in. Off by default, because the long form is the one the product was tuned on.",
+        ),
+    leanGuidanceHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe(
+            "What share of conversations to keep on the long form, so the two can be compared. Whole conversations rather than individual turns, because the guidance sits in the prompt for the whole session.",
+        ),
     iqSearch: z
         .boolean()
         .default(false)
@@ -578,6 +593,7 @@ export const SavingsReportSchema = z.object({
     // Same absence rule as `search`: not measured, never zero.
     map: TurnExperimentSchema.optional(),
     notes: TurnExperimentSchema.optional(),
+    guidance: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 

package/src/schemas/turn-break.ts

@@ -47,3 +47,11 @@ export const RETRY_LADDER_TRIES = RETRY_LADDER_MS.length;
 
 /** The wait before the next rung, or undefined once the ladder is spent. */
 export const retryLadderDelay = (triesWithoutProgress: number): number | undefined => RETRY_LADDER_MS[triesWithoutProgress];
+
+// Where an automatic re-run ladder stands, whichever wall climbs it (an outage's breaker, a stopped turn's rungs).
+// `made` equal to `max` is a spent ladder: nothing more goes unasked.
+export const RetryLadderSchema = z.object({
+    made: z.number().int().min(0).describe("Automatic re-runs already sent for this turn."),
+    max: z.number().int().min(1).describe("How many the ladder may send before it stands down."),
+});
+export type RetryLadder = z.infer<typeof RetryLadderSchema>;

package/src/state/history-state.ts

@@ -113,5 +113,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "runner-pair-consumed.json", portability: "identity" },
     // This container's own identity and reconnect token; elsewhere it would dial the parent as this runner.
     { path: "runner-identity.json", portability: "identity" },
+    // The owner's yes to a workspace's hooks, pinned to their bytes: a trust decision the target's owner makes again.
+    { path: "hook-approvals.json", portability: "identity", note: "Approve the workspace's Claude Code hooks again from Approvals." },
+    // The hook sets waiting for that yes; the next turn that finds them lists them again.
+    { path: "hook-requests.json", portability: "derived" },
+    // The owner's yes to each workspace extension's declared powers, decided again by the target's owner.
+    { path: "extension-approvals.json", portability: "identity", note: "Approve the extensions written in this workspace again from Extensions." },
     { path: "local-cert/", portability: "identity" },
 ];

package/src/state/workspace-state.test.ts

@@ -60,8 +60,8 @@ describe(`staleQueryKeys`, () => {
     });
 
     it(`ignores a store's own temp file while it is mid-swap`, () => {
-        // jsonFile's atomic-rename temp name: `.<name>.<pid>.tmp` beside the target.
-        expect(staleQueryKeys([`.intentic/.settings.json.42.tmp`], [])).toEqual([]);
+        // writeTextFile's atomic-rename temp name: `.<name>.<pid>.<n>.tmp` beside the target.
+        expect(staleQueryKeys([`.intentic/.settings.json.42.7.tmp`], [])).toEqual([]);
         expect(staleQueryKeys([`.intentic/config/settings.json`], [])).toEqual([`settings`, `manifests`]);
     });
 

package/src/text/transcript-fold.test.ts

@@ -186,7 +186,8 @@ describe("foldTurn", () => {
                 code: "provider-outage",
                 message: "Anthropic is down.",
                 autoResume: "scheduled",
-                outage: { retryAt: 1, attempt: 2, maxAttempts: 6 },
+                outage: { retryAt: 1 },
+                retries: { made: 1, max: 6 },
             },
         ];
         // The row states what happened and nothing more: what happens next, and the one control that changes it, are
@@ -200,6 +201,23 @@ describe("foldTurn", () => {
         });
     });
 
+    // The count lives in the record, so a reader scrolling back sees how many times a stuck turn was sent again.
+    it("says on a stopped turn's row which automatic try comes next, or that the ladder stood down", () => {
+        const timedOut = "Google turn timed out waiting for OpenCode.";
+        const booked: AgentEvent[] = [{ kind: "error", message: timedOut, autoResume: "scheduled", nextAt: 1, retries: { made: 1, max: 3 } }];
+        expect(foldOf("hi", booked).at(-1)).toEqual({ role: "notice", text: `${timedOut} Retrying by itself: attempt 2 of 3.` });
+        const spent: AgentEvent[] = [{ kind: "error", message: timedOut, autoResume: "available", retries: { made: 3, max: 3 } }];
+        expect(foldOf("hi", spent).at(-1)).toEqual({
+            role: "notice",
+            text: `${timedOut} Retried 3 of 3 times by itself; nothing more is sent automatically.`,
+        });
+        // An outage nobody armed says so, instead of promising the breaker's retry.
+        const unarmed: AgentEvent[] = [
+            { kind: "error", code: "provider-outage", message: "Anthropic is down.", autoResume: "available", outage: { retryAt: 1 }, retries: { made: 0, max: 6 } },
+        ];
+        expect(foldOf("hi", unarmed).at(-1)).toEqual({ role: "notice", text: "Anthropic is down. Nothing is retrying it, so the turn is waiting here." });
+    });
+
     it("writes the turn's own events down as notices", () => {
         const events: AgentEvent[] = [
             { kind: "worktree", branch: "agent/x", base: "abc1234", sync: { commits: 2, blocked: [] } },
@@ -213,7 +231,7 @@ describe("foldTurn", () => {
             { role: "notice", text: "Context compacted to free up space." },
             {
                 role: "notice",
-                text: "Changes landed in your workspace: review them in the Changes panel. Installing 1 new dependency it added; the project's checks run when that finishes, and the outcome lands in Activity.",
+                text: "Changes landed in your workspace: review them in the Changes panel. Installing 1 dependency it added or changed; the project's checks run when that finishes, and the outcome lands in Activity.",
                 noticeAction: "depsInstall",
             },
         ]);
@@ -495,8 +513,8 @@ describe("patches", () => {
     });
 });
 
-// A refusal that ran nothing offers the message back to the composer — true where somebody typed one, false for a run
-// that started itself, where there is no composer and no typed message.
+// A refusal that ran nothing offers the message back for another press — true where somebody typed one, false for a
+// run that started itself, where there is no composer and no typed message.
 describe(`a refusal that ran nothing`, () => {
     const REFUSED = { kind: `error`, code: `context-window-too-small`, message: `This model accepts 16,384 tokens.` } as const satisfies AgentEvent;
 
@@ -551,9 +569,9 @@ describe(`a refusal that ran nothing`, () => {
         expect(foldOf(`land it`, [REFUSED]).at(-1)?.noticeAction).toBeUndefined();
     });
 
-    // The bug this retraction exists for: the composer keeps the words for another press, so a bubble left standing
-    // here is the SAME message a second time, and a third, once per press against a gate that keeps refusing.
-    it(`takes the message back out, leaving the composer's copy as the only one`, () => {
+    // The bug this retraction exists for: the conversation's queue keeps the words for another press, so a bubble left
+    // standing here is the SAME message a second time, and a third, once per press against a gate that keeps refusing.
+    it(`takes the message back out, leaving the queue's copy as the only one`, () => {
         const fold = new TranscriptFold(openingOf(`land it`));
         const patches = fold.apply(REFUSED);
 

package/src/text/transcript-fold.ts

@@ -62,10 +62,11 @@ const dependencyLine = (deps: { missing: number; started: string[]; deferred: bo
     if (deps === undefined || deps.missing === 0) {
         return ``;
     }
-    const what = `${deps.missing} new ${deps.missing === 1 ? `dependency` : `dependencies`}`;
+    // `missing` counts versions the turn bumped as well as names it added, so the sentence names both.
+    const what = `${deps.missing} ${deps.missing === 1 ? `dependency` : `dependencies`} it added or changed`;
     return deps.deferred
-        ? ` ${what} are queued: installation starts after this turn and any other active agents finish, appears in Work terminals, then its checks and outcome land in Activity.`
-        : ` Installing ${what} it added; the project's checks run when that finishes, and the outcome lands in Activity.`;
+        ? ` ${what} ${deps.missing === 1 ? `is` : `are`} queued: installation starts after this turn and any other active agents finish, appears in Work terminals, then its checks and outcome land in Activity.`
+        : ` Installing ${what}; the project's checks run when that finishes, and the outcome lands in Activity.`;
 };
 
 // One line reporting the daemon's rebase of this agent's branch onto the current workspace; `blocked` names repos it
@@ -106,10 +107,10 @@ const landedRow = (event: Extract<AgentEvent, { kind: "landed" }>): TranscriptRo
     };
 };
 
-// The clause after a refusal that ran nothing. A turn somebody typed is held in the composer for another press; a turn
-// that started itself — an automation, a loop, a watch wake — has no typed message and nobody watching, so promising a
-// resend there names a composer the reader is not looking at. Neither version promises a retry: whether one comes is
-// the scheduler's decision, not this row's to state.
+// The clause after a refusal that ran nothing. A turn somebody typed is held in its conversation's queue for another
+// press; a turn that started itself — an automation, a loop, a watch wake — has no typed message and nobody watching,
+// so promising a resend there names a composer the reader is not looking at. Neither version promises a retry: whether
+// one comes is the scheduler's decision, not this row's to state.
 const undelivered = (unattended: boolean): string =>
     unattended
         ? `Nothing ran, and nothing is held: this run started on its own, so there is no message waiting to be sent again.`
@@ -152,9 +153,7 @@ const errorRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow
     const { message, code } = event;
     switch (code) {
         case "provider-outage":
-            return event.outage === undefined
-                ? { role: "notice", text: `${message} Nothing is retrying it, so the turn is waiting here.` }
-                : { role: "notice", text: `${message} Retrying by itself: attempt ${event.outage.attempt} of ${event.outage.maxAttempts}.` };
+            return { role: "notice", text: `${message} ${retryClause(event) ?? `Nothing is retrying it, so the turn is waiting here.`}` };
         case "claude-token-refused":
             return event.autoResume === "scheduled"
                 ? {
@@ -169,18 +168,31 @@ const errorRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow
             break;
     }
     if (!turnedAwayCode(code)) {
-        return { role: "notice", text: message };
+        const clause = retryClause(event);
+        return { role: "notice", text: clause === undefined ? message : `${message} ${clause}` };
     }
     return heldRow(event);
 };
 
-// The turn's opening user row: text, timestamp, attachments, and whatever the daemon later stamps onto it (checkpoint,
-// notes).
-export const userRow = (text: string, sentAt: number, attachments: readonly string[]): TranscriptRow => {
+// What a laddered wall's automatic re-runs are doing, said on the failure's own row so the count stays in the record.
+const retryClause = (event: Extract<AgentEvent, { kind: "error" }>): string | undefined => {
+    const { retries } = event;
+    if (retries === undefined) {
+        return undefined;
+    }
+    if (event.autoResume === "scheduled") {
+        return `Retrying by itself: attempt ${retries.made + 1} of ${retries.max}.`;
+    }
+    return retries.made >= retries.max ? `Retried ${retries.made} of ${retries.max} times by itself; nothing more is sent automatically.` : undefined;
+};
+
+// The turn's opening user row: text, timestamp, attachments, the message's id, and whatever the daemon later stamps onto
+// it (checkpoint, notes).
+export const userRow = (text: string, sentAt: number, attachments: readonly string[], messageId?: string): TranscriptRow => {
     // Drops an attachment already inline as an @-mention, unless it's a generated upload path (its own thumbnail).
     const inline = new Set(mentionedPathTokens(text));
     const chips = attachments.filter((path) => !inline.has(path) || path.includes(`/records/artifacts/attachments/`));
-    return { role: "user", text, sentAt, ...(chips.length > 0 ? { attachments: chips } : {}) };
+    return { role: "user", text, sentAt, ...(chips.length > 0 ? { attachments: chips } : {}), ...(messageId === undefined ? {} : { messageId }) };
 };
 
 export class TranscriptFold {
@@ -196,7 +208,7 @@ export class TranscriptFold {
     private readonly parked = new Map<string, number>();
     // The turn's opening user row, where the checkpoint and daemon notes land; cleared once `retract` takes it back.
     private opener: number | undefined;
-    // Set by `retract`: this turn was refused before it ran, and its message went back to the composer.
+    // Set by `retract`: this turn was refused before it ran, and its message went back to the conversation's queue.
     private unrun = false;
 
     constructor(
@@ -426,6 +438,7 @@ export class TranscriptFold {
             text: event.text,
             sentAt: event.sentAt,
             ...(event.attachments === undefined ? {} : { attachments: [...event.attachments] }),
+            ...(event.messageId === undefined ? {} : { messageId: event.messageId }),
         });
         // Anchors pair by position with the checkpoints only a person's steer reserves.
         if (event.voice === undefined) {
@@ -461,9 +474,9 @@ export class TranscriptFold {
         );
     }
 
-    // Attended refusals only: the composer holds those words for another press, so a bubble left standing repeats them
-    // once per press. Splicing is safe because nothing ran — no open bubble, no parked card, no steer above it. A turn
-    // the sandbox kept (`held`) keeps its message and is recorded: no composer anywhere holds a copy of it.
+    // Attended refusals only: the conversation's queue holds those words for another press, so a bubble left standing
+    // repeats them once per press. Splicing is safe because nothing ran — no open bubble, no parked card, no steer above
+    // it. A turn the sandbox kept (`held`) keeps its message and is recorded: no queue holds a copy of it.
     private retract(event: Extract<AgentEvent, { kind: "error" }>): TranscriptPatch[] {
         if (!this.turnedAway(event) || event.held !== undefined) {
             return [];