@intentius/chant 0.124.13 → 0.124.14

package/dist/cli/mcp/workspace-tools.js

@@ -0,0 +1,564 @@
+/**
+ * #2707 — the workspace tools of `chant serve mcp`: the read contract and the
+ * record writes, for a harness that speaks MCP and has no shell.
+ *
+ * Served when the server starts at or inside a declared workspace. Each tool
+ * is a thin call into the code the CLI runs:
+ *
+ * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`,
+ *   `workspace-changes`, `workspace-records`, `workspace-points`,
+ *   `workspace-work-history`, `workspace-runs`) run `chant workspace <command>
+ *   ... --json` with the chant this server runs as, in the server's
+ *   directory, and return the
+ *   document it printed, unchanged, with its reason codes (#2536). Running the
+ *   command, rather than calling into it, keeps every rule it has, handing the
+ *   read to the workspace root's pinned chant included (ws-021), and keeps
+ *   anything a command prints away from the protocol on stdout.
+ * - The writes (`records-new`, `records-amend`, `records-review`,
+ *   `records-close`, `points-answer`, `points-retract`) call the functions
+ *   `chant workspace records new|amend|review|close` and `points
+ *   answer|retract` call, and return the
+ *   same JSON result. They keep every rule
+ *   the CLI keeps: the kind's schema, a closed record never changing, an
+ *   approved one changing only as its approval rule allows, a dissent needing
+ *   a note, and `sign` using this host's configured key or refusing with the
+ *   CLI's remedy. Through MCP a new record also opens in the kind's first
+ *   state, `proposed` for a decision, and its stored source block (#2708) says
+ *   it came through MCP: `via: "mcp"` and `client`, the MCP client's
+ *   `clientInfo`. Computed provenance, from git, is unchanged.
+ *
+ * Nothing here listens on a port or authenticates anyone (ws-052): the server
+ * speaks over stdio, and `by` is recorded as given, as `--by` is. A decision
+ * point's answer is the exception (#3817): `chant serve mcp` makes every call
+ * the model's (`lifecycle/gate-origin.ts`), so `points-answer` and
+ * `points-retract` count nobody `by` names toward a point's quorum, as
+ * `op-approve` records its approver as an agent.
+ *
+ * An agent session (#2548): a server started with `CHANT_AGENT` set writes in
+ * that session, bound to its one member, and its writes are refused outside
+ * the session's write scope with the CLI's codes (`write-scope-member`,
+ * `write-scope-kind`, `agent-unknown`). `workspace-agent` returns what the
+ * session reloads from.
+ */
+import { spawn } from "node:child_process";
+/** `AGENT_ENV` of `workspace/write-scope.ts`, kept here so the server loads nothing under workspace/ until a tool is called. */
+const AGENT_ENV = "CHANT_AGENT";
+/**
+ * The chant this process runs as: node with the same flags (from source, the tsx loader
+ * `bin/chant` registers) and the same entry script.
+ */
+export function ownChantCommand() {
+    return [process.execPath, ...process.execArgv, process.argv[1]];
+}
+const PROTOCOL = "Records are proposals until they are reviewed: a new record opens proposed, and people decide it through reviews and amendments. " +
+    "by must name the person or agent that actually proposed or decided it, as it is recorded as given.";
+const kindProp = {
+    type: "string",
+    description: "The record kind: a kind file relative to the server's directory, such as decisions/decision.kind.mjs, or a kind the workspace declaration names. Without it, the one kind the declaration names.",
+};
+const atProp = { type: "string", description: "Read at this git revision instead of the working tree (--at)." };
+const dryRunProp = { type: "boolean", description: "Return the result, with the text it would write, and write nothing (--dry-run)." };
+const signProp = {
+    type: "boolean",
+    description: "Seal with this host's configured key, git's user.signingkey with gpg.format ssh, as --sign does. Refused, with the CLI's remedy, when none is set.",
+};
+export const workspaceReadTools = [
+    {
+        name: "workspace-ls",
+        description: "List the workspace's members and groups: chant workspace ls --json. Returns that document unchanged, which follows ls.schema.json of the read contract, reason codes included.",
+        inputSchema: { type: "object", properties: { at: atProp } },
+    },
+    {
+        name: "workspace-status",
+        description: "What each member has released to an environment, its gates, and the steward that runs it with each Op's last run, from the declaration and the lifecycle ledgers: chant workspace status <env> --json. Returns that document unchanged (status.schema.json).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                env: { type: "string", description: "The environment, such as dev." },
+                compareTo: { type: "string", description: "A second environment to compare with (--compare-to)." },
+            },
+            required: ["env"],
+        },
+    },
+    {
+        name: "workspace-graph",
+        description: "The workspace graph: chant workspace graph --json (graph.schema.json); with intent, the intent graph over one region (graph --intent, intent.schema.json); with composites, each composite instance and the components that can deploy it (graph --composites, composites.schema.json). Returns the document unchanged.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Record kind files whose records join the graph (--kind). The plain graph takes one; intent takes several.",
+                },
+                intent: { type: "string", description: "The region for the intent graph: a workspace path, path:line, path:start-end, or path#symbol for a TypeScript or JavaScript declaration such as src/server.ts#createApp (--intent). The document's why answers why the region is like this." },
+                followSquash: { type: "boolean", description: "With intent: follow squash merges to their pull requests' original commits (--follow-squash, #3035), fetching a pull request ref the clone lacks from origin. Off by default, so a read never reaches the network." },
+                composites: { type: "boolean", description: "The composites document instead (--composites). Takes no kind or intent." },
+                at: atProp,
+            },
+        },
+    },
+    {
+        name: "workspace-changes",
+        description: "The forward coverage check over a diff: chant workspace check --changes <range> --json (changes.schema.json, #2773). Each changed path with the current records whose constrains cover it, and a change-uncovered or change-out-of-scope finding for each gap, at the severity the declaration's changes block sets. Returns the document unchanged.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                range: { type: "string", description: "The diff: <base>..<head>, <base>...<head> (from their merge base), or <base> alone, to HEAD (--changes)." },
+                work: { type: "string", description: "The id of the work item in hand, whose out_of_scope and whose decisions' out_of_scope apply (--work)." },
+                severity: { type: "string", enum: ["off", "warn", "fail"], description: "In place of the declaration's changes.severity (--severity)." },
+                kind: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Record kind files to read in place of the declared ones (--kind).",
+                },
+            },
+            required: ["range"],
+        },
+    },
+    {
+        name: "workspace-records",
+        description: "The records of a kind, validated, with supersession, remediation, provenance, quorum and warnings: chant workspace records --json (records.schema.json). With since, what changed since a revision or a review session (records-since.schema.json). Returns the document unchanged; with id, only that record is kept in records. " +
+            PROTOCOL,
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: kindProp,
+                current: { type: "boolean", description: "Leave out records a closed record supersedes (--current)." },
+                uncommitted: {
+                    type: "boolean",
+                    description: "Only the records the working tree holds modified or new against HEAD, with the checkout's branch, head and base (--uncommitted, #3160). Takes no at or since.",
+                },
+                since: { type: "string", description: "A revision, or a review session id, to compare with (--since)." },
+                id: { type: "string", description: "Keep only the record with this id in the document's records." },
+                at: atProp,
+            },
+        },
+    },
+    {
+        name: "workspace-points",
+        description: "The workspace's decision points and the questions asked of them: chant workspace points --json (points.schema.json, ws-058). A question is open while it is escalated to people, or proposed by a model and not yet confirmed; each lists any model's answer with its confidence and threshold. Returns the document unchanged. chant calls no model to answer this.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                open: { type: "boolean", description: "Only the open questions (--open)." },
+                kind: { type: "string", description: "One answer kind file, in place of the declared ones (--kind)." },
+                at: atProp,
+            },
+        },
+    },
+    {
+        name: "workspace-agent",
+        description: "An agent session and what it reloads from (#2548): chant workspace agent <name> --json (agent.schema.json). The members it is bound to, the record kinds and verbs its write scope allows, and the spec records --current prints, read from the repository alone. Without name, this server's session (CHANT_AGENT). Returns the document unchanged.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "The session's name, as the declaration's agents list gives it." },
+            },
+        },
+    },
+    {
+        name: "workspace-work-history",
+        description: "One work item's lease history, from the lifecycle ledger of the member that owns its work kind: chant workspace work history <item> --json (work-history.schema.json, #2785). Each claim has its fencing token and holder and how it ended: released with an outcome, still held, or never released (expired, or lost to a later claim). Returns the document unchanged.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                item: { type: "string", description: "The work item's id." },
+                kind: { type: "string", description: "The work kind file, when more than one declared work kind has the id (--kind)." },
+            },
+            required: ["item"],
+        },
+    },
+    {
+        name: "workspace-runs",
+        description: "The agent runs in the workspace's run ledger on chant/lifecycle: chant workspace runs --json (runs.schema.json, #3033). Each run has who it worked for, its harness and model, its tokens and cost with the price source, the transcript pinned by hash and the commits it made, and the totals are per work item, per decision and per principal. A run that reports no cost is listed as unpriced, never counted as zero. Returns the document unchanged.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                unit: { type: "string", description: "Only the runs on this work item (--unit)." },
+                decision: { type: "string", description: "Only the runs that carried out this decision, by id or <kind>/<id> (--decision)." },
+                by: { type: "string", description: "Only the runs made for this principal (--by)." },
+                since: { type: "string", description: "Only the runs that made a commit after this revision, or started after it (--since)." },
+                followSquash: { type: "boolean", description: "Join each squash merge on HEAD to the runs its pull request's original commits joined (--follow-squash, #3035), fetching a pull request ref the clone lacks from origin." },
+            },
+        },
+    },
+];
+export const workspaceWriteTools = [
+    {
+        name: "records-new",
+        description: "Propose a new record: chant workspace records new. The record opens in the kind's first state (proposed for a decision); another state is refused. Its source block records that it came through MCP (via mcp, and this client's clientInfo). Validated against the kind's schema; nothing is written on refusal, and nothing is committed. " +
+            PROTOCOL,
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: kindProp,
+                record: { type: "object", description: "The record's fields, as the kind's schema describes them. The id is allocated when left out." },
+                prefix: { type: "string", description: "The id prefix to allocate under, when the records use several (--prefix)." },
+                by: {
+                    type: "string",
+                    description: "Who proposed it: written to the kind's proposedBy field, such as proposed_by, since a record opens proposed. Written to its decider field, such as decided_by, only when the record's fields open it straight into a later state. Required to sign.",
+                },
+                sign: signProp,
+                dryRun: dryRunProp,
+            },
+            required: ["record"],
+        },
+    },
+    {
+        name: "records-amend",
+        description: "Set top-level fields of a record: chant workspace records amend. A closed record never changes, and an approved one changes only in its state, evidence and reviews: anything else, its reasoning included, is a new record that supersedes it. A record moves to its kind's ratified state only once its review quorum is met (ratify-quorum-not-met). A source block given in the fields records that the change came through MCP. " +
+            PROTOCOL,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "The record's id." },
+                kind: kindProp,
+                fields: { type: "object", description: "The top-level fields to set; each replaces the whole field." },
+                by: { type: "string", description: "Who decided: written to the kind's decider field." },
+                sign: signProp,
+                dryRun: dryRunProp,
+            },
+            required: ["id", "fields"],
+        },
+    },
+    {
+        name: "records-review",
+        description: "Give a verdict on a record: chant workspace records review. Appends one entry to its reviews with the digest of the text judged, which moves its quorum. A dissent needs a note. " +
+            PROTOCOL,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "The record's id." },
+                kind: kindProp,
+                verdict: { type: "string", enum: ["agree", "dissent", "abstain"] },
+                by: { type: "string", description: "The reviewer: the person or agent giving the verdict (--by)." },
+                note: { type: "string", description: "Why; required for a dissent (--note)." },
+                session: { type: "string", description: "The open review session the verdict is given in (--session)." },
+                sign: signProp,
+                dryRun: dryRunProp,
+            },
+            required: ["id", "verdict", "by"],
+        },
+    },
+    {
+        name: "records-close",
+        description: "Close an open review session and seal it: chant workspace records close. " + PROTOCOL,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "The session's id." },
+                kind: { type: "string", description: "The session kind file. Without it, the one session kind the declaration names." },
+                dryRun: dryRunProp,
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "points-answer",
+        description: "Record people's answer to an open decision point question, or confirm a model's proposal: chant workspace points answer. Refused unless the point's quorum is met: distinct people, none holding the agent role, each holding one of the quorum's roles when it names any. On a server started with `chant serve mcp`, every call is the model's, so nobody named in by counts toward the quorum (quorum-not-met), and a question whose gate is neverOverMcp is refused outright (answer-never-over-mcp): people answer at a shell or through hud. An answered question never changes in place: points-retract takes it back. " +
+            PROTOCOL,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "The question's id, as workspace-points lists it." },
+                answer: { type: ["string", "boolean"], description: "One of the question's candidates; for a noul, true or false." },
+                by: { type: "array", items: { type: "string" }, description: "Each person who answered (--by)." },
+                note: { type: "string", description: "What the people who answered say with it, kept on the answer (--note)." },
+                relayedBy: { type: "string", description: "Who relayed the answer for the people in by, such as a follower; recorded as relayed_by and not counted toward the quorum (--relayed-by)." },
+                kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
+                dryRun: dryRunProp,
+            },
+            required: ["id", "answer", "by"],
+        },
+    },
+    {
+        name: "points-retract",
+        description: "Take back people's answer to a decision point question: chant workspace points retract. The question is escalated to people again, and the answer, who gave it and its note stay in the record's retractions with who retracted it, when and why. Refused unless the point's quorum is met, counted as for an answer, so over MCP it is refused as an answer is. " +
+            PROTOCOL,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "The question's id, as workspace-points lists it." },
+                by: { type: "array", items: { type: "string" }, description: "Each person who takes the answer back (--by)." },
+                note: { type: "string", description: "Why, kept on the retraction (--note)." },
+                kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
+                dryRun: dryRunProp,
+            },
+            required: ["id", "by"],
+        },
+    },
+];
+/** A tool call that can't be made as given: the client gets it as an error result, and nothing runs. */
+class ToolInputError extends Error {
+}
+function str(params, key, required = false) {
+    const v = params[key];
+    if (v === undefined || v === null) {
+        if (required)
+            throw new ToolInputError(`${key} is required`);
+        return undefined;
+    }
+    if (typeof v !== "string" || v === "")
+        throw new ToolInputError(`${key} must be a non-empty string`);
+    // A value is passed as one argument; one that starts with - would read as a flag.
+    if (v.startsWith("-"))
+        throw new ToolInputError(`${key} may not start with -: ${JSON.stringify(v)}`);
+    return v;
+}
+function bool(params, key) {
+    const v = params[key];
+    if (v === undefined || v === null)
+        return false;
+    if (typeof v !== "boolean")
+        throw new ToolInputError(`${key} must be true or false`);
+    return v;
+}
+function obj(params, key) {
+    const v = params[key];
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        throw new ToolInputError(`${key} must be a JSON object`);
+    return v;
+}
+function kinds(params) {
+    const v = params.kind;
+    if (v === undefined || v === null)
+        return [];
+    const list = typeof v === "string" ? [v] : v;
+    if (!Array.isArray(list))
+        throw new ToolInputError("kind must be a kind file, or a list of them");
+    return list.map((k, i) => str({ [`kind[${i}]`]: k }, `kind[${i}]`, true));
+}
+/** The `chant` arguments each read tool runs, from its input. Exported for the conformance suite's MCP transport. */
+export function readArgv(tool, params) {
+    const at = str(params, "at");
+    const atArgs = at !== undefined ? ["--at", at] : [];
+    switch (tool) {
+        case "workspace-ls":
+            return ["workspace", "ls", ...atArgs, "--json"];
+        case "workspace-status": {
+            const env = str(params, "env", true);
+            const compareTo = str(params, "compareTo");
+            return ["workspace", "status", env, ...(compareTo !== undefined ? ["--compare-to", compareTo] : []), "--json"];
+        }
+        case "workspace-graph": {
+            const intent = str(params, "intent");
+            const composites = bool(params, "composites");
+            const kindArgs = kinds(params).flatMap((k) => ["--kind", k]);
+            if (composites)
+                return ["workspace", "graph", "--composites", ...kindArgs, ...(intent !== undefined ? ["--intent", intent] : []), ...atArgs, "--json"];
+            if (intent !== undefined)
+                return ["workspace", "graph", "--intent", intent, ...kindArgs, ...atArgs, ...(bool(params, "followSquash") ? ["--follow-squash"] : []), "--json"];
+            return ["workspace", "graph", ...kindArgs, ...atArgs, "--json"];
+        }
+        case "workspace-changes": {
+            const range = str(params, "range", true);
+            const work = str(params, "work");
+            const severity = str(params, "severity");
+            if (severity !== undefined && !["off", "warn", "fail"].includes(severity))
+                throw new ToolInputError("severity must be off, warn or fail");
+            return [
+                "workspace",
+                "check",
+                "--changes",
+                range,
+                ...(work !== undefined ? ["--work", work] : []),
+                ...(severity !== undefined ? ["--severity", severity] : []),
+                ...kinds(params).flatMap((k) => ["--kind", k]),
+                "--json",
+            ];
+        }
+        case "workspace-agent": {
+            const name = str(params, "name", true);
+            return ["workspace", "agent", name, "--json"];
+        }
+        case "workspace-work-history": {
+            const item = str(params, "item", true);
+            const kind = str(params, "kind");
+            return ["workspace", "work", "history", item, ...(kind !== undefined ? ["--kind", kind] : []), "--json"];
+        }
+        case "workspace-runs": {
+            const flags = ["unit", "decision", "by", "since"].flatMap((f) => {
+                const v = str(params, f);
+                return v !== undefined ? [`--${f}`, v] : [];
+            });
+            return ["workspace", "runs", ...flags, ...(bool(params, "followSquash") ? ["--follow-squash"] : []), "--json"];
+        }
+        case "workspace-points": {
+            const kind = str(params, "kind");
+            return ["workspace", "points", ...(bool(params, "open") ? ["--open"] : []), ...(kind !== undefined ? ["--kind", kind] : []), ...atArgs, "--json"];
+        }
+        case "workspace-records": {
+            const kind = str(params, "kind");
+            const since = str(params, "since");
+            if (bool(params, "uncommitted") && (at !== undefined || since !== undefined))
+                throw new ToolInputError("uncommitted reads the working tree against HEAD, and takes no at or since");
+            return [
+                "workspace",
+                "records",
+                ...(kind !== undefined ? ["--kind", kind] : []),
+                ...(bool(params, "current") ? ["--current"] : []),
+                ...(bool(params, "uncommitted") ? ["--uncommitted"] : []),
+                ...(since !== undefined ? ["--since", since] : []),
+                ...atArgs,
+                "--json",
+            ];
+        }
+        default:
+            throw new ToolInputError(`${tool} is not a workspace read tool`);
+    }
+}
+/** Run chant and parse the one JSON document it printed. The exit code does not matter: an error document is a document. */
+function runRead(command, argv, cwd) {
+    return new Promise((settle, fail) => {
+        const child = spawn(command[0], [...command.slice(1), ...argv], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf-8").on("data", (s) => (stdout += s));
+        child.stderr.setEncoding("utf-8").on("data", (s) => (stderr += s));
+        child.on("error", (e) => fail(new Error(`could not run chant ${argv.join(" ")}: ${e.message}`)));
+        child.on("close", (status) => {
+            try {
+                settle(JSON.parse(stdout));
+            }
+            catch {
+                const why = stderr.trim() || stdout.trim() || `exit ${status}`;
+                fail(new Error(`chant ${argv.join(" ")} printed no JSON document: ${why}`));
+            }
+        });
+    });
+}
+/** Keep only the record with `id` in a records document, or in each kind of a declared set. */
+function onlyRecord(doc, id) {
+    if (doc === null || typeof doc !== "object")
+        return doc;
+    const d = doc;
+    if (Array.isArray(d.records))
+        return { ...d, records: d.records.filter((r) => r.id === id) };
+    if (Array.isArray(d.kinds))
+        return { ...d, kinds: d.kinds.map((k) => onlyRecord(k, id)) };
+    return doc;
+}
+/** The source block a write through MCP lays over the record's (#2708). */
+function mcpSource(context) {
+    const c = context?.clientInfo;
+    const client = c && typeof c.name === "string" && c.name !== ""
+        ? {
+            name: c.name,
+            ...(typeof c.version === "string" && c.version !== "" ? { version: c.version } : {}),
+            ...(typeof c.title === "string" && c.title !== "" ? { title: c.title } : {}),
+        }
+        : undefined;
+    return { via: "mcp", ...(client ? { client } : {}) };
+}
+/** The workspace tools, reads then writes, bound to the server's directory. */
+export function createWorkspaceTools(options) {
+    const { cwd } = options;
+    const chant = options.chantCommand ?? ownChantCommand();
+    const agent = options.agent ?? (process.env[AGENT_ENV] || undefined);
+    const reads = workspaceReadTools.map((definition) => ({
+        definition,
+        handler: async (params) => {
+            const given = definition.name === "workspace-agent" && params.name === undefined && agent !== undefined ? { ...params, name: agent } : params;
+            const argv = readArgv(definition.name, given);
+            const id = definition.name === "workspace-records" ? str(params, "id") : undefined;
+            const doc = await runRead(chant, argv, cwd);
+            return id !== undefined ? onlyRecord(doc, id) : doc;
+        },
+    }));
+    const write = async () => import("../../workspace/records-write.js");
+    /** The kind file a write goes through: the one named, or the one the declaration names; else the CLI's usage failure. */
+    const writeKind = async (params, schema, missing) => {
+        const w = await write();
+        const named = str(params, "kind");
+        return named !== undefined ? w.resolveWriteKind(named, cwd) : w.declaredWriteKind(schema, cwd, missing);
+    };
+    const sign = (params) => (bool(params, "sign") ? true : undefined);
+    const handlers = {
+        "records-new": async (params, context) => {
+            const w = await write();
+            const record = obj(params, "record");
+            const kind = await writeKind(params, w.RECORDS_NEW_SCHEMA_ID, "new needs the kind file");
+            if (typeof kind !== "string")
+                return kind;
+            return w.newRecord({
+                kind,
+                fields: JSON.stringify(record),
+                prefix: str(params, "prefix"),
+                by: str(params, "by"),
+                sign: sign(params),
+                dryRun: bool(params, "dryRun"),
+                cwd,
+                agent,
+                through: { source: mcpSource(context), opensInitial: true },
+            });
+        },
+        "records-amend": async (params, context) => {
+            const w = await write();
+            const id = str(params, "id", true);
+            const fields = obj(params, "fields");
+            const kind = await writeKind(params, w.RECORDS_AMEND_SCHEMA_ID, "--kind <kind file> is required");
+            if (typeof kind !== "string")
+                return kind;
+            return w.amendRecord({
+                kind,
+                id,
+                fields: JSON.stringify(fields),
+                by: str(params, "by"),
+                sign: sign(params),
+                dryRun: bool(params, "dryRun"),
+                cwd,
+                agent,
+                through: { source: mcpSource(context) },
+            });
+        },
+        "records-review": async (params) => {
+            const w = await write();
+            const id = str(params, "id", true);
+            const kind = await writeKind(params, w.RECORDS_REVIEW_SCHEMA_ID, "--kind <kind file> is required");
+            if (typeof kind !== "string")
+                return kind;
+            return w.reviewRecord({
+                kind,
+                id,
+                verdict: str(params, "verdict", true),
+                by: str(params, "by", true),
+                note: typeof params.note === "string" ? params.note : undefined,
+                session: str(params, "session"),
+                sign: sign(params),
+                dryRun: bool(params, "dryRun"),
+                cwd,
+                agent,
+            });
+        },
+        "points-answer": async (params) => {
+            const { answerPoint } = await import("../../workspace/decide.js");
+            const answer = params.answer;
+            if (typeof answer !== "string" && typeof answer !== "boolean")
+                throw new ToolInputError("answer must be a string, or true or false");
+            const by = params.by;
+            if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== ""))
+                throw new ToolInputError("by must list each person who answered");
+            return answerPoint({ cwd, id: str(params, "id", true), answer, by: by, note: str(params, "note"), relayedBy: str(params, "relayedBy"), kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+        },
+        "points-retract": async (params) => {
+            const { retractAnswer } = await import("../../workspace/decide.js");
+            const by = params.by;
+            if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== ""))
+                throw new ToolInputError("by must list each person who takes the answer back");
+            return retractAnswer({ cwd, id: str(params, "id", true), by: by, note: str(params, "note"), kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+        },
+        "records-close": async (params) => {
+            const w = await write();
+            const { closeRecord, RECORDS_CLOSE_SCHEMA_ID } = await import("../../workspace/records-close.js");
+            const id = str(params, "id", true);
+            const named = str(params, "kind");
+            const kind = named !== undefined ? w.resolveWriteKind(named, cwd) : await w.declaredSessionKind(RECORDS_CLOSE_SCHEMA_ID, cwd);
+            if (typeof kind !== "string")
+                return kind;
+            return closeRecord({ kind, id, dryRun: bool(params, "dryRun"), cwd, agent });
+        },
+    };
+    const writes = workspaceWriteTools.map((definition) => ({ definition, handler: handlers[definition.name] }));
+    return [...reads, ...writes];
+}

package/dist/cli/mcp-config.js

@@ -0,0 +1,70 @@
+import { existsSync, writeFileSync } from "fs";
+import { join } from "path";
+/**
+ * The one place chant decides where a project's MCP server registration
+ * lives, what goes in it, and which command writes it (chant #2383).
+ *
+ * Before this module the three sites disagreed: `chant init` wrote
+ * `mcp.json` into the user's home directory (picking a harness directory
+ * that happened to exist), `chant doctor` looked for `<project>/.mcp.json`,
+ * and the doctor's remediation named `chant agent setup`, which was never
+ * registered in `./main.ts`. A project chant had just scaffolded therefore
+ * failed chant's own doctor, and the fix the warning named could not be run.
+ *
+ * Project scope wins. The file versions with the project it describes, it
+ * keeps `chant init <dir>` from writing outside `<dir>`, and it is already
+ * what `../agents/discover.ts` treats as the project-scope location when
+ * chant audits an agent installation it did not create. Every consumer must
+ * go through the constants here rather than rebuilding the path, so the
+ * three sites cannot drift apart again without the shared test in
+ * ./mcp-config.test.ts noticing.
+ */
+/** Filename of the project-scoped MCP server registration. */
+export const MCP_CONFIG_FILENAME = ".mcp.json";
+/**
+ * The command a user runs to (re)write a missing {@link MCP_CONFIG_FILENAME}
+ * in an existing project. `chant init` also writes it, but init refuses a
+ * non-empty directory without `--force`, so the remediation an already
+ * scaffolded project needs is `chant update` — which is also what the
+ * doctor's neighbouring skills check tells you to run for the same reason.
+ * Kept as a constant so ./mcp-config.test.ts can assert it is a command
+ * `commandRegistry` actually registers.
+ */
+export const MCP_SETUP_COMMAND = "chant update";
+/** Absolute (or caller-relative) path to a project's MCP config. */
+export function mcpConfigPath(projectDir) {
+    return join(projectDir, MCP_CONFIG_FILENAME);
+}
+/**
+ * Detect whether a project uses bun or npm, from its lock file. Lives here
+ * because the package manager is the only variable in the generated config.
+ */
+export function detectPackageManager(dir) {
+    if (dir && (existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock"))))
+        return "bun";
+    return "npm";
+}
+/** The MCP registration chant writes: one stdio server named `chant`. */
+export function generateMcpConfig(pm) {
+    const config = {
+        mcpServers: {
+            chant: {
+                command: pm === "bun" ? "bunx" : "npx",
+                args: ["chant", "serve", "mcp"],
+            },
+        },
+    };
+    return JSON.stringify(config, null, 2);
+}
+/**
+ * Write `<projectDir>/.mcp.json` unless one is already there. Returns the
+ * relative path when a file was created, `undefined` when an existing config
+ * was left alone — callers report that difference to the user.
+ */
+export function writeProjectMcpConfig(projectDir) {
+    const path = mcpConfigPath(projectDir);
+    if (existsSync(path))
+        return undefined;
+    writeFileSync(path, generateMcpConfig(detectPackageManager(projectDir)));
+    return MCP_CONFIG_FILENAME;
+}