@intentic/sandbox-contract 1.231.0 → 1.232.0

package/src/schemas.ts

@@ -1937,6 +1937,23 @@ export const SteerSchema = z
 // /agent fetch (which sends no cancel frame).
 export const StopTurnSchema = z.object({ conversationId: z.string().min(1).describe("Which conversation's running turn to cancel.") });
 
+/* RUN THE HELD TURN AGAIN, and it carries a conversation id and NOTHING else, which is the entire point of it
+ * existing as its own route rather than as a flag on a turn.
+ *
+ * A spent allowance leaves a turn stranded that the daemon still holds in full: the prompt, the attachments, the
+ * model, the effort, the mode, the worktree, the session that holds whatever it managed to do. Every one of
+ * those is on the turn the daemon already has, and a client that re-derived them from its own transcript would
+ * be re-deriving them from the STRIPPED copy it renders (no preamble notes, no attachment note, no model), which
+ * is how a re-send comes to run a different turn from the one it claims to repeat.
+ *
+ * So the caller says only WHICH conversation, and the daemon re-runs the turn it kept. What comes back is an
+ * ordinary StartedTurn, and the caller then attaches to it exactly as it would to a turn somebody else started
+ * (the resume note on the prompt is what tells an attaching window to reuse the bubble that is already there
+ * instead of drawing the same message twice). */
+export const ResumeTurnSchema = z.object({
+    conversationId: z.string().min(1).describe("Which conversation's held turn to run again."),
+});
+
 // ---- claude rate-limit gate ----
 // The GATE signal: whether the provider is letting turns through right now, and, when it is refusing, which
 // window is binding and when it lifts. This is the SDK's rate_limit_event, mapped one-to-one, and it is only
@@ -7890,15 +7907,41 @@ export type MachineSandbox = z.infer<typeof MachineSandboxSchema>;
  *
  * The machine enforces which of them it will do: `sandboxes` covers everything but removal, which takes its own
  * switch, and a refusal comes back as the machine's own sentence naming the control to flip. */
-export const MachineSandboxOpSchema = z.enum(["start", "stop", "restart", "prepare", "update", "rebuild", "rollback", "remove", "logs"]);
+/* `runner-up` / `runner-remove` are the same door for a container that belongs to THIS SANDBOX rather than to
+ * a person: a runner (runners/, docs/remote-runners-plan.md at the workspace root). They ride here because to
+ * the machine they are the same act it already does, run and remove a sandbox container, and to the person
+ * clicking they are the same row of buttons. Both take the `sandboxes` switch and neither takes the removal
+ * one: a runner holds no workspace of its own, only a mirror of the parent's git, so removing it destroys
+ * nothing the parent does not still have. */
+export const MachineSandboxOpSchema = z.enum([
+    "start",
+    "stop",
+    "restart",
+    "prepare",
+    "update",
+    "rebuild",
+    "rollback",
+    "remove",
+    "logs",
+    "runner-up",
+    "runner-remove",
+]);
 export type MachineSandboxOp = z.infer<typeof MachineSandboxOpSchema>;
 
 export const MachineSandboxFlowSchema = z.object({
     op: MachineSandboxOpSchema,
+    // Which sandbox, or, for the two runner ops, which RUNNER: the name it is known by at both ends, the
+    // parent's `/system/runners` list and the machine's `ic runner list`.
     slug: z.string().min(1),
     // The approved overlay's sha256, required by `rebuild` and meaningless to the rest. It is the trust anchor:
     // only content that still hashes to what the owner reviewed is ever built.
     hash: z.string().optional(),
+    /* `runner-up` only, and both are filled in by the DAEMON, never by the caller: where the runner dials
+     * (this sandbox's public URL) and the single-use pairing it redeems there. The browser asks for a runner
+     * on a machine; it never holds the credential that makes one, which is what keeps a pairing out of every
+     * surface between here and that machine. */
+    parentUrl: z.string().optional(),
+    pair: z.string().optional().meta({ secret: true }),
 });
 export type MachineSandboxFlow = z.infer<typeof MachineSandboxFlowSchema>;
 
@@ -8500,6 +8543,73 @@ export const SubagentIdParamSchema = z.object({ id: z.string() });
 // proposal present with a hash different from custom's.
 
 const environmentFileSchema = z.object({ content: z.string(), hash: z.string() });
