@codai/axiom-mcp 2.1.0 → 2.2.0

package/dist/index.js

@@ -1,17 +1,18 @@
 import { createRequire } from "node:module";
-import { ApplyResultSchema, AxiomError, CheckReportSchema, DigestRefSchema, ErrorCodeSchema, JournalPhaseSchema, JournalSchema, ManifestBodySchema, ManifestBundleSchema, PlanSchema, ProfileSchema, RepoSnapshotSchema, TrustStateSchema, TrustStoreSchema, compareUtf8, isValidRelPath } from "@codai/axiom-schema";
+import { ApplyResultSchema, AxiomError, CheckReportSchema, DigestRefSchema, ErrorCodeSchema, JournalPhaseSchema, JournalSchema, ManifestBodySchema, ManifestBundleSchema, PlanArtifactSchema, PlanSchema, ProfileSchema, RepoSnapshotSchema, TrustStateSchema, TrustStoreSchema, compareUtf8, isValidRelPath } from "@codai/axiom-schema";
 import { z } from "zod";
 import { createReadStream, realpath } from "node:fs";
 import { access, chmod, constants, lstat, mkdir, opendir, readFile, readdir, realpath as realpath$1, rename, stat, writeFile } from "node:fs/promises";
 import * as path from "node:path";
 import { promisify } from "node:util";
-import { TRUST_FILE_DEFAULT, TRUST_STATE_FILE, loadProfile, runChecks, verifyBundleSignatures } from "@codai/axiom-checks";
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TRUST_FILE_DEFAULT, TRUST_STATE_FILE, TRUST_STATE_KEY_FILE, loadProfile, runChecks, trustStateMac, trustStateMacOk, verifyBundleSignatures } from "@codai/axiom-checks";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/server";
+import "@modelcontextprotocol/server/stdio";
 import { webEmitter } from "@codai/axiom-emitters-web";
 import { compilePlan, createEmitterRegistry, diffManifests, verifyBundle } from "@codai/axiom-plan";
 import { appliedPath, apply, rollback } from "@codai/axiom-apply";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { canonicalDigestRef } from "@codai/axiom-canon";
-import { createHash } from "node:crypto";
 //#region src/jsonschema.ts
 const SCHEMA_KINDS = [
 	"Plan",
@@ -167,6 +168,53 @@ async function resolveRoot(policy, requested) {
 	} });
 }
 //#endregion
+//#region src/adapter.ts
+/**
+* MCP SDK adapter (v2-architecture §5.4, D-19, S-405).
+*
+* The ONLY module under `packages/mcp/src` allowed to import `@modelcontextprotocol/*`
+* (guard: `check-sdk-adapter`). Everything AXIOM needs from the SDK — server construction,
+* the two serving entries, the result types — is re-exported here under names that do not
+* change when the SDK does, so the next SDK major is a one-file diff.
+*
+* SDK 2.0.0 (2026-07-27) facts this seam encodes:
+* - `@modelcontextprotocol/sdk` is split; the server surface is `@modelcontextprotocol/server`
+*   and stdio lives on its `./stdio` subpath (the root barrel is runtime-neutral).
+* - A hand-connected `McpServer` + `StdioServerTransport` speaks ONLY the 2025 era. Serving the
+*   2026-07-28 revision goes through the factory entries `serveStdio` / `createMcpHandler`,
+*   which pin one instance per connection (stdio) or build one per request (HTTP) and pass the
+*   factory the `era` they are about to serve.
+* - `ttlMs` / `cacheScope` (SEP-2549) are stamped by the SDK on 2026-era cacheable results from
+*   `ServerOptions.cacheHints`; 2025-era responses never carry them.
+*/
+/**
+* Cache policy AXIOM advertises on 2026-era `tools/list` & co. The tool catalogue is static
+* for the life of a process, so a shared 5-minute TTL is safe; `resources/read` is content
+* addressed (`axiom://manifest/<sha>`) and therefore immutable → public, 1 day.
+*/
+const CACHE_HINTS = {
+	"tools/list": {
+		ttlMs: 3e5,
+		cacheScope: "public"
+	},
+	"resources/templates/list": {
+		ttlMs: 3e5,
+		cacheScope: "public"
+	},
+	"server/discover": {
+		ttlMs: 3e5,
+		cacheScope: "public"
+	},
+	"resources/list": {
+		ttlMs: 1e4,
+		cacheScope: "private"
+	},
+	"resources/read": {
+		ttlMs: 864e5,
+		cacheScope: "public"
+	}
+};
+//#endregion
 //#region src/emitters.ts
 /** Template emitters available to `axiom_plan_compile` / `axiom compile` (D-13: optional sugar). */
 const EMITTERS = createEmitterRegistry([webEmitter]);
