@intentius/chant 0.124.13 → 0.124.15

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

@@ -0,0 +1,80 @@
+import { resolve } from "node:path";
+import { readSnapshot } from "../../lifecycle/git.js";
+import { build } from "../../build.js";
+import { computeBuildDigest, diffDigests } from "../../lifecycle/digest.js";
+import { takeSnapshot } from "../../lifecycle/snapshot.js";
+/**
+ * Create lifecycle-snapshot tool definition and handler
+ */
+export function createSnapshotTool(plugins) {
+    return {
+        definition: {
+            name: "lifecycle-snapshot",
+            description: "Capture deployed state for an environment",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    environment: { type: "string", description: "Target environment" },
+                    lexicon: { type: "string", description: "Optional — snapshot all lexicons if omitted" },
+                },
+                required: ["environment"],
+            },
+        },
+        handler: async (params) => {
+            const env = params.environment;
+            const lexiconFilter = params.lexicon;
+            const targetPlugins = lexiconFilter
+                ? plugins.filter((p) => p.name === lexiconFilter)
+                : plugins;
+            const pluginsWithDescribe = targetPlugins.filter((p) => p.describeResources);
+            if (pluginsWithDescribe.length === 0)
+                return "No plugins implement describeResources";
+            const serializers = plugins.map((p) => p.serializer);
+            const buildResult = await build(resolve("."), serializers);
+            if (buildResult.errors.length > 0)
+                return "Build failed";
+            const result = await takeSnapshot(env, pluginsWithDescribe, buildResult);
+            return { snapshots: result.snapshots.length, warnings: result.warnings, errors: result.errors };
+        },
+    };
+}
+/**
+ * Create lifecycle-diff tool definition and handler
+ */
+export function createDiffTool(plugins) {
+    return {
+        definition: {
+            name: "lifecycle-diff",
+            description: "Compare current build declarations against last snapshot's digest",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    environment: { type: "string", description: "Target environment" },
+                    lexicon: { type: "string", description: "Optional — diff all lexicons if omitted" },
+                },
+                required: ["environment"],
+            },
+        },
+        handler: async (params) => {
+            const env = params.environment;
+            const lexiconFilter = params.lexicon;
+            const serializers = plugins.map((p) => p.serializer);
+            const buildResult = await build(resolve("."), serializers);
+            if (buildResult.errors.length > 0)
+                return "Build failed";
+            const currentDigest = computeBuildDigest(buildResult);
+            const lexicons = lexiconFilter ? [lexiconFilter] : buildResult.manifest.lexicons;
+            const results = {};
+            for (const lex of lexicons) {
+                const content = await readSnapshot(env, lex);
+                let previousDigest = undefined;
+                if (content) {
+                    const snapshot = JSON.parse(content);
+                    previousDigest = snapshot.digest;
+                }
+                results[lex] = diffDigests(currentDigest, previousDigest);
+            }
+            return results;
+        },
+    };
+}

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

