@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/conformance/__writer_fixture__/sessions/session.schema.json

@@ -2,9 +2,12 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "urn:intentius:chant:session:1",
   "title": "Review session",
-  "description": "The front matter of a review-session file (#2673, #2650 C10): a group walking an agenda of records together, who attended, and the verdicts the session produced. Each verdict is also an entry in the judged record's reviews list, whose session field names this session. A closed session is sealed: closed_digest is sha256: and the lowercase hex SHA-256 of the JCS form of the whole session without closed_digest (its front matter as core and the text below it as body, line endings LF, #2546), and chant workspace records checks it on every read (session-seal-mismatch).",
+  "description": "The front matter of a review-session file (#2673, #2650 C10): a group walking an agenda of records together, who attended, and the verdicts the session produced. Its verdicts judge decisions, contracts and drivers, the kinds the session kind names as subjects (#3148, ws-082). A comment-mode review of the app's UI is a session too, one per review batch, with its comments, the agent's answers and the rounds of replies (#3350, ws-083). Each verdict is also an entry in the judged record's reviews list, whose session field names this session. A closed session is sealed: closed_digest is sha256: and the lowercase hex SHA-256 of the JCS form of the whole session without closed_digest (its front matter as core and the text below it as body, line endings LF, #2546), and chant workspace records checks it on every read (session-seal-mismatch).",
   "type": "object",
   "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {}
+  },
   "required": ["schema", "id", "title", "state", "agenda", "attendance", "opened", "closed", "verdicts"],
   "properties": {
     "schema": { "const": 1 },
@@ -16,7 +19,7 @@
     "title": { "type": "string", "minLength": 1 },
     "state": { "enum": ["open", "closed"] },
     "agenda": {
-      "description": "What the session walks, in order: a record by its id, or an item of free text.",
+      "description": "What the session walks, in order: a record by its id, or an item of free text. A record may say what it was when it was put up (digest), the evidence records reviewed with it and any screenshot or recording (#3148).",
       "type": "array",
       "minItems": 1,
       "items": {
@@ -25,7 +28,33 @@
             "type": "object",
             "additionalProperties": false,
             "required": ["record"],
-            "properties": { "record": { "type": "string", "minLength": 1 } }
+            "properties": {
+              "record": { "type": "string", "minLength": 1 },
+              "digest": {
+                "description": "The record's digest when it was put up for review, as chant workspace records --json prints it.",
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              },
+              "evidence": {
+                "description": "The evidence records reviewed with it, by id: the SHA-256 each evidence file is named for.",
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+              },
+              "media": {
+                "description": "Screenshots and recordings shown with it, each a workspace path or an https link.",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "ref"],
+                  "properties": {
+                    "kind": { "enum": ["screenshot", "recording"] },
+                    "ref": { "type": "string", "minLength": 1 }
+                  }
+                }
+              }
+            }
           },
           {
             "type": "object",
@@ -46,11 +75,22 @@
         "properties": {
           "principal": { "type": "string", "minLength": 1 },
           "class": { "enum": ["person", "agent"] },
-          "roles": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+          "roles": {
+            "description": "The roles the principal holds in the session, such as reviewer or facilitator. A quorum that names roles counts only verdicts by principals holding one.",
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "joined": { "description": "When the principal joined. Optional.", "$ref": "#/definitions/dateTime" }
         }
       }
     },
     "opened": { "$ref": "#/definitions/dateTime" },
+    "opened_by": {
+      "description": "Who opened the session. Optional.",
+      "type": "string",
+      "minLength": 1
+    },
     "opened_rev": {
       "description": "The commit HEAD named when chant workspace records new wrote the session (#2693), or null when the repository had no commit yet; the next records amend, review --session or close fills it. chant writes it, and records --since <session id> reads it. Optional, so a session written before #2693 stays valid.",
       "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/rev" }]
@@ -63,8 +103,13 @@
       "description": "The commit HEAD named when chant workspace records close closed the session (#2693), or null when the repository had no commit. Only a closed session has it. Optional, so a session closed before #2693 stays valid.",
       "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/rev" }]
     },
