@intentic/sandbox-contract 1.316.0 → 1.317.0

package/src/schemas/needs.ts

@@ -0,0 +1,292 @@
+import { z } from "zod";
+
+// A need: something an agent cannot finish its task without that only a person can provide (a connection, a secret's
+// value, wider reach, a tool in the image). Unlike a parked card it outlives the turn that raised it: the sandbox keeps
+// it until someone answers, draws it wherever it is waiting, and wakes the conversation when it is met
+// (docs/architecture/needs.md). Every word on a need is the daemon's except `why`, the agent's own case.
+
+export const NEED_KINDS = ["capability", "secret", "grant", "release", "environment"] as const;
+export const NeedKindSchema = z.enum(NEED_KINDS).describe("What is being asked for: a connection, a secret's value, wider reach, a gated credential, or a tool in the image.");
+export type NeedKind = z.infer<typeof NeedKindSchema>;
+
+// `working` is a yes still being carried out: a connection whose form is open, an overlay approved but not yet built.
+export const NeedStatusSchema = z
+    .enum(["open", "working", "met", "declined", "cancelled"])
+    .describe(
+        "Where it stands: open (waiting on a person), working (a person said yes and it is being set up), met, declined, or cancelled (the agent withdrew it, or its conversation went away).",
+    );
+export type NeedStatus = z.infer<typeof NeedStatusSchema>;
+
+export const OPEN_NEED_STATUSES: readonly NeedStatus[] = ["open", "working"];
+export const isOpenNeed = (need: { readonly status: NeedStatus }): boolean => OPEN_NEED_STATUSES.includes(need.status);
+
+// A setting value as a form holds it: every field of a catalog entry is a string on the way in.
+const FieldValuesSchema = z.record(z.string(), z.string());
+
+export const CapabilityNeedModeSchema = z
+    .enum(["connect", "reconnect", "change"])
+    .describe("Connect something new, give a connected one a credential that works again, or change a setting on a connected one.");
+export type CapabilityNeedMode = z.infer<typeof CapabilityNeedModeSchema>;
+
+export const CapabilityNeedSchema = z.object({
+    kind: z.literal("capability"),
+    entry: z.string().min(1).describe("The catalog entry, as the catalog names it."),
+    name: z.string().describe("What the catalog calls it, never the agent's spelling."),
+    mode: CapabilityNeedModeSchema,
+    instance: z.string().optional().describe("The connection a reconnect or a change is about."),
+    target: z.string().optional().describe("The site, host or address the connection is for, when the entry can hold several."),
+    prefill: FieldValuesSchema.optional().describe(
+        "Settings the agent could fill in for a new connection, never a credential: the daemon keeps only the entry's own non-secret fields.",
+    ),
+    changes: FieldValuesSchema.optional().describe("For a change: each setting and the value it would take. Never a credential."),
+    reason: z.string().optional().describe("The daemon's own sentence on why this is the ask, such as the refusal a connected credential keeps getting."),
+    reported: z
+        .boolean()
+        .optional()
+        .describe(
+            "The agent reported the credential refused while the connection still probes as working, so only a person's word that it is fixed meets it: the probe could not see the refusal in the first place.",
+        ),
+});
+export type CapabilityNeed = z.infer<typeof CapabilityNeedSchema>;
+
+// The alphabet a `{{secret:NAME}}` reference resolves; a pasted value is stored under exactly this name.
+export const SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+
+export const SecretNeedSchema = z.object({
+    kind: z.literal("secret"),
+    name: z.string().regex(SECRET_NAME).describe("The name it is stored under, and what `{{secret:NAME}}` will resolve."),
+    where: z.string().max(200).optional().describe("How it will be used: the header, the command, the site it goes to."),
+    link: z
+        .string()
+        .url()
+        .refine((url) => url.startsWith("https://"), "only an https link")
+        .optional()
+        .describe("Where a person gets one, shown as a link on the card."),
+    hint: z.string().max(120).optional().describe("What a valid one looks like, so a wrong paste is caught by eye."),
+    replace: z.boolean().optional().describe("One is stored under this name and is being refused: the ask is for a new value in its place."),
+});
+export type SecretNeed = z.infer<typeof SecretNeedSchema>;
+
+export const GrantSubjectSchema = z
+    .enum(["capability", "folder", "shelf", "site"])
+    .describe(
+        "A connected capability the persona leaves out, a folder outside the conversation's reach, a whole shelf of tools, or a site in the person's own browser, which only their browser extension can allow.",
+    );
+export type GrantSubject = z.infer<typeof GrantSubjectSchema>;
+
+// A site as a person's browser grants it: the host alone, whatever scheme, path or pattern it was written with
+// ("https://github.com/*" and "github.com" are one site). What a site grant need is keyed and met by.
+export const grantSite = (origin: string): string =>
+    origin
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")
+        .replace(/[/?#].*$/, "")
+        .toLowerCase();
+
+export const GRANT_SHELVES = ["files", "shell", "code", "web", "browser", "delegate", "sandbox"] as const;
+export const GrantShelfSchema = z.enum(GRANT_SHELVES);
+export type GrantShelf = z.infer<typeof GrantShelfSchema>;
+
+export const GrantScopeSchema = z
+    .enum(["conversation", "persona"])
+    .describe("How far a yes goes: this conversation only, or the persona itself, for every conversation that wears it.");
+export type GrantScope = z.infer<typeof GrantScopeSchema>;
+
+export const GrantNeedSchema = z.object({
+    kind: z.literal("grant"),
+    subject: GrantSubjectSchema,
+    what: z.string().min(1).describe("The capability's id, the folder, or the shelf."),
+    label: z.string().describe("What it is, in the daemon's words: the account and its kind, the folder, the shelf's name."),
+    persona: z.string().optional().describe("The persona that withholds it, when one does."),
+    scope: GrantScopeSchema.optional().describe("How far the yes went, once there was one."),
+});
+export type GrantNeed = z.infer<typeof GrantNeedSchema>;
+
+export const ReleaseNeedSchema = z.object({
+    kind: z.literal("release"),
+    subject: z.string().min(1).describe("The gated account or connector."),
+    approvers: z.array(z.string()).describe("Who may release it. Anyone else's answer is refused and leaves it waiting."),
+});
+export type ReleaseNeed = z.infer<typeof ReleaseNeedSchema>;
+
+export const EnvironmentNeedSchema = z.object({
+    kind: z.literal("environment"),
+    tool: z.string().min(1).describe("What the steps install, the name the proposal is filed under."),
+    steps: z.string().min(1).describe("The Dockerfile steps proposed for the image's custom section: RUN and ENV lines only."),
+    approvedHash: z.string().optional().describe("The overlay these steps were approved into; met once the running container was built from it."),
+});
+export type EnvironmentNeed = z.infer<typeof EnvironmentNeedSchema>;
+
+export const NeedSubjectSchema = z
+    .discriminatedUnion("kind", [CapabilityNeedSchema, SecretNeedSchema, GrantNeedSchema, ReleaseNeedSchema, EnvironmentNeedSchema])
+    .describe("What exactly is asked for.");
+export type NeedSubject = z.infer<typeof NeedSubjectSchema>;
+
+// How the agent learned the outcome: the call it raised the need with, words into its live turn, a turn of its own, or
+// queued behind what the conversation was doing.
+export const NeedToldSchema = z.enum(["call", "turn", "queued"]);
+export type NeedTold = z.infer<typeof NeedToldSchema>;
+
+export const NeedSchema = z.object({
+    id: z.string().describe("The need's handle, the one `needs cancel` takes."),
+    conversationId: z.string().describe("The conversation that asked, and the one its answer wakes."),
+    subject: NeedSubjectSchema,
+    title: z.string().describe("The one line it leads with, in the daemon's words."),
+    why: z.string().max(280).optional().describe("The agent's case for it, and the only words on a need that are the agent's."),
+    status: NeedStatusSchema,
+    createdAt: z.number().describe("When it was raised, in milliseconds."),
+    updatedAt: z.number().describe("When it last moved, in milliseconds."),
+    answeredBy: z.string().optional().describe("Who answered it, as the sandbox verified them."),
+    outcome: z.string().optional().describe("How it ended, in the daemon's words, once it has."),
+    told: NeedToldSchema.optional().describe("How the agent heard the outcome, once it has."),
+    unattended: z.boolean().optional().describe("Raised by a turn nobody was watching, so the card waited for whoever came next."),
+});
+export type Need = z.infer<typeof NeedSchema>;
+
+// What an agent may send: the kind and what it can know about it. Names, titles and every other field the card shows are
+// the daemon's to fill in, from the catalog, the persona, the gate policy.
+export const NeedAskSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("capability"),
+        entry: z.string().min(1).describe("The catalog entry or a connected instance's id."),
+        target: z.string().max(200).optional().describe("The site, host or address it is for."),
+        set: FieldValuesSchema.optional().describe("Settings to fill in, or to change on a connected one. Credentials are refused."),
+        reconnect: z
+            .boolean()
+            .optional()
+            .describe("It is connected, but its credential is being refused: ask for a new one rather than being told to use it."),
+    }),
+    SecretNeedSchema,
+    z.object({
+        kind: z.literal("grant"),
+        subject: GrantSubjectSchema,
+        what: z.string().min(1).max(400),
+    }),
+    z.object({ kind: z.literal("release"), subject: z.string().min(1) }),
+    z.object({ kind: z.literal("environment"), tool: z.string().min(1).max(64), steps: z.string().min(1).max(20_000) }),
+]);
+export type NeedAsk = z.infer<typeof NeedAskSchema>;
+
+// The longest a raising call holds: under the agent shell's 110-second cutoff, so the answer returns on the call.
+export const NEED_WAIT_MAX_S = 100;
+export const NEED_WAIT_DEFAULT_S = 90;
+
+export const NeedRaiseSchema = z.object({
+    ask: NeedAskSchema,
+    why: z.string().max(280).optional(),
+    wait: z
+        .number()
+        .int()
+        .min(0)
+        .max(NEED_WAIT_MAX_S)
+        .optional()
+        .describe("Seconds to hold the call for an answer. Absent is 90 for a watched turn and 0 for an unattended one."),
+});
+export type NeedRaise = z.infer<typeof NeedRaiseSchema>;
+
+// How a raising call ended. `met`: usable now, exit 0. `open`: asked and still waiting, exit 3; the answer arrives in the
+// conversation by itself. `refused`: nothing was raised or it was declined, exit 1.
+export const NeedRaisedSchema = z.object({
+    state: z.enum(["met", "open", "refused"]),
+    message: z.string().describe("The sentence the CLI prints, written for the agent to act on."),
+    need: NeedSchema.optional(),
+    code: z.string().optional().describe("A refusal's type, for a script to branch on."),
+});
+export type NeedRaised = z.infer<typeof NeedRaisedSchema>;
+
+// A person's answer, by what the card offered. A secret's value travels on its own route (needs.contract.ts), never here.
+export const NeedAnswerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("decline"), note: z.string().max(500).optional().describe("Why not, passed to the agent.") }),
+    // A connection's yes before its form is saved: moves the need to working, so the board keeps saying so.
+    z.object({ kind: z.literal("accept") }),
+    // A change to a connected capability's settings, applied as the card showed it.
+    z.object({ kind: z.literal("apply") }),
+    z.object({ kind: z.literal("grant"), scope: GrantScopeSchema }),
+    z.object({ kind: z.literal("release") }),
+    z.object({ kind: z.literal("approve") }),
+]);
+export type NeedAnswer = z.infer<typeof NeedAnswerSchema>;
+
+export const NeedIdParamSchema = z.object({ id: z.string().min(1).describe("Which need.") });
+export const NeedAnswerInputSchema = NeedIdParamSchema.extend({ answer: NeedAnswerSchema });
+export const NeedSecretInputSchema = NeedIdParamSchema.extend({
+    value: z.string().min(1).max(64_000).describe("The secret's value. Stored, never echoed, never written into a transcript."),
+});
+export const NeedsQuerySchema = z.object({
+    conversationId: z.string().optional().describe("One conversation's needs. Absent is every conversation's."),
+    open: z.boolean().optional().describe("Only the ones still waiting."),
+});
+export const NeedsListSchema = z.object({ needs: z.array(NeedSchema).describe("Newest first.") });
+
+// What `capabilities list` reads (GET /capabilities/connectable, a raw route): shared by the daemon's handler and the
+// CLI's suite, so the two cannot drift apart again the way a renamed field once left the command printing nothing.
+export const CapabilityConnectableSchema = z.object({
+    entries: z.array(
+        z.object({
+            entry: z.string().describe("The catalog entry's id, what `capabilities request` takes."),
+            name: z.string(),
+            description: z.string(),
+            connected: z.boolean().describe("Whether an instance of it is live, not merely added."),
+        }),
+    ),
+    suggested: z
+        .array(
+            z.object({
+                entry: z.string(),
+                claim: z.string().describe("What the workspace seems to want, in words."),
+                evidence: z.string().describe("What was read to say so, verbatim: a file, a remote."),
+            }),
+        )
+        .default([]),
+});
+export type CapabilityConnectable = z.infer<typeof CapabilityConnectableSchema>;
+
+// One open need as the conversation's card lists it: enough for the board to say what the agent waits on.
+export const AgentNeedSchema = z.object({
+    id: z.string(),
+    kind: NeedKindSchema,
+    title: z.string(),
+    status: NeedStatusSchema,
+});
+export type AgentNeed = z.infer<typeof AgentNeedSchema>;
+
+// What a person allowed one conversation beyond its persona and area, from a grant need's card
+// (personas/conversation-grants.ts). Honoured from that conversation's next turn on, and revocable on the Grants page.
+export const ConversationGrantSchema = z.object({
+    capabilities: z.array(z.string()).default([]).describe("Connected capabilities it may use although its persona leaves them out."),
+    folders: z.array(z.string()).default([]).describe("Workspace folders its file tools may touch beyond its fence."),
+    shelves: z.array(GrantShelfSchema).default([]).describe("Shelves of tools opened for it."),
+    updatedAt: z.number().describe("When it last changed, in milliseconds."),
+    by: z.string().optional().describe("Who last allowed something here."),
+});
+export type ConversationGrant = z.infer<typeof ConversationGrantSchema>;
+
+// Every yes still standing, by conversation: what its grants widened past its persona or area, and which gated
+// credentials a named person released to it. Reviewed and taken back from Needs you.
+export const StandingGrantsSchema = z.object({
+    conversations: z.array(
+        z.object({
+            conversationId: z.string(),
+            capabilities: z.array(z.string()).describe("Connected capabilities allowed although its persona leaves them out."),
+            folders: z.array(z.string()).describe("Workspace folders its file tools may touch beyond its fence."),
+            shelves: z.array(GrantShelfSchema).describe("Shelves of tools opened for it."),
+            by: z.string().optional().describe("Who last allowed one of those."),
+            updatedAt: z.number().optional().describe("When one of those last changed, in milliseconds."),
+            releases: z
+                .array(z.object({ subject: z.string(), approvedBy: z.string(), at: z.number() }))
+                .describe("Gated credentials released to it, until the daemon restarts or somebody takes one back."),
+        }),
+    ),
+});
+export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
+
+export const GrantRevokeSchema = z.object({
+    conversationId: z.string(),
+    kind: z.enum(["capability", "folder", "shelf", "release"]).describe("Which kind of yes: a grant past the persona or area, or a credential's release."),
+    what: z.string().describe("The capability id, folder, shelf or released credential it named."),
+});
+export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
+
+// The file the needs store keeps: every open need and the recent closed ones, by id.
+export const NeedsFileSchema = z.record(z.string(), NeedSchema);
+export type NeedsFile = z.infer<typeof NeedsFileSchema>;

