@intentic/sandbox-contract 1.243.0 → 1.245.0

package/src/schemas/computers.ts

@@ -1,6 +1,8 @@
 // computers: what ONE of the user's own machines is running
 import { z } from "zod";
 import { HostFactsSchema } from "./hosts.js";
+// The one sentinel every non-release build carries, so a locally compiled agent is never told it is behind.
+import { DEV_VERSION } from "../versions.js";
 /* The other end of desktop sync, stated as a fact instead of a claim.
  *
  * Everything here already existed, as the machine agent's printed status on a terminal nobody running the desktop app
@@ -306,14 +308,21 @@ export type MachineReport = z.infer<typeof MachineReportSchema>;
  * status`) and the browser (the Computers row) both answer this question, and a machine that is behind in one and
  * fine in the other is worse than either answer alone. The remedy is the same in both: restart the loop.
  *
- * Silent whenever either half is unknown, which covers a loop that is stopped (nothing is serving, and the row
- * already says so in louder words), an agent too old to stamp its build, and a machine with no installed agent to
- * compare against — none of which is a skew, and each of which would otherwise nag about a difference nobody can
- * act on. */
-export const watcherBuildSkew = (report: MachineReport): { readonly running: string; readonly installed: string } | undefined => {
+ * AN UNSTAMPED LOOP IS THE LOUDEST CASE, not a missing one, and reading it as "nothing to say" is what let this
+ * whole check miss the machines it was written for. `watcher.build` is stamped into the pidfile by the loop that
+ * claimed it, so a loop old enough to predate the stamp reports none — and it is running, and something newer is
+ * installed beside it, which is a skew by definition and a wider one than any it could have named. Every surface
+ * therefore went quiet on precisely the machines furthest behind: upgrade, see the new number everywhere, watch
+ * nothing change, and have no screen anywhere say why.
+ *
+ * So the running build is OPTIONAL in the answer and the question is asked of the installed one. Still silent
+ * whenever the honest answer is "no idea": a loop that is stopped (nothing is serving, and every surface already
+ * says so in louder words), a machine with no installed agent to compare against, and a working-tree build, which
+ * is not a version and must not be told it is behind. */
+export const watcherBuildSkew = (report: MachineReport): { readonly running: string | undefined; readonly installed: string } | undefined => {
     const running = report.watcher.build;
     const installed = report.agents.sync;
-    if (!report.watcher.running || running === undefined || installed === undefined || running === installed) {
+    if (!report.watcher.running || installed === undefined || installed === DEV_VERSION || running === installed) {
         return undefined;
     }
     return { running, installed };

package/src/schemas/engines.ts

@@ -82,6 +82,7 @@ export const EngineRowSchema = z.object({
     previous: z.string().optional().describe("The version kept one step back, which is what going back means."),
     quarantined: z.array(EngineQuarantineSchema).describe("Versions the store installed and then refused, with the reason."),
     diskBytes: z.number().int().nonnegative().describe("What this engine's kept versions cost on the daemon's volume."),
+    installing: z.boolean().optional().describe("Whether this engine is currently being installed in the background."),
 });
 export type EngineRow = z.infer<typeof EngineRowSchema>;
 

package/src/schemas/plan-limits.ts

@@ -259,6 +259,25 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .boolean()
             .describe("Yes releases exactly one payment. Anything else spends nothing. This click is the only way the money can move."),
     }),
+    /* A GATED CREDENTIAL's release, and the one reply on this list whose sender is CHECKED. Every other card
+     * here is answered by whoever holds a session, because every other card is the owner's to decide; this one
+     * is addressed to a named list, so the daemon reads the verified identity off the request and refuses a
+     * click from anybody else with the card left standing for whoever can answer it. The refusal covers `no`
+     * as well: a stranger may not skip a release on the approver's behalf either, or the gate would be a
+     * denial-of-service anybody with a session could aim at a turn.
+     *
+     * `approve` carries no qualifiers because the gate's own policy decides how far one yes goes: a per-use
+     * gate releases exactly this use and the next one asks again, a conversation-scoped gate covers the rest
+     * of the conversation. The card says which, so the click is never wider than it reads. */
+    z.object({
+        kind: z.literal("credential_offer").describe("Releasing a credential the agent may only use once a named person says so."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        approve: z
+            .boolean()
+            .describe(
+                "Yes releases it, as far as the card says (this one use, or the rest of the conversation). Only the people the card names can answer at all, yes or no.",
+            ),
+    }),
 ]);
 export type AgentReply = z.infer<typeof AgentReplySchema>;
 // Steering: a user message delivered INTO the running turn (injected between tool calls, Claude Code style),

