@intentic/sandbox-contract 1.316.0 → 1.317.0

package/src/contracts/needs.contract.ts

@@ -0,0 +1,103 @@
+import { procedure } from "../protocol/route-meta.js";
+import { OkSchema } from "../schemas/shared.js";
+import {
+    GrantRevokeSchema,
+    NeedAnswerInputSchema,
+    NeedIdParamSchema,
+    NeedRaisedSchema,
+    NeedRaiseSchema,
+    NeedSchema,
+    NeedSecretInputSchema,
+    NeedsListSchema,
+    NeedsQuerySchema,
+    StandingGrantsSchema,
+} from "../schemas/needs.js";
+
+// Needs (docs/architecture/needs.md): the agent's CLIs raise and withdraw them on the agent token; a person reads and
+// answers them from the chat, the board and the Needs you inbox. Answering is the operating tier's, like the capability
+// and secret routes an answer ends up writing through.
+
+const agentDoor = procedure.meta({ agent: true, control: "never" });
+const answerRoute = procedure.meta({ floor: "maintainer", control: "never" });
+
+export const needsContract = {
+    ask: agentDoor
+        .route({
+            method: "POST",
+            path: "/needs/ask",
+            summary: "Ask a person for something the task needs",
+            description:
+                "Raises a need in the conversation the calling shell belongs to and holds the call up to `wait` seconds for an answer. Answers `met` when it is usable now (or already was), `open` when it is still waiting, and `refused` when nothing was raised or a person declined. An open need's answer reaches the conversation by itself.",
+        })
+        // Held open while the person decides, by design.
+        .meta({ stream: true })
+        .input(NeedRaiseSchema)
+        .output(NeedRaisedSchema),
+    mine: agentDoor
+        .route({
+            method: "GET",
+            path: "/needs/mine",
+            summary: "This conversation's needs",
+            description: "Every need the calling shell's conversation raised, newest first, open or answered.",
+        })
+        .output(NeedsListSchema),
+    withdraw: agentDoor
+        .route({
+            method: "POST",
+            path: "/needs/{id}/withdraw",
+            summary: "Withdraw a need",
+            description: "Closes one of this conversation's open needs because the task no longer needs it. Its card says so.",
+        })
+        .input(NeedIdParamSchema)
+        .output(NeedSchema),
+    list: procedure
+        .route({
+            method: "GET",
+            path: "/needs",
+            summary: "What agents are waiting on people for",
+            description: "Needs across the sandbox, or one conversation's, newest first. Never a secret's value.",
+        })
+        .input(NeedsQuerySchema)
+        .output(NeedsListSchema),
+    answer: answerRoute
+        .route({
+            method: "POST",
+            path: "/needs/{id}/answer",
+            summary: "Answer a need",
+            description:
+                "Declines it, or says yes the way its card offered: accept a connection being set up, apply a change, grant for this conversation or the persona, release a gated credential, approve an environment proposal. A release is refused from anyone the gate does not name.",
+        })
+        .input(NeedAnswerInputSchema)
+        .output(NeedSchema),
+    provideSecret: answerRoute
+        .route({
+            method: "POST",
+            path: "/needs/{id}/secret",
+            summary: "Give a secret a need asked for",
+            description:
+                "Stores the value under the name the need asked for and meets it. The value goes to the sandbox's secret store and nowhere else: not the answer, not the transcript, not a log.",
+        })
+        // Puts a credential in motion: withheld from the panel token.
+        .meta({ panel: false })
+        .input(NeedSecretInputSchema)
+        .output(NeedSchema),
+    grants: answerRoute
+        .route({
+            method: "GET",
+            path: "/needs/grants",
+            summary: "The yeses still standing",
+            description:
+                "What people allowed conversations beyond their persona or area, and the gated credentials released to them, by conversation. Names only, never a value.",
+        })
+        .output(StandingGrantsSchema),
+    revokeGrant: answerRoute
+        .route({
+            method: "POST",
+            path: "/needs/grants/revoke",
+            summary: "Take a yes back",
+            description:
+                "Takes back one grant or one release. The conversation's next turn runs without it; a turn already running keeps what it mounted.",
+        })
+        .input(GrantRevokeSchema)
+        .output(OkSchema),
+};