@@ -0,0 +1,306 @@
+/**
+ * MCP tools over Ops — on the runtime seam (#2121), not on any one runtime's
+ * own client.
+ *
+ * Every tool here goes through an {@link OpRuntimeProvider} — the built-in
+ * `local` one by default, or the `runtime` argument's lexicon `opRuntime` when
+ * an agent names one. One provider is built per call, so a long-lived server
+ * picks up a project's config as it is now rather than as it was at boot; the
+ * local provider's in-process run history is the exception and is held for the
+ * life of the module, so `op-status` can answer for a run `op-run` started.
+ *
+ * #2118 owns the ledger-backed record shape; when it lands, `status`/`log`
+ * read the ledger and this file stops depending on the process outliving the
+ * run.
+ */
+import { lexiconNames } from "../../lexicon-module.js";
+import { resolve } from "node:path";
+import { discoverOps } from "../../op/discover.js";
+import { createLocalOpRuntime } from "../../op/runtimes/local.js";
+import { loadChantConfig } from "../../config.js";
+import { loadPlugins } from "../plugins.js";
+import { readGateLedger, latestPendingGate } from "../../lifecycle/gate-ledger.js";
+import { recordGateApproval } from "../handlers/operator.js";
+/** The `local` provider, shared so an `op-run` is visible to a later `op-status`. */
+let localRuntime;
+/**
+ * Resolve the runtime a tool call addresses. `runtime` names a configured
+ * lexicon's `opRuntime`; omitted (or `local`) it is core's built-in provider.
+ * Throws with an actionable message — the MCP layer turns that into `isError`.
+ */
+async function runtimeFor(name) {
+    const wanted = typeof name === "string" && name.length > 0 ? name : "local";
+    if (wanted === "local") {
+        localRuntime ?? (localRuntime = createLocalOpRuntime({ projectPath: resolve(".") }));
+        return localRuntime;
+    }
+    const configured = await loadChantConfig(resolve("."))
+        .then(({ config }) => lexiconNames(config.lexicons ?? []))
+        .catch(() => []);
+    if (!configured.includes(wanted)) {
+        throw new Error(`runtime "${wanted}" is not a configured lexicon` +
+            (configured.length > 0 ? ` (configured: ${configured.join(", ")})` : ""));
+    }
+    const plugin = (await loadPlugins([wanted]))[0];
+    if (!plugin?.opRuntime)
+        throw new Error(`lexicon "${wanted}" does not host Op runs`);
+    return plugin.opRuntime;
+}
+/**
+ * The refusal for an Op that declares `neverOverMcp`, or `undefined` when MCP
+ * may act on it. It names the rule and the way through, which is a person at a
+ * shell. An Op that is not discovered is left to the caller's own not-found
+ * handling.
+ */
+async function neverOverMcpRefusal(name, action, gate) {
+    const { ops } = await discoverOps();
+    let declared = Boolean(ops.get(name)?.config.neverOverMcp);
+    // An Op that is not discovered (fan-out) declares nothing, so its gate
+    // records the rule itself (chant#3485).
+    if (!declared && action === "approve" && gate !== undefined) {
+        const { pending } = await readGateLedger(name).catch(() => ({ pending: [] }));
+        declared = Boolean(latestPendingGate(pending, gate)?.neverOverMcp);
+    }
+    if (!declared)
+        return undefined;
+    return action === "run"
+        ? `Op "${name}" declares neverOverMcp, so it is not run over MCP. Run it at a shell with \`chant run ${name}\`; op-status and op-report still answer here.`
+        : `Op "${name}" declares neverOverMcp, so its gates are not resolved over MCP, whichever channel reached them. ` +
+            `Approvals belong to people: approve at a shell with \`chant approve ${name} <gate>\`.`;
+}
+const RUNTIME_PARAM = {
+    type: "string",
+    description: 'Runtime to address: a lexicon name with an opRuntime, or "local" (the default)',
+};
+export function createOpListTool() {
+    return {
+        definition: {
+            name: "op-list",
+            description: "List all Op definitions discovered from *.op.ts files with their current run state",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    runtime: RUNTIME_PARAM,
+                },
+            },
+        },
+        handler: async (params) => {
+            const { ops, errors } = await discoverOps();
+            let states = new Map();
+            try {
+                const runtime = await runtimeFor(params.runtime);
+                states = await runtime.list([...ops.values()].map((d) => d.config));
+            }
+            catch {
+                // Runtime unavailable — the definitions are still worth listing.
+            }
+            const result = [];
+            for (const [name, { config }] of ops) {
+                result.push({
+                    name,
+                    overview: config.overview,
+                    phases: config.phases.length,
+                    labels: config.labels ?? {},
+                    depends: config.depends ?? [],
+                    runState: states.get(name)?.state ?? "—",
+                });
+            }
+            return { ops: result, errors };
+        },
+    };
+}
+export function createOpRunTool() {
+    return {
+        definition: {
+            name: "op-run",
+            description: "Run an Op on a runtime and return its result. Defaults to the built-in local runtime, which executes the Op in this process. " +
+                "Refuses an Op that declares neverOverMcp.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Op name (e.g. alb-deploy)" },
+                    // chant#3560 — what `chant run --env` passes: the environment the
+                    // run targets. Omitted, the runtime uses its own default.
+                    env: { type: "string", description: "Environment the run targets (defaults to the runtime's own)" },
+                    runtime: RUNTIME_PARAM,
+                },
+                required: ["name"],
+            },
+        },
+        handler: async (params) => {
+            const name = params.name;
+            const { ops } = await discoverOps();
+            const refusal = await neverOverMcpRefusal(name, "run");
+            if (refusal)
+                throw new Error(refusal);
+            if (!ops.has(name)) {
+                const available = [...ops.keys()];
+                return `Op "${name}" not found. Available: ${available.join(", ") || "none"}`;
+            }
+            const runtime = await runtimeFor(params.runtime);
+            const env = typeof params.env === "string" && params.env !== "" ? params.env : undefined;
+            const handle = await runtime.start(ops.get(name).config, env !== undefined ? { env } : {});
+            const status = await handle.result();
+            return {
+                op: status.op,
+                runId: status.runId,
+                state: status.state,
+                startedAt: status.startedAt,
+                endedAt: status.endedAt ?? null,
+                ...(status.records ? { records: status.records } : {}),
+                ...(status.gate ? { gate: status.gate } : {}),
+            };
+        },
+    };
+}
+export function createOpStatusTool() {
+    return {
+        definition: {
+            name: "op-status",
+            description: "Return the current run state of an Op on a runtime",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Op name (e.g. alb-deploy)" },
+                    runtime: RUNTIME_PARAM,
+                },
+                required: ["name"],
+            },
+        },
+        handler: async (params) => {
+            const name = params.name;
+            const { ops } = await discoverOps();
+            if (!ops.has(name))
+                throw new Error(`Op "${name}" not found`);
+            const runtime = await runtimeFor(params.runtime);
+            const status = await runtime.status(name);
+            if (!status)
+                return { op: name, runtime: runtime.name, state: null, message: "no run recorded" };
+            return {
+                op: status.op,
+                runtime: runtime.name,
+                runId: status.runId,
+                state: status.state,
+                startedAt: status.startedAt,
+                endedAt: status.endedAt ?? null,
+                ...(status.records ? { records: status.records } : {}),
+                gate: status.gate ?? null,
+            };
+        },
+    };
+}
+export function createOpApproveTool() {
+    return {
+        definition: {
+            name: "op-approve",
+            description: "Record a gate's resolution on the gate ledger and wake the runtime hosting the gated run. " +
+                "Refuses a gate this same channel reached: a run started with op-run must be approved from " +
+                "somewhere else, normally `chant approve <op> <gate>` at a shell. The approver is recorded as " +
+                "unattested, because this channel cannot verify a name. Also refuses every gate of an Op that " +
+                "declares neverOverMcp, whatever channel reached the gate.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Op name (e.g. alb-deploy)" },
+                    gate: { type: "string", description: "Gate name (e.g. gate-dns-delegation)" },
+                    // chant#2384 — no `approver`. It was free text on a channel that
+                    // cannot verify one, so the model named itself whatever it liked and
+                    // the ledger recorded it indistinguishably from a name a person gave.
+                    note: { type: "string", description: "Free-text context recorded on the resolution" },
+                    url: { type: "string", description: "Absolute http/https URL this resolution happened at" },
+                    // chant#3555 — what `chant run approve --env` passes: the
+                    // environment the woken run runs in. Omitted, the runtime keeps the
+                    // gated run's.
+                    env: { type: "string", description: "Environment the woken run runs in (defaults to the gated run's)" },
+                    runtime: RUNTIME_PARAM,
+                },
+                required: ["name", "gate"],
+            },
+        },
+        handler: async (params) => {
+            const name = params.name;
+            const gate = params.gate;
+            if (!name || !gate)
+                throw new Error("op-approve needs both an Op name and a gate name");
+            const refusal = await neverOverMcpRefusal(name, "approve", gate);
+            if (refusal)
+                throw new Error(refusal);
+            const runtime = await runtimeFor(params.runtime);
+            const outcome = await recordGateApproval(name, gate, {
+                note: params.note,
+                url: params.url,
+                // Named rather than left to the ambient value, so this tool states its
+                // own channel even if it is ever registered on a server that did not.
+                origin: "mcp",
+            });
+            if (!outcome.ok) {
+                throw new Error(`Gate "${gate}" on "${name}" was not recorded. If the gate was reached over MCP, it cannot ` +
+                    `also be resolved over MCP — approve it from another channel, normally ` +
+                    `\`chant approve ${name} ${gate}\` at a shell.`);
+            }
+            if (runtime.resolveGate) {
+                const env = typeof params.env === "string" && params.env !== "" ? params.env : undefined;
+                if (env !== undefined)
+                    await runtime.resolveGate(name, gate, outcome.record, { env });
+                else
+                    await runtime.resolveGate(name, gate, outcome.record);
+            }
+            return {
+                op: name,
+                gate,
+                resolvedBy: outcome.record.resolvedBy,
+                origin: outcome.record.origin,
+                timestamp: outcome.record.timestamp,
+                runtimeNotified: Boolean(runtime.resolveGate),
+            };
+        },
+    };
+}
+export function createOpReportTool() {
+    return {
+        definition: {
+            name: "op-report",
+            description: "Return a markdown report for the latest run of an Op on a runtime",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Op name (e.g. alb-deploy)" },
+                    runtime: RUNTIME_PARAM,
+                },
+                required: ["name"],
+            },
+        },
+        handler: async (params) => {
+            const name = params.name;
+            const { ops } = await discoverOps();
+            if (!ops.has(name))
+                return `Op "${name}" not found`;
+            const { config } = ops.get(name);
+            const runtime = await runtimeFor(params.runtime);
+            const status = await runtime.status(name);
+            if (!status)
+                return `# ${name}\n\n${config.overview}\n\nNo run is recorded on the "${runtime.name}" runtime.\n`;
+            const lines = [
+                `# ${name}`,
+                "",
+                config.overview,
+                "",
+                `- Runtime: ${runtime.name}`,
+                `- Run: ${status.runId}`,
+                `- State: ${status.state}`,
+                `- Started: ${status.startedAt}`,
+                ...(status.endedAt ? [`- Ended: ${status.endedAt}`] : []),
+                ...(status.gate ? [`- Gate: ${status.gate.name} (pending since ${status.gate.since})`] : []),
+                "",
+            ];
+            if (status.records?.length) {
+                lines.push("| Phase | Step | Status | Duration |", "|---|---|---|---|");
+                for (const record of status.records) {
+                    lines.push(`| ${record.phase} | ${record.fn} | ${record.status} | ${record.durationMs}ms |`);
+                }
+                lines.push("");
+            }
+            return lines.join("\n");
+        },
+    };
+}