+    "closed_by": {
+      "description": "Who closes or closed the session, set by an amendment before chant workspace records close seals it. Optional.",
+      "type": "string",
+      "minLength": 1
+    },
     "verdicts": {
-      "description": "The verdicts the session produced, in the order they were given.",
+      "description": "The verdicts the session produced, in the order they were given. Each names a record of one of the session kind's subject kinds: a decision, a contract or a driver.",
       "type": "array",
       "items": {
         "type": "object",
@@ -78,10 +123,34 @@
             "description": "The digest of the record text the verdict judged, as the review entry carries it.",
             "type": "string",
             "pattern": "^[0-9a-f]{64}$"
-          }
+          },
+          "roles": {
+            "description": "The roles the principal gave the verdict in, which a quorum that names roles counts. Optional.",
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "at": { "description": "When the verdict was given. Optional.", "$ref": "#/definitions/dateTime" },
+          "note": { "description": "Why, in the principal's words. Optional.", "type": "string" }
         }
       }
     },
+    "follow_ups": {
+      "description": "Records the session started for later, as <kind>:<id> with kind the record kind's name, the form a Chant-Record trailer uses (ws-075): contracts drafted, work items proposed, decisions opened. Optional.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/definitions/recordRef" }
+    },
+    "comments": {
+      "description": "What people said in the session, in order (#3350, ws-083). A comment-mode review of the app's UI is one session per review batch: each comment is anchored to the page and elements it was made on, the agent that worked the batch answers each one, and a person may reply in later rounds. The comments are numbered from 1 by their position, as hud numbers them. Optional.",
+      "type": "array",
+      "items": { "$ref": "#/definitions/comment" }
+    },
+    "rounds": {
+      "description": "The rounds of a review batch (#3350, ws-083): round 0 is the batch as it was sent, with its note; each later round is a person's replies, which send the batch back for another turn. ended is when the agent's turn for the round ended, null while it is working. Optional.",
+      "type": "array",
+      "items": { "$ref": "#/definitions/round" }
+    },
     "closed_digest": {
       "description": "The seal, written when the session closes.",
       "type": "string",
@@ -90,6 +159,118 @@
   },
   "definitions": {
     "rev": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+    "comment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": {
+          "description": "What the person wrote. Empty when the comment only marks its elements for the round's note.",
+          "type": "string"
+        },
+        "by": { "description": "Who wrote it. Optional; a review batch's reviewer is in attendance.", "type": "string", "minLength": 1 },
+        "at": { "description": "When it was written. Optional.", "$ref": "#/definitions/dateTime" },
+        "anchor": {
+          "description": "Where in the app the comment was made: the page's route and the elements it points at.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["route", "elements"],
+          "properties": {
+            "route": {
+              "description": "The page, as its path with any query and hash.",
+              "type": "string",
+              "minLength": 1
+            },
+            "elements": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["selector", "state"],
+                "properties": {
+                  "selector": { "description": "A CSS selector for the element.", "type": "string", "minLength": 1 },
+                  "tag": { "description": "The element's tag name.", "type": "string", "minLength": 1 },
+                  "text": { "description": "The element's text when the comment was made, cut short.", "type": "string" },
+                  "state": {
+                    "description": "anchored: the selector found exactly the element. ambiguous: it found more than one. lost: it found none.",
+                    "enum": ["anchored", "ambiguous", "lost"]
+                  },
+                  "basis": {
+                    "description": "What the selector was built from: an authored anchor (data-hud-id), the element's id, a test id, or its path in the page. Optional.",
+                    "enum": ["authored", "id", "testid", "path"]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "answers": {
+          "description": "The agent's answers to the comment, one per round it answered in, oldest first; the last is the current one. handled: it changed something, and note says what. skipped: it did not, and note says why. needs-discussion: note is the question a person has to settle, by replying in a later round.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["round", "disposition", "note"],
+            "properties": {
+              "round": { "type": "integer", "minimum": 0 },
+              "disposition": { "enum": ["handled", "skipped", "needs-discussion"] },
+              "note": { "type": "string", "pattern": "\\S" },
+              "by": { "description": "The agent that answered. Optional.", "type": "string", "minLength": 1 },
+              "at": { "$ref": "#/definitions/dateTime" }
+            }
+          }
+        },
+        "replies": {
+          "description": "A person's replies to the comment, one per round from round 1.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["round", "text"],
+            "properties": {
+              "round": { "type": "integer", "minimum": 1 },
+              "text": { "type": "string", "pattern": "\\S" },
+              "by": { "type": "string", "minLength": 1 },
+              "at": { "$ref": "#/definitions/dateTime" }
+            }
+          }
+        },
+        "exit": {
+          "description": "How the comment left the box, once a person decided (hud#703, studio-039): kept, its record stays in the repository as the source of the work its changes are; sent, it went out with Send; dismissed, it was let go. Absent until then.",
+          "enum": ["kept", "sent", "dismissed"]
+        },
+        "follow_ups": {
+          "description": "Records the comment led to, as <kind>:<id>, such as the work item that carries its change. Optional.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/definitions/recordRef" }
+        }
+      }
+    },
+    "round": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["round", "note", "at"],
+      "properties": {
+        "round": { "type": "integer", "minimum": 0 },
+        "note": {
+          "description": "The note sent with the round, or null when there was none. A reply round needs a reply or a note.",
+          "type": ["string", "null"]
+        },
+        "by": { "description": "Who sent the round. Optional.", "type": "string", "minLength": 1 },
+        "at": { "description": "When the round was sent.", "$ref": "#/definitions/dateTime" },
+        "ended": {
+          "description": "When the agent's turn for the round ended, or null while it is working. Optional.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/dateTime" }]
+        }
+      }
+    },
+    "recordRef": {
+      "description": "A record as <kind>:<id>, such as contract:C-002 or work:W-004.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
     "dateTime": {
       "type": "string",
       "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"

package/src/workspace/conformance/__writer_fixture__/work/work.schema.json

@@ -138,6 +138,30 @@
       ],
       "minimum": 1
     },