package/src/contracts/secrets.contract.ts

@@ -7,6 +7,8 @@ import {
     CredentialRequestSchema,
     SecretInventorySchema,
     SecretKeyParamSchema,
+    SecretGeneratedSchema,
+    SecretGenerateSchema,
     SecretKeysSchema,
     SecretRevealSchema,
     SecretSetSchema,
@@ -16,8 +18,8 @@ import { OkSchema } from "../schemas/shared.js";
 // Credentials are the operating tier's, reads included: maintainer is the highest revokable grant, and no token's.
 const secretRoute = procedure.meta({ floor: "maintainer", control: "never" });
 
-// User-supplied secrets, in the gitignored desired-state/.env; `apply` reloads them, no restart. `inventory` aggregates
-// every store (never values) and always answers; the rest refuse until desired-state is scaffolded. `reveal` alone
+// User-supplied secrets, in the gitignored desired-state/.env once DevOps is active and the sandbox's own store before
+// it; `apply` reloads them, no restart. `inventory` aggregates every store (never values) and always answers. `reveal` alone
 // returns a value, owner-only, POST so the key avoids the URL.
 export const secretsContract = {
     set: secretRoute
@@ -26,10 +28,22 @@ export const secretsContract = {
             path: "/secrets",
             summary: "Store a secret",
             description:
-                "Writes one name and value into the sandbox's own store, where running processes pick it up without a restart. Refused until the sandbox has somewhere to keep them.",
+                "Writes one name and value where the agent's references resolve it, without a restart: desired-state/.env once DevOps is active, the sandbox's own secret store before that.",
         })
         .input(SecretSetSchema)
         .output(OkSchema),
+    generate: secretRoute
+        .route({
+            method: "POST",
+            path: "/secrets/generate",
+            summary: "Make and store a random secret",
+            description:
+                "Makes a random value and stores it under a new name, where `set` would have put it, for a secret nobody has to find or paste (a session key, a signing secret, a password the task sets up itself). Answers the name and its length, never the value. Refused for a name something here already holds.",
+        })
+        // The `secrets generate` CLI, on the agent token: it creates a value, and hands none back.
+        .meta({ agent: true })
+        .input(SecretGenerateSchema)
+        .output(SecretGeneratedSchema),
     list: secretRoute
         .route({
             method: "GET",

package/src/contracts/system.contract.ts

@@ -15,6 +15,7 @@ import { PresenceReportSchema } from "../schemas/logs.js";
 import { SandboxMetricsSchema, StorageCleanInputSchema, StorageCleanResultSchema, StorageReportSchema } from "../schemas/metrics.js";
 import { OkSchema } from "../schemas/shared.js";
 import { DaemonSessionSchema, InfoSchema, ManifestProblemsSchema, ManifestRepairSchema } from "../schemas/system.js";
+import { SkipUpdateInputSchema } from "../schemas/updates.js";
 import {
     BrowserNameParamSchema,
     BrowsersListSchema,
@@ -44,6 +45,19 @@ export const systemContract = {
         })
         .meta({ guest: true })
         .output(InfoSchema),
+    // The owner's "not this one" for the update card; /info's `skippedVersion` reads it back.
+    skipUpdate: systemRoute
+        .route({
+            method: "POST",
+            path: "/system/update/skip",
+            summary: "Stop offering one release",
+            description:
+                "Stops offering the named release as an update, typically one this sandbox already tried and went back from. A newer release is offered as usual. Null offers the newest release again.",
+        })
+        // Which version the sandbox runs is the operator's decision, like the update itself.
+        .meta({ floor: "maintainer" })
+        .input(SkipUpdateInputSchema)
+        .output(OkSchema),
     // Own route, not a field on /info: it goes stale on a manifest changing on disk, not on identity changing.
     manifestProblems: systemRoute
         .route({

package/src/events/agent-events.ts

@@ -5,6 +5,7 @@ import { LandConflictSchema } from "../schemas/agents.js";
 import { ContextTrimSchema } from "../schemas/context-trim.js";
 import { RateLimitInfoSchema } from "../schemas/providers/claude-gate.js";
 import { FastModeStateSchema } from "../schemas/providers/fast-mode.js";
+import { NeedSchema } from "../schemas/needs.js";
 import { PromptCacheOpeningSchema, PromptFingerprintSchema } from "../schemas/keep-warm.js";
 import { AgentReplySchema, UsageWindowSchema } from "../schemas/providers/plan-limits.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
@@ -206,6 +207,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // Who released it: `released` names the approver's verified address, `refused` means someone said no. Nothing is
     // pushed for a card nobody answered; `resolved` already says that.
     CredentialReceiptSchema.extend({ kind: z.literal("credential_receipt"), requestId: z.string() }),
+    // Something the agent asked a person for (docs/architecture/needs.md). Parks nothing: the turn carries on, the need
+    // outlives it in the needs store, and its card draws the store's live state by `need.id`.
+    z.object({ kind: z.literal("need"), need: NeedSchema }),
     // The named card is released and the turn resumes; emitted the moment its waiter settles, since nothing else on
     // this stream marks a park's end. `reply` is what a rebuilt transcript freezes the card with.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),

package/src/events/agent-words.ts

@@ -1,5 +1,6 @@
 import type { SubagentVerification } from "../schemas/terminal.js";
 import type { TranscriptAgentWords, TranscriptRow } from "./transcript.js";
+import { needWakeRow } from "./need-wake.js";
 import { watchWakeRow } from "./watch-wake.js";
 
 // Composer and parser of another agent's prompt (a peer's message, a child's report) are one piece of knowledge.
@@ -124,4 +125,4 @@ export const agentWordsRow = (prompt: string): TranscriptRow | undefined => {
 };
 
 /** The row for a prompt nobody at the composer typed; every transcript reader asks this one function. */
-export const unspokenPromptRow = (prompt: string): TranscriptRow | undefined => watchWakeRow(prompt) ?? agentWordsRow(prompt);
+export const unspokenPromptRow = (prompt: string): TranscriptRow | undefined => watchWakeRow(prompt) ?? needWakeRow(prompt) ?? agentWordsRow(prompt);

package/src/events/need-wake.test.ts

@@ -0,0 +1,55 @@
+import { unspokenPromptRow } from "./agent-words.js";
+import { needRowText, needWakeOf, needWakePrompt, needWakeRow, type NeedWakeFields, type NeedWakeOutcome } from "./need-wake.js";
+
+const fields = (over: Partial<NeedWakeFields> = {}): NeedWakeFields => ({
+    outcome: "met",
+    id: "need-7k2q",
+    title: "Connect GitHub",
+    why: "to open the pull request for the fix",
+    result: 'GitHub is connected as "github".',
+    use: ["In this turn, prefix a command with GH_TOKEN={{secret:github/token}}."],
+    ...over,
+});
+
+const OUTCOMES: NeedWakeOutcome[] = ["met", "declined"];
+
+describe("need wake", () => {
+    // The composer and the parser are the same piece of knowledge; this holds them together when either is reworded.
+    it.each(OUTCOMES)("round-trips a %s wake back to its fields", (outcome) => {
+        const prompt = needWakePrompt(fields({ outcome }));
+        expect(needWakeOf(prompt)).toEqual({ outcome, title: "Connect GitHub", id: "need-7k2q", sent: prompt });
+    });
+
+    it("tells a met need to carry on and a declined one not to wait", () => {
+        expect(needWakePrompt(fields()).split("\n").at(-1)).toBe("Continue the task that needed it.");
+        expect(needWakePrompt(fields({ outcome: "declined", use: [] }))).not.toContain("Continue the task");
+    });
+
+    it("leaves the agent's reason out when it gave none, rather than printing an empty label", () => {
+        expect(needWakePrompt(fields({ why: undefined }))).not.toContain("You asked because:");
+        expect(needWakePrompt(fields())).toContain("You asked because: to open the pull request for the fix");
+    });
+
+    it("is not a wake once its labelled lines are gone", () => {
+        const prompt = needWakePrompt(fields());
+        expect(needWakeOf(prompt.replace("Need id: need-7k2q\n", ""))).toBeUndefined();
+        expect(needWakeOf(prompt.replace("Need: Connect GitHub\n", ""))).toBeUndefined();
+        expect(needWakeOf("please connect github")).toBeUndefined();
+    });
+
+    it("becomes a notice row that says what happened, and every transcript reader finds it", () => {
+        const prompt = needWakePrompt(fields());
+        const row = needWakeRow(prompt);
+        expect(row).toEqual({
+            role: "notice",
+            text: "Connect GitHub: done, and the agent carries on.",
+            needWake: { outcome: "met", title: "Connect GitHub", id: "need-7k2q", sent: prompt },
+        });
+        expect(unspokenPromptRow(prompt)).toEqual(row);
+        expect(needWakeRow(needWakePrompt(fields({ outcome: "declined" })))?.text).toBe("Connect GitHub: declined, and the agent was told.");
+    });
+
+    it("words a raised need's row for a reader that draws no card", () => {
+        expect(needRowText({ title: "The OPENAI_API_KEY secret" })).toBe("Needs a person: The OPENAI_API_KEY secret");
+    });
+});

package/src/events/need-wake.ts

@@ -0,0 +1,71 @@
+import type { TranscriptNeedWake, TranscriptRow } from "./transcript.js";
+
+// What a need says when its answer reaches a conversation, and how that reads to a person. Delivered as an ordinary
+// turn prompt (a steer into a live turn, or a turn of its own), so composing it and recognising it stay one piece of
+// knowledge, exactly as a condition watch's wake does (watch-wake.ts): the daemon's record, a steered live turn and a
+// provider's session store all turn this prompt back into the same row.
+
+export type NeedWakeOutcome = TranscriptNeedWake["outcome"];
+
+// Per-outcome opening sentence, which is also what the parser anchors on: keep each unique and stable across releases,
+// or a reworded opening un-recognises wakes already in a record and they read as the user's own words.
+const OPENINGS: Record<NeedWakeOutcome, string> = {
+    met: "Need met: a person gave you what you asked for.",
+    declined: "Need declined: a person said no to what you asked for. Carry on without it, and say plainly what it would have enabled.",
+};
+
+// Labels the prompt writes and the parser reads back. `Need` and `Need id` are load-bearing on both sides.
+const NEED = "Need: ";
+const NEED_ID = "Need id: ";
+const ASKED = "You asked because: ";
+
+export interface NeedWakeFields {
+    readonly outcome: NeedWakeOutcome;
+    readonly id: string;
+    readonly title: string;
+    readonly why: string | undefined;
+    // The daemon's sentence on how it ended ("Connected as "github".", "Stored under OPENAI_API_KEY.").
+    readonly result: string;
+    // What the agent can do with it now, and what arrives on its next turn; empty for a decline.
+    readonly use: readonly string[];
+}
+
+export const needWakePrompt = (fields: NeedWakeFields): string =>
+    [
+        OPENINGS[fields.outcome],
+        `${NEED}${fields.title}`,
+        `${NEED_ID}${fields.id}`,
+        ...(fields.why === undefined || fields.why === "" ? [] : [`${ASKED}${fields.why}`]),
+        fields.result,
+        ...fields.use,
+        ...(fields.outcome === "met" ? ["Continue the task that needed it."] : []),
+    ].join("\n");
+
+const headline = (outcome: NeedWakeOutcome, title: string): string =>
+    outcome === "met" ? `${title}: done, and the agent carries on.` : `${title}: declined, and the agent was told.`;
+
+const valueOn = (lines: readonly string[], label: string): string | undefined => lines.find((line) => line.startsWith(label))?.slice(label.length);
+
+// The words a raised need's row carries for a reader that draws no card (search, an export, an older client); the card
+// itself is drawn from the need.
+export const needRowText = (need: { readonly title: string }): string => `Needs a person: ${need.title}`;
+
+// Which need wake a stored prompt is, if any; undefined for every prompt that isn't one, so any reader can ask without
+// checking first. One that opens as a wake but lost its labelled lines is not one.
+export const needWakeOf = (prompt: string): TranscriptNeedWake | undefined => {
+    const outcome = (Object.keys(OPENINGS) as NeedWakeOutcome[]).find((key) => prompt.startsWith(OPENINGS[key]));
+    if (outcome === undefined) {
+        return undefined;
+    }
+    const lines = prompt.split("\n");
+    const title = valueOn(lines, NEED);
+    const id = valueOn(lines, NEED_ID);
+    return title === undefined || id === undefined ? undefined : { outcome, title, id, sent: prompt };
+};
+
+// The row a wake becomes: a notice, since a need being answered happened to the conversation rather than being said by
+// either side. Undefined when the prompt is not a need wake at all.
+export const needWakeRow = (prompt: string): TranscriptRow | undefined => {
+    const wake = needWakeOf(prompt);
+    return wake === undefined ? undefined : { role: "notice", text: headline(wake.outcome, wake.title), needWake: wake };
+};

package/src/events/transcript.ts

@@ -3,6 +3,7 @@ import { AgentHarnessSchema, AgentProviderSchema } from "../schemas/agent.js";
 import { ShareDetailSchema } from "../schemas/share.js";
 import { TurnErrandSchema, TurnSpeakerSchema } from "../schemas/speaker.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
+import { NeedSchema } from "../schemas/needs.js";
 import { RetryLadderSchema } from "../schemas/turn-break.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";
@@ -155,6 +156,15 @@ export const TranscriptWatchWakeSchema = z.object({
 });
 export type TranscriptWatchWake = z.infer<typeof TranscriptWatchWakeSchema>;
 
+// A need's answer that reached this conversation as a prompt (need-wake.ts); the row keeps the prompt and names the need.
+export const TranscriptNeedWakeSchema = z.object({
+    outcome: z.enum(["met", "declined"]).describe("How the need ended: a person gave it, or said no."),
+    title: z.string().describe("The need, as its card leads with it."),
+    id: z.string().describe("The need's handle, which its live card is keyed by."),
+    sent: z.string().describe("The whole prompt the model received, disclosed under the row."),
+});
+export type TranscriptNeedWake = z.infer<typeof TranscriptNeedWakeSchema>;
+
 // Another agent's words that reached this conversation as a prompt; the row keeps the prompt and names the sender.
 export const TranscriptAgentWordsSchema = z.object({
     kind: z.enum(["peer", "child"]).describe("Who sent it: another conversation in the workspace, or a subagent this one started."),
@@ -299,6 +309,12 @@ export const TranscriptRowSchema = z.object({
     capabilityOffer: TranscriptCapabilityOfferSchema.optional().describe("The capability setup this row asked for, the decision, and the outcome."),
     paymentOffer: TranscriptPaymentOfferSchema.optional().describe("The payment this row asked for, the decision, and the receipt."),
     watchWake: TranscriptWatchWakeSchema.optional().describe("The condition watch that woke this conversation, and the prompt it was woken with."),
+    // A need is not a parked card: it holds no turn open, outlives the one that raised it, and its live state is the
+    // needs store's, keyed by `need.id`. What rides here is the need as it was raised, for a reader with no store.
+    need: NeedSchema.optional().describe(
+        "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."),
     backgroundJob: TranscriptBackgroundJobSchema.optional().describe("The background job this row marks the start of."),
     credentialOffer: TranscriptCredentialOfferSchema.optional().describe(

package/src/index.ts

@@ -32,6 +32,7 @@ import { netdiskContract } from "./contracts/netdisk.contract.js";
 import { providersContract } from "./contracts/providers.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
 import { safetyContract } from "./contracts/safety.contract.js";
+import { needsContract } from "./contracts/needs.contract.js";
 import { secretsContract } from "./contracts/secrets.contract.js";
 import { sessionsContract } from "./contracts/sessions.contract.js";
 import { settingsContract } from "./contracts/settings.contract.js";
@@ -92,6 +93,7 @@ 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 { safetyContract } from "./contracts/safety.contract.js";
+export { needsContract } from "./contracts/needs.contract.js";
 export { secretsContract } from "./contracts/secrets.contract.js";
 export { sessionsContract } from "./contracts/sessions.contract.js";
 export { settingsContract } from "./contracts/settings.contract.js";
@@ -115,6 +117,7 @@ export * from "./events/land-breakage.js";
 export * from "./events/land-conflict.js";
 export * from "./events/verify-nudge.js";
 export * from "./events/errands.js";
+export * from "./events/need-wake.js";
 export * from "./events/watch-wake.js";
 export * from "./policy/request-status.js";
 export * from "./events/child-run.js";
@@ -214,6 +217,7 @@ export * from "./schemas/providers/provider-subscriptions.js";
 export * from "./schemas/public.js";
 export * from "./schemas/push.js";
 export * from "./schemas/git/remote-refs.js";
+export * from "./schemas/needs.js";
 export * from "./schemas/secrets.js";
 export * from "./schemas/netdisk.js";
 export * from "./schemas/sessions.js";
@@ -224,6 +228,7 @@ export * from "./schemas/shared.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
 export * from "./schemas/state-plan.js";
+export * from "./schemas/updates.js";
 export * from "./schemas/terminal.js";
 export * from "./schemas/turn-break.js";
 export * from "./schemas/keep-warm.js";
@@ -285,6 +290,7 @@ export const sandboxContract = {
     public: publicContract,
     providers: providersContract,
     push: pushContract,
+    needs: needsContract,
     secrets: secretsContract,
     system: systemContract,
     translator: translatorContract,

package/src/protocol/raw-routes.ts

@@ -83,9 +83,8 @@ export const RAW_ROUTES = {
     "GET /extensions/{id}/bundle": { lane: "bulk" },
     // An extension backend's own namespace, proxied verbatim.
     "ALL /x/*": {},
-    // The `capabilities` CLI: discovery by name, and the ask that parks on an owner-decided card.
+    // The `capabilities` CLI's discovery by name; its ask is the needs door (contracts/needs.contract.ts).
     "GET /capabilities/connectable": { floor: "maintainer", agent: true, control: "never" },
-    "POST /capabilities/ask": { floor: "maintainer", agent: true, control: "never" },
     // The `sandboxes` CLI; every create parks on a card in the owner's chat first.
     "GET /sandboxes": { agent: true },
     "POST /sandboxes": { agent: true },

package/src/schemas/agents.ts

@@ -4,6 +4,7 @@ import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, Conversatio
 import { LoopStateSchema } from "./loops.js";
 import { LimitPolicySchema, RetryPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
 import { KeepWarmSchema } from "./keep-warm.js";
+import { AgentNeedSchema } from "./needs.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
@@ -56,7 +57,7 @@ export const AgentAttentionSchema = z.object({
     plan: z.boolean().describe("It has proposed a plan and is waiting for a yes."),
     question: z.boolean().describe("It has asked you something."),
     permission: z.boolean().describe("It wants to use a tool it needs permission for."),
-    // A missing capability (capabilities/offers/capability-offer.ts); lets the lane say "setup needed" rather than a generic
+    // A missing capability on a card from before needs (docs/architecture/needs.md); lets the lane say "setup needed" rather than a generic
     // pause.
     capability: z.boolean().describe("It needs something connected that is not connected yet."),
     // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear
@@ -65,6 +66,11 @@ export const AgentAttentionSchema = z.object({
         .boolean()
         .describe("It is waiting for a named person to release a credential. The one pause that may not be yours to clear, whatever your role."),
     conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
+    // A need outlives its turn (docs/architecture/needs.md), so this can stand on a card that is not running at all.
+    need: z
+        .boolean()
+        .optional()
+        .describe("It asked a person for something it still needs: a connection, a secret, wider reach, a tool. Absent from a daemon older than needs."),
 });
 export type AgentAttention = z.infer<typeof AgentAttentionSchema>;
 // What the last turn left open, measured at the moment it ended, unlike AgentAttentionSchema's live parked waits.
@@ -527,6 +533,13 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Outside conditions this conversation is parked on, each of which will wake it. Absent means none, which is nearly every conversation: an armed watch is why a finished-looking agent starts working by itself, and why a hosted machine will not go idle.",
         ),
+    // Kept in the needs store, so unlike `jobs` this survives a restart and stands while the conversation is idle.
+    needs: z
+        .array(AgentNeedSchema)
+        .optional()
+        .describe(
+            "What it is waiting on people for and has not got yet, oldest first. Absent means nothing: an open need is why an idle-looking agent still needs you.",
+        ),
     // In memory only: a daemon restart leaves transcript rows naming jobs this list no longer carries.
     jobs: z
         .array(

package/src/schemas/capabilities.ts

@@ -104,6 +104,15 @@ export const SshConfigSchema = z.discriminatedUnion("auth", [
         user: z.string().min(1).describe("Which user to connect as."),
         privateKey: z.string().min(1).describe("The private key, whole. Stored with tight permissions and never echoed back."),
     }),
+    // The sandbox made this key itself (capabilities.sshKey), so its private half never crossed the wire; stored and
+    // written exactly like a pasted one.
+    z.object({
+        auth: z.literal("generated").describe("Sign in with a key the sandbox generated. Its private half never left the sandbox."),
+        host: z.string().min(1).describe("The machine's address."),
+        port: z.coerce.number().default(22).describe("Which port it listens on."),
+        user: z.string().min(1).describe("Which user to connect as."),
+        privateKey: z.string().min(1).describe("The private half of the generated key. Stored with tight permissions and never echoed back."),
+    }),
     z.object({
         auth: z.literal("password").describe("Sign in with a password."),
         host: z.string().min(1).describe("The machine's address."),
@@ -112,6 +121,14 @@ export const SshConfigSchema = z.discriminatedUnion("auth", [
         password: z.string().min(1).describe("The password. Stored, never echoed back."),
     }),
 ]);
+// What a form sends where a generated key's private half goes: the token capabilities.sshKey answered with, which the
+// add swaps for the key the daemon kept. VAULTED's sibling (policy/capability-secrets.ts) for a value not stored yet; a
+// marker with nothing held behind it is refused, never written.
+const STASHED_PREFIX = "__intentic_stashed__:";
+export const stashedMarker = (token: string): string => `${STASHED_PREFIX}${token}`;
+// The token a marker names; undefined for anything else (a real key, VAULTED, a blank).
+export const stashedToken = (value: unknown): string | undefined =>
+    typeof value === "string" && value.startsWith(STASHED_PREFIX) && value.length > STASHED_PREFIX.length ? value.slice(STASHED_PREFIX.length) : undefined;
 // What is optional about the in-sandbox Docker Engine: `gpu` is an IMAGE option (rides the Dockerfile overlay, needs a
 // rebuild), everything else is an ENGINE option (rewrites daemon.json, restarts dockerd, no rebuild but stops running
 // containers). Flat strings, not nested booleans, to match the manifest's own two-state convention.
@@ -460,3 +477,14 @@ export const CapabilityProbeSchema = z.object({
     who: z.string().optional().describe("Who the service said the credential belongs to, when it said."),
 });
 export type CapabilityProbe = z.infer<typeof CapabilityProbeSchema>;
+// POST /capabilities/ssh-key: a key pair made inside the sandbox for a connection being set up. The public half is the
+// whole answer; the private half stays in the daemon until an add sends `stashedMarker(token)` where it goes.
+export const SshKeySchema = z.object({
+    publicKey: z.string().describe("The public half, as the one line a server's authorized_keys holds: `ssh-ed25519 AAAA… intentic-<sandbox>`."),
+    token: z
+        .string()
+        .describe(
+            "Stands for the private half, which never leaves the sandbox. Sent wrapped as a marker in the private key's place, it installs that key once, and it lapses after thirty minutes.",
+        ),
+});
+export type SshKey = z.infer<typeof SshKeySchema>;

package/src/schemas/devices.ts

@@ -1,6 +1,7 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
 import { parseHostConnection, type DeviceFacts, DeviceFactsSchema, MachineIdSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
+import { RollbackTargetSchema, UpdateOutcomeSchema } from "./updates.js";
 import { DEV_VERSION } from "../state/versions.js";
 // Desktop-sync report shape shared by the agent, daemon and browser, produced only by the agent's own `deviceReport`.
 // The agent never reports `sandboxes`; the docker half is filled in by whoever reads the report, scoped to the reader's
@@ -76,6 +77,19 @@ export const DeviceSandboxSchema = z.object({
     resources: SandboxResourcesSchema.optional(),
     // The update `ic sandbox prepare` built and left waiting for this sandbox; absent when nothing is staged.
     staged: z.object({ image: z.string(), version: z.string().optional(), channel: z.string().optional() }).optional(),
+    // Everything below is read off an `ic` new enough to know it; an older ic's listing simply lacks it.
+    // What the running image says it is.
+    version: z.string().optional(),
+    // An interrupted swap left the old container set aside with no replacement: the sandbox is down, and `start` (or
+    // any swap) puts it back. `running` is false while this is true.
+    parked: z.boolean().optional(),
+    // A swap has just happened and the previous version is still parked and ready: until this moment the host watches
+    // the new one and goes back by itself if it keeps crashing, never becomes ready, or loses its tunnel.
+    probationUntil: z.number().optional(),
+    // What the host last did about this sandbox's version (the same record the sandbox reads as `lastUpdate`).
+    lastUpdate: UpdateOutcomeSchema.optional(),
+    // Newest first: what `rollback` would return to, then the older versions kept on this machine for `rollback --to`.
+    rollbackTargets: z.array(RollbackTargetSchema).optional(),
 });
 export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
@@ -118,6 +132,9 @@ export const DeviceSandboxFlowSchema = z.strictObject({
     slug: z.string().min(1),
     // Approved overlay's sha256, required only by `rebuild`; only content matching it is ever built.
     hash: z.string().optional(),
+    // `rollback` only: a version or pinned image from the sandbox's `rollbackTargets` to go back to instead of the
+    // previous one. Sent only to an agent that advertises `rollback-to`: an older one refuses the field.
+    to: z.string().min(1).optional(),
     // `set-shape` only, both required by it: the whole shape, and when it takes effect.
     // Strict too, unlike the same shape read off a report (where a newer ic's extra field must not fail an older
     // reader): an order carrying a field this agent does not know is refused rather than carried out without it.

package/src/schemas/hosts.ts

@@ -68,10 +68,13 @@ export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 // - `set-shape`: the `set-shape`/`forget-shape` ops, and `start`/`restart` applying a saved shape, all through an `ic`
 //   whose `ic sandbox shape` takes the contract's own shape (`--set`); advertised only when the agent's `ic` does.
 //   Both features ride that verb, so an agent advertises both or neither.
-export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape"]);
+// - `rollback-to`: the `rollback` op's `to`, going back to an older version kept on the machine rather than the
+//   previous one; advertised only when the agent's `ic sandbox rollback` takes `--to`.
+export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape", "rollback-to"]);
 export type DeviceFeature = z.infer<typeof DeviceFeatureSchema>;
 export const DEVICE_FEATURE_RESHAPE_LATER: DeviceFeature = "reshape-later";
 export const DEVICE_FEATURE_SET_SHAPE: DeviceFeature = "set-shape";
+export const DEVICE_FEATURE_ROLLBACK_TO: DeviceFeature = "rollback-to";
 // The features an agent advertised that this build knows; an unknown one is a newer agent's and means nothing here.
 export const deviceFeatures = (facts: Pick<DeviceFacts, "features"> | undefined): DeviceFeature[] =>
     (facts?.features ?? []).flatMap((feature) => {