@cavelang/cli 0.27.3 → 0.29.0

package/dist/internal/loop/demo.js

@@ -0,0 +1,67 @@
+/**
+ * Runnable demo (spec §18): the multi-hop recovery pattern central to the
+ * active-reconstruction thesis (spec §11.3).
+ *
+ * Starting from the single cue `reject-valid-tokens` — the *symptom* — the
+ * loop must travel edges that only exist as inverse reads:
+ *
+ * 1. `reject-valid-tokens` ← CAUSED-BY — `token-expiry` (inverse CAUSE)
+ * 2. `token-expiry` ← PART-OF — `topic/auth-hardening` (inverse CONTAINS)
+ * 3. topic expansion → `auth/middleware`, and with it the bug, the broken
+ *    check and the fix.
+ *
+ * ```
+ * pnpm --filter @cavelang/cli/loop demo
+ * ```
+ */
+import { emitClaim } from '@cavelang/canonical';
+import { posix, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { memoryStoreOfText } from "./store.js";
+import { heuristicPolicy, reconstruct } from "./reconstruct.js";
+export const knowledge = `
+auth/middleware HAS bug: token-expiry #security #topic:auth-hardening
+token-expiry CAUSE reject-valid-tokens
+expiry-check USES \`<\`
+expiry-check NEEDS \`<=\`
+\`<=\` FIX token-expiry @auth.ts:42
+auth/middleware NEEDS test: boundary-cases @ 70%
+topic/auth-hardening CONTAINS token-expiry
+topic/auth-hardening CONTAINS auth/middleware
+topic/auth-hardening CONTAINS expiry-check
+deploy VIA github-actions
+unrelated/service USES postgres
+`;
+export const run = () => {
+    const store = memoryStoreOfText(knowledge);
+    const { claims, trace } = reconstruct(store, heuristicPolicy({ maxSteps: 12 }), ['reject-valid-tokens']);
+    const lines = [];
+    lines.push('cave-loop demo — multi-hop recovery from the symptom cue');
+    lines.push('');
+    lines.push('trace:');
+    for (const step of trace) {
+        const edges = step.edges
+            .map(edge => `${edge.rel ?? `${edge.verb}(un-named reverse)`} → ${edge.to}`)
+            .join(', ');
+        lines.push(`  ${step.step}. expand ${step.cue.entity} (score ${step.cue.score.toFixed(2)})` +
+            `${edges === '' ? '' : ` — ${edges}`}`);
+    }
+    lines.push('');
+    lines.push('reconstructed claims:');
+    for (const claim of claims) {
+        lines.push(`  ${emitClaim(claim)}`);
+    }
+    return { lines };
+};
+export const isDirectInvocation = (moduleUrl, entryPath, platform = process.platform) => {
+    if (entryPath === undefined)
+        return false;
+    const path = platform === 'win32' ? win32 : posix;
+    const modulePath = fileURLToPath(moduleUrl, { windows: platform === 'win32' });
+    return path.resolve(modulePath) === path.resolve(entryPath);
+};
+const invokedDirectly = isDirectInvocation(import.meta.url, process.argv[1]);
+if (invokedDirectly) {
+    console.log(run().lines.join('\n'));
+}
+//# sourceMappingURL=demo.js.map

package/dist/internal/loop/demo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../src/demo.ts"],"names":[],"mappings":"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"}

package/dist/internal/loop/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@cavelang/cli/loop` — cave-loop, the active-reconstruction agent layer over the
+ * CAVE graph (spec §18, non-normative).
+ *
+ * The agent layer is deliberately outside the language specification:
+ * reconstruction is a *policy* over the graph. This package provides the
+ * injectable `CaveStore` and `Policy` interfaces, an in-memory store and a
+ * SQLite adapter, a deterministic heuristic policy (the eval baseline), the
+ * LLM-driven policy over any shell-agent command template (spec §18)
+ * and a runnable multi-hop recovery demo.
+ */
+export * as Demo from './demo.ts';
+export type { CaveStore, Edge } from './store.ts';
+export { memoryStore, memoryStoreOfText } from './store.ts';
+export { sqliteStore } from './sqlite.ts';
+export { heuristicPolicy, reconstruct, reconstructAsync } from './reconstruct.ts';
+export type { AsyncPolicy, Cue, HeuristicOptions, Policy, Reconstruction, State, Step } from './reconstruct.ts';
+export { llmPolicy, parseSelection, selectPrompt, shellComplete, stopToken } from './llm.ts';
+export type { Complete, LlmOptions, ShellCompleteOptions } from './llm.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/internal/loop/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACjF,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC/G,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAC5F,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA"}

package/dist/internal/loop/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@cavelang/cli/loop` — cave-loop, the active-reconstruction agent layer over the
+ * CAVE graph (spec §18, non-normative).
+ *
+ * The agent layer is deliberately outside the language specification:
+ * reconstruction is a *policy* over the graph. This package provides the
+ * injectable `CaveStore` and `Policy` interfaces, an in-memory store and a
+ * SQLite adapter, a deterministic heuristic policy (the eval baseline), the
+ * LLM-driven policy over any shell-agent command template (spec §18)
+ * and a runnable multi-hop recovery demo.
+ */
+export * as Demo from "./demo.js";
+export { memoryStore, memoryStoreOfText } from "./store.js";
+export { sqliteStore } from "./sqlite.js";
+export { heuristicPolicy, reconstruct, reconstructAsync } from "./reconstruct.js";
+export { llmPolicy, parseSelection, selectPrompt, shellComplete, stopToken } from "./llm.js";
+//# sourceMappingURL=index.js.map

package/dist/internal/loop/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEjF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA"}

package/dist/internal/loop/llm.d.ts

@@ -0,0 +1,99 @@
+/**
+ * LLM-driven policy (spec §18) — the model makes the
+ * select/stop decisions; the loop stays unchanged.
+ *
+ * The deterministic heuristic in `reconstruct.ts` spends no tokens and is
+ * the eval baseline (`cave eval` runs it when no agent is given); this
+ * policy spends one completion per step and should earn its cost by
+ * reading the claims. Design decisions:
+ *
+ * - **One completion per step.** The sketch this file grew from asked the
+ *   model twice per step (select, then "are we done?"). Both decisions fit
+ *   one prompt: the model replies with the next cue to expand *or* `STOP`,
+ *   and the loop already treats an `undefined` selection as the stop
+ *   signal. `done` then only enforces the hard budgets, for free.
+ * - **Scoring stays local.** Models are better spent on select/stop than
+ *   on per-edge arithmetic; `score` is the same parent × confidence ×
+ *   decay the heuristic uses, so the scores shown in the prompt mean the
+ *   same thing in both policies.
+ * - **Claims render as canonical CAVE text** (`emitClaim`) — compact,
+ *   line-oriented, and exactly the notation the model knows from the spec
+ *   card and the MCP server instructions.
+ * - **Replies parse leniently, and degrade to the heuristic.** An answer
+ *   that names no frontier cue and never says stop expands the strongest
+ *   cue instead of silently ending the reconstruction — the budgets bound
+ *   the damage, and the result stays useful.
+ *
+ * The model itself stays out-of-band (spec §19.5): `shellComplete` adapts
+ * any shell-agent command template — the same `--agent` contract
+ * `cave ingest` and `cave eval` use — into a `Complete`, so no LLM SDK
+ * ever becomes a dependency of this package.
+ */
+import type { AsyncPolicy, Cue, State } from './reconstruct.ts';
+/** Minimal completion function the policy needs: prompt in, reply out. */
+export type Complete = (prompt: string) => Promise<string>;
+export type LlmOptions = {
+    /** What the reconstruction should answer — shown to the model each step. */
+    readonly query?: string;
+    /** Extra guidance appended to every step prompt. */
+    readonly instructions?: string;
+    /** Hard step budget — and completion budget, one per step (default 16). */
+    readonly maxSteps?: number;
+    /** Stop once this many claims are collected (default ∞). */
+    readonly maxClaims?: number;
+    /** Per-hop decay of the local edge score (default 0.8). */
+    readonly decay?: number;
+    /** Strongest frontier cues offered to the model per step (default 16). */
+    readonly maxCues?: number;
+};
+/** The reply that ends the reconstruction. */
+export declare const stopToken = "STOP";
+/**
+ * The single per-step prompt: the query, the claims collected so far as
+ * canonical CAVE lines, the strongest frontier cues with their scores, and
+ * the reply protocol. Exported for tests and for adapter authors who want
+ * the same rendering under a different transport.
+ */
+export declare const selectPrompt: (state: State, options?: LlmOptions) => string;
+/**
+ * Decides what the model asked for. In order:
+ *
+ * 1. the trimmed reply, its last non-empty line, or either with list
+ *    markers/quotes stripped, is exactly a frontier entity → that cue;
+ * 2. the reply's first word is the stop token (any case) → stop;
+ * 3. the earliest frontier entity mentioned anywhere in the reply → that
+ *    cue (ties at one position go to the longer name; occurrences inside
+ *    larger words don't count);
+ * 4. the stop token appears as a word anywhere → stop;
+ * 5. otherwise the strongest cue — an unparseable reply degrades to the
+ *    heuristic instead of silently ending the reconstruction.
+ */
+export declare const parseSelection: (reply: string, frontier: readonly Cue[]) => undefined | Cue;
+/**
+ * The LLM-driven `AsyncPolicy` (spec §18): the model reads the collected
+ * claims and the scored frontier, and answers with the next cue or
+ * `STOP`; budgets stay local and completions cost one per step. Errors
+ * from `complete` propagate — a failing agent must look like a failure,
+ * not like a decision to stop.
+ */
+export declare const llmPolicy: (complete: Complete, options?: LlmOptions) => AsyncPolicy;
+export type ShellCompleteOptions = {
+    /** Seconds before the agent process is killed (default 120). */
+    readonly timeoutSeconds?: number;
+    /** Working directory the agent runs in (default: the process cwd). */
+    readonly cwd?: string;
+};
+/**
+ * A `Complete` from a shell-agent command template — the same contract as
+ * `cave ingest --agent` and `cave eval --agent`: the prompt is piped to
+ * stdin and substituted for `{prompt-file}` (written to a temporary file,
+ * substituted shell-quoted) when the template names it; stdout is the
+ * model's reply; stderr passes through; a non-zero exit, spawn failure or
+ * timeout rejects.
+ *
+ * ```ts
+ * const policy = llmPolicy(shellComplete(`claude -p`), { query })
+ * ```
+ */
+export declare const shellComplete: (template: string, options?: ShellCompleteOptions) => Complete;
+//# sourceMappingURL=llm.d.ts.map

package/dist/internal/loop/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE/D,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAE1D,MAAM,MAAM,UAAU,GAAG;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,8CAA8C;AAC9C,eAAO,MAAM,SAAS,SAAS,CAAA;AAQ/B;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,EAAE,UAAS,UAAe,KAAG,MAiBrE,CAAA;AA4BD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,UAAU,SAAS,GAAG,EAAE,KAAG,SAAS,GAAG,GAiCpF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,QAAQ,EAAE,UAAS,UAAe,KAAG,WAkBxE,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,gEAAgE;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,UAAS,oBAAyB,KAAG,QAwDpF,CAAA"}

package/dist/internal/loop/llm.js

@@ -0,0 +1,231 @@
+/**
+ * LLM-driven policy (spec §18) — the model makes the
+ * select/stop decisions; the loop stays unchanged.
+ *
+ * The deterministic heuristic in `reconstruct.ts` spends no tokens and is
+ * the eval baseline (`cave eval` runs it when no agent is given); this
+ * policy spends one completion per step and should earn its cost by
+ * reading the claims. Design decisions:
+ *
+ * - **One completion per step.** The sketch this file grew from asked the
+ *   model twice per step (select, then "are we done?"). Both decisions fit
+ *   one prompt: the model replies with the next cue to expand *or* `STOP`,
+ *   and the loop already treats an `undefined` selection as the stop
+ *   signal. `done` then only enforces the hard budgets, for free.
+ * - **Scoring stays local.** Models are better spent on select/stop than
+ *   on per-edge arithmetic; `score` is the same parent × confidence ×
+ *   decay the heuristic uses, so the scores shown in the prompt mean the
+ *   same thing in both policies.
+ * - **Claims render as canonical CAVE text** (`emitClaim`) — compact,
+ *   line-oriented, and exactly the notation the model knows from the spec
+ *   card and the MCP server instructions.
+ * - **Replies parse leniently, and degrade to the heuristic.** An answer
+ *   that names no frontier cue and never says stop expands the strongest
+ *   cue instead of silently ending the reconstruction — the budgets bound
+ *   the damage, and the result stays useful.
+ *
+ * The model itself stays out-of-band (spec §19.5): `shellComplete` adapts
+ * any shell-agent command template — the same `--agent` contract
+ * `cave ingest` and `cave eval` use — into a `Complete`, so no LLM SDK
+ * ever becomes a dependency of this package.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { emitClaim } from '@cavelang/canonical';
+/** The reply that ends the reconstruction. */
+export const stopToken = 'STOP';
+const defaultMaxCues = 16;
+/** Strongest first; stable sort keeps FIFO order on ties, like the heuristic. */
+const strongestFirst = (frontier) => [...frontier].sort((a, b) => b.score - a.score);
+/**
+ * The single per-step prompt: the query, the claims collected so far as
+ * canonical CAVE lines, the strongest frontier cues with their scores, and
+ * the reply protocol. Exported for tests and for adapter authors who want
+ * the same rendering under a different transport.
+ */
+export const selectPrompt = (state, options = {}) => {
+    const cues = strongestFirst(state.frontier).slice(0, options.maxCues ?? defaultMaxCues);
+    return [
+        'You are driving memory reconstruction over a CAVE claim graph, one step at a time.',
+        ...options.query === undefined ? [] : ['', `Query: ${options.query}`],
+        '',
+        'Claims collected so far (canonical CAVE):',
+        ...state.collected.length === 0 ? ['(none yet)'] : state.collected.map(claim => emitClaim(claim)),
+        '',
+        'Frontier cues (entity @ score); expanding a cue collects its claims and its neighbors:',
+        ...cues.map(cue => `${cue.entity} @ ${cue.score.toFixed(2)}`),
+        ...options.instructions === undefined ? [] : ['', options.instructions],
+        '',
+        'Reply with exactly one line: the name of the single frontier cue to expand next, ' +
+            `or ${stopToken} when the collected claims already answer the query ` +
+            '(or nothing on the frontier would help).'
+    ].join('\n');
+};
+/** List markers, punctuation, quotes and backticks around a model's answer. */
+const stripped = (line) => line.trim()
+    .replace(/^[-*\d.)\s]+/, '')
+    .replace(/[.!,;:]+$/, '')
+    .replace(/^[`'"]+|[`'"]+$/g, '')
+    .trim();
+const wordChar = /[A-Za-z0-9_/-]/;
+/** First occurrence of `entity` in `reply` not embedded in a larger word. */
+const mentionAt = (reply, entity) => {
+    for (let from = 0;;) {
+        const index = reply.indexOf(entity, from);
+        if (index === -1) {
+            return -1;
+        }
+        const before = index === 0 ? undefined : reply[index - 1];
+        const after = index + entity.length >= reply.length ? undefined : reply[index + entity.length];
+        if ((before === undefined || !wordChar.test(before)) && (after === undefined || !wordChar.test(after))) {
+            return index;
+        }
+        from = index + 1;
+    }
+};
+/**
+ * Decides what the model asked for. In order:
+ *
+ * 1. the trimmed reply, its last non-empty line, or either with list
+ *    markers/quotes stripped, is exactly a frontier entity → that cue;
+ * 2. the reply's first word is the stop token (any case) → stop;
+ * 3. the earliest frontier entity mentioned anywhere in the reply → that
+ *    cue (ties at one position go to the longer name; occurrences inside
+ *    larger words don't count);
+ * 4. the stop token appears as a word anywhere → stop;
+ * 5. otherwise the strongest cue — an unparseable reply degrades to the
+ *    heuristic instead of silently ending the reconstruction.
+ */
+export const parseSelection = (reply, frontier) => {
+    if (frontier.length === 0) {
+        return undefined;
+    }
+    const byEntity = new Map(frontier.map(cue => [cue.entity, cue]));
+    const lastLine = reply.split('\n').map(line => line.trim()).filter(line => line !== '').at(-1) ?? '';
+    for (const candidate of [reply.trim(), lastLine, stripped(lastLine), stripped(reply)]) {
+        const exact = byEntity.get(candidate);
+        if (exact !== undefined) {
+            return exact;
+        }
+    }
+    if (new RegExp(`^${stopToken}\\b`, 'i').test(reply.trim())) {
+        return undefined;
+    }
+    let mentioned;
+    for (const cue of frontier) {
+        const at = mentionAt(reply, cue.entity);
+        if (at === -1) {
+            continue;
+        }
+        if (mentioned === undefined || at < mentioned.at ||
+            (at === mentioned.at && cue.entity.length > mentioned.cue.entity.length)) {
+            mentioned = { cue, at };
+        }
+    }
+    if (mentioned !== undefined) {
+        return mentioned.cue;
+    }
+    if (new RegExp(`\\b${stopToken}\\b`, 'i').test(reply)) {
+        return undefined;
+    }
+    return strongestFirst(frontier)[0];
+};
+/**
+ * The LLM-driven `AsyncPolicy` (spec §18): the model reads the collected
+ * claims and the scored frontier, and answers with the next cue or
+ * `STOP`; budgets stay local and completions cost one per step. Errors
+ * from `complete` propagate — a failing agent must look like a failure,
+ * not like a decision to stop.
+ */
+export const llmPolicy = (complete, options = {}) => {
+    const decay = options.decay ?? 0.8;
+    const maxSteps = options.maxSteps ?? 16;
+    const maxClaims = options.maxClaims ?? Number.POSITIVE_INFINITY;
+    return {
+        async select(state) {
+            if (state.frontier.length === 0) {
+                return undefined;
+            }
+            return parseSelection(await complete(selectPrompt(state, options)), state.frontier);
+        },
+        async score(edge, from) {
+            return from.score * edge.conf * decay;
+        },
+        async done(state) {
+            return state.steps >= maxSteps || state.collected.length >= maxClaims;
+        }
+    };
+};
+/**
+ * A `Complete` from a shell-agent command template — the same contract as
+ * `cave ingest --agent` and `cave eval --agent`: the prompt is piped to
+ * stdin and substituted for `{prompt-file}` (written to a temporary file,
+ * substituted shell-quoted) when the template names it; stdout is the
+ * model's reply; stderr passes through; a non-zero exit, spawn failure or
+ * timeout rejects.
+ *
+ * ```ts
+ * const policy = llmPolicy(shellComplete(`claude -p`), { query })
+ * ```
+ */
+export const shellComplete = (template, options = {}) => {
+    const timeoutSeconds = options.timeoutSeconds ?? 120;
+    return prompt => new Promise((resolvePromise, rejectPromise) => {
+        let dir;
+        let command = template;
+        if (template.includes('{prompt-file}')) {
+            dir = mkdtempSync(join(tmpdir(), 'cave-loop-'));
+            const file = join(dir, 'prompt.md');
+            writeFileSync(file, prompt);
+            // Quoted like ingest's substitutions — one argument, never re-parsed.
+            command = template.replaceAll('{prompt-file}', `'${file.replaceAll("'", `'\\''`)}'`);
+        }
+        let settled = false;
+        const settle = (finish) => {
+            if (!settled) {
+                settled = true;
+                if (dir !== undefined) {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                // Grandchildren of a killed shell can inherit the stdio pipes;
+                // dropping our end releases the event loop from waiting on them.
+                child.stdout.destroy();
+                child.stdin.destroy();
+                finish();
+            }
+        };
+        const child = spawn(command, {
+            shell: true,
+            timeout: timeoutSeconds * 1000,
+            stdio: ['pipe', 'pipe', 'inherit'],
+            ...options.cwd === undefined ? {} : { cwd: options.cwd }
+        });
+        let stdout = '';
+        child.stdout.on('data', chunk => {
+            stdout += String(chunk);
+        });
+        child.on('error', error => settle(() => rejectPromise(new Error(`agent failed: ${error.message}`))));
+        // A killed shell can leave grandchildren holding the stdio pipes open,
+        // so the signal path settles on `exit` — waiting for `close` would wait
+        // for processes the timeout was meant to cut loose.
+        child.on('exit', (_code, signal) => {
+            if (signal !== null) {
+                settle(() => rejectPromise(new Error(`agent killed by ${signal} after ${timeoutSeconds}s`)));
+            }
+        });
+        child.on('close', code => settle(() => {
+            if (code === 0) {
+                resolvePromise(stdout);
+            }
+            else {
+                rejectPromise(new Error(`agent exited with ${code}`));
+            }
+        }));
+        child.stdin.on('error', () => { });
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+};
+//# sourceMappingURL=llm.js.map

package/dist/internal/loop/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../src/llm.ts"],"names":[],"mappings":"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"}

package/dist/internal/loop/reconstruct.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The reconstruction loop (spec §18, §11.3) — Ji et al.'s Algorithm 1
+ * (*Memory is Reconstructed, Not Retrieved*, 2026) as a functional loop
+ * over the CAVE graph:
+ *
+ * - **Cues** are entities used as query anchors;
+ * - **route**: expanding a cue collects its claims (content) and pushes
+ *   scored neighbors — forward edges, named inverse edges, and topic
+ *   containment in both directions (ϕτ→e and ϕv→(c,g)) — onto the
+ *   frontier;
+ * - **select / stop** are policy decisions, injected — the loop itself is
+ *   deliberately outside the language (spec §18).
+ *
+ * The loop comes in two shapes sharing one step core: `reconstruct` for
+ * synchronous policies (the deterministic heuristic), `reconstructAsync`
+ * for policies that await a model between steps (`llmPolicy`).
+ */
+import { Claim } from '@cavelang/core';
+import type { CaveStore, Edge } from './store.ts';
+/** A scored frontier entry. */
+export type Cue = {
+    readonly entity: string;
+    readonly score: number;
+    readonly depth: number;
+};
+export type State = {
+    readonly frontier: readonly Cue[];
+    readonly visited: ReadonlySet<string>;
+    readonly collected: readonly Claim.t[];
+    readonly steps: number;
+};
+/** Injectable policy: select the next cue, score neighbors, decide to stop. */
+export type Policy = {
+    /** Next cue to expand, `undefined` to stop. Must pick from `state.frontier`. */
+    select(state: State): undefined | Cue;
+    /** Frontier score of a neighbor reached via `edge` from `from`. */
+    score(edge: Edge, from: Cue): number;
+    /** Stop condition, checked before every step. */
+    done(state: State): boolean;
+};
+/** Async twin of `Policy` for LLM-backed implementations (`llmPolicy`). */
+export type AsyncPolicy = {
+    select(state: State): Promise<undefined | Cue>;
+    score(edge: Edge, from: Cue): Promise<number>;
+    done(state: State): Promise<boolean>;
+};
+export type Step = {
+    readonly step: number;
+    readonly cue: Cue;
+    readonly edges: readonly Edge[];
+    readonly collected: number;
+};
+export type Reconstruction = {
+    /** Deduplicated claims, in discovery order. */
+    readonly claims: readonly Claim.t[];
+    readonly trace: readonly Step[];
+    readonly state: State;
+};
+/**
+ * Runs the loop from seed entities until the policy stops or the frontier
+ * empties. Pure given its inputs — same store + policy + seeds, same
+ * reconstruction.
+ */
+export declare const reconstruct: (store: CaveStore, policy: Policy, seeds: readonly string[]) => Reconstruction;
+/**
+ * The async twin of `reconstruct`, for policies that await a model between
+ * steps (spec §18): same algorithm, same trace, decisions awaited.
+ */
+export declare const reconstructAsync: (store: CaveStore, policy: AsyncPolicy, seeds: readonly string[]) => Promise<Reconstruction>;
+export type HeuristicOptions = {
+    /** Per-hop score decay (default 0.8). */
+    readonly decay?: number;
+    /** Hard step budget (default 16). */
+    readonly maxSteps?: number;
+    /** Cues scoring below this are never selected (default 0.05). */
+    readonly minScore?: number;
+    /** Stop once this many claims are collected (default ∞). */
+    readonly maxClaims?: number;
+};
+/**
+ * Deterministic heuristic policy for dependency-free testing (spec §18):
+ * greedy best-first by score (FIFO tiebreak), score = parent score ×
+ * edge confidence × decay, hard budgets for steps and claims. Also the
+ * eval baseline the LLM policy is measured against (spec §18).
+ */
+export declare const heuristicPolicy: (options?: HeuristicOptions) => Policy;
+//# sourceMappingURL=reconstruct.d.ts.map

package/dist/internal/loop/reconstruct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconstruct.d.ts","sourceRoot":"","sources":["../../src/reconstruct.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,EAAO,MAAM,gBAAgB,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEjD,+BAA+B;AAC/B,MAAM,MAAM,GAAG,GAAG;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,EAAE,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,KAAK,CAAC,CAAC,EAAE,CAAA;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,+EAA+E;AAC/E,MAAM,MAAM,MAAM,GAAG;IACnB,gFAAgF;IAChF,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,GAAG,CAAA;IACrC,mEAAmE;IACnE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,GAAG,MAAM,CAAA;IACpC,iDAAiD;IACjD,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;CAC5B,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,GAAG,GAAG,CAAC,CAAA;IAC9C,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7C,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IACjB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,CAAC,CAAC,EAAE,CAAA;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACtB,CAAA;AA0FD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,SAAS,EAAE,QAAQ,MAAM,EAAE,OAAO,SAAS,MAAM,EAAE,KAAG,cAWxF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,SAAS,EAChB,QAAQ,WAAW,EACnB,OAAO,SAAS,MAAM,EAAE,KACvB,OAAO,CAAC,cAAc,CAexB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,UAAS,gBAAqB,KAAG,MAyBhE,CAAA"}