klyro 1.0.0 → 1.0.2

package/dist/mcp/config.d.ts

@@ -24,6 +24,16 @@ export interface McpServersConfig {
     /** Where each server entry came from (for doctor/diagnostics). */
     sources: Record<string, string>;
 }
+/** Upper bound for per-server timeouts — larger values are clamped, not rejected. */
+export declare const MAX_MCP_TIMEOUT_MS = 600000;
+/**
+ * Expand `${env:VAR}` references from `process.env`.
+ *
+ * A reference to an UNSET or empty variable expands to `''` (silent empty
+ * expansion): the entry is kept with the empty value rather than rejected,
+ * so callers always see the effective spec. Pure — exported for unit tests.
+ */
+export declare function expandEnv(value: string): string;
 /** Load + merge global and project MCP server specs. Invalid entries are skipped. */
 export declare function loadMcpServers(cwd: string): McpServersConfig;
 /** Servers eligible for connection (configured and not disabled). */

package/dist/mcp/config.js

@@ -25,7 +25,16 @@ export const McpServerSpecSchema = z.object({
     disabled: z.boolean().optional(),
     policy: McpServerPolicySchema.optional(),
 });
-function expandEnv(value) {
+/** Upper bound for per-server timeouts — larger values are clamped, not rejected. */
+export const MAX_MCP_TIMEOUT_MS = 600_000;
+/**
+ * Expand `${env:VAR}` references from `process.env`.
+ *
+ * A reference to an UNSET or empty variable expands to `''` (silent empty
+ * expansion): the entry is kept with the empty value rather than rejected,
+ * so callers always see the effective spec. Pure — exported for unit tests.
+ */
+export function expandEnv(value) {
     return value.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => process.env[name] ?? '');
 }
 function normalizeRaw(raw) {
@@ -55,10 +64,18 @@ export function loadMcpServers(cwd) {
     for (const [filePath, label] of [[globalPath, 'global'], [projectPath, 'project']]) {
         const raw = normalizeRaw(readJsonFile(filePath));
         for (const [name, specRaw] of Object.entries(raw)) {
+            // Empty server names can never produce a valid tool name — skip
+            // silently (shape stays `{servers, sources}`; registry reports
+            // empty TOOL names as errors at registration time).
+            if (name === '')
+                continue;
             const parsed = McpServerSpecSchema.safeParse(specRaw);
             if (!parsed.success)
                 continue;
             const spec = parsed.data;
+            if (spec.policy?.timeoutMs !== undefined && spec.policy.timeoutMs > MAX_MCP_TIMEOUT_MS) {
+                spec.policy.timeoutMs = MAX_MCP_TIMEOUT_MS;
+            }
             if (spec.env) {
                 const env = {};
                 for (const [k, v] of Object.entries(spec.env))

package/dist/mcp/registry.d.ts

@@ -1,21 +1,3 @@
-/**
- * P1 — MCP tool registration (r-11-17.md §3.1).
- *
- * Exposes MCP server tools through the {@link ToolRegistry} under
- * `mcp__<server>__<tool>` names. Security properties (non-negotiable):
- *
- *   1. Deny-by-default: `evaluateMcpPolicy` runs BEFORE any client I/O; a
- *      denied tool returns POLICY_DENIED without touching the subprocess.
- *   2. Redact-before-transcript: every success value AND error message passes
- *      through `redact()` before it can reach the model or trace.
- *   3. `requireApproval` servers add an ask-rule to the PolicyEngine so the
- *      runtime loop prompts before executing.
- *
- * Permission class: no code in src consumes `Tool.permission` (it is
- * write-only metadata today), so we pick the most restrictive class,
- * 'admin' — the same class as `spawn_agent`, since MCP tools execute
- * arbitrary external side effects (read/write/network) outside our control.
- */
 import { type McpClientLike } from './client.js';
 import { type McpServerSpec } from './config.js';
 import type { PolicyEngine } from '../policy/engine.js';
@@ -37,7 +19,16 @@ export interface RegisterMcpOpts {
     policy?: PolicyEngine;
     clientFactory?: (name: string, spec: McpServerSpec) => McpClientLike;
 }
-/** `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64. */
+/** Success values are redacted FIRST, then truncated to this many chars. */
+export declare const MCP_SUCCESS_MAX_CHARS = 12000;
+/**
+ * `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64.
+ *
+ * No `'server'`/`'tool'` fallbacks: an empty raw part (or one that
+ * sanitizes to empty) yields an empty segment, and registration skips that
+ * tool with an `empty-name` error instead of masking a misconfiguration
+ * behind a plausible-looking name.
+ */
 export declare function sanitizeMcpName(server: string, tool: string): string;
 export declare function registerMcpServers(cfg: {
     servers: Record<string, McpServerSpec>;
@@ -47,4 +38,17 @@ export declare function loadAndRegisterMcp(opts: {
     registry: ToolRegistry;
     policy?: PolicyEngine;
     clientFactory?: (name: string, spec: McpServerSpec) => McpClientLike;
+    /**
+     * Consent gate for project-sourced (`.mcp.json`) servers, which can
+     * auto-spawn processes. Global-source servers connect as before; a project
+     * server connects ONLY when this callback returns true. When the callback
+     * is ABSENT, project servers are never auto-connected — each surfaces as
+     * an error (`project server requires approval (skipped)`) so the skip is
+     * visible. Callers may compose this with `McpTrust` (see `./trust.js`) to
+     * remember approvals per spec hash.
+     */
+    approveProjectServer?: (info: {
+        name: string;
+        source: 'global' | 'project';
+    }) => Promise<boolean>;
 }): Promise<McpRegisterResult>;

package/dist/mcp/registry.js

@@ -15,7 +15,18 @@
  * write-only metadata today), so we pick the most restrictive class,
  * 'admin' — the same class as `spawn_agent`, since MCP tools execute
  * arbitrary external side effects (read/write/network) outside our control.
+ *
+ * Debug capture: when `KLYRO_MCP_DEBUG=1` is set, every MCP tool success
+ * AND error ALSO writes the UNREDACTED raw JSON payload (pre-redaction,
+ * may contain secrets — handle accordingly) to
+ * `<configDir>/tool-output/mcp-<server>-<ts>.json` (mode 0600) and notes
+ * the path on stderr. `<configDir>` is `$KLYRO_CONFIG_DIR` when set,
+ * otherwise `~/.klyro`. Default off: with the flag unset (or any value
+ * other than `1`) no file is written and behaviour is unchanged.
  */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { McpClient, McpError } from './client.js';
 import { loadMcpServers } from './config.js';
 import { evaluateMcpPolicy } from './policy.js';
@@ -26,20 +37,61 @@ import { defineTool } from '../tools/types.js';
 const MAX_NAME_LEN = 64;
 /** Server part is capped here; the tool part takes whatever remains. */
 const MAX_SERVER_PART = 20;
+/** Success values are redacted FIRST, then truncated to this many chars. */
+export const MCP_SUCCESS_MAX_CHARS = 12_000;
 function sanitizePart(s) {
     return s.replace(/[^A-Za-z0-9_]/g, '_');
 }
-/** `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64. */
+/**
+ * `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64.
+ *
+ * No `'server'`/`'tool'` fallbacks: an empty raw part (or one that
+ * sanitizes to empty) yields an empty segment, and registration skips that
+ * tool with an `empty-name` error instead of masking a misconfiguration
+ * behind a plausible-looking name.
+ */
 export function sanitizeMcpName(server, tool) {
-    const srv = sanitizePart(server).slice(0, MAX_SERVER_PART) || 'server';
+    const srv = sanitizePart(server).slice(0, MAX_SERVER_PART);
     const maxTool = Math.max(1, MAX_NAME_LEN - 'mcp__'.length - srv.length - '__'.length);
-    const tl = sanitizePart(tool).slice(0, maxTool) || 'tool';
+    const tl = sanitizePart(tool).slice(0, maxTool);
     return `mcp__${srv}__${tl}`;
 }
 function errMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
-async function executeMcpTool(spec, toolDef, client, input, ctx) {
+/** Debug-capture filename disambiguator when Date.now() collides. */
+let mcpDebugCounter = 0;
+/**
+ * `KLYRO_MCP_DEBUG=1` capture: write the UNREDACTED raw payload to
+ * `<configDir>/tool-output/mcp-<server>-<ts>.json` (mode 0600) + a stderr
+ * note. Best-effort and synchronous — never throws into the tool path.
+ */
+function captureMcpDebug(server, tool, payload) {
+    if (process.env.KLYRO_MCP_DEBUG !== '1')
+        return;
+    try {
+        const base = process.env.KLYRO_CONFIG_DIR ?? path.join(os.homedir() || process.cwd(), '.klyro');
+        const dir = path.join(base, 'tool-output');
+        fs.mkdirSync(dir, { recursive: true });
+        const safe = server.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 32) || 'server';
+        let file = path.join(dir, `mcp-${safe}-${Date.now()}.json`);
+        if (fs.existsSync(file)) {
+            mcpDebugCounter += 1;
+            file = path.join(dir, `mcp-${safe}-${Date.now()}-${mcpDebugCounter}.json`);
+        }
+        fs.writeFileSync(file, JSON.stringify({ server, tool, payload }, null, 2), { mode: 0o600 });
+        try {
+            process.stderr.write(`klyro: mcp debug captured ${server}/${tool} -> ${file}\n`);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    catch {
+        /* best-effort only */
+    }
+}
+async function executeMcpTool(server, spec, toolDef, client, input, ctx) {
     try {
         // (1) Deny-by-default — runs BEFORE any client I/O.
         const decision = evaluateMcpPolicy(spec.policy, toolDef.name);
@@ -58,16 +110,29 @@ async function executeMcpTool(spec, toolDef, client, input, ctx) {
             // (3) Typed server failures keep their code; everything else is TOOL_ERROR.
             // Redact BEFORE the message can reach the model/trace.
             if (err instanceof McpError) {
+                captureMcpDebug(server, toolDef.name, { code: err.code, message: err.message, details: err.details });
                 return { ok: false, error: { code: err.code, message: redact(err.message) } };
             }
+            captureMcpDebug(server, toolDef.name, { message: errMessage(err) });
             return { ok: false, error: { code: 'TOOL_ERROR', message: redact(errMessage(err)) } };
         }
         // (4) Server-reported error → TOOL_ERROR, redacted, bounded.
         if (res.isError) {
+            captureMcpDebug(server, toolDef.name, res.raw);
             return { ok: false, error: { code: 'TOOL_ERROR', message: redact(res.text).slice(0, 2000) } };
         }
-        // (5) Success — redact BEFORE the value reaches the model/trace.
-        return { ok: true, value: redact(res.text) };
+        // (5) Success — redact BEFORE the value reaches the model/trace, then
+        // truncate to a bounded size with a marker.
+        captureMcpDebug(server, toolDef.name, res.raw);
+        const redacted = redact(res.text);
+        if (redacted.length > MCP_SUCCESS_MAX_CHARS) {
+            return {
+                ok: true,
+                value: redacted.slice(0, MCP_SUCCESS_MAX_CHARS) +
+                    `\n... [truncated ${redacted.length - MCP_SUCCESS_MAX_CHARS} chars]`,
+            };
+        }
+        return { ok: true, value: redacted };
     }
     catch (err) {
         // Tool contract: never throw — always return a ToolResult.
@@ -81,6 +146,9 @@ export async function registerMcpServers(cfg, opts) {
     const errors = [];
     const skipped = [];
     const clients = [];
+    // Sanitized name → first raw (server, tool) that claimed it, used to tell
+    // sanitization-collisions apart from exact-duplicates (see below).
+    const claimed = new Map();
     for (const [server, spec] of Object.entries(cfg.servers)) {
         try {
             // enabledServers-style: skip disabled entries silently.
@@ -116,11 +184,35 @@ export async function registerMcpServers(cfg, opts) {
             }
             clients.push(client);
             for (const toolDef of tools) {
+                // Empty raw names (or names that sanitize to empty) are a
+                // misconfiguration — skip as an error, never with a fallback name.
+                if (!server || !toolDef.name || sanitizePart(server) === '' || sanitizePart(toolDef.name) === '') {
+                    errors.push({ server, message: `empty-name: server "${server}" tool "${toolDef.name}" sanitizes to an empty name part (skipped)` });
+                    continue;
+                }
                 const name = sanitizeMcpName(server, toolDef.name);
+                const prior = claimed.get(name);
+                if (prior) {
+                    if (prior.server === server && prior.tool === toolDef.name) {
+                        skipped.push({ name, reason: 'name-collision' });
+                        continue;
+                    }
+                    // Sanitization-collision: two DIFFERENT raw names map to the same
+                    // sanitized name. This is an error (not a silent skip) and names
+                    // both raw identities so the conflict is actionable.
+                    errors.push({
+                        server,
+                        message: `name collision: "${prior.server}/${prior.tool}" and "${server}/${toolDef.name}" both sanitize to "${name}" (skipped)`,
+                    });
+                    continue;
+                }
                 if (registry.get(name)) {
+                    // Exact-duplicate: the literal name already exists (e.g. a
+                    // builtin) — skip quietly, first registration wins.
                     skipped.push({ name, reason: 'name-collision' });
                     continue;
                 }
+                claimed.set(name, { server, tool: toolDef.name });
                 // Capture per-tool bindings for the closure.
                 const boundSpec = spec;
                 const boundDef = toolDef;
@@ -132,7 +224,7 @@ export async function registerMcpServers(cfg, opts) {
                     // 'admin': most restrictive class — MCP tools run arbitrary
                     // external side effects; nothing in src reads this field yet.
                     permission: 'admin',
-                    execute: (input, ctx) => executeMcpTool(boundSpec, boundDef, boundClient, input, ctx),
+                    execute: (input, ctx) => executeMcpTool(server, boundSpec, boundDef, boundClient, input, ctx),
                 });
                 registry.register(tool);
                 registered.push(name);
@@ -158,7 +250,34 @@ export async function registerMcpServers(cfg, opts) {
 export async function loadAndRegisterMcp(opts) {
     try {
         const cfg = loadMcpServers(opts.cwd);
-        return await registerMcpServers(cfg, opts);
+        const filtered = {};
+        const gateErrors = [];
+        for (const [name, spec] of Object.entries(cfg.servers)) {
+            if (cfg.sources[name] !== 'project') {
+                filtered[name] = spec;
+                continue;
+            }
+            if (!opts.approveProjectServer) {
+                gateErrors.push({ server: name, message: 'project server requires approval (skipped)' });
+                continue;
+            }
+            let ok = false;
+            try {
+                ok = await opts.approveProjectServer({ name, source: 'project' });
+            }
+            catch (err) {
+                gateErrors.push({ server: name, message: `project server approval error (skipped): ${errMessage(err)}` });
+                continue;
+            }
+            if (!ok) {
+                gateErrors.push({ server: name, message: 'project server not approved (skipped)' });
+                continue;
+            }
+            filtered[name] = spec;
+        }
+        const res = await registerMcpServers({ servers: filtered }, opts);
+        res.errors.unshift(...gateErrors);
+        return res;
     }
     catch (err) {
         // Never throws — surface load failures as error entries.

package/dist/mcp/schema.d.ts

@@ -2,10 +2,17 @@
  * P1 — JSON Schema → Zod converter for MCP tool input schemas.
  *
  * MCP servers describe inputs with JSON Schema; Klyro tools validate with
- * Zod. This converts the common subset (object/string/number/integer/
- * boolean/array/enum + required) and falls back to a permissive
- * `z.looseObject({}).catchall(z.unknown())`-style schema for anything else —
- * validation must never trust, but must also never crash on exotic schemas.
+ * Zod. Supported subset:
+ *
+ *   - `type`: `object` (with `properties` + `required`), `string`,
+ *     `number`, `integer`, `boolean`, `array` (with `items`)
+ *   - string `enum` (handled before `type`)
+ *   - a schema object WITHOUT a `type` but WITH a `properties` map is
+ *     treated as `type: 'object'` (many servers omit the type)
+ *
+ * Anything else — an empty/absent schema, non-object input, an unknown
+ * `type` — falls back to `z.unknown()` (accept anything, validate nothing).
+ * Validation must never trust, but must also never crash on exotic schemas.
  */
 import { z } from 'zod';
 export declare function jsonSchemaToZod(schema: unknown): z.ZodTypeAny;

package/dist/mcp/schema.js

@@ -2,22 +2,43 @@
  * P1 — JSON Schema → Zod converter for MCP tool input schemas.
  *
  * MCP servers describe inputs with JSON Schema; Klyro tools validate with
- * Zod. This converts the common subset (object/string/number/integer/
- * boolean/array/enum + required) and falls back to a permissive
- * `z.looseObject({}).catchall(z.unknown())`-style schema for anything else —
- * validation must never trust, but must also never crash on exotic schemas.
+ * Zod. Supported subset:
+ *
+ *   - `type`: `object` (with `properties` + `required`), `string`,
+ *     `number`, `integer`, `boolean`, `array` (with `items`)
+ *   - string `enum` (handled before `type`)
+ *   - a schema object WITHOUT a `type` but WITH a `properties` map is
+ *     treated as `type: 'object'` (many servers omit the type)
+ *
+ * Anything else — an empty/absent schema, non-object input, an unknown
+ * `type` — falls back to `z.unknown()` (accept anything, validate nothing).
+ * Validation must never trust, but must also never crash on exotic schemas.
  */
 import { z } from 'zod';
+function objectFrom(s) {
+    const props = s['properties'] ?? {};
+    const required = new Set(Array.isArray(s['required']) ? s['required'].filter((v) => typeof v === 'string') : []);
+    const shape = {};
+    for (const [k, v] of Object.entries(props)) {
+        const inner = jsonSchemaToZod(v);
+        shape[k] = required.has(k) ? inner : inner.optional();
+    }
+    return z.looseObject(shape);
+}
 export function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-        return z.looseObject({}).catchall(z.unknown());
+        return z.unknown();
     }
     const s = schema;
     const enumerated = Array.isArray(s['enum']) ? s['enum'] : undefined;
     if (enumerated && enumerated.length > 0 && enumerated.every((v) => typeof v === 'string')) {
         return z.enum(enumerated);
     }
-    switch (s['type']) {
+    const t = s['type'];
+    if (t === 'object' || (t === undefined && s['properties'] !== undefined && typeof s['properties'] === 'object' && s['properties'] !== null && !Array.isArray(s['properties']))) {
+        return objectFrom(s);
+    }
+    switch (t) {
         case 'string':
             return z.string();
         case 'number':
@@ -30,16 +51,6 @@ export function jsonSchemaToZod(schema) {
             const items = jsonSchemaToZod(s['items']);
             return z.array(items);
         }
-        case 'object': {
-            const props = s['properties'] ?? {};
-            const required = new Set(Array.isArray(s['required']) ? s['required'].filter((v) => typeof v === 'string') : []);
-            const shape = {};
-            for (const [k, v] of Object.entries(props)) {
-                const inner = jsonSchemaToZod(v);
-                shape[k] = required.has(k) ? inner : inner.optional();
-            }
-            return z.looseObject(shape);
-        }
         default:
             return z.unknown();
     }

package/dist/mcp/trust.d.ts

@@ -0,0 +1,20 @@
+import type { McpServerSpec } from './config.js';
+export interface McpTrustRecord {
+    sha256: string;
+    trustedAt: number;
+}
+export type McpTrustStore = Record<string, McpTrustRecord>;
+/** sha256 of the canonical (key-sorted) JSON encoding of a server spec. */
+export declare function hashSpec(spec: McpServerSpec): string;
+export declare function defaultMcpTrustStorePath(): string;
+export declare class McpTrust {
+    private readonly storePath;
+    private store;
+    constructor(storePath?: string);
+    private load;
+    private save;
+    /** True only when `name` was approved for exactly this spec hash. */
+    isTrusted(name: string, hash: string): boolean;
+    /** Record approval of `name` for exactly this spec hash. */
+    approve(name: string, hash: string): void;
+}

package/dist/mcp/trust.js

@@ -0,0 +1,74 @@
+/**
+ * P1 — MCP server-spec trust store (hash-based approval persistence).
+ *
+ * Companions the project-server consent gate in `registry.ts`: callers ask
+ * the user to approve a project-sourced server once via
+ * `approveProjectServer`, then persist `(name → sha256(spec))` here so later
+ * runs can auto-approve unchanged specs. Any spec change (new hash) requires
+ * fresh approval. Decisions persist in `~/.klyro/mcp-trust.json`.
+ *
+ * `registry.ts` does NOT use this class directly — callers compose it with
+ * the `approveProjectServer` callback. This module is intentionally
+ * side-effect free on import (file I/O happens in the constructor).
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Deterministic JSON: object keys sorted recursively, arrays preserved. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+    const entries = Object.entries(value)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+/** sha256 of the canonical (key-sorted) JSON encoding of a server spec. */
+export function hashSpec(spec) {
+    return crypto.createHash('sha256').update(stableStringify(spec), 'utf-8').digest('hex');
+}
+export function defaultMcpTrustStorePath() {
+    return path.join(os.homedir() || process.cwd(), '.klyro', 'mcp-trust.json');
+}
+export class McpTrust {
+    storePath;
+    store = {};
+    constructor(storePath = defaultMcpTrustStorePath()) {
+        this.storePath = storePath;
+        this.load();
+    }
+    load() {
+        try {
+            const raw = fs.readFileSync(this.storePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                this.store = parsed;
+            }
+        }
+        catch {
+            this.store = {};
+        }
+    }
+    save() {
+        try {
+            fs.mkdirSync(path.dirname(this.storePath), { recursive: true });
+            fs.writeFileSync(this.storePath, JSON.stringify(this.store, null, 2), 'utf-8');
+        }
+        catch {
+            /* best-effort — trust stays in memory for the session */
+        }
+    }
+    /** True only when `name` was approved for exactly this spec hash. */
+    isTrusted(name, hash) {
+        const rec = this.store[name];
+        return !!rec && rec.sha256 === hash;
+    }
+    /** Record approval of `name` for exactly this spec hash. */
+    approve(name, hash) {
+        this.store[name] = { sha256: hash, trustedAt: Date.now() };
+        this.save();
+    }
+}

package/dist/persistence/audit.d.ts

@@ -2,6 +2,11 @@
  * Audit log — append-only JSONL of runtime events. Same shape as the
  * future durable-task scheduler will read, so the data layout is
  * forward-compatible.
+ *
+ * Durability: every record is hash-chained. Each line carries `prevHash`
+ * (hex sha256 of the previous line's canonical JSON, 'GENESIS' for the
+ * first line) and `hash` (sha256 of the record-with-prevHash canonical
+ * JSON). `verifyAuditChain` recomputes the chain for `klyro audit`.
  */
 export type AuditEvent = {
     kind: 'session_created';
@@ -68,8 +73,31 @@ export type AuditEvent = {
     attempt: number;
     ts: number;
 };
+export declare const AUDIT_GENESIS = "GENESIS";
+export interface ChainedAuditRecord {
+    prevHash: string;
+    hash: string;
+    [key: string]: unknown;
+}
+/** Canonical JSON: object keys sorted recursively, so hashes are stable. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(s: string): string;
+/** Hash of a chained record excluding its own `hash` field. */
+export declare function hashAuditRecord(record: Record<string, unknown>): string;
 export declare class AuditLog {
     private readonly filePath;
+    /** Serializes chained appends so concurrent writes can't fork the chain. */
+    private chain;
     constructor(filePath: string);
     write(event: AuditEvent): Promise<void>;
+    private appendChained;
 }
+/**
+ * Recompute the hash chain of a session JSONL file.
+ * Sessions live at `<sessionsDir>/<sessionId>.jsonl` (see SessionStore).
+ */
+export declare function verifyAuditChain(sessionsDir: string, sessionId: string): Promise<{
+    ok: boolean;
+    events: number;
+    error?: string;
+}>;

package/dist/persistence/audit.js

@@ -2,14 +2,114 @@
  * Audit log — append-only JSONL of runtime events. Same shape as the
  * future durable-task scheduler will read, so the data layout is
  * forward-compatible.
+ *
+ * Durability: every record is hash-chained. Each line carries `prevHash`
+ * (hex sha256 of the previous line's canonical JSON, 'GENESIS' for the
+ * first line) and `hash` (sha256 of the record-with-prevHash canonical
+ * JSON). `verifyAuditChain` recomputes the chain for `klyro audit`.
  */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import { SessionStore } from './store.js';
+export const AUDIT_GENESIS = 'GENESIS';
+/** Canonical JSON: object keys sorted recursively, so hashes are stable. */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const rec = value;
+    const keys = Object.keys(rec).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(rec[k])}`).join(',')}}`;
+}
+export function sha256Hex(s) {
+    return crypto.createHash('sha256').update(s, 'utf-8').digest('hex');
+}
+/** Hash of a chained record excluding its own `hash` field. */
+export function hashAuditRecord(record) {
+    const { hash: _omit, ...body } = record;
+    void _omit;
+    return sha256Hex(canonicalJson(body));
+}
+async function readLastLine(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const lines = raw.split('\n').filter((l) => l.trim());
+        return lines.length > 0 ? lines[lines.length - 1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** prevHash for the next record: hash of the previous line, or GENESIS. */
+async function prevHashFor(filePath) {
+    const last = await readLastLine(filePath);
+    if (!last)
+        return AUDIT_GENESIS;
+    try {
+        const parsed = JSON.parse(last);
+        if (typeof parsed.hash === 'string' && parsed.hash)
+            return parsed.hash;
+        return sha256Hex(canonicalJson(parsed));
+    }
+    catch {
+        return sha256Hex(last);
+    }
+}
 export class AuditLog {
     filePath;
+    /** Serializes chained appends so concurrent writes can't fork the chain. */
+    chain = Promise.resolve();
     constructor(filePath) {
         this.filePath = filePath;
     }
     async write(event) {
-        await SessionStore.appendJsonl(this.filePath, event);
+        const task = this.chain.then(() => this.appendChained(event));
+        // Keep the chain alive across failures; the caller still sees its error.
+        this.chain = task.catch(() => undefined);
+        return task;
+    }
+    async appendChained(event) {
+        const prevHash = await prevHashFor(this.filePath);
+        const body = { ...event, prevHash };
+        const record = { ...body, prevHash, hash: sha256Hex(canonicalJson(body)) };
+        await SessionStore.appendJsonl(this.filePath, record);
+    }
+}
+/**
+ * Recompute the hash chain of a session JSONL file.
+ * Sessions live at `<sessionsDir>/<sessionId>.jsonl` (see SessionStore).
+ */
+export async function verifyAuditChain(sessionsDir, sessionId) {
+    const filePath = path.join(sessionsDir, `${sessionId}.jsonl`);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return { ok: false, events: 0, error: `audit log not found: ${filePath}` };
+    }
+    const lines = raw.split('\n').filter((l) => l.trim());
+    let expectedPrev = AUDIT_GENESIS;
+    let events = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return { ok: false, events, error: `line ${i + 1}: unparseable JSON` };
+        }
+        if (parsed.prevHash !== expectedPrev) {
+            return { ok: false, events, error: `line ${i + 1}: prevHash mismatch (chain fork or truncation)` };
+        }
+        if (typeof parsed.hash !== 'string' || parsed.hash !== hashAuditRecord(parsed)) {
+            return { ok: false, events, error: `line ${i + 1}: hash mismatch (tampered record)` };
+        }
+        expectedPrev = parsed.hash;
+        events++;
     }
+    return { ok: true, events };
 }