+    "retry": {
+      "description": "A person's request to build the item again after a failed build (#3406, ws-087, arugula-salad/studio#232): after names the lease token of the failed build it follows, so one request starts one run. Written through chant workspace records amend; a factory never retries a failed build without it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["after", "by"],
+      "properties": {
+        "after": { "type": "string", "minLength": 1, "description": "The fencing token of the failed build this request follows." },
+        "by": { "type": "string", "minLength": 1, "description": "Who asked." },
+        "at": { "type": "string", "description": "When, as an ISO 8601 timestamp." }
+      }
+    },
+    "implements_proposed": {
+      "description": "The decisions the factory proposed this item implements when it recorded the build done (#3406, arugula-salad/studio#243): each a decision in force that constrains, by path, a path the build changed, with those paths. They are also added to implements, and listed here so a reader tells them from links a person wrote.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["decision", "paths"],
+        "properties": {
+          "decision": { "type": "string", "minLength": 1 },
+          "paths": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
     "result": {
       "description": "What the last build of the item ran under (#3147): only the lease token, which joins the item to the run record and to the commits carrying it. Build provenance (agent, model, harness, session, cost) is the run record's, never the item's.",
       "type": "object",
@@ -370,6 +394,7 @@
                 "intent-decision-unimplemented",
                 "intent-work-blocked",
                 "intent-work-open-decided-code",
+                "intent-commit-join-conflict",
                 "change-uncovered",
                 "change-out-of-scope"
               ]

package/src/workspace/conformance/broker.test.ts

@@ -0,0 +1,122 @@
+/**
+ * The broker suite (#3164) against the reference broker, which serves every
+ * standard capability and must pass, and against two brokers that break the
+ * protocol, which the suite must catch.
+ */
+
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { describe, expect, test } from "vitest";
+import { BROKER_ROUTES } from "../broker-protocol";
+import { describeBrokerConformance } from "./vitest";
+import { startReferenceBroker } from "./__fixtures__/reference-broker";
+import { BROKER_CONFORMANCE_CAPABILITIES, runBrokerConformance, schemaInstance, type BrokerConformanceEnv, type BrokerListen, type StartedBroker } from "./index";
+
+/** The suite's upstreams on loopback ports, as a broker's test serves them. */
+const listen: BrokerListen = (handler) =>
+  new Promise((resolve) => {
+    const server = createServer(handler);
+    server.listen(0, "127.0.0.1", () =>
+      resolve({ url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`, close: () => new Promise<void>((r) => server.close(() => r())) }),
+    );
+  });
+
+describeBrokerConformance({ name: "the reference broker", start: startReferenceBroker, listen, capabilities: BROKER_CONFORMANCE_CAPABILITIES });
+
+/**
+ * The reference broker behind a proxy that changes each request with
+ * `rewrite` on the way in, so a test makes a broker that breaks one rule.
+ */
+async function behind(
+  env: BrokerConformanceEnv,
+  rewrite: (path: string, headers: Record<string, string>, body: string) => { headers: Record<string, string>; body: string },
+  answered: (path: string, headers: Record<string, string>) => void = () => {},
+): Promise<StartedBroker> {
+  const inner = await startReferenceBroker(env);
+  const server = createServer(async (req, res) => {
+    let body = "";
+    for await (const chunk of req) body += chunk;
+    const headers: Record<string, string> = {};
+    for (const [k, v] of Object.entries(req.headers)) if (v !== undefined && k !== "host" && k !== "content-length" && k !== "connection") headers[k] = [v].flat().join(", ");
+    const changed = rewrite(req.url ?? "/", headers, body);
+    const answer = await fetch(`${inner.url}${req.url}`, { method: req.method, headers: changed.headers, body: req.method === "GET" || req.method === "HEAD" ? undefined : changed.body });
+    const out: Record<string, string> = {};
+    answer.headers.forEach((v, k) => {
+      if (!["content-length", "content-encoding", "transfer-encoding", "connection", "keep-alive"].includes(k)) out[k] = v;
+    });
+    answered(req.url ?? "/", out);
+    res.writeHead(answer.status, out);
+    res.end(Buffer.from(await answer.arrayBuffer()));
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", () => r()));
+  return {
+    url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
+    tokens: inner.tokens,
+    close: async () => {
+      await new Promise<void>((r) => server.close(() => r()));
+      await inner.close?.();
+    },
+  };
+}
+
+describe("the broker suite catches a broker that breaks the protocol", () => {
+  test("a broker that grants every scope whatever the box declared fails each refusal check", async () => {
+    const all = (broker: string) => ({
+      capabilities: [
+        { name: "inference", broker, scope: ["agent", "decide"] },
+        { name: "egress", broker, scope: ["CONFORMANCE", "CONFORMANCE_UNHELD"] },
+        { name: "feedback", broker, scope: ["agent", "passive"] },
+        { name: "fountain", broker, scope: ["agent", "conversations", "sandboxes", "vault"] },
+      ],
+    });
+    const report = await runBrokerConformance({
+      name: "grants everything",
+      listen,
+      capabilities: BROKER_CONFORMANCE_CAPABILITIES,
+      start: (env) => behind(env, (path, headers, body) => ({ headers, body: path === BROKER_ROUTES.declaration && body.includes('"capabilities"') ? JSON.stringify(all(env.broker)) : body })),
+    });
+    const failed = new Set(report.results.filter((r) => r.problems.length > 0).map((r) => r.id));
+    for (const id of ["inference-agent-refused", "decide-refused", "egress-refused", "feedback-refused", "fountain-refused"]) expect(failed, id).toContain(id);
+    expect(failed).not.toContain("inference-forwards");
+    expect(failed).not.toContain("unreported-refused");
+  }, 60_000);
+
+  test("a broker that passes a box's token upstream fails token-isolation", async () => {
+    const report = await runBrokerConformance({
+      name: "leaks the token",
+      listen,
+      start: (env) => behind(env, (_path, headers, body) => ({ headers: { ...headers, "x-box-token": headers.authorization ?? headers["x-api-key"] ?? "" }, body })),
+    });
+    const isolation = report.results.find((r) => r.id === "token-isolation");
+    expect(isolation?.problems.length).toBeGreaterThan(0);
+    expect(report.problems.every((p) => p.startsWith("token-isolation:"))).toBe(true);
+  }, 60_000);
+
+  test("a broker whose payer differs between the report's answer and a Messages answer, or is said on one only, fails payer-consistent (#3474)", async () => {
+    for (const change of [(h: Record<string, string>) => (h["chant-payer"] = "visitor github:someone"), (h: Record<string, string>) => delete h["chant-payer"]]) {
+      const report = await runBrokerConformance({
+        name: "payer disagrees",
+        listen,
+        start: (env) => behind(env, (_path, headers, body) => ({ headers, body }), (path, headers) => path.startsWith(BROKER_ROUTES.inference) && change(headers)),
+      });
+      expect(report.problems.length).toBeGreaterThan(0);
+      expect(report.problems.every((p) => p.startsWith("payer-consistent:"))).toBe(true);
+    }
+  }, 60_000);
+
+  test("the default capabilities are the lobby's, and fountain's checks are skipped", async () => {
+    const report = await runBrokerConformance({ name: "the reference broker as a lobby", start: startReferenceBroker, listen });
+    expect(report.problems).toEqual([]);
+    expect(report.results.filter((r) => r.skipped).map((r) => r.id)).toEqual(["fountain-forwards", "fountain-refused"]);
+  }, 60_000);
+});
+
+describe("schemaInstance", () => {
+  test("answers a structured-output schema with the first option and an even split", () => {
+    const schema = {
+      type: "object",
+      properties: { reason: { type: "string" }, choice: { type: "string", enum: ["small", "large"] }, probabilities: { type: "object", properties: { small: { type: "number" }, large: { type: "number" } } } },
+    };
+    expect(schemaInstance(schema)).toEqual({ reason: "The conformance upstream's reason.", choice: "small", probabilities: { small: 0.5, large: 0.5 } });
+  });
+});