package/src/schemas/secrets.ts

@@ -16,6 +16,102 @@ export const SecretKeysSchema = z.object({
 });
 export const SecretKeyParamSchema = z.object({ key: z.string().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 CREDENTIAL THE AGENT MAY NOT USE UNTIL A NAMED PERSON SAYS SO, and who that person is.
+ *
+ * Masking already answers "can the model SEE this value" (no: it reads a `{{secret:name}}` reference), and
+ * the answer was enough while the only question was disclosure. It is not the whole question. A reference the
+ * model can write is a credential the model can SPEND, at whatever moment its own reasoning arrives at, and
+ * for the small set of credentials where one wrong spend is the incident — the production database's
+ * password, the company X account, the card-shaped connector — the owner wants the moment itself decided by a
+ * person, not the storage of the value. That is what a gate is: not a second lock on the vault, a REQUIRED
+ * CLICK in front of the exit.
+ *
+ * WHAT IT IS NOT A WALL AGAINST. A shell in this container runs as the workspace's owner and the policy file
+ * sits beside the vault it guards; anything that can read one can read the other, and a compromised container
+ * is out of scope here exactly as it is for the vault (SECURITY.md). The gate is a wall against the AGENT's
+ * own judgment being the last word — a prompt-injected model can ask for a release and cannot grant itself
+ * one — and against the ordinary accident of a turn reaching for the live credential when the staging one was
+ * meant.
+ *
+ * THE APPROVERS ARE AN EXACT LIST, not a role floor, and the owner is not on it implicitly. "Only Bob may
+ * release the production password" is the sentence people actually mean, and a floor cannot say it: a floor of
+ * `maintainer` says "anyone senior enough", which is the thing the owner was trying to narrow. So the list is
+ * the list, the owner adds themselves when they mean themselves, and a click from anybody else is refused
+ * server-side with the card left standing for whoever can. */
+export const CredentialGateScopeSchema = z
+    .enum(["use", "conversation"])
+    .describe(
+        "How far one release goes: `use` asks again every single time (one click releases exactly one use), `conversation` covers the rest of this conversation and is forgotten when the daemon restarts.",
+    );
+export type CredentialGateScope = z.infer<typeof CredentialGateScopeSchema>;
+
+// What a gate is ABOUT: one stored secret by its reference name, or one whole connected capability (a
+// connector's env, a browser account's profile, an MCP server) by its id. Two kinds rather than one because
+// they are withheld differently — a secret is refused at the exit it would resolve at, a capability is simply
+// never mounted for the turn — and the subject namespaces are disjoint anyway (env keys are SCREAMING_SNAKE).
+export const CredentialGateKindSchema = z
+    .enum(["secret", "capability"])
+    .describe("Whether this gate covers one stored secret, by the name a reference carries, or one whole connected capability, by its id.");
+export type CredentialGateKind = z.infer<typeof CredentialGateKindSchema>;
+
+/* WHICH EXIT A RELEASE WAS ASKED FOR, so the card can say what is about to happen in the reader's terms
+ * rather than in the daemon's. The three secret exits are the ones the use ledger already names (a shell
+ * command, a JS run's script, a browser keystroke); `session` is a whole capability being mounted for the
+ * turn (a signed-in browser profile, a connector's env, an MCP server), and `otp` is one derived one-time
+ * code off a stored TOTP seed. */
+export const CredentialLaneSchema = z
+    .enum(["shell", "code", "browser", "session", "otp"])
+    .describe("What the credential was about to be used for: a shell command, a script, typing into a page, mounting a connected account, or one one-time code.");
+export type CredentialLane = z.infer<typeof CredentialLaneSchema>;
+
+export const CredentialGateSchema = z.object({
+    // An env/generated KEY (`DATABASE_URL`), or a capability id (`reddit`, `komodo`). A vault name's field
+    // half (`reddit/password`) is deliberately NOT a subject: gating one field of a connected account and not
+    // its neighbours would be a gate with a hole in it, so the whole capability is the unit.
+    subject: z.string().min(1).describe("What is gated: a secret's name, or a connected capability's id."),
+    kind: CredentialGateKindSchema,
+    approvers: z
+        .array(z.string().min(3))
+        .min(1)
+        .describe(
+            "Exactly who may release it, by email, from the people on the Access roster. Not a seniority floor: nobody outside this list can release it, the owner included, unless the owner is on it.",
+        ),
+    scope: CredentialGateScopeSchema,
+});
+export type CredentialGate = z.infer<typeof CredentialGateSchema>;
+
+export const CredentialGatesSchema = z.object({
+    gates: z
+        .array(CredentialGateSchema)
+        .describe("Every gate in force. Names, subjects and approver addresses only: this answer never carries a credential."),
+});
+export type CredentialGates = z.infer<typeof CredentialGatesSchema>;
+
+export const CredentialGateSubjectParamSchema = z.object({
+    subject: z.string().min(1).describe("Which gate, by the secret name or capability id it covers."),
+});
+
+/* THE AGENT'S OWN DOOR, `secrets request <subject> --why "…"`. A gated capability is ABSENT from a turn
+ * rather than refused inside it (its profile is not mounted, its env is not exported), so the model cannot
+ * discover the gate by tripping over it the way a secret reference does — it would conclude the account is
+ * disconnected and go looking for another road. This route is the road: it raises the same card the exits
+ * raise, and a release is worded as a grant for the REST OF THE CONVERSATION, because a session-shaped
+ * credential cannot be handed out for one use. */
+export const CredentialRequestSchema = z.object({
+    subject: z.string().min(1).describe("What to ask for: the secret's name, or the connected capability's id."),
+    why: z.string().max(280).optional().describe("One line on what it is for. The only words on the card that are the agent's."),
+    // Which conversation's chat the card goes up in, filled by the CLI from the turn's own environment, so
+    // the model cannot aim a card at somebody else's conversation.
+    conversationId: z.string().optional().describe("Which conversation to raise the card in. The CLI fills this from the running turn."),
+});
+
+export const CredentialGrantSchema = z.object({
+    granted: z.literal(true).describe("Always true: a refusal is an error with a sentence, never a `false` here."),
+    approvedBy: z.string().describe("Who released it."),
+    message: z.string().describe("What the grant means in practice, and what to do next."),
+});
+
 // One entry per secret the sandbox knows about, across every store: intent env secrets and intentic-generated
 // passwords (from the desired-state repo), capability credentials, and AI-provider accounts. Values never ride
 // this shape, `revealable` says whether `reveal` can return one (everything but provider accounts).
@@ -56,9 +152,23 @@ export const SecretInventoryEntrySchema = z.object({
                 .string()
                 .optional()
                 .describe("Where it went: the start of the command or script, or the site. Names and destinations only, never values."),
+            // Who released it, when a gate made that use somebody's decision. Absent on an ungated use, which
+            // is nearly all of them: the ledger row records a person only where a person was actually asked.
+            approvedBy: z.string().optional().describe("Who released it for that use, when it is gated. Absent when nothing had to be approved."),
         })
         .optional()
         .describe("The last time an agent actually spent this secret. Absent while it never has been, which most never are."),
+    /* THE APPROVAL THIS ENTRY IS BEHIND, joined on from the gate policy so the row can say "needs approval
+     * from Bob" without a second call. Absent on the overwhelming majority of entries: gating is for the few
+     * credentials where one wrong use is the incident, and a sandbox where everything asks is a sandbox where
+     * nobody reads the cards. */
+    gate: z
+        .object({
+            approvers: z.array(z.string()).describe("Who may release it, by email. Nobody else can, whatever their role."),
+            scope: CredentialGateScopeSchema,
+        })
+        .optional()
+        .describe("Who has to release this before the agent can use it, and for how long one release lasts. Absent when it is not gated."),
 });
 export type SecretInventoryEntry = z.infer<typeof SecretInventoryEntrySchema>;
 export const SecretInventorySchema = z.object({

package/src/schemas/settings.ts

@@ -1,5 +1,6 @@
 // settings: per-sandbox agent settings (.intentic/config/settings.json)
 import { z } from "zod";
+import { CommandJudgeModeSchema } from "../safety-policy.js";
 import { AdmissionPolicySchema, AdmissionRuleSchema, AgentRunPinSchema } from "./agent.js";
 // Which prompt the agent is, before this turn composes anything on top. Two built-in bases and an escape
 // hatch: Intentic's own (the default), Claude Code's preset, or the owner's text. Declared out here rather
@@ -715,17 +716,50 @@ export const SandboxSettingsSchema = z.object({
         .record(z.string(), AdmissionRuleSchema)
         .default({})
         .describe("What an agent may do out in the world, per kind of action: go ahead, ask first, or never."),
-    /* THE COMMAND GATE IS NOT CONFIGURED HERE. It used to be: `commandRules` was a verdict per CommandClass and
-     * `explainCommands` decided whether a card carried a sentence. Both are gone, and the reason is the whole
-     * safety redesign (safety-policy.ts argues it): a regex verdict per class asked about `echo "rm -rf /"` and
-     * an actual delete in the same words, and no setting of six switches fixes that, because telling the two
-     * apart is an act of understanding rather than a threshold. What replaced them is the owner's written
-     * policy at .intentic/config/safety.md, read by a judge that also sees what the daemon knows about the turn,
-     * plus one typed hard rule the judge cannot waive. The Safety page edits that document; nothing about the
-     * command gate belongs in this object.
-     *
-     * The sentence on a card is no longer optional either: it is the judge's own reason for the verdict, so a
-     * card without one would be a card that could not say why it exists. */
+    /* NO VERDICT FOR THE COMMAND GATE LIVES HERE, and the two settings that do are about the JUDGE rather than
+     * about what it should decide. `commandRules` used to be a verdict per CommandClass and `explainCommands`
+     * decided whether a card carried a sentence; both are gone, and the reason is the whole safety redesign
+     * (safety-policy.ts argues it). A regex verdict per class asked about `echo "rm -rf /"` and an actual delete
+     * in the same words, and no setting of six switches fixes that, because telling the two apart is an act of
+     * understanding rather than a threshold. What replaced them is the owner's written policy at
+     * .intentic/config/safety.md, read by a judge that also sees what the daemon knows about the turn, plus one
+     * typed hard rule the judge cannot waive. The Safety page edits that document; what a command may DO is
+     * settled there and nowhere in this object.
+     *
+     * WHETHER THE JUDGE RUNS AT ALL is a different question, and one this object has to answer, because it is
+     * the only tier of the design that spends money and interrupts people. An owner who does not want either is
+     * entitled to say so, and before this they could not: the old rulebook could be set to allow everything, and
+     * the redesign quietly made itself the one part of the sandbox you could only opt further into.
+     *
+     * Judged commands are also the one automatic job whose model choice genuinely differs from the rest of
+     * `quickModel`'s work, which is why the list below exists rather than a line in the comment above it: a
+     * commit message written by a model that misread the diff is a sentence somebody edits, and a verdict
+     * written by a model that misread a command is a card that should not have been raised or, worse, one that
+     * should have been. */
+    commandJudge: CommandJudgeModeSchema.default("on").describe(
+        "Whether a model reads your safety policy before a flagged command runs. Off judges nothing and asks about nothing; Watch judges everything and records it without ever interrupting you, which is how you find out what your policy actually does before you let it stop anything; On lets the verdict decide. Wiping a disk or deleting under /history asks at every setting — that rule is typed rather than judged, and cannot be turned off.",
+    ),
+    /* WHICH MODEL READS THE POLICY, an ordered list of `${provider}:${modelId}` keys (quickModelKey) walked top
+     * to bottom, or EMPTY for whatever the quick model would be.
+     *
+     * A LIST, for the reason every other model setting here is one: the head runs out and the whole feature goes
+     * with it. Falling back to the quick chain rather than to Auto is deliberate — it is what this did before the
+     * setting existed, so an owner who never opens the row keeps exactly the behaviour they had, and one who
+     * writes an entry is saying that command verdicts are worth a different model than commit messages.
+     *
+     * THE ARGUMENT FOR SETTING IT AT ALL, since the cheapest connected rung is the default: this prompt is the
+     * one quick job that is genuinely adversarial. Its input includes text the agent is about to run, which may
+     * have arrived from a stranger's web page, and a small model can be talked round by it (command-judge.ts is
+     * candid about that). It is also the job where being WRONG is expensive in both directions — a needless card
+     * teaches the owner to click through the next one. Neither is a reason for us to spend somebody's frontier
+     * allowance by default; both are reasons for them to be able to. */
+    commandJudgeModels: z
+        .array(z.string())
+        .max(10)
+        .default([])
+        .describe(
+            "Which models decide whether a flagged command should run, tried in order so one spent account does not take the gate down. Empty uses whatever the quick model is, which is what this did before the setting existed.",
+        ),
     /* HOW MUCH AN AGENT MAY DELEGATE, the three ceilings the Claude Code harness enforces on its own Agent
      * tool, surfaced here because their defaults are tuned for a laptop and this is a container the owner sized.
      *

package/src/transcript-fold.test.ts

@@ -392,6 +392,53 @@ describe("foldTurn", () => {
         ]);
     });
 
+    /* A GATED CREDENTIAL's card keeps WHO released it, not merely that something was approved: the approver is
+     * the whole point of the gate, and the reply cannot carry them (it is the daemon that verified the
+     * identity), so the receipt frame is the only place that name ever appears. */
+    it("keeps who released a gated credential on the card that asked for it", () => {
+        const offer = {
+            subject: "DATABASE_URL",
+            kind: "secret" as const,
+            lane: "shell" as const,
+            detail: "psql {{secret:DATABASE_URL}}",
+            why: "run the migration",
+            approvers: ["bob@corp.com"],
+            scope: "use" as const,
+        };
+        const events: AgentEvent[] = [
+            { kind: "credential_offer", requestId: "c1", offer },
+            { kind: "resolved", requestId: "c1", reply: { kind: "credential_offer", requestId: "c1", approve: true } },
+            { kind: "credential_receipt", requestId: "c1", outcome: "released", approvedBy: "bob@corp.com" },
+            { kind: "delta", text: "Migrated." },
+        ];
+        expect(foldOf("migrate", events).slice(1)).toEqual([
+            {
+                role: "assistant",
+                text: "",
+                credentialOffer: { requestId: "c1", offer, status: "approved", receipt: { outcome: "released", approvedBy: "bob@corp.com" } },
+            },
+            { role: "assistant", text: "Migrated." },
+        ]);
+    });
+
+    /* A release nobody answered is nobody's refusal. The deadline passing freezes the card `cancelled` and
+     * writes NO receipt, because "refused" would name a decision a person never made — the same split the
+     * gate's two refusal sentences make to the agent. */
+    it("freezes an unanswered release as nobody's decision, with no receipt", () => {
+        const offer = {
+            subject: "reddit",
+            kind: "capability" as const,
+            lane: "session" as const,
+            approvers: ["alice@corp.com"],
+            scope: "conversation" as const,
+        };
+        const events: AgentEvent[] = [{ kind: "credential_offer", requestId: "c1", offer }];
+        expect(foldTurn(openingOf("post it"), events, "stopped").slice(1)).toEqual([
+            { role: "assistant", text: "", credentialOffer: { requestId: "c1", offer, status: "cancelled" } },
+            { role: "notice", text: "Stopped." },
+        ]);
+    });
+
     // A turn the user stopped says so, after freezing whatever it was parked on.
     it("writes a stop down after cancelling what the turn was waiting on", () => {
         const events: AgentEvent[] = [

package/src/transcript-fold.ts

@@ -407,6 +407,8 @@ export class TranscriptFold {
                 return this.park(event.requestId, { capabilityOffer: { requestId: event.requestId, offer: event.offer, status: "pending" } });
             case "payment_offer":
                 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 "resolved":
                 // The card above was released, and the frame says how. The window that answered already froze its
                 // own card the instant its reply was accepted (card-status.ts, the same derivation), so this is a
@@ -441,6 +443,15 @@ export class TranscriptFold {
                         };
                     }
                 });
+            case "credential_receipt":
+                return this.patchParked(event.requestId, (row) => {
+                    if (row.credentialOffer !== undefined) {
+                        row.credentialOffer.receipt = {
+                            outcome: event.outcome,
+                            ...(event.approvedBy === undefined ? {} : { approvedBy: event.approvedBy }),
+                        };
+                    }
+                });
             // Facts about the turn, not rows in it (TURN_FACT_KINDS): the run relays them as themselves.
             case "session":
             case "init":

package/src/workspace-state.test.ts

@@ -359,6 +359,13 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             // 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".
             `${STATE_DIR}/config/heavy-commands.json`,
+            /* The scripts the rules run. Tracked because the exclude list carves entries out BY NAME, so a
+             * directory nobody marked is invisible both to `git add -A` and to the land: that is how 559e896
+             * came to repoint settings.json at two scripts it never staged, and how the pair written in a
+             * worktree never arrived. What the workspace held from then on was settings naming two hooks that
+             * did not exist, and every edit for a day firing `node` at a missing file. A rule is reviewable;
+             * the code it runs on every write has to be. */
+            `${STATE_DIR}/config/hooks/`,
             `${STATE_DIR}/config/loop-designs.json`,
             `${STATE_DIR}/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

@@ -273,6 +273,34 @@ const STATE_FILES = [
      * — 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 SCRIPTS THE RULE TABLE RUNS, one file per reader, at the moments settings.json points them at: the
+     * per-edit linter and byte scan today (`file.edited`), whatever the owner adds beside them tomorrow.
+     *
+     * IT IS HERE BECAUSE IT WAS NOT, and the gap was silent. The root repository excludes `.intentic/config/*`
+     * with one carve-out per tracked entry, derived from this table's `versioned` flags (history.ts
+     * rootExcludes), so a directory nobody marked is ignored — and an ignored file is invisible to the land.
+     * The two scripts were written in an agent's worktree; the rules naming them were written into
+     * settings.json, which IS tracked; and only the rules arrived. What the workspace held from then on was two
+     * hooks pointing at files that did not exist: a per-edit gate that looked armed on the settings screen,
+     * spawned a process on every edit, and read nothing. The linter and the byte scan ran nowhere between an
+     * edit and a push for as long as that stood.
+     *
+     * `versioned` for the strongest form of the reason the config slice generally is. This is not a setting that
+     * decides how the sandbox behaves, it is the CODE that runs when it does, against every file an agent
+     * writes: a change here deserves review more than a change to the rule that calls it. `carry`, because it is
+     * authored text about this workspace's own conventions, holding no credential and nothing about this
+     * machine. Invalidating nothing is a real answer here rather than a gap: the settings screen renders the
+     * RULES, which live in settings.json and have their own key. */
+    {
+        path: ".intentic/config/hooks/",
+        invalidates: [],
+        why: "The settings screen renders the rules that name these scripts, out of settings.json; nothing in the browser reads the scripts themselves.",
+        portability: "carry",
+        versioned: true,
+        // The daemon never BUILDS this path, it only runs what a rule's command names, so there is no statePath
+        // call for the coverage pair to find. Whoever authors a reader is the writer here.
+        outsideWriter: "the owner or an agent, authoring them; the daemon only ever RUNS one, by the path a rule's command names",
+    },
     // 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.