package/src/schemas/secrets.ts

@@ -19,6 +19,29 @@ export const SecretKeysSchema = z.object({
 export const SecretKeyParamSchema = z.object({ key: secretKey.describe("Which secret, by name.") });
 export const SecretRevealSchema = z.object({ value: z.string().describe("The value itself. The only place in this API one is ever returned.") });
 
+// A secret nobody has to find or paste: a session key, a webhook signing secret, a database password the task sets up
+// itself. The sandbox makes it and keeps it; the caller gets its reference and length, never the value.
+export const SECRET_FORMATS = ["hex", "base64url", "alnum"] as const;
+export const SecretGenerateSchema = z.object({
+    key: secretKey.describe("The name to store it under: a name nothing here holds yet, since a new value would break whatever uses the old one."),
+    bytes: z
+        .number()
+        .int()
+        .min(16)
+        .max(128)
+        .default(32)
+        .describe("How much randomness, in bytes. 32 unless whatever reads it demands a particular length."),
+    format: z
+        .enum(SECRET_FORMATS)
+        .default("hex")
+        .describe("How it is spelled: `hex` (0-9, a-f), `base64url` (letters, digits, - and _), or `alnum` (letters and digits only, for readers that refuse symbols)."),
+});
+export const SecretGeneratedSchema = z.object({
+    key: z.string().describe("The name it is stored under."),
+    length: z.number().int().describe("How many characters it is, which a reader's validation may care about."),
+    stored: z.enum(["env", "sandbox"]).describe("Where it was kept: desired-state/.env once DevOps is active, the sandbox's own store before that."),
+});
+
 // A wall against the agent's own judgment, not a compromised container: a shell here can read the policy same as the
 // vault. Approvers are an exact list, never a role floor; the owner isn't on it unless added.
 export const CredentialGateScopeSchema = z

package/src/schemas/settings.ts

@@ -457,6 +457,14 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Which heavy work runs on a runner on one of your machines instead of this sandbox: agents' commands by the kind the heavy-command rules sort them into (tests, typechecks, verify…). The code travels as it stands, uncommitted work included; the output streams back, and any file the command changed comes back with it. A machine that is offline, outdated or busy hands the work back to this sandbox, and the output says so.",
         ),
+    // A person answering a need is exactly the moment they want the work to go on (docs/architecture/needs.md), unlike a
+    // restart nobody watched, so this one is on to begin with.
+    continueWhenNeedMet: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Whether a conversation carries on by itself once something it asked a person for arrives: a connection made, a secret given, access allowed, a tool built into the image. Off leaves the answer on the conversation's card until someone sends a message.",
+        ),
     autoResumeOnRestart: z
         .boolean()
         .default(false)