package/dist/cli/mcp/resource-handlers.js

@@ -0,0 +1,258 @@
+import { resolve, join, dirname } from "node:path";
+import { readFile } from "node:fs/promises";
+import { collectComposites } from "./tools/composites.js";
+import { getContext } from "./resources/context.js";
+import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git.js";
+import { discoverOps } from "../../op/discover.js";
+import { createLocalOpRuntime } from "../../op/runtimes/local.js";
+import { loadOkfBundle } from "../../okf-read.js";
+import { loadChantConfigUpward, resolveKnowledgeDir } from "../../config.js";
+/**
+ * Core resource definitions (always present regardless of plugins)
+ */
+export const coreResourceDefinitions = [
+    {
+        uri: "chant://context",
+        name: "chant Context",
+        description: "Lexicon-specific instructions and patterns for chant development",
+        mimeType: "text/markdown",
+    },
+    {
+        uri: "chant://examples/list",
+        name: "Examples List",
+        description: "List of available chant examples",
+        mimeType: "application/json",
+    },
+    {
+        uri: "chant://ops",
+        name: "Ops",
+        description: "All Op definitions discovered from *.op.ts files",
+        mimeType: "application/json",
+    },
+    {
+        uri: "chant://ops/{name}/runs",
+        name: "Op run history",
+        description: "Run history for a named Op, newest first",
+        mimeType: "application/json",
+    },
+    {
+        uri: "chant://ops/{name}/runs/latest",
+        name: "Op latest run",
+        description: "Latest run state for a named Op",
+        mimeType: "application/json",
+    },
+    {
+        uri: "chant://composites",
+        name: "Composite catalog",
+        description: "Every composite the loaded lexicons export, with what each bundles and its parameters (#2662)",
+        mimeType: "application/json",
+    },
+    {
+        uri: "chant://knowledge",
+        name: "Knowledge bundle",
+        description: "The project's OKF knowledge bundle (#1864, #1059): index.md and every authored concept, empty when no bundle exists",
+        mimeType: "application/json",
+    },
+    {
+        uri: "chant://state/{environment}",
+        name: "State (all lexicons)",
+        description: "All lexicon snapshots for an environment",
+        mimeType: "application/json",
+    },
+    {
+        uri: "chant://state/{environment}/{lexicon}",
+        name: "State (single lexicon)",
+        description: "Single lexicon snapshot for an environment",
+        mimeType: "application/json",
+    },
+];
+/**
+ * Build the full resources list merging core + plugin resources
+ */
+export function buildResourcesList(pluginResources) {
+    const resources = [...coreResourceDefinitions];
+    for (const { definition } of pluginResources.values()) {
+        resources.push(definition);
+    }
+    return { resources };
+}
+/**
+ * Collect example resources from plugins whose URI contains "examples/"
+ */
+export function collectExamples(pluginResources) {
+    const examples = [];
+    for (const [uri, { definition }] of pluginResources.entries()) {
+        if (uri.includes("/examples/")) {
+            const name = uri.replace(/^chant:\/\/[^/]+\/examples\//, "");
+            examples.push({ name, description: definition.description });
+        }
+    }
+    return examples;
+}
+/**
+ * Handle resources/read request — checks plugin resources after core
+ */
+export async function handleResourcesRead(params, pluginResources, plugins = []) {
+    const uri = params.uri;
+    // The whole composite catalog (#2662), static data from each lexicon's
+    // `composites()`; the `composites` tool filters the same list.
+    if (uri === "chant://composites") {
+        return {
+            contents: [{ uri, mimeType: "application/json", text: JSON.stringify(collectComposites(plugins), null, 2) }],
+        };
+    }
+    if (uri === "chant://context") {
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "text/markdown",
+                    text: getContext(),
+                },
+            ],
+        };
+    }
+    if (uri === "chant://examples/list") {
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify(collectExamples(pluginResources)),
+                },
+            ],
+        };
+    }
+    // Authored knowledge (#1867, #1864, design #1059): same bundle the CLI's
+    // `chant explain` reads, over MCP — the resource path has no local
+    // filesystem, so this is the only way an MCP client sees the `knowledge/`
+    // directory's contents at all. Resolved from cwd, matching every other
+    // path-less resource here (`chant://ops`, `chant://state/...`). A missing
+    // bundle is not an error — `loadOkfBundle` already treats it as empty, and
+    // a missing `index.md` reads as `index: null` rather than throwing.
+    if (uri === "chant://knowledge") {
+        const cwd = resolve(".");
+        const loaded = await loadChantConfigUpward(cwd);
+        const projectRoot = loaded.configPath ? dirname(loaded.configPath) : cwd;
+        const dir = resolveKnowledgeDir(loaded.config, projectRoot);
+        const bundle = await loadOkfBundle(dir);
+        let index = null;
+        try {
+            index = await readFile(join(dir, "index.md"), "utf8");
+        }
+        catch {
+            index = null;
+        }
+        return {
+            contents: [{
+                    uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify({ dir, index, concepts: bundle.concepts }, null, 2),
+                }],
+        };
+    }
+    // Op resources
+    if (uri === "chant://ops") {
+        const { ops } = await discoverOps();
+        const list = Array.from(ops.values()).map(({ config }) => ({
+            name: config.name,
+            overview: config.overview,
+            phases: config.phases.length,
+            labels: config.labels ?? {},
+            depends: config.depends ?? [],
+        }));
+        return {
+            contents: [{ uri, mimeType: "application/json", text: JSON.stringify(list, null, 2) }],
+        };
+    }
+    // Both run resources read the built-in local runtime (#2121, #2116) — the
+    // one an MCP client can address without naming a lexicon. `status` and `log`
+    // answer from the run ledger (#2118), so a run that ended in an earlier
+    // process still reads back here.
+    if (uri.startsWith("chant://ops/") && uri.endsWith("/runs/latest")) {
+        const name = uri.replace("chant://ops/", "").replace("/runs/latest", "");
+        try {
+            const status = await createLocalOpRuntime({ projectPath: resolve(".") }).status(name);
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify(status ?? null, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }) }],
+            };
+        }
+    }
+    if (uri.startsWith("chant://ops/") && uri.endsWith("/runs")) {
+        const name = uri.replace("chant://ops/", "").replace("/runs", "");
+        try {
+            const runs = await createLocalOpRuntime({ projectPath: resolve(".") }).log(name);
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify(runs, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }) }],
+            };
+        }
+    }
+    // State resources: chant://state/{environment} and chant://state/{environment}/{lexicon}
+    if (uri.startsWith("chant://state/")) {
+        const parts = uri.replace("chant://state/", "").split("/");
+        const environment = parts[0];
+        const lexicon = parts[1];
+        if (lexicon) {
+            const content = await readSnapshot(environment, lexicon);
+            if (!content)
+                throw new Error(`No snapshot found for ${environment}/${lexicon}`);
+            return {
+                contents: [{ uri, mimeType: "application/json", text: content }],
+            };
+        }
+        else {
+            const snapshots = await readEnvironmentSnapshots(environment);
+            const result = {};
+            for (const [lex, content] of snapshots) {
+                result[lex] = JSON.parse(content);
+            }
+            return {
+                contents: [{ uri, mimeType: "application/json", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+    }
+    if (uri.startsWith("chant://examples/")) {
+        // Look up example in plugin resources
+        const name = uri.replace("chant://examples/", "");
+        for (const [pluginUri, pluginResource] of pluginResources.entries()) {
+            if (pluginUri.endsWith(`/examples/${name}`)) {
+                const text = await pluginResource.handler();
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: pluginResource.definition.mimeType ?? "text/typescript",
+                            text,
+                        },
+                    ],
+                };
+            }
+        }
+        throw new Error(`Example not found: ${name}`);
+    }
+    // Check plugin resources
+    const pluginResource = pluginResources.get(uri);
+    if (pluginResource) {
+        const text = await pluginResource.handler();
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: pluginResource.definition.mimeType ?? "text/plain",
+                    text,
+                },
+            ],
+        };
+    }
+    throw new Error(`Unknown resource: ${uri}`);
+}