+
+/* ---- environment DRIFT: what the live container has that the image did not put there ----
+ *
+ * Anything installed outside /work dies with the container, and transcript mining showed the same tools being
+ * reinstalled session after session (cargo-xwin six times, a Windows rustup target eight) before anyone thought
+ * to bake them. Drift is the daemon OBSERVING that gap rather than trusting the model to report it: apt installs
+ * read from dpkg's own log, everything else from system paths newer than the container itself. Two channels
+ * because they are disjoint by construction — dpkg unpacks files with their archive mtimes, so an mtime sweep
+ * cannot see apt, and nothing apt does lands under the swept prefixes' hand-installed corners. */
+export const EnvironmentDriftSchema = z.object({
+    // When this container was created (PID 1's start). A snapshot whose bornAt is not the running container's
+    // describes a container that no longer exists, and every reader must treat it as no drift at all.
+    bornAt: z.number(),
+    // When the probe ran.
+    at: z.number(),
+    // Debian packages installed since the container was born, from /var/log/dpkg.log.
+    apt: z.array(z.string()),
+    // System paths (outside /work) newer than the container, collapsed so a browser download is one entry.
+    paths: z.array(z.string()),
+});
+export type EnvironmentDrift = z.infer<typeof EnvironmentDriftSchema>;
+
+// How a runtime install was made, which decides whether the daemon can draft a Dockerfile step for it
+// mechanically (apt/cargo/npm/rustup-target) or only surface it for a person to route (pip belongs in a venv or
+// a Debian package, "other" is a curl|sh whose replay could embed anything).
+export const RuntimeInstallKindSchema = z.enum(["apt", "pip", "cargo", "npm", "rustup-target", "playwright", "gem", "pipx", "go", "other"]);
+export type RuntimeInstallKind = z.infer<typeof RuntimeInstallKindSchema>;
+
+/* One tool's runtime-install history across sessions: the ledger entry behind the recurrence signal. Sessions
+ * are the unit of recurrence — a session that retries an install five times needed it once — and the entry
+ * survives container recreates (the file lives under /work), which is exactly what makes "installed again in a
+ * fresh container" observable at all. */
+export const RuntimeInstallSchema = z.object({
+    tool: z.string(),
+    kind: RuntimeInstallKindSchema,
+    // Distinct conversation ids that installed it, capped; length is the recurrence count that gates drafting.
+    sessions: z.array(z.string()),
+    // The most recent install commands, capped, secrets already masked to references by the harness.
+    commands: z.array(z.string()),
+    firstAt: z.number(),
+    lastAt: z.number(),
+    count: z.number(),
+    // The owner rejected an auto-drafted step for this tool: never propose it again until this is cleared.
+    declinedAt: z.number().optional(),
+});
+export type RuntimeInstall = z.infer<typeof RuntimeInstallSchema>;
+
+export const RuntimeInstallsFileSchema = z.object({
+    installs: z.array(RuntimeInstallSchema),
+    // The last drift snapshot, persisted so a daemon restart does not blank the card until the next sweep.
+    drift: EnvironmentDriftSchema.optional(),
+});
+export type RuntimeInstallsFile = z.infer<typeof RuntimeInstallsFileSchema>;
+
+// A ledger entry as the Environment card shows it: recurrence joined with whether the install is present in the
+// LIVE container (drift-corroborated), already drafted for approval, or previously declined.
+export const EnvironmentRecurringSchema = z.object({
+    tool: z.string(),
+    kind: RuntimeInstallKindSchema,
+    sessions: z.number(),
+    lastAt: z.number(),
+    live: z.boolean(),
+    drafted: z.boolean().optional(),
+    declined: z.boolean().optional(),
+});
+export type EnvironmentRecurring = z.infer<typeof EnvironmentRecurringSchema>;
+
 export const EnvironmentSchema = z.object({
     proposal: environmentFileSchema.optional(),
     // The owner-approved agent-written custom section (.intentic/config/environment.custom.Dockerfile).
@@ -8509,6 +8619,10 @@ export const EnvironmentSchema = z.object({
     appliedHash: z.string().optional(),
     // config.sandbox.name, the UI derives the rebuild one-liner's slug from it.
     container: z.string().optional(),
+    // What the live container has that the image did not put there; absent until the first sweep of this container.
+    drift: EnvironmentDriftSchema.optional(),
+    // Runtime installs worth the owner's attention: recurring across sessions, or present-and-doomed right now.
+    recurring: z.array(EnvironmentRecurringSchema).optional(),
 });
 export type Environment = z.infer<typeof EnvironmentSchema>;
 export const EnvironmentApproveSchema = z.object({ hash: z.string().min(1) });
@@ -8577,33 +8691,10 @@ export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
  * by entry in WORKSPACE_STATE_FILES / HISTORY_STATE_FILES. It cannot carry the other two, and the honest
  * consequence is that an import ends in a REPORT rather than a claim of equivalence, the container has no
  * docker socket, so only the host can rebuild the image the overlay describes.
- */
-
-// What the bundle says about itself, written as its first tar entry so a reader learns the shape before the
-// bytes. `secrets` is the owner's export-time choice; the restorer re-derives every decision from the manifests
-// rather than trusting this, and uses it only to explain what is missing.
-export const BundleManifestSchema = z.object({
-    // Bumped when the layout changes in a way an older daemon would misread. Refused rather than guessed at.
-    version: z.literal(1),
-    // Where it came from, for the report's first line. Never used to authorize anything.
-    sandbox: z.object({ name: z.string() }).optional(),
-    createdAt: z.number(),
-    secrets: z.boolean(),
-    /* The environment the target has to reproduce, carried as FACTS rather than as the composed file (which the
-     * target recomposes against its OWN base image on first boot). `customDockerfile` is the owner-approved
-     * source section; `capabilities` names what contributed the remaining fragments, so the report can list what
-     * to re-add when the configs themselves did not travel. */
-    environment: z.object({
-        customDockerfile: z.string().optional(),
-        baseImage: z.string().optional(),
-        approvedHash: z.string().optional(),
-        capabilities: z.array(z.object({ id: z.string(), kind: z.string() })),
-    }),
-    // Every path class the bundle deliberately left out, with the manifest's own note where it has one. This is
-    // what turns "the export skipped things" from a silence into a list the owner can act on.
-    excluded: z.array(z.object({ path: z.string(), portability: z.string(), note: z.string().optional() })),
-});
-export type BundleManifest = z.infer<typeof BundleManifestSchema>;
+ *
+ * The bundle's manifest (BundleManifestSchema) lives in definition.ts beside the sandbox DEFINITION it embeds:
+ * a bundle is definition + state, and keeping the two schemas together is what keeps the two export doors from
+ * drifting into different answers about what an environment is. */
 
 // What a restore actually did. `needsAction` is the part that matters: the environment rebuild command, the
 // credentials to re-enter, the logins to redo, each one a thing the target cannot do for itself.

package/src/workspace-state.test.ts

@@ -343,6 +343,10 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             // The owner's per-extension update posture (notify / agent / auto): a standing decision about
             // what may run unattended, which is exactly the kind of edit worth a line in `git log`.
             `.intentic/config/extension-update-policy.json`,
+            // Which commands are heavy enough to take turns, and how many may run at once. Tracked because
+            // raising that limit is a decision about every session sharing the box, and `git log` is the only
+            // thing that answers "since when have we been allowing four of these at a time".
+            `.intentic/config/heavy-commands.json`,
             `.intentic/config/loop-designs.json`,
             `.intentic/config/personas.json`,
             // A persona's own kit: the prompt it runs on and the skills only its turns reach. Tracked for the

package/src/workspace-state.ts

@@ -221,6 +221,18 @@ const STATE_FILES = [
     },
 
     { path: ".intentic/config/settings.json", invalidates: ["settings", "manifests"], portability: "carry", versioned: true },
+    /* Which agent commands are heavy enough to take turns, and how many may run at once (the daemon reads it
+     * per Bash command: platform/heavy-commands.ts).
+     *
+     * `carry`, because the answer is a property of the WORKSPACE rather than of this machine: `pnpm test` fans
+     * out to the same 74 packages wherever the repo is cloned, so a fresh sandbox should arrive already knowing
+     * which commands to queue rather than rediscovering it by freezing once.
+     *
+     * `versioned` for the reason the config slice generally is (personas.json's entry argues it): the file
+     * changes at human speed, it holds no secret, and a change to it is exactly the kind a reviewer should see
+     * — raising the limit is a decision about everyone's sessions on that box, and `git log` is the only thing
+     * that answers "since when have we allowed four of these at once". */
+    { path: ".intentic/config/heavy-commands.json", invalidates: ["settings"], portability: "carry", versioned: true },
     // The rule table's last-fired stamps, beside the rules themselves. `derived` rather than `carry`: it is a
     // record of what happened in THIS sandbox, and carrying it to a fresh one would date every rule to work
     // that machine never did.
@@ -230,6 +242,13 @@ const STATE_FILES = [
         portability: "derived",
         note: "Stamps of when each rule last did something; the new sandbox starts its own record.",
     },
+    /* The runtime-install ledger: which tools sessions installed into the container at runtime, how often, and
+     * the last drift snapshot (environment/runtime-installs.ts). `carry` where rule-firings chose `derived`,
+     * because the two record different subjects: a firing is about what THIS machine did, while the ledger is
+     * about what this WORKSPACE's tasks keep needing — a workspace moved to a fresh sandbox will hit the same
+     * missing tools, and arriving with the recurrence memory is the whole reason it is kept. The drift snapshot
+     * inside is machine-scoped, and self-expires on the move: its bornAt can never match the new container. */
+    { path: ".intentic/records/runtime-installs.json", invalidates: ["environment"], portability: "carry" },
     /* Written by the AGENT's file tools (the drafts skill), read by the owner's approval inbox, the one entry
      * here whose whole point is that a change arrives from outside the browser that renders it. `authored`:
      * a draft is text somebody wrote, and "find the reddit draft about X" is an ordinary search.