package/src/schemas/state-plan.ts

@@ -40,8 +40,15 @@ export type StatePlan = z.infer<typeof StatePlanSchema>;
 
 // The `state` of `/health`: whether an update's state changes are still uncommitted. The host rolls an update back when
 // the journal stays open, so this rides the same probe as the boot's progress.
+// `failed`: a conversion or structural step threw partway through this boot; the daemon put back every file the episode
+// had touched and keeps running on read-time conversions, and a host rolls the update back as it would an open journal
+// that never commits (this version could not bring the files to its shape, the one before it can read them as they are).
 export const StateStatusSchema = z.object({
-    journal: z.enum(["open", "none"]).describe("Open from the start of a boot that changed stored files until that boot has converged."),
+    journal: z
+        .enum(["open", "none", "failed"])
+        .describe(
+            "Open from the start of a boot that changed stored files until that boot has converged. Failed when a conversion threw partway: the files were put back as they were, and a host takes that as the update not having taken.",
+        ),
     engine: z.number().describe("The running build's conversion count."),
 });
 export type StateStatus = z.infer<typeof StateStatusSchema>;

package/src/schemas/system.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { StatePlanSchema } from "./state-plan.js";
+import { UpdateOutcomeSchema, WithdrawnReleaseSchema } from "./updates.js";
 // version is this build's baked-in version; latest/updateAvailable come from comparing it to the published stable
 // release.
 // Whether a runtime can serve a turn, probed off the turn path. "unknown" reads as available-but-unverified, never as