@@ -266,6 +314,251 @@ async function listStored(roots, sub) {
 	return out;
 }
 //#endregion
+//#region src/tasks.ts
+/**
+* S-406 / D-24 — tool-level tasks and chunked plan sessions.
+*
+* MCP SDK v2 ships the `io.modelcontextprotocol/tasks` wire vocabulary but no runtime (the
+* `tasks/*` methods are excluded from `setRequestHandler`, and the 2026-07-28 `tools/call` codec
+* rejects a `CreateTaskResult`). AXIOM therefore models long-running work as ordinary tools:
+* `axiom_check_start` → `{ taskId, status: "working", pollIntervalMs, ttlMs }`, then
+* `axiom_task_get` until `status` is terminal, `axiom_task_cancel` to abort. This works on every
+* client that can call a tool (Copilot, codai agent-core, SDK v1 and v2) and on both wire eras.
+*
+* State is per factory (shared by every server instance a `serverFactory` builds, like
+* `seenRoots`), never persisted: a restarted server has no tasks, and a poll for an unknown id is
+* `ERR_TASK_NOT_FOUND`. Terminal tasks are kept for `ttlMs` after finishing, then dropped.
+*
+* The same store hosts chunked plan sessions (`axiom_plan_begin` → `axiom_plan_add`* →
+* `axiom_plan_seal`): artifacts accumulate server-side so a Plan whose JSON would exceed the
+* per-call 4 MiB payload cap can still be compiled. Sealing feeds the assembled Plan to the very
+* same `compilePlan`, so the digest is identical to a one-shot compile (property test).
+*/
+const TASK_STATUSES = [
+	"working",
+	"completed",
+	"failed",
+	"cancelled"
+];
+/** How long a finished task stays pollable. */
+const TASK_TTL_MS = 6e5;
+/** Advisory poll interval returned to clients. */
+const TASK_POLL_INTERVAL_MS = 2e3;
+/** Concurrent `working` tasks per server process; the (n+1)th `axiom_check_start` is refused. */
+const TASK_MAX_WORKING = 8;
+/** Idle sessions (no `add`/`seal`) are dropped after this. */
+const PLAN_SESSION_TTL_MS = 18e5;
+/** Artifacts a session may hold — same bound as `PlanSchema.artifacts.max`. */
+const PLAN_SESSION_MAX_ARTIFACTS = 2e3;
+/** Summed UTF-8 JSON bytes of every chunk a session accepts (64 MiB, the `default` profile's `maxTotalBytes`). */
+const PLAN_SESSION_MAX_BYTES = 67108864;
+const TaskStatusSchema = z.enum(TASK_STATUSES);
+const TaskErrorSchema = z.object({
+	code: z.string(),
+	message: z.string(),
+	details: z.record(z.string(), z.unknown()).optional()
+});
+var TaskStore = class {
+	tasks = /* @__PURE__ */ new Map();
+	now;
+	ttlMs;
+	pollIntervalMs;
+	maxWorking;
+	constructor(opts = {}) {
+		this.now = opts.now ?? Date.now;
+		this.ttlMs = opts.ttlMs ?? 6e5;
+		this.pollIntervalMs = opts.pollIntervalMs ?? 2e3;
+		this.maxWorking = opts.maxWorking ?? 8;
+	}
+	/**
+	* Start `work` in the background. The returned record is `working` until the promise settles;
+	* a rejection becomes `failed` (AxiomError → its closed code, anything else → `ERR_INTERNAL`),
+	* a rejection after `cancel()` stays `cancelled`.
+	*/
+	start(tool, work, meta = {}) {
+		this.sweep();
+		const working = [...this.tasks.values()].filter((t) => t.status === "working").length;
+		if (working >= this.maxWorking) throw new AxiomError("ERR_EBUSY", `too many running tasks (${working}/${this.maxWorking})`, { details: {
+			working,
+			max: this.maxWorking
+		} });
+		const controller = new AbortController();
+		const rec = {
+			taskId: randomUUID(),
+			tool,
+			status: "working",
+			createdAt: this.now(),
+			controller
+		};
+		if (meta.root !== void 0) rec.root = meta.root;
+		this.tasks.set(rec.taskId, rec);
+		work(controller.signal).then((result) => {
+			if (rec.status !== "working") return;
+			rec.status = "completed";
+			rec.result = result;
+			rec.finishedAt = this.now();
+		}, (err) => {
+			if (rec.status !== "working") return;
+			rec.status = controller.signal.aborted ? "cancelled" : "failed";
+			rec.error = toTaskError(err);
+			rec.finishedAt = this.now();
+		});
+		return rec;
+	}
+	get(taskId) {
+		this.sweep();
+		const rec = this.tasks.get(taskId);
+		if (rec === void 0) throw new AxiomError("ERR_TASK_NOT_FOUND", `no task ${taskId}`, { details: { taskId } });
+		return rec;
+	}
+	/** Abort a `working` task; terminal tasks are left as they are (idempotent). */
+	cancel(taskId) {
+		const rec = this.get(taskId);
+		if (rec.status === "working") {
+			rec.status = "cancelled";
+			rec.finishedAt = this.now();
+			rec.error = {
+				code: "ERR_TASK_CANCELLED",
+				message: "cancelled via axiom_task_cancel"
+			};
+			rec.controller.abort();
+		}
+		return rec;
+	}
+	describe(rec) {
+		return {
+			taskId: rec.taskId,
+			tool: rec.tool,
+			status: rec.status,
+			pollIntervalMs: this.pollIntervalMs,
+			ttlMs: this.ttlMs,
+			elapsedMs: Math.max(0, (rec.finishedAt ?? this.now()) - rec.createdAt)
+		};
+	}
+	/** Drop terminal tasks older than `ttlMs`. */
+	sweep() {
+		const cutoff = this.now() - this.ttlMs;
+		for (const [id, t] of this.tasks) if (t.finishedAt !== void 0 && t.finishedAt < cutoff) this.tasks.delete(id);
+	}
+	/** Abort everything still running (server shutdown). */
+	abortAll() {
+		for (const t of this.tasks.values()) if (t.status === "working") this.cancel(t.taskId);
+	}
+	get size() {
+		return this.tasks.size;
+	}
+};
+function toTaskError(err) {
+	if (err instanceof AxiomError) {
+		const j = err.toJSON();
+		const out = {
+			code: j.code,
+			message: j.message
+		};
+		if (j.details !== void 0) out.details = j.details;
+		return out;
+	}
+	return {
+		code: "ERR_INTERNAL",
+		message: err instanceof Error ? err.message : String(err)
+	};
+}
+var PlanSessionStore = class {
+	sessions = /* @__PURE__ */ new Map();
+	now;
+	ttlMs;
+	maxOpen;
+	maxArtifacts;
+	maxBytes;
+	constructor(opts = {}) {
+		this.now = opts.now ?? Date.now;
+		this.ttlMs = opts.ttlMs ?? 18e5;
+		this.maxOpen = opts.maxOpen ?? 16;
+		this.maxArtifacts = opts.maxArtifacts ?? 2e3;
+		this.maxBytes = opts.maxBytes ?? 67108864;
+	}
+	begin(header) {
+		this.sweep();
+		if (this.sessions.size >= this.maxOpen) throw new AxiomError("ERR_EBUSY", `too many open plan sessions (${this.sessions.size}/${this.maxOpen})`, { details: {
+			open: this.sessions.size,
+			max: this.maxOpen
+		} });
+		const t = this.now();
+		const s = {
+			sessionId: randomUUID(),
+			header,
+			artifacts: [],
+			paths: /* @__PURE__ */ new Set(),
+			bytes: 0,
+			createdAt: t,
+			touchedAt: t,
+			sealed: false
+		};
+		this.sessions.set(s.sessionId, s);
+		return s;
+	}
+	get(sessionId) {
+		this.sweep();
+		const s = this.sessions.get(sessionId);
+		if (s === void 0) throw new AxiomError("ERR_TASK_NOT_FOUND", `no plan session ${sessionId}`, { details: { sessionId } });
+		return s;
+	}
+	/** Append already-validated artifacts; duplicates (within or across chunks) are `ERR_INVALID_PLAN`. */
+	add(sessionId, artifacts, chunkBytes) {
+		const s = this.get(sessionId);
+		if (s.sealed) throw new AxiomError("ERR_PLAN_SESSION_STATE", "plan session is already sealed", { details: { sessionId } });
+		if (s.artifacts.length + artifacts.length > this.maxArtifacts) throw new AxiomError("ERR_PLAN_SESSION_STATE", `session would hold ${s.artifacts.length + artifacts.length} artifacts; max ${this.maxArtifacts}`, { details: {
+			sessionId,
+			have: s.artifacts.length,
+			adding: artifacts.length
+		} });
+		if (s.bytes + chunkBytes > this.maxBytes) throw new AxiomError("ERR_PLAN_SESSION_STATE", `session would hold ${s.bytes + chunkBytes} bytes; max ${this.maxBytes}`, { details: {
+			sessionId,
+			have: s.bytes,
+			adding: chunkBytes,
+			max: this.maxBytes
+		} });
+		for (const a of artifacts) if (s.paths.has(a.path)) throw new AxiomError("ERR_INVALID_PLAN", "duplicate artifact path across chunks", {
+			path: a.path,
+			details: { sessionId }
+		});
+		for (const a of artifacts) {
+			s.paths.add(a.path);
+			s.artifacts.push(a);
+		}
+		s.bytes += chunkBytes;
+		s.touchedAt = this.now();
+		return s;
+	}
+	/** Mark sealed and return the assembled Plan input; the session is dropped. */
+	seal(sessionId) {
+		const s = this.get(sessionId);
+		if (s.sealed) throw new AxiomError("ERR_PLAN_SESSION_STATE", "plan session is already sealed", { details: { sessionId } });
+		s.sealed = true;
+		this.sessions.delete(sessionId);
+		return {
+			session: s,
+			plan: {
+				apiVersion: "axiom.dev/v2",
+				kind: "Plan",
+				...s.header,
+				artifacts: s.artifacts
+			}
+		};
+	}
+	/** Drop an unsealed session without compiling. Unknown ids are a no-op. */
+	abandon(sessionId) {
+		return this.sessions.delete(sessionId);
+	}
+	sweep() {
+		const cutoff = this.now() - this.ttlMs;
+		for (const [id, s] of this.sessions) if (s.touchedAt < cutoff) this.sessions.delete(id);
+	}
+	get size() {
+		return this.sessions.size;
+	}
+};
+//#endregion
 //#region src/keys.ts
 /**
 * Key material and trust-store I/O for the CLI/MCP layer (D-16).
@@ -279,6 +572,9 @@ function trustFilePath(root, rel = TRUST_FILE_DEFAULT) {
 function trustStatePath(root) {
 	return path.join(root, ...TRUST_STATE_FILE.split("/"));
 }
+function trustStateKeyPath(root) {
+	return path.join(root, ...TRUST_STATE_KEY_FILE.split("/"));
+}
 async function writeJsonAtomic(file, value, mode) {
 	await mkdir(path.dirname(file), { recursive: true });
 	const tmp = `${file}.tmp-${process.pid}`;
@@ -302,7 +598,7 @@ async function verifyBundleAgainstRoot(root, bundle, rel = TRUST_FILE_DEFAULT) {
 	const store = await loadTrustStore(root, rel);
 	if (store === void 0) return void 0;
 	const v = verifyBundleSignatures(bundle, store, bundle.manifest.counter);
-	return {
+	const report = {
 		trustFile: rel,
 		keyids: v.keyids,
 		findings: v.findings.map((f) => ({
@@ -311,6 +607,8 @@ async function verifyBundleAgainstRoot(root, bundle, rel = TRUST_FILE_DEFAULT) {
 		})),
 		ok: v.keyids.length > 0 && v.findings.length === 0
 	};
+	if (!report.ok) report.code = (bundle.signatures ?? []).length === 0 ? "ERR_SIGNATURE_MISSING" : "ERR_SIGNATURE_INVALID";
+	return report;
 }
 async function loadTrustStore(root, rel = TRUST_FILE_DEFAULT) {
 	const raw = await readJsonOrUndefined(trustFilePath(root, rel));
@@ -319,11 +617,47 @@ async function loadTrustStore(root, rel = TRUST_FILE_DEFAULT) {
 	if (!parsed.success) throw new AxiomError("ERR_INVALID_PROFILE", `trust store ${rel} is invalid`, { details: { issues: parsed.error.issues.slice(0, 10).map((i) => i.message) } });
 	return parsed.data;
 }
+async function loadStateKey(root) {
+	let text;
+	try {
+		text = await readFile(trustStateKeyPath(root), "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return void 0;
+		throw err;
+	}
+	const hex = text.trim();
+	if (!/^[0-9a-f]{64}$/.test(hex)) throw new AxiomError("ERR_TRUST_STATE_CORRUPT", `${TRUST_STATE_KEY_FILE} is not 32 hex bytes`);
+	return hex;
+}
+/** Create `.axiom/trust/state.key` (32 random bytes, hex, 0600) when absent; return the key. */
+async function ensureStateKey(root) {
+	const existing = await loadStateKey(root);
+	if (existing !== void 0) return existing;
+	const hex = randomBytes(32).toString("hex");
+	const file = trustStateKeyPath(root);
+	await mkdir(path.dirname(file), { recursive: true });
+	const tmp = `${file}.tmp-${process.pid}`;
+	await writeFile(tmp, `${hex}\n`, {
+		encoding: "utf8",
+		mode: 384
+	});
+	await chmod(tmp, 384).catch(() => void 0);
+	await rename(tmp, file);
+	return hex;
+}
 async function loadTrustState(root) {
-	const raw = await readJsonOrUndefined(trustStatePath(root));
+	let raw;
+	try {
+		raw = await readJsonOrUndefined(trustStatePath(root));
+	} catch (err) {
+		if (err instanceof SyntaxError) throw new AxiomError("ERR_TRUST_STATE_CORRUPT", `${TRUST_STATE_FILE} is not valid JSON`, { cause: err });
+		throw err;
+	}
 	if (raw === void 0) return void 0;
 	const parsed = TrustStateSchema.safeParse(raw);
-	if (!parsed.success) throw new AxiomError("ERR_JOURNAL_CORRUPT", `${TRUST_STATE_FILE} is invalid`);
+	if (!parsed.success) throw new AxiomError("ERR_TRUST_STATE_CORRUPT", `${TRUST_STATE_FILE} is invalid`, { details: { issues: parsed.error.issues.slice(0, 5).map((i) => i.message) } });
+	const keyHex = await loadStateKey(root);
+	if (keyHex !== void 0 && !trustStateMacOk(parsed.data, keyHex)) throw new AxiomError("ERR_TRUST_STATE_CORRUPT", `${TRUST_STATE_FILE} failed its MAC (edited by hand, or ${TRUST_STATE_KEY_FILE} rotated)`, { details: { reason: parsed.data.mac === void 0 ? "NO_MAC" : "BAD_MAC" } });
 	return parsed.data;
 }
 /**
@@ -336,11 +670,16 @@ async function advanceTrustState(root, bundle) {
 	if (counter === void 0) return void 0;
 	const cur = await loadTrustState(root);
 	if (cur !== void 0 && cur.lastCounter >= counter) return cur;
-	const next = {
+	const keyHex = await ensureStateKey(root);
+	const unsigned = {
 		version: 1,
 		lastCounter: counter,
 		manifestDigest: bundle.manifestDigest
 	};
+	const next = {
+		...unsigned,
+		mac: trustStateMac(unsigned, keyHex)
+	};
 	await writeJsonAtomic(trustStatePath(root), next);
 	return next;
 }
@@ -616,18 +955,20 @@ async function profileFor(ctx, bundle, name, rootReal) {
 	});
 	return loadProfile(profileName, { searchDirs });
 }
-async function checkBundle(ctx, bundle, profileName, rootReal) {
+async function checkBundle(ctx, bundle, profileName, rootReal, signal) {
 	const opts = {
 		bundle,
 		profile: await profileFor(ctx, bundle, profileName, rootReal),
 		checks: bundle.manifest.checks,
 		...ctx.guards
 	};
+	if (signal !== void 0) opts.signal = signal;
 	if (rootReal !== void 0) {
 		opts.root = rootReal;
 		opts.casDir = path.join(rootReal, ".axiom", "cas");
 	}
 	const report = await runChecks(opts);
+	if (signal?.aborted) throw new AxiomError("ERR_TASK_CANCELLED", "check cancelled", { details: { manifestDigest: bundle.manifestDigest } });
 	if (rootReal !== void 0) {
 		await saveReport(rootReal, report);
 		ctx.seenRoots.add(rootReal);
@@ -674,7 +1015,9 @@ const ManifestVerifyOutput = z.object({
 			id: z.string(),
 			message: z.string()
 		})),
-		ok: z.boolean()
+		ok: z.boolean(),
+		/** `ERR_SIGNATURE_MISSING` (no signatures at all) or `ERR_SIGNATURE_INVALID`; absent when `ok`. */
+		code: z.enum(["ERR_SIGNATURE_MISSING", "ERR_SIGNATURE_INVALID"]).optional()
 	}).optional()
 });
 const RollbackOutput = z.object({
@@ -715,6 +1058,43 @@ const AxmParseOutput = z.object({
 	}))
 });
 const BundleOrRef = z.union([DigestRefSchema, LooseObject]).describe("A ManifestBundle object, or `sha256:<hex>` of a bundle stored under <root>/.axiom/manifests");
