@intentic/sandbox-contract 1.322.0 → 1.324.0

package/src/events/transcript.ts

@@ -6,8 +6,27 @@ import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema }
 import { NeedSchema } from "../schemas/needs.js";
 import { HeldEndingSchema, RetryLadderSchema } from "../schemas/turn-break.js";
 import { NoticeCodeSchema } from "./sandbox-notice.js";
-import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind} from "./requests.js";
-import { browserHelpRequest, capabilityOfferRequest, CapabilityOutcomeSchema, credentialOfferRequest, CredentialReceiptSchema, paymentOfferRequest, PaymentReceiptSchema, PermissionAskSchema, permissionRequest, planRequest, questionRequest, terminalHelpRequest, TodoItemSchema, ToolCallContentSchema, ToolCallLocationSchema, ToolCallStatusSchema, ToolKindSchema } from "./requests.js";
+import { TranscriptAgentNoticeSchema } from "./agent-ui.js";
+import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind } from "./requests.js";
+import {
+    browserHelpRequest,
+    capabilityOfferRequest,
+    CapabilityOutcomeSchema,
+    credentialOfferRequest,
+    CredentialReceiptSchema,
+    paymentOfferRequest,
+    PaymentReceiptSchema,
+    PermissionAskSchema,
+    permissionRequest,
+    planRequest,
+    questionRequest,
+    terminalHelpRequest,
+    TodoItemSchema,
+    ToolCallContentSchema,
+    ToolCallLocationSchema,
+    ToolCallStatusSchema,
+    ToolKindSchema,
+} from "./requests.js";
 
 // A conversation as recorded and replayed: the rows, the cards they carry, and the patches that change them while a
 // turn runs. One shape for the live row and the recorded one, since they're the same row.