@@ -82,6 +83,20 @@ export const InfoSchema = z.object({
     staged: StagedUpdateSchema.optional().describe(
         "An update already downloaded and built on the machine running this container, waiting only for the restart that applies it. That restart is seconds, where an unprepared update is minutes, which is a different decision entirely. Absent when nothing is waiting.",
     ),
+    // What the host last did about this sandbox's version (update-outcome.json on /history, written by ic); absent
+    // when no host has said, which is every hosted sandbox and every host older than the file.
+    lastUpdate: UpdateOutcomeSchema.optional().describe(
+        "What the machine running this sandbox last did about its version: an update that took, one it gave up on and why, and until when the previous version stays ready. Absent when that machine has never said.",
+    ),
+    // The running version was taken back after it shipped; absent for every version still standing.
+    withdrawn: WithdrawnReleaseSchema.optional().describe(
+        "Set when the version this sandbox runs was withdrawn after it shipped, which is the moment to go back to the one before it. Absent for every version still standing.",
+    ),
+    // The owner's "not this one" (POST /system/update/skip); updateAvailable reads false while `latest` is it.
+    skippedVersion: z
+        .string()
+        .optional()
+        .describe("A release the owner chose to skip. While it is the newest, no update is offered; a newer one is. Absent when nothing is skipped."),
 });
 export type Info = z.infer<typeof InfoSchema>;
 // What the daemon could not read in its own `.intentic/` state files, and in the files on its volume that

