@intentic/sandbox-contract 1.331.0 → 1.332.0

package/src/chores/probes.ts

@@ -58,7 +58,9 @@ const asString = (value: unknown): string | undefined => (typeof value === `stri
 const countOf = (value: unknown): number => (Array.isArray(value) ? value.length : 0);
 
 // Leading-integer parts of a version, compared positionally rather than via full semver; prerelease/build metadata
-// can't change which position differs first.
+// can't change which position differs first. Not the contract's compareVersions: this asks which part an upgrade steps
+// (major, minor or patch), not which version is newer, and it reads whatever pnpm prints, `1.2.3(peer@1)` included,
+// where the semver reader would refuse the whole string.
 const versionParts = (version: string): number[] =>
     version
         .replace(/^[^\d]*/, ``)

package/src/contracts/agent.contract.ts

@@ -2,7 +2,15 @@ import { procedure } from "../protocol/route-meta.js";
 import { streamOf } from "../protocol/routes.js";
 import { AgentCommandsQuerySchema, AgentCommandsSchema } from "../events/requests.js";
 import { AttachFrameSchema } from "../events/agent-events.js";
-import { AgentRunSchema, AttachTurnSchema, ConversationQueueSchema, MessageReceiptSchema, QueueResumedSchema, StartedTurnSchema } from "../schemas/agent.js";
+import {
+    AgentRunSchema,
+    AttachTurnSchema,
+    ConversationQueueSchema,
+    MessageReceiptSchema,
+    QueueResumedSchema,
+    QueueTakenBackSchema,
+    StartedTurnSchema,
+} from "../schemas/agent.js";
 import { ChatRouteAskSchema, ChatRouteSchema } from "../schemas/chat-route.js";
 import { RewindResultSchema, RewindTurnSchema } from "../schemas/history.js";
 import {
@@ -19,6 +27,7 @@ import {
     StopResultSchema,
     StopTurnSchema,
 } from "../schemas/providers/plan-limits.js";
+import { ChooseHandoffSchema } from "../schemas/providers/handoff.js";
 import { OkSchema } from "../schemas/shared.js";
 
 // A turn executes as a detached daemon-side run. `run` starts it, or says the message into the running turn, or queues it
@@ -101,11 +110,11 @@ export const agentContract = {
             path: "/agent/queue/remove",
             summary: "Take back a waiting message",
             description:
-                "Removes a message from the conversation's queue before the agent gets it. Name the revision you read it at: a message somebody reworded since is left alone, so you never take back words you have not seen.",
+                "Removes a message from the conversation's queue before the agent gets it. Name the revision you read it at: a message somebody reworded since is left alone, so you never take back words you have not seen. A message that opened its conversation by being scheduled, with nothing else in that conversation since, takes the conversation with it: the answer says so, and the words are the caller's to put back where they were written.",
         })
         .meta({ floor: "collaborator", guest: true })
         .input(QueuedMessageRefSchema)
-        .output(ConversationQueueSchema),
+        .output(QueueTakenBackSchema),
     queueResume: procedure
         .route({
             method: "POST",
@@ -154,6 +163,18 @@ export const agentContract = {
         .meta({ floor: "collaborator", guest: true })
         .input(SwitchAccountSchema)
         .output(AccountSwitchedSchema),
+    // NOT_FOUND when no spent allowance holds a turn there, or the hand-off named is not one this turn can take.
+    chooseHandoff: procedure
+        .route({
+            method: "POST",
+            path: "/agent/handoff",
+            summary: "Choose how a held turn continues",
+            description:
+                "Records how the turn a spent allowance is holding continues the conversation once it is sent again: carry the session as it is, trim it, or summarise it. Starts nothing: a press, a booked move or the reset sends it, and each uses this pick.",
+        })
+        .meta({ floor: "collaborator", guest: true })
+        .input(ChooseHandoffSchema)
+        .output(OkSchema),
     // CONFLICT while a turn is running; NOT_FOUND when the message has no checkpoint; PRECONDITION_FAILED when the
     // position no longer holds the message named.
     rewind: procedure

package/src/contracts/offload.contract.ts

@@ -1,7 +1,15 @@
 import { z } from "zod";
 import { procedure } from "../protocol/route-meta.js";
 import { streamOf } from "../protocol/routes.js";
-import { OffloadFrameSchema, OffloadKindSchema, OffloadRecordSchema, OffloadRunSchema, OffloadTargetSchema } from "../schemas/offload.js";
+import {
+    FleetAdviceInputSchema,
+    FleetAdviceSchema,
+    OffloadFrameSchema,
+    OffloadKindSchema,
+    OffloadRecordSchema,
+    OffloadRunSchema,
+    OffloadTargetSchema,
+} from "../schemas/offload.js";
 import { OkSchema } from "../schemas/shared.js";
 
 // The in-sandbox `offload-run` command drives the first three on the agent token: the Bash hook and the check after
@@ -57,4 +65,16 @@ export const offloadContract = {
             description: "The heavy commands this sandbox sent to runners lately, newest first, with where they ran and how they ended.",
         })
         .output(z.object({ runs: z.array(OffloadRecordSchema) })),
+    // Read by the composer while a new conversation is still a draft (settings `offload.sessions`); measuring a runner
+    // asks it over its link, so a closed composer costs the fleet nothing.
+    placement: procedure
+        .route({
+            method: "GET",
+            path: "/offload/placement",
+            summary: "Which machine a new session should start on",
+            description:
+                "How full this sandbox and each runner on your machines are right now, measured the same way on every one, and the runner a new session should start on instead of here when this machine is busy and another has room. Name the draft's provider and harness: a runner it could not sign in from is never suggested.",
+        })
+        .input(FleetAdviceInputSchema)
+        .output(FleetAdviceSchema),
 };

package/src/contracts/privacy.contract.ts

@@ -2,7 +2,9 @@ import { z } from "zod";
 import { procedure } from "../protocol/route-meta.js";
 import {
     PRIVACY_KNOWN_BATCH_MAX,
+    PRIVACY_IMAGE_ID,
     PrivacyDictionarySchema,
+    PrivacyImagePairSchema,
     PrivacyKnownSourceSchema,
     PrivacyKnownValueSchema,
     PrivacyLedgerEntrySchema,
@@ -57,6 +59,17 @@ export const privacyContract = {
         .meta({ floor: "owner", control: "never", panel: false })
         .input(PrivacyRevealSchema)
         .output(z.record(z.string(), z.string())),
+    image: procedure
+        .route({
+            method: "POST",
+            path: "/privacy/image",
+            summary: "An image before and after masking",
+            description:
+                "The picture as it was and as the shield painted it before it left, for a log entry's image replacement. The picture before holds the personal data, so only the owner may ask. Only the most recent images are kept; an older one answers not found.",
+        })
+        .meta({ floor: "owner", control: "never", panel: false })
+        .input(z.object({ id: z.string().regex(PRIVACY_IMAGE_ID) }))
+        .output(PrivacyImagePairSchema),
     dictionary: procedure
         .route({
             method: "GET",

package/src/contracts/settings.contract.ts

@@ -8,6 +8,7 @@ import {
     MemberAudienceSchema,
     BuiltinPromptTextSchema,
     FieldNotesStatusSchema,
+    GettingStartedSchema,
     REPO_CHECKS_FILE,
     RepoChecksAdoptSchema,
     RepoChecksListSchema,
@@ -142,6 +143,28 @@ export const settingsContract = {
         .meta({ guest: true, floor: "viewer" })
         .input(AudienceAnswerSchema)
         .output(AudienceStateSchema),
+    // Like the audience, a person's own and not a sandbox setting: nobody's choice to put the checklist away or pass a
+    // step over changes another member's screen.
+    gettingStarted: procedure
+        .route({
+            method: "GET",
+            path: "/settings/getting-started",
+            summary: "What you said about the getting-started checklist here",
+            description:
+                "Whether you put the editor's getting-started checklist away on this sandbox, and which of its steps you passed over. Whether a step is done is not kept here: the editor reads that from the sandbox itself.",
+        })
+        .output(GettingStartedSchema),
+    setGettingStarted: procedure
+        .route({
+            method: "POST",
+            path: "/settings/getting-started",
+            summary: "Put away or bring back the getting-started checklist",
+            description:
+                "Replaces what you said about the editor's getting-started checklist on this sandbox: whether it is put away, and which steps you passed over. Other members keep their own.",
+        })
+        .meta({ floor: "viewer" })
+        .input(GettingStartedSchema)
+        .output(GettingStartedSchema),
     adoptRepoChecks: procedure
         .route({
             method: "POST",

package/src/events/agent-events.ts

@@ -10,6 +10,7 @@ import { PromptCacheOpeningSchema, PromptFingerprintSchema } from "../schemas/ke
 import { AgentReplySchema, UsageWindowSchema } from "../schemas/providers/plan-limits.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
 import { RetryLadderSchema } from "../schemas/turn-break.js";
+import { HandedOffSchema, HandoffOfferSchema } from "../schemas/providers/handoff.js";
 import { AgentCommandSchema, browserHelpRequest, capabilityOfferRequest, CapabilityOutcomeSchema, ContextUsageSchema, credentialOfferRequest, CredentialReceiptSchema, pageAskRequest, PageSchema, paymentOfferRequest, PaymentReceiptSchema, PermissionRequestSchema, PlanRequestSchema, QuestionRequestSchema, terminalHelpRequest, TodoItemSchema, ToolCallContentSchema, ToolCallLocationSchema, ToolCallStatusSchema, ToolKindSchema } from "./requests.js";
 import { TranscriptPatchSchema, TranscriptRowSchema, TurnNoteSchema } from "./transcript.js";
 import { agentNoticeEvent, agentStatusEvent } from "./agent-ui.js";
@@ -56,6 +57,8 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // The other half of `preamble`: what a window too small for a full turn left OUT. A note that never rode has no
     // message to be drawn beside, so this is the only place the reader can learn the turn ran thin.
     ContextTrimSchema.extend({ kind: z.literal("context_trim") }),
+    // How a turn a spent allowance held continued the conversation: the whole session, a trimmed copy, or a summary.
+    HandedOffSchema.extend({ kind: z.literal("handoff") }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
     // `prompt` names the parts the cache is keyed on, so a later turn can say which of them changed.
     z.object({ kind: z.literal("init"), model: z.string(), prompt: PromptFingerprintSchema.optional() }),
@@ -92,6 +95,8 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         target: z.string().optional(),
         locations: z.array(ToolCallLocationSchema).optional(),
         content: z.array(ToolCallContentSchema).optional(),
+        // The call's input as bounded JSON text, for a call with no one-line `target` (TranscriptTool.input).
+        input: z.string().optional(),
         parentToolUseId: z.string().optional(),
     }),
     // A later state of a call, correlated by `id`. Status and/or fresh content/locations REPLACE the prior value
@@ -102,6 +107,8 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         status: ToolCallStatusSchema.optional(),
         content: z.array(ToolCallContentSchema).optional(),
         locations: z.array(ToolCallLocationSchema).optional(),
+        // A command's exit code, from a runtime that reports it as a number (TranscriptTool.exitCode).
+        exitCode: z.number().int().optional(),
     }),
     // The agent started running Bash in its live `agent-<id>` tmux session; one per turn, reused across all of a turn's
     // commands including subagents'.
@@ -296,6 +303,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // The privacy shield is on, the provider is untrusted, and the runtime is one it cannot read by content at
                 // all (an ACP agent, Pi), refused before sending; the words wait for a covered provider.
                 "privacy-unshielded",
+                // The turn carries a tool list (an automation's `allowedTools`) and its runtime cannot keep one
+                // (AgentCapabilities.toolAllowlist), refused before sending; the words wait for a runtime that can.
+                "tools-unenforced",
                 // The protected execution-domain policy is unsupported or unreadable; refused before any model/helper ran.
                 "agent-domain-refused",
                 // The privacy shield found personal data in instructions the runtime loads itself, past every channel it
@@ -361,6 +371,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // Set when the owner's policy is already moving this turn to the named account, instead of offering a
                 // press.
                 moving: z.string().optional(),
+                // The ways this turn can continue once its cache is cold, the one the sandbox suggests, and the one a
+                // person picked (schemas/providers/handoff.ts). Absent where there is nothing to carry.
+                handoff: HandoffOfferSchema.optional(),
             })
             .optional(),
         // provider-outage only, while the breaker has tries left: epoch seconds its backoff next lets one through.

package/src/events/agent-words.ts

@@ -1,3 +1,4 @@
+import { oneLine } from "@intentic/base/one-line";
 import type { SubagentVerification } from "../schemas/terminal.js";
 import type { TranscriptAgentWords, TranscriptRow } from "./transcript.js";
 import { needWakeRow } from "./need-wake.js";
@@ -11,11 +12,9 @@ const CHILD_OPENING = "Report from a subagent you started: ";
 // What a report opened with before a spawned agent was called a subagent like every other; still in stored prompts.
 const LEGACY_CHILD_OPENING = "Report from a child agent you started: ";
 
-// The parser reads the first line only, so a title may not break it.
-const oneLine = (text: string): string => text.replaceAll(/\s+/gu, " ").trim();
-
 // `sub-x7` or `sub-x7 ("Port the parser")`.
 const senderOf = (from: string, title: string | undefined): string => {
+    // The parser reads the first line only, so a title may not break it.
     const label = title === undefined ? "" : oneLine(title);
     return label === "" ? `\`${from}\`` : `\`${from}\` ("${label}")`;
 };