+const TaskDescriptorOutput = z.object({
+	taskId: z.string(),
+	tool: z.string(),
+	status: TaskStatusSchema,
+	pollIntervalMs: z.int().positive(),
+	ttlMs: z.int().positive(),
+	elapsedMs: z.int().nonnegative()
+});
+/** `axiom_task_get`: the descriptor plus, once terminal, the result or the error. */
+const TaskGetOutput = TaskDescriptorOutput.extend({
+	/** Present iff `status === "completed"`; for `axiom_check` tasks a `CheckReport`. */
+	result: CheckReportSchema.optional(),
+	/** Present iff `status` is `failed` or `cancelled`. */
+	error: TaskErrorSchema.optional()
+});
+const PlanHeaderShape = {
+	name: PlanSchema.shape.name,
+	intent: PlanSchema.shape.intent,
+	profile: PlanSchema.shape.profile.optional(),
+	capabilities: PlanSchema.shape.capabilities.optional(),
+	checks: PlanSchema.shape.checks.optional(),
+	counter: PlanSchema.shape.counter,
+	metadata: PlanSchema.shape.metadata.optional()
+};
+const PlanSessionOutput = z.object({
+	sessionId: z.string(),
+	artifacts: z.int().nonnegative(),
+	bytes: z.int().nonnegative(),
+	/** Remaining budget before `axiom_plan_add` refuses with `ERR_PLAN_SESSION_STATE`. */
+	limits: z.object({
+		maxArtifacts: z.int().positive(),
+		maxBytes: z.int().positive()
+	}),
+	ttlMs: z.int().positive()
+});
+const SessionIdArg = z.string().min(1).describe("sessionId returned by axiom_plan_begin");
+const TaskIdArg = z.string().min(1).describe("taskId returned by axiom_check_start");
 const TOOL_DEFS = [
 	defineTool({
 		name: "axiom_plan_validate",
@@ -775,31 +1155,9 @@ const TOOL_DEFS = [
 		annotations: ACT,
 		async handler(ctx, { plan, store, root }) {
 			guardPayloadSize("plan", plan);
-			const rootReal = root !== void 0 || store === "cas" ? (await resolveRoot(ctx.policy, root)).rootReal : void 0;
-			const opts = {
-				store: store ?? "inline",
-				emitters: EMITTERS
-			};
-			if (rootReal !== void 0) opts.root = rootReal;
-			const { bundle } = await compilePlan(plan, opts);
-			if (rootReal !== void 0) {
-				await saveManifest(rootReal, bundle);
-				ctx.seenRoots.add(rootReal);
-			}
-			ctx.log.info("compiled", {
-				manifestDigest: bundle.manifestDigest,
-				artifacts: bundle.manifest.artifacts.length
-			});
-			return bundle;
+			return compileToBundle(ctx, plan, store, root);
 		},
-		summarize: (b) => ({
-			manifestDigest: b.manifestDigest,
-			planDigest: b.manifest.planDigest,
-			name: b.manifest.name,
-			profile: b.manifest.profile,
-			artifacts: b.manifest.artifacts.length,
-			blobs: Object.keys(b.blobs).length
-		})
+		summarize: summarizeBundle
 	}),
 	defineTool({
 		name: "axiom_manifest_verify",
@@ -861,6 +1219,135 @@ const TOOL_DEFS = [
 		},
 		summarize: summarizeReport
 	}),
+	defineTool({
+		name: "axiom_check_start",
+		title: "Start policy checks as a background task",
+		description: "Same evaluation as axiom_check, but returned immediately as a task so long `guard.external` suites (up to 15 min per guard) outlive the client's per-call timeout. Poll axiom_task_get with the returned taskId every pollIntervalMs until status is completed|failed|cancelled; the CheckReport is in `result`. Finished tasks are pollable for ttlMs, then forgotten. Tasks live in this server process only (D-24 — tool-level tasks, not the io.modelcontextprotocol/tasks wire extension).",
+		inputSchema: {
+			bundle: LooseObject.describe("ManifestBundle"),
+			profile: ProfileArg,
+			root: RootArg
+		},
+		outputSchema: TaskDescriptorOutput,
+		annotations: READ,
+		async handler(ctx, { bundle, profile, root }) {
+			const parsed = parseBundle(bundle);
+			const rootReal = await optionalRoot(ctx, root);
+			const meta = {};
+			if (rootReal !== void 0) meta.root = rootReal;
+			const rec = ctx.tasks.start("axiom_check", (signal) => checkBundle(ctx, parsed, profile, rootReal, signal), meta);
+			ctx.log.info("task started", {
+				taskId: rec.taskId,
+				manifestDigest: parsed.manifestDigest,
+				root: rootReal
+			});
+			return ctx.tasks.describe(rec);
+		},
+		summarize: (o) => o
+	}),
+	defineTool({
+		name: "axiom_task_get",
+		title: "Poll a task",
+		description: "Status of a task created by axiom_check_start. While `working` only the descriptor is returned; once terminal, `result` (completed) or `error` (failed|cancelled) is attached. Unknown or expired taskId → ERR_TASK_NOT_FOUND.",
+		inputSchema: { taskId: TaskIdArg },
+		outputSchema: TaskGetOutput,
+		annotations: READ,
+		async handler(ctx, { taskId }) {
+			const rec = ctx.tasks.get(taskId);
+			const out = ctx.tasks.describe(rec);
+			if (rec.status === "completed") out.result = CheckReportSchema.parse(rec.result);
+			else if (rec.error !== void 0) out.error = rec.error;
+			return out;
+		},
+		summarize: (o) => ({
+			taskId: o.taskId,
+			status: o.status,
+			elapsedMs: o.elapsedMs,
+			pollIntervalMs: o.pollIntervalMs,
+			result: o.result === void 0 ? void 0 : summarizeReport(o.result),
+			error: o.error
+		})
+	}),
+	defineTool({
+		name: "axiom_task_cancel",
+		title: "Cancel a task",
+		description: "Abort a `working` task: every running guard process tree is killed and the task ends `cancelled` with error ERR_TASK_CANCELLED. Idempotent — a terminal task is returned unchanged.",
+		inputSchema: { taskId: TaskIdArg },
+		outputSchema: TaskDescriptorOutput,
+		annotations: ACT,
+		async handler(ctx, { taskId }) {
+			const rec = ctx.tasks.cancel(taskId);
+			ctx.log.info("task cancelled", {
+				taskId,
+				status: rec.status
+			});
+			return ctx.tasks.describe(rec);
+		},
+		summarize: (o) => o
+	}),
+	defineTool({
+		name: "axiom_plan_begin",
+		title: "Open a chunked plan session",
+		description: "Start assembling a Plan whose JSON would exceed the 4 MiB per-call cap: send the header here (everything except `artifacts`), append artifacts in chunks with axiom_plan_add, then axiom_plan_seal compiles the whole. The sealed bundle's manifestDigest is identical to a one-shot axiom_plan_compile of the same Plan. Sessions are in-memory, expire after 30 min idle, and hold at most 2000 artifacts / 64 MiB.",
+		inputSchema: PlanHeaderShape,
+		outputSchema: PlanSessionOutput,
+		annotations: ACT,
+		async handler(ctx, header) {
+			const s = ctx.planSessions.begin(header);
+			ctx.log.debug("plan session opened", {
+				sessionId: s.sessionId,
+				name: header.name
+			});
+			return describeSession(ctx.planSessions, s);
+		},
+		summarize: (o) => o
+	}),
+	defineTool({
+		name: "axiom_plan_add",
+		title: "Append artifacts to a plan session",
+		description: "Add a chunk of Plan artifacts (each ≤ 4 MiB call, inline content ≤ 256 KiB per artifact as in a Plan) to an open session. Paths must be unique across every chunk (ERR_INVALID_PLAN otherwise); a sealed or over-budget session is ERR_PLAN_SESSION_STATE.",
+		inputSchema: {
+			sessionId: SessionIdArg,
+			artifacts: z.array(LooseObject).min(1).describe("Plan artifacts, same shape as Plan.artifacts[]")
+		},
+		outputSchema: PlanSessionOutput,
+		annotations: ACT,
+		async handler(ctx, { sessionId, artifacts }) {
+			guardPayloadSize("artifacts", artifacts);
+			const parsed = z.array(PlanArtifactSchema).safeParse(artifacts);
+			if (!parsed.success) throw new AxiomError("ERR_INVALID_PLAN", "artifacts do not match PlanArtifactSchema", { details: { issues: parsed.error.issues.slice(0, 20).map((i) => ({
+				path: i.path.map(String).join("."),
+				message: i.message
+			})) } });
+			const bytes = Buffer.byteLength(JSON.stringify(artifacts), "utf8");
+			const s = ctx.planSessions.add(sessionId, parsed.data, bytes);
+			return describeSession(ctx.planSessions, s);
+		},
+		summarize: (o) => o
+	}),
+	defineTool({
+		name: "axiom_plan_seal",
+		title: "Seal a plan session and compile it",
+		description: "Assemble the session's header + every added artifact into one Plan and compile it exactly like axiom_plan_compile (same options, same digest). The session is consumed whether or not compilation succeeds. Bundles whose inline blobs exceed 4 MiB need `store: cas` (and therefore a root).",
+		inputSchema: {
+			sessionId: SessionIdArg,
+			store: z.enum(["inline", "cas"]).optional().describe("Blob transport; default inline"),
+			root: RootArg
+		},
+		outputSchema: ManifestBundleSchema,
+		annotations: ACT,
+		async handler(ctx, { sessionId, store, root }) {
+			const { plan, session } = ctx.planSessions.seal(sessionId);
+			const bundle = await compileToBundle(ctx, plan, store, root);
+			ctx.log.info("plan session sealed", {
+				sessionId,
+				artifacts: session.artifacts.length,
+				manifestDigest: bundle.manifestDigest
+			});
+			return bundle;
+		},
+		summarize: summarizeBundle
+	}),
 	defineTool({
 		name: "axiom_apply_dry_run",
 		title: "Dry-run apply (stage + diff, no writes to the tree)",
@@ -1074,6 +1561,47 @@ async function resolveBundleOrRef(ctx, v, label) {
 	}
 	return parseBundle(v);
 }
+/** Shared by `axiom_plan_compile` and `axiom_plan_seal` so both produce byte-identical bundles. */
+async function compileToBundle(ctx, plan, store, root) {
+	const rootReal = root !== void 0 || store === "cas" ? (await resolveRoot(ctx.policy, root)).rootReal : void 0;
+	const opts = {
+		store: store ?? "inline",
+		emitters: EMITTERS
+	};
+	if (rootReal !== void 0) opts.root = rootReal;
+	const { bundle } = await compilePlan(plan, opts);
+	if (rootReal !== void 0) {
+		await saveManifest(rootReal, bundle);
+		ctx.seenRoots.add(rootReal);
+	}
+	ctx.log.info("compiled", {
+		manifestDigest: bundle.manifestDigest,
+		artifacts: bundle.manifest.artifacts.length
+	});
+	return bundle;
+}
+function summarizeBundle(b) {
+	return {
+		manifestDigest: b.manifestDigest,
+		planDigest: b.manifest.planDigest,
+		name: b.manifest.name,
+		profile: b.manifest.profile,
+		artifacts: b.manifest.artifacts.length,
+		blobs: Object.keys(b.blobs).length
+	};
+}
+function describeSession(store, s) {
+	return {
+		sessionId: s.sessionId,
+		artifacts: s.artifacts.length,
+		bytes: s.bytes,
+		limits: {
+			maxArtifacts: store.maxArtifacts,
+			maxBytes: store.maxBytes
+		},
+		ttlMs: store.ttlMs
+	};
+}
 function summarizeReport(r) {
 	return {
 		manifestDigest: r.manifestDigest,
@@ -1178,20 +1706,25 @@ function createServer(policy, opts = {}) {
 	const ctx = {
 		policy,
 		log,
-		seenRoots: /* @__PURE__ */ new Set()
+		seenRoots: opts.seenRoots ?? /* @__PURE__ */ new Set(),
+		tasks: opts.tasks ?? new TaskStore(),
+		planSessions: opts.planSessions ?? new PlanSessionStore()
 	};
 	if (opts.guards !== void 0) ctx.guards = opts.guards;
 	const server = new McpServer({
 		name: SERVER_NAME,
 		version: SERVER_VERSION
-	}, { capabilities: {
-		tools: {},
-		resources: {}
-	} });
+	}, {
+		capabilities: {
+			tools: { listChanged: false },
+			resources: { listChanged: false }
+		},
+		cacheHints: CACHE_HINTS
+	});
 	for (const def of opts.tools ?? TOOL_DEFS) server.registerTool(def.name, {
 		title: def.title,
 		description: def.description,
-		inputSchema: def.inputSchema,
+		inputSchema: z.object(def.inputSchema),
 		outputSchema: def.outputSchema,
 		annotations: {
 			title: def.title,
@@ -1268,6 +1801,7 @@ function createServer(policy, opts = {}) {
 	log.info("server created", {
 		name: SERVER_NAME,
 		version: SERVER_VERSION,
+		era: opts.era ?? "legacy",
 		roots: [...policy.roots]
 	});
 	return server;
@@ -1289,6 +1823,6 @@ function renderToolsSpec() {
 	return `${JSON.stringify(buildToolsSpec(), null, 2)}\n`;
 }
 //#endregion
-export { BUNDLE_BYTES_MAX, LOG_LEVELS, SCHEMA_KINDS, SERVER_NAME, SERVER_VERSION, SUMMARY_LIST_MAX, TOOL_DEFS, buildToolsSpec, createLogger, createRootsPolicy, createServer, isLogLevel, isSameOrInside, isSchemaKind, jsonSchemaFor, renderToolsSpec, resolveRoot, riskClassOf, toStructuredError, toolByName };
+export { BUNDLE_BYTES_MAX, LOG_LEVELS, PLAN_SESSION_MAX_ARTIFACTS, PLAN_SESSION_MAX_BYTES, PLAN_SESSION_TTL_MS, PlanSessionStore, SCHEMA_KINDS, SERVER_NAME, SERVER_VERSION, SUMMARY_LIST_MAX, TASK_MAX_WORKING, TASK_POLL_INTERVAL_MS, TASK_STATUSES, TASK_TTL_MS, TOOL_DEFS, TaskStore, buildToolsSpec, createLogger, createRootsPolicy, createServer, isLogLevel, isSameOrInside, isSchemaKind, jsonSchemaFor, renderToolsSpec, resolveRoot, riskClassOf, toStructuredError, toolByName };
 
 //# sourceMappingURL=index.js.map