package/src/schemas/updates.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+// WHAT THE HOST LAST DID ABOUT THIS SANDBOX'S VERSION, in the host's own words. Written by `ic` (the swap, its health
+// check and the probation that follows it: _sandbox/ic/src/sandbox/outcome.rs) onto /history as `update-outcome.json`,
+// the same volume whichever container runs, so the version that ends up running reads what happened to the other one.
+// Advisory: the swap and its undoing are the host's; this is only how the sandbox and its owner hear about them.
+export const UpdateOutcomeResultSchema = z.enum(["updated", "kept", "restored", "rolled-back"]);
+export type UpdateOutcomeResult = z.infer<typeof UpdateOutcomeResultSchema>;
+
+export const UpdateOutcomeSchema = z.object({
+    result: UpdateOutcomeResultSchema.describe(
+        "What happened. Updated: the new version passed its first health check and runs, with the previous one kept ready until keepUntil. Kept: that probation ended and the new version stays. Restored: the new version never came up, so the previous container was put back at once. Rolled back: the new version came up and then failed its probation (it kept crashing, never became ready, or lost its tunnel), so the host went back to the previous one by itself.",
+    ),
+    // What the person or program asked for. A string rather than an enum: a newer ic's verb must not make an older
+    // daemon drop the whole outcome.
+    verb: z.string().optional().describe("What was asked for: update, rollback, rebuild, dev, reshape, or the probation watch acting on its own."),
+    at: z.number().describe("When it happened, in milliseconds."),
+    from: z.string().optional().describe("The version (or, when it would not say, the image) that ran before."),
+    to: z.string().optional().describe("The version (or image) that was moved onto, or that was tried and given up on."),
+    // Plain words for the owner: why a version was given up on. Absent for an update that simply worked.
+    reason: z.string().optional().describe("Why the host gave up on the new version, in plain words. Absent when nothing went wrong."),
+    // A path on the machine that runs the sandbox, which only means something to a person on that machine.
+    log: z.string().optional().describe("Where the host kept the full log of the swap, as a path on the machine that runs the sandbox."),
+    keepUntil: z
+        .number()
+        .optional()
+        .describe(
+            "Until when the previous version stays parked and ready, in milliseconds. While it does, going back takes seconds and nothing is downloaded or rebuilt; after it, going back uses the pinned image.",
+        ),
+});
+export type UpdateOutcome = z.infer<typeof UpdateOutcomeSchema>;
+
+// A published release that was taken back after it shipped (the release pipeline's rollback-stable.sh marks it on its
+// GitHub release). A sandbox running one is told, and offered the way back.
+export const WithdrawnReleaseSchema = z.object({
+    version: z.string().describe("The withdrawn version, which is the one this sandbox is running."),
+    reason: z.string().optional().describe("Why it was withdrawn, as the people who withdrew it put it."),
+});
+export type WithdrawnRelease = z.infer<typeof WithdrawnReleaseSchema>;
+
+// The owner's "not this one": no update is offered while the newest release is the skipped one. `null` clears it.
+export const SkipUpdateInputSchema = z.object({
+    version: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe("The release to stop offering, or null to offer the newest release again. A newer release than the skipped one is always offered."),
+});
+export type SkipUpdateInput = z.infer<typeof SkipUpdateInputSchema>;
+
+// One image a sandbox can go back to, as `ic sandbox versions` knows it: the pinned local image and what it says it is.
+export const RollbackTargetSchema = z.object({
+    image: z.string().describe("The local image a rollback would run, pinned under a tag no other flow writes."),
+    version: z.string().optional().describe("What that image says it is. Absent when it would not say."),
+});
+export type RollbackTarget = z.infer<typeof RollbackTargetSchema>;