package/src/events/resume.test.ts

@@ -1,4 +1,4 @@
-import { RESUME_NOTES, resumeDisclosure, resumeNoticeRow, withResumeNote, withoutResumeNote } from "./resume.js";
+import { RESUME_NOTES, resumeDisclosure, resumeNoteWith, resumeNoticeRow, withResumeNote, withoutResumeNote } from "./resume.js";
 
 // Wrapping then unwrapping a resume note must return the exact original prompt; a mismatch leaks machine narration into
 // the user's own words on screen.
@@ -69,11 +69,23 @@ test("a re-run's notice row names its reason beside its words", () => {
     const disclosure = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.restart));
     expect(disclosure?.kind === "notice" ? resumeNoticeRow(disclosure) : undefined).toEqual({
         role: "notice",
-        text: "The sandbox came back, this turn picked up where it left off.",
+        text: "The sandbox came back; background commands and dev servers this turn started have ended; this turn picked up where it left off.",
         noticeCode: { code: "resumed", params: { reason: "restart" } },
     });
 });
 
+// A restart's re-run also says what the restart cost it; the note stays the prefix, so a prompt from before the tail
+// existed and one carrying it read as the same re-run, and the person's words come back out whole.
+test("a note's tail goes with the note, and a prompt stored without one still reads the same", () => {
+    const note = resumeNoteWith(RESUME_NOTES.restart, "The whole container restarted.\n\n/tmp was emptied.");
+    expect(note).toBe(`${RESUME_NOTES.restart} The whole container restarted.\n/tmp was emptied.`);
+    expect(resumeNoteWith(RESUME_NOTES.restart, undefined)).toBe(RESUME_NOTES.restart);
+    const prompt = withResumeNote("ship the parser\n\nand the lexer", note);
+    expect(withoutResumeNote(prompt)).toBe("ship the parser\n\nand the lexer");
+    expect(resumeDisclosure(prompt)).toEqual(resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.restart)));
+    expect(withoutResumeNote(withResumeNote("ship the parser", RESUME_NOTES.restart))).toBe("ship the parser");
+});
+
 // A Continue on a turn the sandbox kept nothing of sends the note alone: no words of the person's to strip back out, and
 // the row it records is the sandbox's line, never a message from them.
 test("a carried-on turn's note stands alone, leaves no words, and records as a notice", () => {

package/src/events/resume.ts

@@ -17,6 +17,10 @@ export const RESUME_NOTES = {
     limit: `The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again. ${REPEATED}`,
     switched:
         "The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again on a different account, which starts a fresh session. The conversation so far has been carried across above, including the part of the request that was already completed, and the sandbox has measured where the work actually stands (the files changed on this branch, what was verified, what the checklist still holds) in the note headed 'Where the work stands': trust that note over anything recalled, then continue from that point instead of starting over.",
+    // The two cold-cache hand-offs a person can pick (schemas/providers/handoff.ts) besides carrying the session whole.
+    trimmed: `The model provider's usage allowance ran out while this conversation was running, and this turn has been sent again in a copy of the same session, to save re-reading it: every message and tool call is still here, but the output of older tool calls has been cleared (each says so where it was). Run a command or read a file again if you need what it returned. ${REPEATED}`,
+    summarized:
+        "The model provider's usage allowance ran out while this conversation was running, and this turn has been sent again in a fresh session, to save re-reading the old one. A summary of the conversation so far is in the note headed 'Summary of the conversation so far', the most recent part of it is carried across above, and the sandbox has measured where the work actually stands in the note headed 'Where the work stands': trust that note over the summary where they differ, then continue from that point instead of starting over.",
     // `carried` switches account but keeps the session, so REPEATED stays true here, unlike `switched`.
     carried: `The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again on a different account of the same provider, in this same session: everything you knew is still here. ${REPEATED}`,
     refused:
@@ -44,15 +48,34 @@ export const RESUME_NOTES = {
 export const withResumeNote = (prompt: string, note: string): string =>
     Object.values(RESUME_NOTES).some((known) => prompt.startsWith(known)) ? prompt : `${note}\n\n${prompt}`;
 
+/**
+ * A note with what this one re-run alone can say added in its own paragraph's tail: what the restart cost the turn (its
+ * background commands, /tmp, why it happened). The note itself stays the prefix every reader recognises, so a prompt
+ * stored before tails existed, and one with a tail, both read as the same re-run. A tail holds no blank line: the first
+ * one ends the note.
+ */
+export const resumeNoteWith = (note: string, tail: string | undefined): string => {
+    const said = tail?.replaceAll(/\n\s*\n/g, "\n").trim();
+    return said === undefined || said === "" ? note : `${note} ${said}`;
+};
+
 // The user's own words inside a resumed prompt, note and explanation stripped. Returns the prompt unchanged when it
-// isn't a resume, so any attach head can pass through it. A note standing alone (`continued`) leaves no words.
+// isn't a resume, so any attach head can pass through it. A note standing alone (`continued`) leaves no words, and a
+// note's tail (resumeNoteWith) goes with it, up to the blank line that ends it.
 export const withoutResumeNote = (prompt: string): string => {
     const note = Object.values(RESUME_NOTES).find((known) => prompt.startsWith(known));
     if (note === undefined) {
         return prompt;
     }
     const rest = prompt.slice(note.length);
-    return rest.startsWith("\n\n") ? rest.slice(2) : rest;
+    if (rest.startsWith("\n\n")) {
+        return rest.slice(2);
+    }
+    if (!rest.startsWith(" ")) {
+        return rest;
+    }
+    const end = rest.indexOf("\n\n");
+    return end === -1 ? "" : rest.slice(end + 2);
 };
 
 export type ResumeReason = keyof typeof RESUME_NOTES;
@@ -69,12 +92,18 @@ const notice = (reason: ResumeNoticeReason, text: string): ResumeDisclosure => (
 const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
     auth: notice("auth", "Claude sign-in renewed, this turn picked up where it left off."),
     outage: notice("outage", "The model provider came back, this turn picked up where it left off."),
-    restart: notice("restart", "The sandbox came back, this turn picked up where it left off."),
+    // Says what a restart costs a turn, since the turn re-runs as if nothing changed and finds its servers gone.
+    restart: notice(
+        "restart",
+        "The sandbox came back; background commands and dev servers this turn started have ended; this turn picked up where it left off.",
+    ),
     stopped: notice("stopped", "Sent again after the turn stopped short, picking up where it left off."),
     // None of these four auto-resumed, a person pressed Continue; `switched`/`carried` name the differing account.
     limit: notice("limit", "Sent again after the allowance ran out mid-turn, picking up where it left off."),
     switched: notice("switched", "Sent again on the switched account after the allowance ran out mid-turn, in a fresh session."),
     carried: notice("carried", "Sent again on the switched account after the allowance ran out mid-turn, carrying the session with it."),
+    trimmed: notice("trimmed", "Sent again after the allowance ran out, in a copy of the session with older tool output cleared."),
+    summarized: notice("summarized", "Sent again after the allowance ran out, in a fresh session opened with a summary of the conversation."),
     refused: notice("refused", "Sent again after the allowance refused it: nothing had run."),
     door: notice("door", "Sent again: the first attempt was turned away before anything ran."),
     overflow: notice("overflow", "Sent again in a fresh session after the last one outgrew the model's context window."),

package/src/events/sandbox-notice.ts

@@ -26,7 +26,22 @@ const failure = {
 };
 
 // The re-runs a resumed turn's row can name (events/resume.ts); a reason a reader does not know draws the row's text.
-const ResumeNoticeReasonSchema = z.enum(["auth", "outage", "restart", "stopped", "limit", "switched", "carried", "refused", "door", "overflow", "flagged", "continued"]);
+const ResumeNoticeReasonSchema = z.enum([
+    "auth",
+    "outage",
+    "restart",
+    "stopped",
+    "limit",
+    "switched",
+    "carried",
+    "trimmed",
+    "summarized",
+    "refused",
+    "door",
+    "overflow",
+    "flagged",
+    "continued",
+]);
 export type ResumeNoticeReason = z.infer<typeof ResumeNoticeReasonSchema>;
 
 // Every code this build writes, one per sentence shape, each with the facts that shape needs.
@@ -66,6 +81,21 @@ export const SandboxNoticeSchema = z.discriminatedUnion("code", [
     // A turn sent thin for a small window ("16k"): what was left out, and whether the base instructions were swapped too.
     z.object({ code: z.literal("contextTrim"), params: z.object({ window: z.string(), omitted: z.string().optional(), base: z.boolean() }) }),
     z.object({ code: z.literal("resumed"), params: z.object({ reason: ResumeNoticeReasonSchema }) }),
+    // How a turn a spent allowance held continued the conversation (schemas/providers/handoff.ts): `tokens` the context
+    // it started from and `from` the one carrying the session whole would have re-read (both worded, "118k"); `cleared`
+    // older tool outputs a trimmed copy stubbed; `model` the one that wrote a summary. `fellBack` names the hand-off that
+    // was asked for and could not be built, which then went on with the record's short hand-off instead.
+    z.object({
+        code: z.literal("handedOff"),
+        params: z.object({
+            mode: z.enum(["carry", "trim", "summary"]),
+            tokens: z.string().optional(),
+            from: z.string().optional(),
+            cleared: count.optional(),
+            model: z.string().optional(),
+            fellBack: z.boolean().optional(),
+        }),
+    }),
     // An agent's own dependency install starting: into its conversation's own copy (`ownCopy`) or the main tree; the
     // workspace root (`root`) and up to three project folders named (`projects`, each with its slash, already joined),
     // and how many `more` were not named.

package/src/events/transcript.ts

@@ -5,6 +5,7 @@ import { TurnErrandSchema, TurnSpeakerSchema } from "../schemas/speaker.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
 import { NeedSchema } from "../schemas/needs.js";
 import { HeldEndingSchema, RetryLadderSchema } from "../schemas/turn-break.js";
+import { HandoffOfferSchema } from "../schemas/providers/handoff.js";
 import { NoticeCodeSchema } from "./sandbox-notice.js";
 import { TranscriptAgentNoticeSchema } from "./agent-ui.js";
 import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind } from "./requests.js";
@@ -134,6 +135,18 @@ export const TranscriptToolSchema: z.ZodType<TranscriptTool> = z.lazy(() =>
         subagent: TranscriptSubagentSchema.optional().describe(
             "The helper this call started, as the daemon's registry sees it: what it is, how it is going, what it has spent. What a card can say about a backgrounded child whose result is minutes away.",
         ),
+        input: z
+            .string()
+            .optional()
+            .describe(
+                "What the call was given, as JSON text cut to a few kilobytes, on a call whose input names no one-line target: an MCP tool's arguments, a delegation's prompt. Read afterwards to learn what was asked when the card alone cannot say.",
+            ),
+        startedAt: z.number().optional().describe("When the call was seen, in milliseconds. Absent on calls recorded before cards were stamped."),
+        endedAt: z
+            .number()
+            .optional()
+            .describe("When its result arrived, in milliseconds; absent while it runs, and on a call whose result never came."),
+        exitCode: z.number().int().optional().describe("A command's exit code, where the runtime reports one as a number rather than in its output."),
     }),
 );
 // The subagent a call started, on that call's card whichever mechanism started it (transcript-fold.ts places it).
@@ -176,6 +189,10 @@ export interface TranscriptTool {
     nested?: number | undefined;
     thinking?: string | undefined;
     subagent?: TranscriptSubagent | undefined;
+    input?: string | undefined;
+    startedAt?: number | undefined;
+    endedAt?: number | undefined;
+    exitCode?: number | undefined;
 }
 
 // Every ending that wakes a conversation off a condition watch; composing and parsing the wake is watch-wake.ts.
@@ -260,12 +277,17 @@ export const TranscriptRowSchema = z.object({
         .describe(
             "The run that produced this row. Present on everything a turn produced, absent on rows written outside one. A client draws a run's rows over whatever it already holds for that run, which is what this identifies; content cannot, because the last row of a live run keeps growing.",
         ),
-    // The turn's send time (user rows only), not settlement; the only row-moment the daemon actually knows.
+    // The turn's send time (user rows only), not settlement; the agent's rows carry `openedAt` instead.
     sentAt: z
+        .number()
+        .optional()
+        .describe("When it was sent, in milliseconds. On the user's rows only; the agent's own rows and notices carry `openedAt`."),
+    // Stamped by the daemon as it folds the frame that opens the row, since the frames themselves carry no clock.
+    openedAt: z
         .number()
         .optional()
         .describe(
-            "When it was sent, in milliseconds. On the user's rows only, because that is the only moment actually known: a turn's own frames arrive with no clock, so stamping the agent's rows could only ever mean the whole turn's start or end.",
+            "When an assistant bubble or a notice opened, in milliseconds, as the daemon folded the frame that started it. Absent on user rows, which carry `sentAt`, and on rows recorded before rows were stamped.",
         ),
     // A position moves under a rewind and a message's words can repeat, so this is the one name a message keeps.
     messageId: z
@@ -476,6 +498,9 @@ export const TurnEndingSchema = z.object({
                 .describe(
                     "The account the owner's policy is already moving this turn to, when it is; the surface then reports the move rather than offering a press.",
                 ),
+            handoff: HandoffOfferSchema.optional().describe(
+                "How the held turn can continue once its cache is cold: carry the session, trim it, or summarise it, which one the sandbox suggests, and which one a person picked. Absent where there is nothing to carry.",
+            ),
         })
         .optional()
         .describe("Present when the daemon still holds the refused turn whole, so a press re-runs it rather than appending a message after it."),

package/src/index.ts

@@ -188,6 +188,7 @@ export * from "./models/model-order.js";
 export * from "./models/model-offer.js";
 export * from "./models/model-pins.js";
 export * from "./models/model-roles.js";
+export * from "./models/model-setups.js";
 export * from "./models/plan-pools.js";
 export * from "./text/path-refs.js";
 export * from "./text/archives.js";
@@ -224,6 +225,7 @@ export * from "./schemas/extension-updates.js";
 export * from "./schemas/providers/fast-mode.js";
 export * from "./schemas/diff.js";
 export * from "./schemas/git/git.js";
+export * from "./schemas/git/git-scope.js";
 export * from "./schemas/git/git-history.js";
 export * from "./schemas/history.js";
 export * from "./schemas/hosts.js";
@@ -242,7 +244,9 @@ export * from "./schemas/panels.js";
 export * from "./schemas/personas.js";
 export * from "./schemas/privacy.js";
 export * from "./schemas/providers/plan-limits.js";
+export * from "./schemas/providers/handoff.js";
 export * from "./schemas/platform-link.js";
+export * from "./schemas/project-bring-back.js";
 export * from "./schemas/ports.js";
 export * from "./schemas/providers/provider-oauth.js";
 export * from "./schemas/providers/provider-subscriptions.js";
@@ -257,6 +261,7 @@ export * from "./schemas/settings.js";
 export * from "./schemas/settings-history.js";
 export * from "./schemas/share.js";
 export * from "./schemas/shared.js";
+export * from "./schemas/short-codes.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
 export * from "./schemas/state-plan.js";

package/src/models/agent-catalog.test.ts

@@ -29,7 +29,7 @@ describe("every provider/harness pair declares what it can do", () => {
     it.each(pairs)("$provider on the $harness harness", ({ provider, harness }) => {
         const capabilities = capabilitiesOf(provider, harness);
 
-        expect(["claude-code", "codex", "cursor", "opencode", "opencode-gemini", "acp", "pi"]).toContain(capabilities.runtime);
+        expect(["claude-code", "codex", "cursor", "opencode", "opencode-gemini", "acp", "devin", "pi"]).toContain(capabilities.runtime);
         expect(["modes", "plan"]).toContain(capabilities.permissions);
         expect(["full", "tools", "http", "none"]).toContain(capabilities.mcp);
         expect(capabilities.execution).toContain("shell");
@@ -163,11 +163,12 @@ test("every axis a record can lack has words for it", () => {
         rulebook: "none",
         secrets: "none",
         privacy: "none",
+        toolAllowlist: false,
     };
 
-    // Thirteen disclosable axes, thirteen sentences; `fastMode` is disclosed via fastAllowed, and `warm` (keep-warm, off by
+    // Fourteen disclosable axes, fourteen sentences; `fastMode` is disclosed via fastAllowed, and `warm` (keep-warm, off by
     // default) is no limit on the turn itself.
-    expect(limitationsOf(nothing)).toHaveLength(13);
+    expect(limitationsOf(nothing)).toHaveLength(14);
     expect(limitationsOf(nothing).join(" ")).not.toContain("fast");
 });
 

package/src/models/agent-catalog.ts

@@ -106,19 +106,21 @@ export const modesFor = (capabilities: AgentCapabilities): readonly PermissionMo
 export const clampMode = (mode: PermissionMode, capabilities: AgentCapabilities): PermissionMode =>
     modesFor(capabilities).includes(mode) ? mode : "bypassPermissions";
 
+// What each reach of `mcp` leaves out, said once per answer.
+const MCP_LIMITS = {
+    none: ["no MCP tools or plugins"],
+    http: ["MCP servers only, none of the daemon's own tools, no plugins"],
+    tools: ["no plugins"],
+    full: [],
+} as const satisfies Record<AgentCapabilities["mcp"], readonly string[]>;
+
 // What this pair cannot do, phrased for the sender; empty means the full ceiling. `fastMode` is deliberately not
 // disclosed here, since it also depends on the route and model; fastAllowed answers that instead.
 export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.permissions === "plan" ? ["no per-tool approvals"] : []),
     ...(capabilities.questions ? [] : ["no clarifying questions"]),
     ...(capabilities.steering ? [] : ["no mid-turn steering"]),
-    ...(capabilities.mcp === "none"
-        ? ["no MCP tools or plugins"]
-        : capabilities.mcp === "http"
-          ? ["MCP servers only, none of the daemon's own tools, no plugins"]
-          : capabilities.mcp === "tools"
-            ? ["no plugins"]
-            : []),
+    ...MCP_LIMITS[capabilities.mcp],
     ...(capabilities.execution.includes("js") ? [] : ["no code runs, shell only"]),
     ...(capabilities.effort ? [] : ["no effort control"]),
     ...(capabilities.commands ? [] : ["no slash commands"]),
@@ -131,6 +133,7 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.rulebook === "refuse-only" ? ["command rules can refuse but not hold"] : []),
     ...(capabilities.rulebook === "none" ? ["command rules not applied"] : []),
     ...(capabilities.secrets === "none" ? ["secrets reach the model unmasked"] : []),
+    ...(capabilities.toolAllowlist ? [] : ["no tool lists: an automation limited to some tools won't run here"]),
 ];
 
 // Claude's compile-time model floor, shared by daemon and web pre-load; versioned ids only, never a tier alias.