@intentic/sandbox-contract 1.176.2 → 1.209.0

package/src/capability-ledger.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import { type AgentCapabilities, capabilitiesOf, limitationsOf } from "./agent-catalog.js";
+
+/* THE CAPABILITY LEDGER — which claims in the record are backed by machinery, and which by prose.
+ *
+ * agent-catalog.test.ts asks two other questions: does every provider/harness pair HAVE a row, and does every
+ * axis a record can lack have words for it. A row can pass both and still be a lie. The ability is declared,
+ * the sentence renders in the picker's footer, and nothing anywhere behaves differently — so the day the
+ * runtime gains the ability (or loses it), the declaration keeps its old value and the footer keeps telling the
+ * user something that stopped being true. Over-promising is the direction that hurts: told a runtime can be
+ * steered, someone types a mid-turn correction into a queue that does not exist.
+ *
+ * The record's header already states the rule — "a capability is listed here only if something READS it". This
+ * is the rule with teeth. Every field is ENFORCED (a seam opens or closes on it, and the entry cites where) or
+ * DESCRIPTIVE (it gates nothing; its whole job is that one sentence). `Record<keyof AgentCapabilities, …>`
+ * makes the split exhaustive at COMPILE time: a field added to the interface without an entry here does not
+ * typecheck, and neither does an entry for a field that no longer exists. There is no way to add an ability and
+ * leave the question of what backs it unanswered.
+ *
+ * WHAT THIS DOES NOT DO, deliberately: prove an ENFORCED gate exists. Those gates live in the daemon and the
+ * web, which sit ABOVE this package and must not be imported back into it. So an enforced entry's citation is a
+ * comment a reader checks, and the honest reading is "someone verified this once" — not "CI verifies it". The
+ * descriptive half IS machine-checked below, because it can be: those claims reach the user through
+ * `limitationsOf`, which is right here.
+ *
+ * Moving a field between the two sets belongs in the same change that adds or removes its gate. */
+
+type Backing = "enforced" | "descriptive";
+
+const LEDGER: Record<keyof AgentCapabilities, Backing> = {
+    // adapter-registry.ts maps runtime → the adapter that serves the turn; getting it wrong runs the turn on
+    // the wrong loop entirely. Also keys the daemon's per-runtime health probes (useSandboxVersion.ts).
+    runtime: "enforced",
+    // conversation.ts's `steerable` — the composer offers mid-turn injection only where there is a queue.
+    steering: "enforced",
+    // turn-plan.ts forwards `permissionMode` only under "modes" (bar plan); modesFor/clampMode build the
+    // composer's mode list from it, so a plan-only runtime is offered two postures rather than four names.
+    permissions: "enforced",
+    // turn-plan.ts opens the tool seam on "full" and attaches the setup notice when it is anything less.
+    mcp: "enforced",
+    // turn-plan.ts drops `effort` unless the runtime takes it; ComposerEffort.vue renders no scale without it.
+    effort: "enforced",
+    // turn-plan.ts drops `fast` unless the loop can ask for it. The one axis with no sentence of its own: a
+    // record alone cannot tell the truth about it (a translator-routed turn reads true and still cannot go
+    // fast), so the user-facing answer comes from fastAllowed instead.
+    fastMode: "enforced",
+    // turn-plan.ts tells a "cwd" turn where its worktree is, because an absolute /work path still reaches the
+    // shared checkout there. Under "namespace" the mount does it and the note would be noise.
+    isolation: "enforced",
+    /* system-prompt.ts composes a turn's standing instructions AGAINST this value — a replacement where one may
+     * be sent, an addition where only that is possible, and the user-message door for the persona note where
+     * there is no system seam at all — and each adapter reads the field the composition set (codex-agent.ts's
+     * two config keys, grok-agent.ts's per-message `system`). It is also the one axis whose absence was the bug
+     * that produced it: before the field existed, every runtime was composed for as though it were the Claude
+     * Code loop, and five of the six silently dropped the owner's prompt. */
+    instructions: "enforced",
+    // turn-plan.ts (honoured) plans the JS backend only where "js" is declared, so a runtime without it is
+    // handed no `jsExecution` and mounts no Code tool — the same drop-what-you-can't-honour rule as `effort`.
+    execution: "enforced",
+
+    /* DESCRIPTIVE — true of the runtime, and nothing consults them. Each describes behaviour that is emergent
+     * rather than gated: an agent that never emits `question` frames simply never asks, one that publishes no
+     * commands leaves the `/` popover empty. Nothing has to switch off, which is why nothing does. That also
+     * means the declaration and the behaviour are two independent facts, and only the reader below keeps them
+     * from disagreeing in the one place a user can see. Wiring one up (hiding the terminal tab, skipping
+     * auto-resume) moves it to ENFORCED — in the change that wires it. */
+    questions: "descriptive",
+    commands: "descriptive",
+    terminals: "descriptive",
+    recovery: "descriptive",
+};
+
+// The full ceiling: every ability real, so `limitationsOf` has nothing to say about it. Read from the catalog
+// rather than written out, so this is the record the product actually ships.
+const CEILING = capabilitiesOf("claude", "native");
+
+const fieldsWhere = (backing: Backing): (keyof AgentCapabilities)[] =>
+    (Object.keys(LEDGER) as (keyof AgentCapabilities)[]).filter((field) => LEDGER[field] === backing);
+
+/* The compiler pins the ledger against the INTERFACE. This pins it against a live record, which is not the same
+ * claim: an optional field, or one a record leaves off, typechecks and then is not there to gate anything. */
+it("classifies exactly the fields a live record carries", () => {
+    expect(Object.keys(LEDGER).toSorted()).toEqual(Object.keys(CEILING).toSorted());
+});
+
+/* A DESCRIPTIVE field earns its place by reaching the user, since by definition it does nothing else. Checked
+ * per field rather than by counting sentences: an aggregate is satisfied by one axis contributing two lines
+ * while another contributes none, which is exactly the case worth catching. Anything that survives here without
+ * a sentence is decoration, and the fix is to delete the field or wire it up — not to add an exemption. */
+describe("a descriptive claim reaches the user", () => {
+    it("has something to disclose against: the ceiling discloses nothing", () => {
+        expect(limitationsOf(CEILING)).toEqual([]);
+    });
+
+    it.each(fieldsWhere("descriptive"))("%s puts its own sentence in the picker when the runtime lacks it", (field) => {
+        expect(typeof CEILING[field], `${field} is descriptive but not a boolean — teach the flip below how to diminish it`).toBe("boolean");
+
+        const lacking: AgentCapabilities = { ...CEILING, [field]: false };
+
+        expect(limitationsOf(lacking)).toHaveLength(1);
+    });
+});
+
+/* The ledger is a split, not a label: a set that swallowed everything would typecheck and prove nothing. Both
+ * sides being occupied is what makes reading an entry informative — and if the descriptive side ever empties
+ * because every axis got wired up, that is a real event, and deleting this file is the right response to it. */
+it("is a real split — neither side is empty", () => {
+    expect(fieldsWhere("enforced").length).toBeGreaterThan(0);
+    expect(fieldsWhere("descriptive").length).toBeGreaterThan(0);
+});