package/src/state/history-state.ts

@@ -78,6 +78,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "engines/", portability: "derived" },
     // An update the host downloaded and built for this sandbox (`ic sandbox prepare`); about this machine only.
     { path: "update-staged.json", portability: "derived" },
+    // What the host last did about this sandbox's version (ic writes it), the owner's skipped release, and why the
+    // last boot could not start (the daemon writes it, the host's probation reads it): all rebuilt by whoever next says.
+    { path: "update-outcome.json", portability: "derived" },
+    { path: "update-skipped.json", portability: "derived" },
+    { path: "boot-failure.json", portability: "derived" },
 
     /* ---- credentials ---- */
 

package/src/state/workspace-state.ts

@@ -132,6 +132,10 @@ const STATE_FILES = [
     // needing, not what one machine did. The drift snapshot self-expires on a move since its `bornAt` won't match the
     // new container.
     { path: ".intentic/records/runtime-installs.json", invalidates: ["environment"], portability: "carry" },
+    // What agents are waiting on people for (docs/architecture/needs.md): every open need and the recent closed ones.
+    // Holds no credential (a secret need names the secret, its value goes to the secret store), so it may `carry`: a
+    // question a moved sandbox still has to ask. `needs` is the chat cards', the board's and the inbox's shared read.
+    { path: ".intentic/records/needs.json", invalidates: ["needs"], portability: "carry" },
     // Where each agent engine's version comes from: blessed list, upstream newest, a pin, or the image
     // (schemas/engines.ts). The versions themselves are machine state on the daemon's volume (architecture-specific
     // binaries); the policy here travels. `versioned`: a human decision worth reviewing. Own key, not `environment`'s:

package/src/text/transcript-fold.ts

@@ -16,6 +16,7 @@ import { isLandConflict } from "../events/land-conflict.js";
 import { turnedAwayCode } from "../policy/turned-away.js";
 import { mentionedPathTokens } from "./mentions.js";
 import { unspokenPromptRow } from "../events/agent-words.js";
+import { needRowText } from "../events/need-wake.js";
 
 // Folds a turn's frames into rows once, live and for the settled record alike, so a reopened chat matches what was on
 // screen. `tag` selects the stream read: undefined is the main turn, a tool-call id is the subagent it spawned; other
@@ -408,6 +409,9 @@ export class TranscriptFold {
                 return this.park(event.requestId, { paymentOffer: { requestId: event.requestId, offer: event.offer, status: "pending" } });
             case "credential_offer":
                 return this.park(event.requestId, { credentialOffer: { requestId: event.requestId, offer: event.offer, status: "pending" } });
+            case "need":
+                // A row of its own, not a park: the turn goes on, and the card reads the need's live state by its id.
+                return this.pushRow({ role: "notice", text: needRowText(event.need), need: event.need });
             case "resolved":
                 // Releases the card; the answering window already froze it locally, so this is a no-op there.
                 return this.patchParked(event.requestId, (row) => Object.assign(row, settledRequests(row, event.reply)));