@@ -19,7 +38,8 @@ export const PlanStatusSchema = z.enum(["pending", "approved", "rejected", "canc
 export type PlanStatus = z.infer<typeof PlanStatusSchema>;
 export const QuestionStatusSchema = z.enum(["pending", "answered", "cancelled"]);
 export type QuestionStatus = z.infer<typeof QuestionStatusSchema>;
-export const PermissionStatusSchema = z.enum(["pending", "allowed", "always", "denied", "cancelled"]);
+// `everything`: allowed by a conversation-wide yes, the one given on this card or one already standing.
+export const PermissionStatusSchema = z.enum(["pending", "allowed", "always", "everything", "denied", "cancelled"]);
 export type PermissionStatus = z.infer<typeof PermissionStatusSchema>;
 export const HelpStatusSchema = z.enum(["pending", "helped", "declined", "cancelled"]);
 export type HelpStatus = z.infer<typeof HelpStatusSchema>;
@@ -38,10 +58,17 @@ export const TranscriptQuestionSchema = z.object({
         .record(z.string(), z.array(z.string()))
         .optional()
         .describe("What was chosen, keyed by the question, with the chosen labels or the user's own words."),
+    attachments: z
+        .record(z.string(), z.array(z.string()))
+        .optional()
+        .describe("Files the user attached to their own-words answer, keyed by the question, as workspace-relative paths."),
 });
 export type TranscriptQuestion = z.infer<typeof TranscriptQuestionSchema>;
 // `explain`, the judge's sentence, arrives via PermissionAskSchema at raise time; nothing patches it in after.
-export const TranscriptPermissionSchema = PermissionAskSchema.extend({ ...permissionRequest, status: PermissionStatusSchema.describe("Where the decision stands.") });
+export const TranscriptPermissionSchema = PermissionAskSchema.extend({
+    ...permissionRequest,
+    status: PermissionStatusSchema.describe("Where the decision stands."),
+});
 export type TranscriptPermission = z.infer<typeof TranscriptPermissionSchema>;
 export const TranscriptBrowserHelpSchema = z.object({ ...browserHelpRequest, status: HelpStatusSchema.describe("How the hand-over ended.") });
 export type TranscriptBrowserHelp = z.infer<typeof TranscriptBrowserHelpSchema>;
@@ -297,15 +324,16 @@ export const TranscriptRowSchema = z.object({
         .optional()
         .describe("The wait this notice describes, by name, so a reader can say whether it is still on."),
     // Which one, for a wait whose kind can have several in flight at once; without it two armed watches settle together.
-    noticeWaitId: z
-        .string()
-        .optional()
-        .describe("Which instance of the wait this notice names, for a kind that can have several running at once."),
+    noticeWaitId: z.string().optional().describe("Which instance of the wait this notice names, for a kind that can have several running at once."),
     // The sandbox's own notice by name, beside its English `text` (sandbox-notice.ts); absent on every other row, and
     // on the notices written before rows carried it, which a reader draws from `text` as it always did.
     noticeCode: NoticeCodeSchema.optional().describe(
         "Which of the sandbox's own notices this row is, and the facts it was worded from, so a reader can say it in the reader's own language. The text stays the English sentence.",
     ),
+    // A notice a runtime's own extension or loop said (events/agent-ui.ts), the words in `text`; absent on every other row.
+    agentNotice: TranscriptAgentNoticeSchema.optional().describe(
+        "This notice was said by the agent's runtime or one of its extensions rather than by the sandbox: how loud, and who said it.",
+    ),
     // At most one card per row; a card closes its bubble. One field per kind, so a reader reaches it by name.
     plan: TranscriptPlanSchema.optional().describe("The plan this row asked approval for, and the answer."),
     question: TranscriptQuestionSchema.optional().describe("The questions this row asked, and the picks that answered them."),
@@ -321,7 +349,9 @@ export const TranscriptRowSchema = z.object({
         "Something the agent asked a person for, as it was when raised. Its live state (answered, met) is read by its id, since it outlives the turn.",
     ),
     needWake: TranscriptNeedWakeSchema.optional().describe("The answered need that reached this conversation, and the prompt it came as."),
-    agentWords: TranscriptAgentWordsSchema.optional().describe("Another agent's words that reached this conversation, whose they are, and the prompt they came as."),
+    agentWords: TranscriptAgentWordsSchema.optional().describe(
+        "Another agent's words that reached this conversation, whose they are, and the prompt they came as.",
+    ),
     backgroundJob: TranscriptBackgroundJobSchema.optional().describe("The background job this row marks the start of."),
     credentialOffer: TranscriptCredentialOfferSchema.optional().describe(
         "The gated credential this row asked to use, who may release it, and who did.",
@@ -352,10 +382,25 @@ export const isAwaitingDecision = (row: TranscriptRequests): boolean => REQUEST_
 // everything else replaces its row; `drop` removes a row that opened and never wrote.
 export const TranscriptPatchSchema = z.discriminatedUnion("op", [
     z.object({ op: z.literal("append").describe("A new row at the end."), row: TranscriptRowSchema }),
-    z.object({ op: z.literal("replace").describe("This row, whole, in place of the one at that index."), index: z.number().int().nonnegative(), row: TranscriptRowSchema }),
-    z.object({ op: z.literal("drop").describe("The row at that index is gone: it was opened and never written into."), index: z.number().int().nonnegative() }),
-    z.object({ op: z.literal("text").describe("More of the agent's prose, onto that row's text."), index: z.number().int().nonnegative(), text: z.string() }),
-    z.object({ op: z.literal("thinking").describe("More of the agent's reasoning, onto that row's thinking."), index: z.number().int().nonnegative(), text: z.string() }),
+    z.object({
+        op: z.literal("replace").describe("This row, whole, in place of the one at that index."),
+        index: z.number().int().nonnegative(),
+        row: TranscriptRowSchema,
+    }),
+    z.object({
+        op: z.literal("drop").describe("The row at that index is gone: it was opened and never written into."),
+        index: z.number().int().nonnegative(),
+    }),
+    z.object({
+        op: z.literal("text").describe("More of the agent's prose, onto that row's text."),
+        index: z.number().int().nonnegative(),
+        text: z.string(),
+    }),
+    z.object({
+        op: z.literal("thinking").describe("More of the agent's reasoning, onto that row's thinking."),
+        index: z.number().int().nonnegative(),
+        text: z.string(),
+    }),
     z.object({
         op: z.literal("toolThinking").describe("More of a delegated subagent's reasoning, onto the thinking of the card that started it."),
         index: z.number().int().nonnegative(),
@@ -391,26 +436,41 @@ export const TurnEndingSchema = z.object({
     resetsAt: z
         .number()
         .optional()
-        .describe("When the spent allowance reopens, in epoch seconds. Absent for every ending that names no instant, and for a provider that publishes none."),
+        .describe(
+            "When the spent allowance reopens, in epoch seconds. Absent for every ending that names no instant, and for a provider that publishes none.",
+        ),
     held: z
         .object({
-            ran: z.boolean().describe("Whether the held turn got anywhere before it was refused, which is a different sentence from one refused at the door."),
+            ran: z
+                .boolean()
+                .describe("Whether the held turn got anywhere before it was refused, which is a different sentence from one refused at the door."),
             contextTokens: z
                 .number()
                 .optional()
-                .describe("How much context a press that keeps the session re-reads once, on this account at the reset or carried to another. Absent when no usage frame measured it."),
+                .describe(
+                    "How much context a press that keeps the session re-reads once, on this account at the reset or carried to another. Absent when no usage frame measured it.",
+                ),
             handoffTokens: z
                 .number()
                 .optional()
-                .describe("What a press that opens a fresh session pays instead: the capped record plus the sandbox's measured brief, counted at the failure."),
-            moving: z.string().optional().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."),
+                .describe(
+                    "What a press that opens a fresh session pays instead: the capped record plus the sandbox's measured brief, counted at the failure.",
+                ),
+            moving: z
+                .string()
+                .optional()
+                .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.",
+                ),
         })
         .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."),
     scheduled: z
         .boolean()
         .optional()
-        .describe("Whether something other than the user is already booked to send this turn again, so the surface reports the wait instead of offering a press."),
+        .describe(
+            "Whether something other than the user is already booked to send this turn again, so the surface reports the wait instead of offering a press.",
+        ),
     // `resetsAt` is the provider's fact about the allowance; this is the daemon's own appointment, and the two differ
     // whenever a ladder rung falls short of the reset, or an ending with no allowance at all is armed.
     nextAt: z
@@ -440,7 +500,11 @@ export const AgentTranscriptSchema = SessionTranscriptSchema.extend({
         "How the last turn ended, when it left work behind that one press finishes. Absent for a conversation whose last turn ended on its own, and for the failures that name something to repair first.",
     ),
     // `from` offsets every `rewindIndex` here, and is the `before` for the page above; `more` flags older messages.
-    from: z.number().int().nonnegative().describe("Where the first message sits in the whole record, and the `before` that asks for the page above this one."),
+    from: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Where the first message sits in the whole record, and the `before` that asks for the page above this one."),
     more: z.boolean().describe("Whether older messages precede this page."),
 });
 

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

@@ -90,6 +90,33 @@
     "server": {
       "description": "What a terminal socket sends as JSON text; the pane's own bytes travel as binary messages.",
       "oneOf": [
+        {
+          "description": "The shared pane's grid. Viewport resize requests remain the viewer's own available size.",
+          "properties": {
+            "cols": {
+              "format": "uint16",
+              "maximum": 65535,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "rows": {
+              "format": "uint16",
+              "maximum": 65535,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "type": {
+              "const": "grid",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type",
+            "cols",
+            "rows"
+          ],
+          "type": "object"
+        },
         {
           "description": "The session is over, and the browser must not reconnect; `reason` is tmux's own words when it had any.",
           "properties": {

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

@@ -49,4 +49,4 @@ export type TerminalClientMessage = { "type": "input", data: string, } | { "type
 /**
  * What a terminal socket sends as JSON text; the pane's own bytes travel as binary messages.
  */
-export type TerminalServerMessage = { "type": "exit", code: number, reason?: string, } | { "type": "pong" };
+export type TerminalServerMessage = { "type": "grid", cols: number, rows: number, } | { "type": "exit", code: number, reason?: string, } | { "type": "pong" };

package/src/index.ts

@@ -31,6 +31,7 @@ import { publicContract } from "./contracts/public.contract.js";
 import { netdiskContract } from "./contracts/netdisk.contract.js";
 import { providersContract } from "./contracts/providers.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
+import { privacyContract } from "./contracts/privacy.contract.js";
 import { safetyContract } from "./contracts/safety.contract.js";
 import { needsContract } from "./contracts/needs.contract.js";
 import { secretsContract } from "./contracts/secrets.contract.js";
@@ -95,6 +96,7 @@ export { portsContract } from "./contracts/ports.contract.js";
 export { publicContract } from "./contracts/public.contract.js";
 export { providersContract, type RunnableProviders, RunnableProvidersSchema } from "./contracts/providers.contract.js";
 export { pushContract } from "./contracts/push.contract.js";
+export { privacyContract } from "./contracts/privacy.contract.js";
 export { safetyContract } from "./contracts/safety.contract.js";
 export { needsContract } from "./contracts/needs.contract.js";
 export { secretsContract } from "./contracts/secrets.contract.js";
@@ -111,6 +113,7 @@ export { vpnContract } from "./contracts/vpn.contract.js";
 export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
 export * from "./events/agent-events.js";
+export * from "./events/agent-ui.js";
 export * from "./events/agent-words.js";
 export * from "./events/requests.js";
 export * from "./events/resume.js";
@@ -216,7 +219,9 @@ export * from "./schemas/marketplace.js";
 export * from "./schemas/metrics.js";
 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/platform-link.js";
 export * from "./schemas/ports.js";
 export * from "./schemas/providers/provider-oauth.js";
 export * from "./schemas/providers/provider-subscriptions.js";
@@ -277,6 +282,7 @@ export const sandboxContract = {
     endpoints: endpointsContract,
     extensions: extensionsContract,
     personas: personasContract,
+    privacy: privacyContract,
     safety: safetyContract,
     sessions: sessionsContract,
     settings: settingsContract,

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

@@ -162,6 +162,7 @@ test("every axis a record can lack has words for it", () => {
         skillDiscovery: "prompt",
         rulebook: "none",
         secrets: "none",
+        privacy: "none",
     };
 
     // Thirteen disclosable axes, thirteen sentences; `fastMode` is disclosed via fastAllowed, and `warm` (keep-warm, off by

package/src/models/agent-runtimes.ts

@@ -51,6 +51,11 @@ export interface AgentCapabilities {
     readonly rulebook: "hooks" | "approval" | "refuse-only" | "none";
     // Whether a credential is masked; "none" is structural, only the Claude Code loop can rewrite a model's read.
     readonly secrets: "masked" | "none";
+    // Whether the privacy shield can stand between this loop and its provider: `gateway` when the daemon names the base
+    // URL the loop sends its model requests to (so the gateway reads and masks every byte of them), `none` when the loop
+    // talks to its provider on a wire or a configuration the daemon does not own. A `none` loop on an untrusted provider
+    // is refused while the shield is on.
+    readonly privacy: "gateway" | "none";
 }
 
 // The Claude Code Agent SDK loop, the ceiling every other runtime is measured against: the only one that owns the whole
@@ -75,6 +80,8 @@ export const CLAUDE_CODE: AgentCapabilities = {
     // The only runtime with its own pre-execution hook, so the only one where a hold can park instead of refusing.
     rulebook: "hooks",
     secrets: "masked",
+    // Every request goes to ANTHROPIC_BASE_URL, which the daemon sets per turn.
+    privacy: "gateway",
 };
 
 // Codex app-server: item-level events, the turn's remote MCP servers over http, and four seams (steer, a question
@@ -100,6 +107,8 @@ export const CODEX: AgentCapabilities = {
     // Asked only when the owner has written command rules; an unconfigured workspace pays nothing for it.
     rulebook: "approval",
     secrets: "none",
+    // Its model provider's base_url is the daemon's, written into the per-thread config.
+    privacy: "gateway",
 };
 
 // OpenCode (the Grok runtime): its own agentic loop and tools, with the turn's remote MCP servers mounted on the shared
@@ -126,6 +135,8 @@ export const OPENCODE: AgentCapabilities = {
     // hold parked on a card while the turn's inactivity watchdog is held.
     rulebook: "approval",
     secrets: "none",
+    // The shared server's provider baseURLs are written by the daemon at spawn.
+    privacy: "gateway",
 };
 
 // The same OpenCode loop, serving Gemini instead of xAI, identical abilities. The Claude Code loop announces itself in
@@ -157,6 +168,8 @@ export const ACP: AgentCapabilities = {
     // In the protocol floor, so every agent has it; which calls it asks about is entirely its own choice.
     rulebook: "approval",
     secrets: "none",
+    // The agent picks its own provider and endpoint from its own login and environment.
+    privacy: "none",
 };
 
 // Pi driven over its RPC mode: above the ACP floor and below the Claude Code ceiling. Real mid-turn steering, an effort
@@ -181,6 +194,8 @@ export const PI: AgentCapabilities = {
     // The one runtime with no seam at all: bash runs in-process, and no rule the owner writes can apply.
     rulebook: "none",
     secrets: "none",
+    // Pi calls its provider from its own login; the daemon names no endpoint.
+    privacy: "none",
 };
 
 // Cursor's own runtime, driven through `@cursor/sdk` from this daemon's process; an embedding surface, so most seams
@@ -219,4 +234,6 @@ export const CURSOR: AgentCapabilities = {
     rulebook: "hooks",
     // none, structurally: its hooks only allow/deny or are discarded, nothing here to substitute a reference into.
     secrets: "none",
+    // Cursor's own RPC to its own servers, which then reach the model: redirectable, not readable.
+    privacy: "none",
 };

package/src/models/capability-ledger.test.ts

@@ -34,6 +34,9 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     rulebook: "enforced",
     // agent/run/turn/cache-keepwarm.ts files nothing to keep warm for a turn whose runtime lacks it.
     warm: "enforced",
+    // agent/run/decide/turn-decision.ts refuses a "none" runtime on an untrusted provider while the privacy shield is
+    // on; "gateway" runtimes get the daemon's gateway as their base URL (privacy/gateway).
+    privacy: "enforced",
 
     // Descriptive: true of the runtime but nothing consults these; wiring one up moves it to enforced.
     questions: "descriptive",

package/src/policy/request-status.ts

@@ -1,4 +1,4 @@
-import { REQUEST_FIELDS, type RequestField, type TranscriptRequests, type TranscriptRow } from "../events/transcript.js";
+import { type PermissionStatus, REQUEST_FIELDS, type RequestField, type TranscriptRequests, type TranscriptRow } from "../events/transcript.js";
 import type { AgentReply } from "../schemas/providers/plan-limits.js";
 import { startedChildCard } from "../events/child-run.js";
 
@@ -7,6 +7,21 @@ import { startedChildCard } from "../events/child-run.js";
 // of the wrong kind cannot settle a card of another, since requestId is what matches them.
 type Cards = { -readonly [K in RequestField]?: TranscriptRow[K] };
 
+// A permission card's ending, from the reply that released it: each kind of yes keeps its own word.
+const permissionStatusOf = (reply: AgentReply | undefined): PermissionStatus => {
+    if (reply?.kind !== "permission") {
+        return "cancelled";
+    }
+    switch (reply.decision) {
+        case "deny":
+            return "denied";
+        case "once":
+            return "allowed";
+        default:
+            return reply.decision;
+    }
+};
+
 export const settledRequests = (cards: TranscriptRequests, reply: AgentReply | undefined): TranscriptRequests => {
     const out: Cards = {};
     const { plan, question, permission, browserHelp, terminalHelp, capabilityOffer, paymentOffer, credentialOffer } = cards;
@@ -15,23 +30,18 @@ export const settledRequests = (cards: TranscriptRequests, reply: AgentReply | u
     }
     if (question !== undefined) {
         const answers = reply?.kind === "question" ? reply.answers : undefined;
+        const attachments = reply?.kind === "question" ? reply.attachments : undefined;
         out.question = {
             ...question,
             status: reply?.kind === "question" && reply.cancelled !== true ? "answered" : "cancelled",
             ...(answers === undefined ? {} : { answers }),
+            ...(attachments === undefined ? {} : { attachments }),
         };
     }
     if (permission !== undefined) {
         out.permission = {
             ...startedChildCard(permission, reply),
-            status:
-                reply?.kind !== "permission"
-                    ? "cancelled"
-                    : reply.decision === "deny"
-                      ? "denied"
-                      : reply.decision === "always"
-                        ? "always"
-                        : "allowed",
+            status: permissionStatusOf(reply),
         };
     }
     if (browserHelp !== undefined) {

package/src/policy/turned-away.ts

@@ -11,6 +11,8 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "unknown-command",
     "context-window-too-small",
     "model-helper-only",
+    // The privacy shield refused an untrusted provider on a runtime it cannot stand in front of.
+    "privacy-unshielded",
     "sandbox-memory-low",
     "trial-unavailable",
     "trial-model-unavailable",

package/src/protocol/raw-routes.ts

@@ -8,6 +8,9 @@ import { runnerTranslatorPath } from "./runner-protocol.js";
 export const RAW_ROUTES = {
     // The "is a daemon there" probe every flow uses; it names the sandbox and says whether it is still converging.
     "GET /health": { auth: "door", beforeBoot: true },
+    // A person opening this sandbox's own address in a browser: sent to the app's /open on it, the address being what
+    // they may still hold when the platform has lost the rest. Anything else gets the same 401 as before it existed.
+    "GET /": { auth: "door", beforeBoot: true },
     "GET /diff/raw": { lane: "bulk" },
     // Arming the dictation model is a read any tier makes; dictating is writing a message, the collaborator's grant.
     "GET /speech/status": { guest: true },
@@ -59,6 +62,8 @@ export const RAW_ROUTES = {
     "POST /members": { control: "never" },
     "DELETE /members": { control: "never" },
     "DELETE /members/self": { floor: "viewer", guest: true, control: "never" },
+    // The owner's Reconnect: register with the platform now, having it adopt the sandbox first when it holds no record.
+    "POST /platform/relink": { control: "never" },
     "GET /environment": {},
     "GET /environment/contents": {},
     "POST /environment/approve": {},
@@ -153,6 +158,10 @@ export const RAW_ROUTES = {
     "POST /system/runners/credentials": { auth: "door", control: "never" },
     "POST /system/runners/credentials/refresh": { auth: "door", control: "never" },
     [`ALL ${runnerTranslatorPath}/*` as const]: { auth: "door", control: "never" },
+    // The privacy shield's gateway: every shielded runtime's model requests, on the signed session its base URL carries
+    // (privacy/gateway/session-token.ts), which names the provider and the only upstream it may forward to. Held open
+    // while a model streams its answer.
+    "ALL /privacy/gateway/{session}/*": { auth: "door", control: "never", stream: true },
     "POST /system/control/tokens": { control: "never" },
     "GET /system/control/tokens": { control: "never" },
     "DELETE /system/control/tokens/{id}": { control: "never" },

package/src/schemas/agent.ts

@@ -304,15 +304,28 @@ const AgentTurnFieldsSchema = z.object({
     editorContext: EditorContextSchema.optional().describe(
         'What the user has open in their editor, folded into the prompt so that pointing words like "this" resolve.',
     ),
-    // The composer's scheduled send: a person who knows the account is spent books the message for its reopen instead of
-    // sending it into a refusal. Held in the conversation's queue, never started early; the queue's `until` is this.
+    // The composer's scheduled send: a time the person chose, or a spent account's reopen they would rather wait for than
+    // send into a refusal. Held in the conversation's queue, never started early; the queue's `until` is this.
     sendAt: z
         .number()
         .int()
         .positive()
         .optional()
         .describe(
-            "Hold this message until then (epoch milliseconds) instead of starting a turn now, for an allowance you know is spent. It waits in the conversation's queue, where it can be sent early, reworded or removed, and goes by itself at that instant. Ignored when already past, or when a turn is running.",
+            "Hold this message until then (epoch milliseconds) instead of starting a turn now: a time you chose, or the reopen of an allowance you know is spent. It waits in the conversation's queue, where it can be sent early, reworded, rescheduled or removed, and goes by itself at that instant, even for a conversation this message opens or one whose turn is running now. Ignored when already past; at most a month ahead.",
+        ),
+    // The other scheduled send: work that builds on another agent's, held until that agent's work is in the workspace.
+    // Held in the queue like `sendAt`; the queue's `after` is this. Never both: a hold waits on exactly one thing.
+    sendAfter: ConversationIdSchema.optional().describe(
+        "Hold this message until the conversation named here has finished and all of its work has landed in the workspace, instead of starting a turn now: for work that builds on another agent's. It waits in this conversation's queue, where it can be sent early, reworded, rescheduled or removed. Sent at once when that conversation has nothing running and nothing left to land.",
+    ),
+    // Decided like `isolated`: the opening turn's answer, latched on the entry it opens. A maintainer's alone, since the
+    // standing answer it sets is what `agents.autoLand` sets, and that route is a maintainer's.
+    conversationAutoLand: z
+        .boolean()
+        .optional()
+        .describe(
+            "Whether this conversation's finished work merges into the workspace by itself from now on: its own answer to the sandbox-wide setting, the one `agents.autoLand` changes later. Read only from the message that opens the conversation, and only from a maintainer. Unlike `autoLand`, it holds for every later turn.",
         ),
 });
 export const AgentTurnSchema = AgentTurnFieldsSchema
@@ -335,8 +348,24 @@ export const AgentTurnSchema = AgentTurnFieldsSchema
     // "then" needs a checkout of its own; rolling back the shared tree under everyone else is what it must never mean.
     .refine((turn) => turn.forkOf?.files !== "then" || turn.isolated === true, {
         message: 'forkOf.files "then" requires isolated',
+    })
+    .refine((turn) => turn.sendAt === undefined || turn.sendAfter === undefined, {
+        message: "sendAt and sendAfter are two different holds: name one",
+    })
+    .refine((turn) => turn.sendAfter === undefined || turn.sendAfter !== turn.conversationId, {
+        message: "a conversation cannot wait for its own work to land",
     });
 export type AgentTurn = z.infer<typeof AgentTurnSchema>;
+// What `agent.run` takes: a turn, plus the one field only a request carries and no stored turn keeps. A daemon from before
+// `continues` reads past it and takes `prompt` as the words, which is why a client still sends some.
+export const AgentRunSchema = AgentTurnSchema.safeExtend({
+    continues: z
+        .literal(true)
+        .optional()
+        .describe(
+            "Carry the conversation on from where its last turn stopped instead of saying anything: nothing of yours is added to the conversation, and `prompt` is ignored. A turn the sandbox still holds runs again as it was; otherwise the agent is told to continue in its own session. Refused while a turn is running.",
+        ),
+});
 // What a turn naming no provider or loop runs on, stated once. Applied where a request comes in (the daemon's turn port),
 // so nothing downstream defaults them again: the engine takes a turn with both named (withRuntimeDefaults).
 /** A turn with its provider and loop named, as the engine takes it past the door. */
@@ -491,12 +520,15 @@ export const ConversationQueueSchema = z.object({
     items: z.array(QueuedMessageSchema).describe("What waits, in the order it goes out."),
     revision: z.number().int().nonnegative().describe("Moves with every change to the queue, so of two copies the higher is the newer."),
     paused: QueuePauseSchema.optional().describe(
-        "Why nothing goes out by itself: somebody stopped the turn, the turn these messages started was refused before it ran, or they were scheduled for later. Resuming lets them go, and so does sending another message unless they are scheduled.",
+        "Why nothing goes out by itself: somebody stopped the turn, the turn these messages started was refused before it ran, or they were scheduled for a time or for after another conversation's work lands. Resuming lets them go, and so does sending another message.",
     ),
     until: z
         .number()
         .optional()
         .describe("When scheduled messages go out by themselves, in milliseconds. Only on a queue paused as `scheduled`."),
+    after: ConversationIdSchema.optional().describe(
+        "The conversation whose finished work must land before scheduled messages go out by themselves. Only on a queue paused as `scheduled`, in place of `until`.",
+    ),
 });
 export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;
 // What resuming a queue did: started a turn with what waited, when nothing else ran.

package/src/schemas/agents.ts

@@ -89,12 +89,14 @@ export const UnfinishedWorkSchema = z.object({
         })
         .optional()
         .describe("The agent's own checklist where that turn left it. Absent for a conversation that kept no list."),
-    // Name of the `turn.ending` check still failing when the turn ended. Retired with that check: nothing writes it now, and
-    // it stays so entries written before still read.
+    // Name of the `turn.ending` check still failing when the turn ended, from when a failing one left the work unfinished.
+    // Nothing writes it now, and it stays so entries written before still read.
     check: z
         .string()
         .optional()
-        .describe("The end-of-turn check that was still failing when the turn ended, by name. No longer written: nothing checks inside a turn."),
+        .describe(
+            "The end-of-turn check that was still failing when the turn ended, by name. No longer written: what a check finds as a turn ends is said back to the model and never leaves its work unfinished.",
+        ),
 });
 export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
 // What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
@@ -357,7 +359,7 @@ export const AgentSummarySchema = z.object({
     // Root repo's short base sha; per-repo bases stay daemon-internal.
     base: z.string().optional().describe("The commit its private copy started from, shortened."),
     costUsd: z.number().optional().describe("What it has cost so far, in dollars. A subagent's spend is its own and is not folded in here."),
-    inputTokens: z.number().optional().describe("Tokens sent."),
+    inputTokens: z.number().optional().describe("Uncached input tokens, excluding cache reads and cache writes."),
     outputTokens: z.number().optional().describe("Tokens received."),
     contextTokens: z.number().optional().describe("How much of the window the conversation currently fills."),
     contextWindow: z.number().optional().describe("How large that window is."),
@@ -616,6 +618,17 @@ export const AgentSummarySchema = z.object({
                     .describe(
                         "Who stopped it: the sandbox, when the turn that used it ended without handing it over; a person; or the agent itself. Present from the moment the stop is asked. Absent for a job that exited by itself.",
                     ),
+                // agent/tools/jobs/input-wait.ts: told from /proc, never from what it printed, since a prompt can go
+                // straight to the terminal or sit in a pipe.
+                inputWait: z
+                    .object({
+                        since: z.number().describe("When it went still, in milliseconds."),
+                        program: z.string().describe("The process blocked reading the terminal, as its command line."),
+                    })
+                    .optional()
+                    .describe(
+                        "Present while it sits blocked reading its terminal with nothing moving: a prompt nobody in the sandbox will answer, which only stopping it or a person typing into its terminal ends. Absent while it runs on, and once it ends.",
+                    ),
             }),
         )
         .optional()