@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/box-ship.test.ts

@@ -0,0 +1,96 @@
+/**
+ * A box's ship (ws-100): the declaration's box.ship with its defaults, and
+ * what status --json says of it: the commit the box's site serves (the
+ * latest release in the ship's environment, under the box member) and the
+ * files waiting to ship between that commit and the working tree, tracked
+ * or not, bookkeeping left out.
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import type { ReleaseRecord } from "../lifecycle/release-ledger";
+import { cleanScratch, commitAll, contract, git, repo } from "./__fixtures__/contract-repo";
+import { readDeclaration } from "./declaration";
+import { workingTree } from "./tree";
+import declarationSchema from "./declaration.schema.json";
+import statusSchema from "./status.schema.json";
+import { SHIP_PENDING_PATHS_MAX, workspaceStatus, type StatusBoxShip } from "./status";
+
+afterAll(cleanScratch);
+
+function declaration(ship: Record<string, unknown> | undefined): string {
+  return `${JSON.stringify(
+    {
+      name: "demo",
+      schema: 1,
+      members: [
+        { name: "app", dir: "app", kind: "other", because: "a plain Node server" },
+        { name: "box", dir: "box", kind: "other", because: "the box", box: { services: [{ name: "web", cmd: "node server.mjs" }], ...(ship ? { ship } : {}) } },
+      ],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+const release = (commit: string): ReleaseRecord =>
+  ({ version: 1, component: "site", env: "box", digest: `sha256:${"a".repeat(64)}`, gitSha: commit, runId: "r1", timestamp: "2026-10-04T00:00:00Z", actor: "github:ada" }) as ReleaseRecord;
+
+async function shipOf(root: string, records: ReleaseRecord[] | Error, seen: string[] = []): Promise<StatusBoxShip | null> {
+  const doc = await workspaceStatus({
+    cwd: root,
+    env: "local",
+    readLedger: async (path) => {
+      seen.push(path);
+      if (records instanceof Error) throw records;
+      return { records: path === "box/releases.jsonl" || path.endsWith("/box/releases.jsonl") ? records : [], malformed: 0 };
+    },
+  });
+  contract(statusSchema).expectValid(doc);
+  return (doc as { members: { name: string; box: { ship: StatusBoxShip | null } | null }[] }).members.find((m) => m.name === "box")!.box!.ship;
+}
+
+describe("box.ship", () => {
+  test("the declaration fills in the gate, environment and bookkeeping, and the schema takes exactly these fields", () => {
+    const root = repo({ "chant.workspace.json": declaration({ op: "release", bookkeeping: ["./decisions/", "work"] }), "app/x": "", "box/x": "" });
+    const box = readDeclaration(workingTree(root)).members.find((m) => m.name === "box")!.box!;
+    expect(box.ship).toEqual({ op: "release", gate: "ship", env: "box", bookkeeping: ["decisions", "work"], pointer: "/members/1/box/ship" });
+    const { validate } = contract(declarationSchema);
+    expect(validate(JSON.parse(declaration({ op: "release", gate: "go", env: "site", bookkeeping: ["decisions"] })))).toBe(true);
+    expect(validate(JSON.parse(declaration({ gate: "ship" })))).toBe(false);
+    expect(validate(JSON.parse(declaration({ op: "release", bookkeeping: ["../out"] })))).toBe(false);
+    expect(validate(JSON.parse(declaration({ op: "release", extra: 1 })))).toBe(false);
+  });
+
+  test("status prints what the site serves and what is waiting: changes since that release, untracked files too, bookkeeping left out", async () => {
+    const root = repo({ "chant.workspace.json": declaration({ op: "release", bookkeeping: ["decisions"] }), "app/server.mjs": "v1\n", "decisions/D-1.md": "a\n" }, true);
+    const shipped = git(root, "rev-parse", "HEAD");
+    // Nothing shipped: no serving commit, nothing to compare with.
+    expect(await shipOf(root, [])).toEqual({ op: "release", gate: "ship", env: "box", bookkeeping: ["decisions"], serving: null, pending: null });
+
+    const seen: string[] = [];
+    expect((await shipOf(root, [release(shipped)], seen))!.pending).toEqual({ files: 0, paths: [] });
+    expect(seen).toContain("box/releases.jsonl");
+
+    // A commit since, an uncommitted edit, an untracked file, and bookkeeping that doesn't count.
+    writeFileSync(join(root, "app", "server.mjs"), "v2\n");
+    writeFileSync(join(root, "decisions", "D-1.md"), "b\n");
+    commitAll(root);
+    writeFileSync(join(root, "app", "style.css"), "body{}\n");
+    writeFileSync(join(root, "README.md"), "hi\n");
+    writeFileSync(join(root, "decisions", "D-2.md"), "c\n");
+    const ship = await shipOf(root, [release(shipped)]);
+    expect(ship!.serving).toEqual({ commit: shipped, digest: `sha256:${"a".repeat(64)}`, component: "site", at: "2026-10-04T00:00:00Z", actor: "github:ada" });
+    expect(ship!.pending).toEqual({ files: 3, paths: ["README.md", "app/server.mjs", "app/style.css"] });
+    expect(SHIP_PENDING_PATHS_MAX).toBe(200);
+  });
+
+  test("a release from a commit this checkout doesn't have, or a ledger that can't be read, leaves pending null; no ship, no view", async () => {
+    const root = repo({ "chant.workspace.json": declaration({ op: "release" }), "app/x": "" }, true);
+    const ship = await shipOf(root, [release("f".repeat(40))]);
+    expect(ship!.serving!.commit).toBe("f".repeat(40));
+    expect(ship!.pending).toBeNull();
+    expect((await shipOf(root, new Error("fatal: bad object")))!.serving).toBeNull();
+    expect(await shipOf(repo({ "chant.workspace.json": declaration(undefined), "app/x": "" }, true), [])).toBeNull();
+  });
+});

package/src/workspace/broker-protocol.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/broker-protocol/v1/broker-protocol.schema.json",
+  "title": "chant broker protocol, version 1",
+  "description": "The bodies a box and its broker exchange (#3164, ws-097). A box holds no credential: each capability its box block declares is reached through a broker, which holds the credential, swaps the box's own token for it, and refuses what the box's declaration does not allow. Each $def is one body; broker-protocol.ts names the routes, and the broker conformance suite in @intentius/chant/workspace/conformance checks an implementation. Unknown fields are ignored by readers and a field is only ever added within a version.",
+  "$defs": {
+    "capabilityName": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,62}$",
+      "description": "A capability's name, as the box block gives it: inference, egress, feedback, fountain, or one a lexicon or runtime adds."
+    },
+    "scopeWord": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[^\\u0000-\\u001f]+$",
+      "description": "One word of a capability's scope. The broker reads it; chant records it."
+    },
+    "capability": {
+      "type": "object",
+      "description": "One entry of a box block's capabilities, as chant workspace status --json lists it.",
+      "required": ["name"],
+      "properties": {
+        "name": { "$ref": "#/$defs/capabilityName" },
+        "broker": {
+          "type": ["string", "null"],
+          "description": "The broker the box block names for the capability. A broker keeps only the entries that name it."
+        },
+        "scope": {
+          "type": "array",
+          "maxItems": 50,
+          "items": { "$ref": "#/$defs/scopeWord" }
+        }
+      }
+    },
+    "declarationReport": {
+      "type": "object",
+      "description": "POST /api/box/declaration: the capabilities chant workspace status --json lists for the box's block, sent by the box's steward with the box's own token. At most 32 KB. Each report replaces the last.",
+      "required": ["capabilities"],
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "$ref": "#/$defs/capability" }
+        }
+      }
+    },
+    "declarationKept": {
+      "type": "object",
+      "description": "The 200 answer to a report: the entries the broker keeps, those that name it, each name once, and when it took them.",
+      "required": ["capabilities", "at"],
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "broker", "scope"],
+            "properties": {
+              "name": { "$ref": "#/$defs/capabilityName" },
+              "broker": { "type": "string", "minLength": 1 },
+              "scope": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/scopeWord" } }
+            }
+          }
+        },
+        "at": { "type": "string", "minLength": 1, "description": "An ISO 8601 time." },
+        "payer": { "$ref": "#/$defs/payer" }
+      }
+    },
+    "payer": {
+      "type": "object",
+      "description": "Whose credential pays for the box's model calls (#3474, ws-098), when the broker says. shared: a credential neither the box's owner nor its visitor owns, such as a house or operator key. owner: the box owner's own. visitor: the credential a person brought for this box. principal is the payer in ws-080's form (github:<login>) when the broker knows them, else null. Optional: a broker that does not say leaves it out, and a box treats that as unknown. The same fact rides on each answer from /llm/anthropic and /decide as the chant-payer header.",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["shared", "owner", "visitor"] },
+        "principal": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "pattern": "^[^\\s]+$" }
+      }
+    },
+    "refusal": {
+      "type": "object",
+      "description": "The body of every refusal: error is the message, or an object holding it. A refusal by declaration is a 403 whose message names the capability and the scope word the box would have to declare.",
+      "required": ["error"],
+      "properties": {
+        "type": { "type": "string" },
+        "error": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "object",
+              "required": ["message"],
+              "properties": {
+                "type": { "type": "string" },
+                "message": { "type": "string", "minLength": 1 }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "decideRequest": {
+      "type": "object",
+      "description": "POST /decide/v1/systemone: chant's decide wire format (#2491, op/decide-backend.ts), asked with the box's token as the bearer.",
+      "required": ["model", "state", "questions"],
+      "properties": {
+        "model": { "type": "string", "minLength": 1 },
+        "state": {},
+        "questions": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "object",
+            "required": ["type", "instructions", "criteria"],
+            "properties": {
+              "type": { "enum": ["noul", "choice", "score"] },
+              "instructions": { "type": "string" },
+              "criteria": { "type": ["object", "array"] }
+            }
+          }
+        }
+      }
+    },
+    "decideAnswer": {
+      "description": "One answer. reason is the model's own explanation (#3345); chant keeps it in the answer record.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type", "noul"],
+          "properties": {
+            "type": { "const": "noul" },
+            "noul": { "type": "number", "minimum": 0, "maximum": 1 },
+            "reason": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "choice"],
+          "properties": {
+            "type": { "const": "choice" },
+            "choice": { "type": "string" },
+            "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } },
+            "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+            "reason": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": { "const": "score" },
+            "score": { "type": "number" },
+            "legend": {},
+            "probabilities": { "type": "object", "additionalProperties": { "type": "number" } },
+            "confidence": { "type": "number" },
+            "reason": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": { "type": { "const": "unsupported" } }
+        }
+      ]
+    },
+    "decideResponse": {
+      "type": "object",
+      "description": "The 200 answer: the model that answered, as the request pinned it, and one answer per question asked.",
+      "required": ["model", "answers"],
+      "properties": {
+        "model": { "type": "string", "minLength": 1 },
+        "answers": { "type": "object", "additionalProperties": { "$ref": "#/$defs/decideAnswer" } },
+        "usage": { "type": "object" }
+      }
+    },
+    "feedbackBatch": {
+      "type": "object",
+      "description": "POST /api/feedback: a box's agents' feedback (studio#257). entries needs feedback scope agent, counts needs passive; a batch carries at least one. What an entry holds is the receiver's wire format, not this protocol's.",
+      "properties": {
+        "entries": { "type": "array" },
+        "counts": { "type": "object" }
+      },
+      "anyOf": [
+        { "required": ["entries"] },
+        { "required": ["counts"] }
+      ]
+    }
+  }
+}

package/src/workspace/broker-protocol.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "vitest";
+import {
+  declaredRefusal,
+  EGRESS_CAPABILITY,
+  FEEDBACK_CAPABILITY,
+  formatPayerHeader,
+  GRANT_MAX_LENGTH,
+  isGrantValue,
+  FOUNTAIN_CAPABILITY,
+  INFERENCE_CAPABILITY,
+  parseDeclarationReport,
+  parsePayerHeader,
+  payerOf,
+  refusalMessage,
+  STANDARD_CAPABILITIES,
+} from "./broker-protocol";
+
+describe("the broker protocol's capabilities (#3164)", () => {
+  test("inference: /llm/anthropic needs agent, its hello needs nothing, decide needs decide, anything else is not served", () => {
+    expect(INFERENCE_CAPABILITY.scopes({ method: "POST", path: "/llm/anthropic/v1/messages" })).toEqual(["agent"]);
+    expect(INFERENCE_CAPABILITY.scopes({ method: "POST", path: "/llm/anthropic/v1/messages/count_tokens" })).toEqual(["agent"]);
+    expect(INFERENCE_CAPABILITY.scopes({ method: "GET", path: "/llm/anthropic/v1/models/claude-opus-5" })).toEqual(["agent"]);
+    expect(INFERENCE_CAPABILITY.scopes({ method: "HEAD", path: "/llm/anthropic/api/hello" })).toEqual([]);
+    expect(INFERENCE_CAPABILITY.scopes({ method: "POST", path: "/decide/v1/systemone" })).toEqual(["decide"]);
+    expect(INFERENCE_CAPABILITY.scopes({ method: "POST", path: "/llm/anthropic/v1/complete" })).toBeNull();
+    expect(INFERENCE_CAPABILITY.scopes({ method: "GET", path: "/decide/v1/systemone" })).toBeNull();
+  });
+
+  test("egress: the secret's name is the scope word", () => {
+    expect(EGRESS_CAPABILITY.scopes({ method: "POST", path: "/egress/STRIPE/v1/charges" })).toEqual(["STRIPE"]);
+    expect(EGRESS_CAPABILITY.scopes({ method: "GET", path: "/egress/GITHUB_API" })).toEqual(["GITHUB_API"]);
+    expect(EGRESS_CAPABILITY.scopes({ method: "GET", path: "/egress/stripe/v1" })).toBeNull();
+    expect(EGRESS_CAPABILITY.scopes({ method: "GET", path: "/egressor/STRIPE" })).toBeNull();
+  });
+
+  test("feedback: entries need agent, counts need passive, an empty batch needs nothing", () => {
+    expect(FEEDBACK_CAPABILITY.scopes({ method: "POST", path: "/api/feedback", body: { entries: [{}], counts: { x: 1 } } })).toEqual(["agent", "passive"]);
+    expect(FEEDBACK_CAPABILITY.scopes({ method: "POST", path: "/api/feedback", body: { counts: { x: 1 } } })).toEqual(["passive"]);
+    expect(FEEDBACK_CAPABILITY.scopes({ method: "POST", path: "/api/feedback", body: {} })).toEqual([]);
+    expect(FEEDBACK_CAPABILITY.scopes({ method: "GET", path: "/api/feedback" })).toBeNull();
+  });
+
+  test("fountain: starting a conversation needs agent, the rest by resource", () => {
+    expect(FOUNTAIN_CAPABILITY.scopes({ method: "POST", path: "/fountain/api/conversations" })).toEqual(["agent"]);
+    expect(FOUNTAIN_CAPABILITY.scopes({ method: "GET", path: "/fountain/api/conversations/c1" })).toEqual(["conversations"]);
+    expect(FOUNTAIN_CAPABILITY.scopes({ method: "DELETE", path: "/fountain/api/sandboxes/s1" })).toEqual(["sandboxes"]);
+    expect(FOUNTAIN_CAPABILITY.scopes({ method: "GET", path: "/fountain/api/vaults/v1" })).toEqual(["vault"]);
+    expect(FOUNTAIN_CAPABILITY.scopes({ method: "GET", path: "/fountain/api/agents" })).toBeNull();
+  });
+
+  test("the standard capabilities are the four, by name", () => {
+    expect(Object.keys(STANDARD_CAPABILITIES).sort()).toEqual(["egress", "feedback", "fountain", "inference"]);
+    for (const [name, spec] of Object.entries(STANDARD_CAPABILITIES)) expect(spec.name).toBe(name);
+  });
+});
+
+describe("a declaration report", () => {
+  test("keeps the entries that name this broker, each name once with its scopes merged", () => {
+    const parsed = parseDeclarationReport(
+      {
+        capabilities: [
+          { name: "inference", broker: "lobby", scope: ["agent"] },
+          { name: "inference", broker: "lobby", scope: ["decide", "agent"] },
+          { name: "fountain-callback", broker: "fountain", scope: ["owner"] },
+          { name: "egress", broker: "lobby" },
+        ],
+      },
+      "lobby",
+    );
+    expect(parsed).toEqual({
+      capabilities: [
+        { name: "inference", broker: "lobby", scope: ["agent", "decide"] },
+        { name: "egress", broker: "lobby", scope: [] },
+      ],
+    });
+  });
+
+  test("refuses a body that is not one, and a name that is not a capability's", () => {
+    expect(parseDeclarationReport({}, "lobby")).toHaveProperty("error");
+    expect(parseDeclarationReport({ capabilities: [{ name: "Inference" }] }, "lobby")).toHaveProperty("error");
+    expect(parseDeclarationReport({ capabilities: Array.from({ length: 21 }, (_, i) => ({ name: `c${i}` })) }, "lobby")).toHaveProperty("error");
+  });
+
+  test("a refusal names the capability and the word, and the entry to add", () => {
+    const declared = { capabilities: [{ name: "inference", broker: "lobby", scope: ["agent"] }] };
+    expect(declaredRefusal(declared, "lobby", "inference", "agent")).toBeNull();
+    expect(declaredRefusal(declared, "lobby", "inference", "decide")).toMatch(/inference.*decide/);
+    expect(declaredRefusal(declared, "lobby", "egress", "STRIPE")).toContain('{ "name": "egress", "broker": "lobby", "scope": ["STRIPE"] }');
+    expect(declaredRefusal(declared, "door", "inference", "agent")).toContain("brokered by door");
+    expect(declaredRefusal(undefined, "lobby", "inference", "agent")).toContain("no declaration");
+  });
+
+  test("a refusal's message is read from either body shape", () => {
+    expect(refusalMessage({ error: "no" })).toBe("no");
+    expect(refusalMessage({ type: "error", error: { type: "permission_error", message: "no" } })).toBe("no");
+    expect(refusalMessage({ error: {} })).toBeUndefined();
+  });
+});
+
+describe("the payer (#3474)", () => {
+  test("the header carries a kind and, when known, the principal, and reads back the same", () => {
+    expect(formatPayerHeader({ kind: "shared" })).toBe("shared");
+    expect(formatPayerHeader({ kind: "visitor", principal: "github:ada" })).toBe("visitor github:ada");
+    expect(parsePayerHeader("visitor github:ada")).toEqual({ kind: "visitor", principal: "github:ada" });
+    expect(parsePayerHeader(" owner ")).toEqual({ kind: "owner", principal: null });
+    for (const bad of [undefined, null, "", "house", "owner a b", "visitor\tx y"]) expect(parsePayerHeader(bad), String(bad)).toBeUndefined();
+  });
+  test("payerOf reads the declaration's answer, and takes a malformed payer as none", () => {
+    expect(payerOf({ capabilities: [], at: "t", payer: { kind: "owner", principal: "github:bo" } })).toEqual({ kind: "owner", principal: "github:bo" });
+    expect(payerOf({ capabilities: [], at: "t", payer: { kind: "shared" } })).toEqual({ kind: "shared", principal: null });
+    expect(payerOf({ capabilities: [], at: "t" })).toBeUndefined();
+    expect(payerOf({ payer: { kind: "house" } })).toBeUndefined();
+    expect(payerOf({ payer: { kind: "visitor", principal: "has space" } })).toBeUndefined();
+  });
+});
+
+describe("a grant (#3477)", () => {
+  test("is printable ASCII without spaces, bounded in length", () => {
+    expect(isGrantValue("lobbyg1.eyJ0.abc_-")).toBe(true);
+    for (const bad of ["", "has space", "line\nbreak", "x".repeat(GRANT_MAX_LENGTH + 1), 42, null]) expect(isGrantValue(bad), String(bad).slice(0, 20)).toBe(false);
+  });
+});