package/src/chores/chores.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { CHORE_KINDS, CHORES } from "./chores.js";
+
+/* THE BOOK'S ORDER, checked. The reading order used to be a paragraph of prose above a hand-sorted array, which
+ * is the one kind of claim this file cannot make: English cannot be compiled, and the array it described was
+ * maintained by whoever added the last chore. Now the order is derived from `kind`, and these are the three
+ * things that derivation is only worth anything if they hold. */
+
+describe(`the chore book's order`, () => {
+    it(`groups the book by kind, in CHORE_KINDS order`, () => {
+        const ranks = CHORES.map((chore) => CHORE_KINDS.findIndex((spec) => spec.kind === chore.kind));
+        // Every chore's kind is one CHORE_KINDS names (-1 would sort it to the front and silently outrank
+        // security), and no kind is interleaved with another.
+        expect(ranks).not.toContain(-1);
+        expect(ranks).toEqual(ranks.toSorted((left, right) => left - right));
+    });
+
+    it(`keeps every chore in the book`, () => {
+        // The sort cannot drop an entry — but a future refactor to a filter-into-groups could, so the count is
+        // pinned to the ids rather than to a number, which says which one went missing.
+        expect(new Set(CHORES.map((chore) => chore.id)).size).toBe(CHORES.length);
+        expect(CHORES.length).toBe(17);
+    });
+
+    it(`says "surveying" exactly when a chore is a survey`, () => {
+        // The two are the same claim: a survey has no measurement, so "due because it has been that long" IS the
+        // surveying kind. Checked in both directions, because either half drifting makes the grouping a lie.
+        for (const chore of CHORES) {
+            expect(chore.survey === true).toBe(chore.kind === `surveying`);
+        }
+    });
+});