@caupulican/pi-adaptative 0.80.96 → 0.80.98

package/dist/core/delegation/session-worker-result.js

@@ -1,12 +1,29 @@
 import { cloneWorkerResultForStorage, isWorkerResult } from "./worker-result.js";
 export const WORKER_RESULT_CUSTOM_TYPE = "worker_result";
-export function appendWorkerResultSnapshot(sessionManager, result) {
+export function appendWorkerResultSnapshot(sessionManager, result, request) {
     const payload = {
         version: 1,
         result: cloneWorkerResultForStorage(result),
+        ...(request ? { request: structuredClone(request) } : {}),
     };
     return sessionManager.appendCustomEntry(WORKER_RESULT_CUSTOM_TYPE, payload);
 }
+/** Requests persisted alongside results (absent for pre-G2 entries). */
+export function getWorkerRequestSnapshots(entries) {
+    const requests = [];
+    for (const entry of entries) {
+        if (entry.type !== "custom" || entry.customType !== WORKER_RESULT_CUSTOM_TYPE)
+            continue;
+        const payload = entry.data;
+        if (!isPlainRecord(payload) || payload.version !== 1)
+            continue;
+        const request = payload.request;
+        if (isPlainRecord(request) && typeof request.id === "string") {
+            requests.push(structuredClone(request));
+        }
+    }
+    return requests;
+}
 function isPlainRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;

package/dist/core/delegation/session-worker-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-worker-result.js","sourceRoot":"","sources":["../../../src/core/delegation/session-worker-result.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEjF,MAAM,CAAC,MAAM,yBAAyB,GAAG,eAAe,CAAC;AAOzD,MAAM,UAAU,0BAA0B,CACzC,cAAyD,EACzD,MAAoB,EACX;IACT,MAAM,OAAO,GAAgC;QAC5C,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,2BAA2B,CAAC,MAAM,CAAC;KAC3C,CAAC;IACF,OAAO,cAAc,CAAC,iBAAiB,CAAC,yBAAyB,EAAE,OAAO,CAAC,CAAC;AAAA,CAC5E;AAED,SAAS,aAAa,CAAC,KAAc,EAAoC;IACxE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9E,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAAA,CAC5D;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAgC,EAAkB;IAC1F,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,KAAK,yBAAyB,EAAE,CAAC;YAC/E,SAAS;QACV,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC;QAC3B,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,IAAI,OAAO,CAAC,OAAO,KAAK,CAAC;YAAE,SAAS;QACpC,IAAI,CAAC,CAAC,QAAQ,IAAI,OAAO,CAAC;YAAE,SAAS;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAAC;QACnD,CAAC;IACF,CAAC;IAED,OAAO,OAAO,CAAC;AAAA,CACf","sourcesContent":["import type { WorkerResult } from \"../autonomy/contracts.ts\";\nimport type { SessionEntry, SessionManager } from \"../session-manager.ts\";\nimport { cloneWorkerResultForStorage, isWorkerResult } from \"./worker-result.ts\";\n\nexport const WORKER_RESULT_CUSTOM_TYPE = \"worker_result\";\n\nexport interface WorkerResultSnapshotPayload {\n\tversion: 1;\n\tresult: WorkerResult;\n}\n\nexport function appendWorkerResultSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tresult: WorkerResult,\n): string {\n\tconst payload: WorkerResultSnapshotPayload = {\n\t\tversion: 1,\n\t\tresult: cloneWorkerResultForStorage(result),\n\t};\n\treturn sessionManager.appendCustomEntry(WORKER_RESULT_CUSTOM_TYPE, payload);\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nexport function getWorkerResultSnapshots(entries: readonly SessionEntry[]): WorkerResult[] {\n\tconst results: WorkerResult[] = [];\n\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== WORKER_RESULT_CUSTOM_TYPE) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst payload = entry.data;\n\t\tif (!isPlainRecord(payload)) continue;\n\t\tif (payload.version !== 1) continue;\n\t\tif (!(\"result\" in payload)) continue;\n\t\tconst result = payload.result;\n\t\tif (isWorkerResult(result)) {\n\t\t\tresults.push(cloneWorkerResultForStorage(result));\n\t\t}\n\t}\n\n\treturn results;\n}\n"]}
+{"version":3,"file":"session-worker-result.js","sourceRoot":"","sources":["../../../src/core/delegation/session-worker-result.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEjF,MAAM,CAAC,MAAM,yBAAyB,GAAG,eAAe,CAAC;AAWzD,MAAM,UAAU,0BAA0B,CACzC,cAAyD,EACzD,MAAoB,EACpB,OAAuB,EACd;IACT,MAAM,OAAO,GAAgC;QAC5C,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,2BAA2B,CAAC,MAAM,CAAC;QAC3C,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzD,CAAC;IACF,OAAO,cAAc,CAAC,iBAAiB,CAAC,yBAAyB,EAAE,OAAO,CAAC,CAAC;AAAA,CAC5E;AAED,wEAAwE;AACxE,MAAM,UAAU,yBAAyB,CAAC,OAAgC,EAAmB;IAC5F,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,KAAK,yBAAyB;YAAE,SAAS;QACxF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC;QAC3B,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,KAAK,CAAC;YAAE,SAAS;QAC/D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC9D,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAA6B,CAAC,CAAC;QACrE,CAAC;IACF,CAAC;IACD,OAAO,QAAQ,CAAC;AAAA,CAChB;AAED,SAAS,aAAa,CAAC,KAAc,EAAoC;IACxE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9E,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAAA,CAC5D;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAgC,EAAkB;IAC1F,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,KAAK,yBAAyB,EAAE,CAAC;YAC/E,SAAS;QACV,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC;QAC3B,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,IAAI,OAAO,CAAC,OAAO,KAAK,CAAC;YAAE,SAAS;QACpC,IAAI,CAAC,CAAC,QAAQ,IAAI,OAAO,CAAC;YAAE,SAAS;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAAC;QACnD,CAAC;IACF,CAAC;IAED,OAAO,OAAO,CAAC;AAAA,CACf","sourcesContent":["import type { WorkerRequest, WorkerResult } from \"../autonomy/contracts.ts\";\nimport type { SessionEntry, SessionManager } from \"../session-manager.ts\";\nimport { cloneWorkerResultForStorage, isWorkerResult } from \"./worker-result.ts\";\n\nexport const WORKER_RESULT_CUSTOM_TYPE = \"worker_result\";\n\nexport interface WorkerResultSnapshotPayload {\n\tversion: 1;\n\tresult: WorkerResult;\n\t/** The originating request (G2): persisted so a result is auditable against exactly what was\n\t * asked — instructions, route, and the capability envelope that bounded it. Optional for\n\t * backward compatibility with pre-G2 entries. */\n\trequest?: WorkerRequest;\n}\n\nexport function appendWorkerResultSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tresult: WorkerResult,\n\trequest?: WorkerRequest,\n): string {\n\tconst payload: WorkerResultSnapshotPayload = {\n\t\tversion: 1,\n\t\tresult: cloneWorkerResultForStorage(result),\n\t\t...(request ? { request: structuredClone(request) } : {}),\n\t};\n\treturn sessionManager.appendCustomEntry(WORKER_RESULT_CUSTOM_TYPE, payload);\n}\n\n/** Requests persisted alongside results (absent for pre-G2 entries). */\nexport function getWorkerRequestSnapshots(entries: readonly SessionEntry[]): WorkerRequest[] {\n\tconst requests: WorkerRequest[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== WORKER_RESULT_CUSTOM_TYPE) continue;\n\t\tconst payload = entry.data;\n\t\tif (!isPlainRecord(payload) || payload.version !== 1) continue;\n\t\tconst request = payload.request;\n\t\tif (isPlainRecord(request) && typeof request.id === \"string\") {\n\t\t\trequests.push(structuredClone(request) as unknown as WorkerRequest);\n\t\t}\n\t}\n\treturn requests;\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nexport function getWorkerResultSnapshots(entries: readonly SessionEntry[]): WorkerResult[] {\n\tconst results: WorkerResult[] = [];\n\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== WORKER_RESULT_CUSTOM_TYPE) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst payload = entry.data;\n\t\tif (!isPlainRecord(payload)) continue;\n\t\tif (payload.version !== 1) continue;\n\t\tif (!(\"result\" in payload)) continue;\n\t\tconst result = payload.result;\n\t\tif (isWorkerResult(result)) {\n\t\t\tresults.push(cloneWorkerResultForStorage(result));\n\t\t}\n\t}\n\n\treturn results;\n}\n"]}

package/dist/core/learning/observation-store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,
+ * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same
+ * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.
+ */
+export declare function observationKey(layer: string, summary: string): string;
+export declare class ObservationStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    static forAgentDir(agentDir: string): ObservationStore;
+    private load;
+    private save;
+    /** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */
+    private evict;
+    /** Record one more observation of `key` and return the new (capped) count. */
+    increment(key: string, at?: string): number;
+    /** Current observation count for `key` (0 if never observed). */
+    get(key: string): number;
+}
+//# sourceMappingURL=observation-store.d.ts.map

package/dist/core/learning/observation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-store.d.ts","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YAAY,QAAQ,EAAE,MAAM,EAE3B;IAED,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAErD;IAED,OAAO,CAAC,IAAI;IAoCZ,OAAO,CAAC,IAAI;IAKZ,6FAA6F;IAC7F,OAAO,CAAC,KAAK;IAab,8EAA8E;IAC9E,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1C;IAED,iEAAiE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvB;CACD","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\n\tconstructor(filePath: string) {\n\t\tthis.filePath = filePath;\n\t}\n\n\tstatic forAgentDir(agentDir: string): ObservationStore {\n\t\treturn new ObservationStore(join(agentDir, \"state\", \"learning-observations.json\"));\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\tmkdirSync(dirname(this.filePath), { recursive: true });\n\t\twriteFileSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`, \"utf-8\");\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/** Record one more observation of `key` and return the new (capped) count. */\n\tincrement(key: string, at?: string): number {\n\t\tconst file = this.load();\n\t\tconst now = at ?? new Date().toISOString();\n\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\tfile.observations[key] = { count, lastAt: now };\n\t\tthis.evict(file);\n\t\tthis.save(file);\n\t\treturn count;\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}

package/dist/core/learning/observation-store.js

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a
+ * durable change only once it has been *observed* enough times; a single reflection pass sees a
+ * lesson once, so without persistence every proposal would look brand-new and never accumulate the
+ * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by
+ * its durable layer + normalized summary) has been proposed across passes and sessions.
+ *
+ * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under
+ * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.
+ */
+/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */
+const MAX_COUNT = 100;
+/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */
+const MAX_KEYS = 500;
+/**
+ * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,
+ * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same
+ * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.
+ */
+export function observationKey(layer, summary) {
+    const normalized = summary.toLowerCase().replace(/\s+/g, " ").trim();
+    return createHash("sha256").update(`${layer}\n${normalized}`).digest("hex").slice(0, 24);
+}
+export class ObservationStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    static forAgentDir(agentDir) {
+        return new ObservationStore(join(agentDir, "state", "learning-observations.json"));
+    }
+    load() {
+        try {
+            if (!existsSync(this.filePath))
+                return { version: 1, observations: {} };
+            const parsed = JSON.parse(readFileSync(this.filePath, "utf-8"));
+            if (parsed &&
+                parsed.version === 1 &&
+                parsed.observations &&
+                typeof parsed.observations === "object" &&
+                !Array.isArray(parsed.observations)) {
+                // Sanitize per-entry so a partially-mangled file still yields a usable store rather than
+                // leaking NaN/undefined counts into the gate.
+                const clean = { version: 1, observations: {} };
+                for (const [key, value] of Object.entries(parsed.observations)) {
+                    if (value &&
+                        typeof value === "object" &&
+                        typeof value.count === "number" &&
+                        Number.isFinite(value.count) &&
+                        typeof value.lastAt === "string") {
+                        clean.observations[key] = {
+                            count: Math.min(Math.max(0, Math.floor(value.count)), MAX_COUNT),
+                            lastAt: value.lastAt,
+                        };
+                    }
+                }
+                return clean;
+            }
+        }
+        catch {
+            // Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.
+        }
+        return { version: 1, observations: {} };
+    }
+    save(file) {
+        mkdirSync(dirname(this.filePath), { recursive: true });
+        writeFileSync(this.filePath, `${JSON.stringify(file, null, "\t")}\n`, "utf-8");
+    }
+    /** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */
+    evict(file) {
+        const keys = Object.keys(file.observations);
+        if (keys.length <= MAX_KEYS)
+            return;
+        keys.sort((a, b) => {
+            const la = file.observations[a].lastAt;
+            const lb = file.observations[b].lastAt;
+            return la < lb ? -1 : la > lb ? 1 : 0;
+        });
+        for (const key of keys.slice(0, keys.length - MAX_KEYS)) {
+            delete file.observations[key];
+        }
+    }
+    /** Record one more observation of `key` and return the new (capped) count. */
+    increment(key, at) {
+        const file = this.load();
+        const now = at ?? new Date().toISOString();
+        const count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);
+        file.observations[key] = { count, lastAt: now };
+        this.evict(file);
+        this.save(file);
+        return count;
+    }
+    /** Current observation count for `key` (0 if never observed). */
+    get(key) {
+        return this.load().observations[key]?.count ?? 0;
+    }
+}
+//# sourceMappingURL=observation-store.js.map

package/dist/core/learning/observation-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-store.js","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\n\tconstructor(filePath: string) {\n\t\tthis.filePath = filePath;\n\t}\n\n\tstatic forAgentDir(agentDir: string): ObservationStore {\n\t\treturn new ObservationStore(join(agentDir, \"state\", \"learning-observations.json\"));\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\tmkdirSync(dirname(this.filePath), { recursive: true });\n\t\twriteFileSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`, \"utf-8\");\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/** Record one more observation of `key` and return the new (capped) count. */\n\tincrement(key: string, at?: string): number {\n\t\tconst file = this.load();\n\t\tconst now = at ?? new Date().toISOString();\n\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\tfile.observations[key] = { count, lastAt: now };\n\t\tthis.evict(file);\n\t\tthis.save(file);\n\t\treturn count;\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}

package/dist/core/model-router/executor-route.d.ts

@@ -0,0 +1,8 @@
+import { type ToolkitScript } from "../toolkit/script-registry.ts";
+export interface ExecutorRouteVerdict {
+    execute: boolean;
+    scriptName?: string;
+    reason: string;
+}
+export declare function classifyExecutorTurn(prompt: string, scripts: readonly ToolkitScript[]): ExecutorRouteVerdict;
+//# sourceMappingURL=executor-route.d.ts.map

package/dist/core/model-router/executor-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor-route.d.ts","sourceRoot":"","sources":["../../../src/core/model-router/executor-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAmBvF,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,oBAAoB,CAc5G","sourcesContent":["import { matchToolkitScript, type ToolkitScript } from \"../toolkit/script-registry.ts\";\n\n/**\n * Executor-lane classifier (G16): decides when a USER turn is a direct toolkit command that a\n * small local executor model can own end-to-end (\"restore db staging\", \"run the status report\"),\n * instead of spending the frontier model on a one-tool reflex.\n *\n * Deliberately conservative — ALL of:\n *   - the deterministic Level-0 matcher scores an EXACT/direct hit (the same margin rule that\n *     gates tool-side matching; ambiguity never routes to the executor, it stays with the big\n *     model + reflex brain), and\n *   - the prompt LOOKS like a command: single line, short, no code fences/paths of substance.\n * Everything else falls through to normal routing. The executor model itself is gated by the\n * caller (configured + resolved + tool-call fitness), and failures escalate via the existing\n * cheap-tier escalation path.\n */\n\nconst EXECUTOR_MAX_PROMPT_CHARS = 120;\n\nexport interface ExecutorRouteVerdict {\n\texecute: boolean;\n\tscriptName?: string;\n\treason: string;\n}\n\nexport function classifyExecutorTurn(prompt: string, scripts: readonly ToolkitScript[]): ExecutorRouteVerdict {\n\tconst trimmed = prompt.trim();\n\tif (scripts.length === 0) return { execute: false, reason: \"no_toolkit_scripts\" };\n\tif (trimmed.length === 0 || trimmed.length > EXECUTOR_MAX_PROMPT_CHARS) {\n\t\treturn { execute: false, reason: \"not_command_shaped\" };\n\t}\n\tif (trimmed.includes(\"\\n\") || trimmed.includes(\"```\")) {\n\t\treturn { execute: false, reason: \"not_command_shaped\" };\n\t}\n\tconst match = matchToolkitScript(trimmed, scripts);\n\tif (match.kind !== \"exact\") {\n\t\treturn { execute: false, reason: match.kind === \"ambiguous\" ? \"ambiguous_match\" : \"no_match\" };\n\t}\n\treturn { execute: true, scriptName: match.script.name, reason: \"level0_direct_hit\" };\n}\n"]}

package/dist/core/model-router/executor-route.js

@@ -0,0 +1,33 @@
+import { matchToolkitScript } from "../toolkit/script-registry.js";
+/**
+ * Executor-lane classifier (G16): decides when a USER turn is a direct toolkit command that a
+ * small local executor model can own end-to-end ("restore db staging", "run the status report"),
+ * instead of spending the frontier model on a one-tool reflex.
+ *
+ * Deliberately conservative — ALL of:
+ *   - the deterministic Level-0 matcher scores an EXACT/direct hit (the same margin rule that
+ *     gates tool-side matching; ambiguity never routes to the executor, it stays with the big
+ *     model + reflex brain), and
+ *   - the prompt LOOKS like a command: single line, short, no code fences/paths of substance.
+ * Everything else falls through to normal routing. The executor model itself is gated by the
+ * caller (configured + resolved + tool-call fitness), and failures escalate via the existing
+ * cheap-tier escalation path.
+ */
+const EXECUTOR_MAX_PROMPT_CHARS = 120;
+export function classifyExecutorTurn(prompt, scripts) {
+    const trimmed = prompt.trim();
+    if (scripts.length === 0)
+        return { execute: false, reason: "no_toolkit_scripts" };
+    if (trimmed.length === 0 || trimmed.length > EXECUTOR_MAX_PROMPT_CHARS) {
+        return { execute: false, reason: "not_command_shaped" };
+    }
+    if (trimmed.includes("\n") || trimmed.includes("```")) {
+        return { execute: false, reason: "not_command_shaped" };
+    }
+    const match = matchToolkitScript(trimmed, scripts);
+    if (match.kind !== "exact") {
+        return { execute: false, reason: match.kind === "ambiguous" ? "ambiguous_match" : "no_match" };
+    }
+    return { execute: true, scriptName: match.script.name, reason: "level0_direct_hit" };
+}
+//# sourceMappingURL=executor-route.js.map

package/dist/core/model-router/executor-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor-route.js","sourceRoot":"","sources":["../../../src/core/model-router/executor-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAsB,MAAM,+BAA+B,CAAC;AAEvF;;;;;;;;;;;;;GAaG;AAEH,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAQtC,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,OAAiC,EAAwB;IAC7G,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAClF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,yBAAyB,EAAE,CAAC;QACxE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IAChG,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;AAAA,CACrF","sourcesContent":["import { matchToolkitScript, type ToolkitScript } from \"../toolkit/script-registry.ts\";\n\n/**\n * Executor-lane classifier (G16): decides when a USER turn is a direct toolkit command that a\n * small local executor model can own end-to-end (\"restore db staging\", \"run the status report\"),\n * instead of spending the frontier model on a one-tool reflex.\n *\n * Deliberately conservative — ALL of:\n *   - the deterministic Level-0 matcher scores an EXACT/direct hit (the same margin rule that\n *     gates tool-side matching; ambiguity never routes to the executor, it stays with the big\n *     model + reflex brain), and\n *   - the prompt LOOKS like a command: single line, short, no code fences/paths of substance.\n * Everything else falls through to normal routing. The executor model itself is gated by the\n * caller (configured + resolved + tool-call fitness), and failures escalate via the existing\n * cheap-tier escalation path.\n */\n\nconst EXECUTOR_MAX_PROMPT_CHARS = 120;\n\nexport interface ExecutorRouteVerdict {\n\texecute: boolean;\n\tscriptName?: string;\n\treason: string;\n}\n\nexport function classifyExecutorTurn(prompt: string, scripts: readonly ToolkitScript[]): ExecutorRouteVerdict {\n\tconst trimmed = prompt.trim();\n\tif (scripts.length === 0) return { execute: false, reason: \"no_toolkit_scripts\" };\n\tif (trimmed.length === 0 || trimmed.length > EXECUTOR_MAX_PROMPT_CHARS) {\n\t\treturn { execute: false, reason: \"not_command_shaped\" };\n\t}\n\tif (trimmed.includes(\"\\n\") || trimmed.includes(\"```\")) {\n\t\treturn { execute: false, reason: \"not_command_shaped\" };\n\t}\n\tconst match = matchToolkitScript(trimmed, scripts);\n\tif (match.kind !== \"exact\") {\n\t\treturn { execute: false, reason: match.kind === \"ambiguous\" ? \"ambiguous_match\" : \"no_match\" };\n\t}\n\treturn { execute: true, scriptName: match.script.name, reason: \"level0_direct_hit\" };\n}\n"]}

package/dist/core/model-router/tool-escalation.d.ts

@@ -3,5 +3,7 @@ export declare function shouldEscalateModelRouterTool(options: {
     tier: ModelTier;
     toolName: string;
     args?: unknown;
+    /** The route's reasonCode; executor-lane turns carry "executor_direct". */
+    reasonCode?: string;
 }): boolean;
 //# sourceMappingURL=tool-escalation.d.ts.map

package/dist/core/model-router/tool-escalation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-escalation.d.ts","sourceRoot":"","sources":["../../../src/core/model-router/tool-escalation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AA2F1D,wBAAgB,6BAA6B,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAUrH","sourcesContent":["import type { ModelTier } from \"../autonomy/contracts.ts\";\n\nconst READ_ONLY_TOOL_NAMES = new Set([\n\t\"read\",\n\t\"grep\",\n\t\"find\",\n\t\"ls\",\n\t\"list\",\n\t\"search\",\n\t\"glob\",\n\t\"view_file\",\n\t\"list_dir\",\n\t\"grep_search\",\n\t\"search_web\",\n\t\"read_url_content\",\n\t\"read_browser_page\",\n]);\n\nconst SHELL_TOOL_NAMES = new Set([\"bash\", \"exec\", \"execute\", \"run\", \"run_command\", \"shell\"]);\n\nconst READ_ONLY_COMMANDS = new Set([\n\t\"awk\",\n\t\"cat\",\n\t\"date\",\n\t\"df\",\n\t\"du\",\n\t\"env\",\n\t\"git\",\n\t\"grep\",\n\t\"head\",\n\t\"jq\",\n\t\"ls\",\n\t\"node\",\n\t\"npm\",\n\t\"pnpm\",\n\t\"pwd\",\n\t\"rg\",\n\t\"sed\",\n\t\"tail\",\n\t\"test\",\n\t\"tsc\",\n\t\"wc\",\n\t\"which\",\n\t\"yarn\",\n]);\n\nconst READ_ONLY_GIT_SUBCOMMANDS = new Set([\"branch\", \"diff\", \"log\", \"rev-parse\", \"show\", \"status\", \"tag\"]);\nconst READ_ONLY_NPM_SUBCOMMANDS = new Set([\"info\", \"list\", \"ls\", \"outdated\", \"view\", \"whoami\"]);\nconst MUTATING_SHELL_TOKEN_RE =\n\t/(^|\\s)(>|>>|2>|&>|tee\\b|rm\\b|mv\\b|cp\\b|mkdir\\b|touch\\b|chmod\\b|chown\\b|install\\b|commit\\b|push\\b|publish\\b|deploy\\b|apply\\b|add\\b|checkout\\b|switch\\b|reset\\b|clean\\b|stash\\b|merge\\b|rebase\\b|npm\\s+(?:i|install|ci|update|publish|run)\\b|pnpm\\s+(?:i|install|update|publish|run)\\b|yarn\\s+(?:add|install|upgrade|publish|run)\\b)/i;\nconst MUTATING_TOOL_NAME_RE =\n\t/(bash|exec|execute|run|shell|write|edit|patch|replace|delete|remove|move|rename|create|mkdir|touch|install|commit|push|publish|deploy|apply)/i;\n\nfunction getShellCommand(args: unknown): string | undefined {\n\tif (!args || typeof args !== \"object\") return undefined;\n\tconst record = args as Record<string, unknown>;\n\tconst command = record.command ?? record.cmd ?? record.shellCommand;\n\treturn typeof command === \"string\" ? command.trim() : undefined;\n}\n\nfunction commandName(segment: string): string | undefined {\n\tconst first = segment.trim().match(/^[A-Za-z0-9_./-]+/)?.[0];\n\tif (!first) return undefined;\n\tconst parts = first.split(\"/\");\n\treturn parts[parts.length - 1]?.toLowerCase();\n}\n\nfunction commandArg(segment: string, index: number): string | undefined {\n\treturn segment.trim().split(/\\s+/)[index]?.toLowerCase();\n}\n\nfunction isReadOnlyShellSegment(segment: string): boolean {\n\tconst name = commandName(segment);\n\tif (!name || !READ_ONLY_COMMANDS.has(name)) return false;\n\tif (name === \"git\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_GIT_SUBCOMMANDS.has(subcommand));\n\t}\n\tif (name === \"npm\" || name === \"pnpm\" || name === \"yarn\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_NPM_SUBCOMMANDS.has(subcommand));\n\t}\n\treturn true;\n}\n\nfunction isReadOnlyShellCommand(command: string): boolean {\n\tif (!command || MUTATING_SHELL_TOKEN_RE.test(command)) return false;\n\tconst segments = command.split(/\\s*&&\\s*/).map((segment) => segment.trim());\n\treturn segments.length > 0 && segments.every(isReadOnlyShellSegment);\n}\n\nexport function shouldEscalateModelRouterTool(options: { tier: ModelTier; toolName: string; args?: unknown }): boolean {\n\tif (options.tier !== \"cheap\") return false;\n\tconst toolName = options.toolName.trim().toLowerCase();\n\tif (!toolName) return true;\n\tif (READ_ONLY_TOOL_NAMES.has(toolName)) return false;\n\tif (SHELL_TOOL_NAMES.has(toolName)) {\n\t\tconst command = getShellCommand(options.args);\n\t\treturn command ? !isReadOnlyShellCommand(command) : true;\n\t}\n\treturn MUTATING_TOOL_NAME_RE.test(toolName) || !toolName.startsWith(\"read_\");\n}\n"]}
+{"version":3,"file":"tool-escalation.d.ts","sourceRoot":"","sources":["../../../src/core/model-router/tool-escalation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AA2F1D,wBAAgB,6BAA6B,CAAC,OAAO,EAAE;IACtD,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAeV","sourcesContent":["import type { ModelTier } from \"../autonomy/contracts.ts\";\n\nconst READ_ONLY_TOOL_NAMES = new Set([\n\t\"read\",\n\t\"grep\",\n\t\"find\",\n\t\"ls\",\n\t\"list\",\n\t\"search\",\n\t\"glob\",\n\t\"view_file\",\n\t\"list_dir\",\n\t\"grep_search\",\n\t\"search_web\",\n\t\"read_url_content\",\n\t\"read_browser_page\",\n]);\n\nconst SHELL_TOOL_NAMES = new Set([\"bash\", \"exec\", \"execute\", \"run\", \"run_command\", \"shell\"]);\n\nconst READ_ONLY_COMMANDS = new Set([\n\t\"awk\",\n\t\"cat\",\n\t\"date\",\n\t\"df\",\n\t\"du\",\n\t\"env\",\n\t\"git\",\n\t\"grep\",\n\t\"head\",\n\t\"jq\",\n\t\"ls\",\n\t\"node\",\n\t\"npm\",\n\t\"pnpm\",\n\t\"pwd\",\n\t\"rg\",\n\t\"sed\",\n\t\"tail\",\n\t\"test\",\n\t\"tsc\",\n\t\"wc\",\n\t\"which\",\n\t\"yarn\",\n]);\n\nconst READ_ONLY_GIT_SUBCOMMANDS = new Set([\"branch\", \"diff\", \"log\", \"rev-parse\", \"show\", \"status\", \"tag\"]);\nconst READ_ONLY_NPM_SUBCOMMANDS = new Set([\"info\", \"list\", \"ls\", \"outdated\", \"view\", \"whoami\"]);\nconst MUTATING_SHELL_TOKEN_RE =\n\t/(^|\\s)(>|>>|2>|&>|tee\\b|rm\\b|mv\\b|cp\\b|mkdir\\b|touch\\b|chmod\\b|chown\\b|install\\b|commit\\b|push\\b|publish\\b|deploy\\b|apply\\b|add\\b|checkout\\b|switch\\b|reset\\b|clean\\b|stash\\b|merge\\b|rebase\\b|npm\\s+(?:i|install|ci|update|publish|run)\\b|pnpm\\s+(?:i|install|update|publish|run)\\b|yarn\\s+(?:add|install|upgrade|publish|run)\\b)/i;\nconst MUTATING_TOOL_NAME_RE =\n\t/(bash|exec|execute|run|shell|write|edit|patch|replace|delete|remove|move|rename|create|mkdir|touch|install|commit|push|publish|deploy|apply)/i;\n\nfunction getShellCommand(args: unknown): string | undefined {\n\tif (!args || typeof args !== \"object\") return undefined;\n\tconst record = args as Record<string, unknown>;\n\tconst command = record.command ?? record.cmd ?? record.shellCommand;\n\treturn typeof command === \"string\" ? command.trim() : undefined;\n}\n\nfunction commandName(segment: string): string | undefined {\n\tconst first = segment.trim().match(/^[A-Za-z0-9_./-]+/)?.[0];\n\tif (!first) return undefined;\n\tconst parts = first.split(\"/\");\n\treturn parts[parts.length - 1]?.toLowerCase();\n}\n\nfunction commandArg(segment: string, index: number): string | undefined {\n\treturn segment.trim().split(/\\s+/)[index]?.toLowerCase();\n}\n\nfunction isReadOnlyShellSegment(segment: string): boolean {\n\tconst name = commandName(segment);\n\tif (!name || !READ_ONLY_COMMANDS.has(name)) return false;\n\tif (name === \"git\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_GIT_SUBCOMMANDS.has(subcommand));\n\t}\n\tif (name === \"npm\" || name === \"pnpm\" || name === \"yarn\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_NPM_SUBCOMMANDS.has(subcommand));\n\t}\n\treturn true;\n}\n\nfunction isReadOnlyShellCommand(command: string): boolean {\n\tif (!command || MUTATING_SHELL_TOKEN_RE.test(command)) return false;\n\tconst segments = command.split(/\\s*&&\\s*/).map((segment) => segment.trim());\n\treturn segments.length > 0 && segments.every(isReadOnlyShellSegment);\n}\n\nexport function shouldEscalateModelRouterTool(options: {\n\ttier: ModelTier;\n\ttoolName: string;\n\targs?: unknown;\n\t/** The route's reasonCode; executor-lane turns carry \"executor_direct\". */\n\treasonCode?: string;\n}): boolean {\n\tif (options.tier !== \"cheap\") return false;\n\tconst toolName = options.toolName.trim().toLowerCase();\n\t// Executor-lane turns (G16) exist to run exactly one tool: run_toolkit_script, which enforces\n\t// its own safety (danger confirmation, structural exit-code contract). Escalating on it would\n\t// abort every executor turn at the moment it does its job. Any OTHER mutating tool still\n\t// escalates to the expensive model as usual.\n\tif (options.reasonCode === \"executor_direct\" && toolName === \"run_toolkit_script\") return false;\n\tif (!toolName) return true;\n\tif (READ_ONLY_TOOL_NAMES.has(toolName)) return false;\n\tif (SHELL_TOOL_NAMES.has(toolName)) {\n\t\tconst command = getShellCommand(options.args);\n\t\treturn command ? !isReadOnlyShellCommand(command) : true;\n\t}\n\treturn MUTATING_TOOL_NAME_RE.test(toolName) || !toolName.startsWith(\"read_\");\n}\n"]}

package/dist/core/model-router/tool-escalation.js

@@ -84,6 +84,12 @@ export function shouldEscalateModelRouterTool(options) {
     if (options.tier !== "cheap")
         return false;
     const toolName = options.toolName.trim().toLowerCase();
+    // Executor-lane turns (G16) exist to run exactly one tool: run_toolkit_script, which enforces
+    // its own safety (danger confirmation, structural exit-code contract). Escalating on it would
+    // abort every executor turn at the moment it does its job. Any OTHER mutating tool still
+    // escalates to the expensive model as usual.
+    if (options.reasonCode === "executor_direct" && toolName === "run_toolkit_script")
+        return false;
     if (!toolName)
         return true;
     if (READ_ONLY_TOOL_NAMES.has(toolName))

package/dist/core/model-router/tool-escalation.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-escalation.js","sourceRoot":"","sources":["../../../src/core/model-router/tool-escalation.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ModelTier } from \"../autonomy/contracts.ts\";\n\nconst READ_ONLY_TOOL_NAMES = new Set([\n\t\"read\",\n\t\"grep\",\n\t\"find\",\n\t\"ls\",\n\t\"list\",\n\t\"search\",\n\t\"glob\",\n\t\"view_file\",\n\t\"list_dir\",\n\t\"grep_search\",\n\t\"search_web\",\n\t\"read_url_content\",\n\t\"read_browser_page\",\n]);\n\nconst SHELL_TOOL_NAMES = new Set([\"bash\", \"exec\", \"execute\", \"run\", \"run_command\", \"shell\"]);\n\nconst READ_ONLY_COMMANDS = new Set([\n\t\"awk\",\n\t\"cat\",\n\t\"date\",\n\t\"df\",\n\t\"du\",\n\t\"env\",\n\t\"git\",\n\t\"grep\",\n\t\"head\",\n\t\"jq\",\n\t\"ls\",\n\t\"node\",\n\t\"npm\",\n\t\"pnpm\",\n\t\"pwd\",\n\t\"rg\",\n\t\"sed\",\n\t\"tail\",\n\t\"test\",\n\t\"tsc\",\n\t\"wc\",\n\t\"which\",\n\t\"yarn\",\n]);\n\nconst READ_ONLY_GIT_SUBCOMMANDS = new Set([\"branch\", \"diff\", \"log\", \"rev-parse\", \"show\", \"status\", \"tag\"]);\nconst READ_ONLY_NPM_SUBCOMMANDS = new Set([\"info\", \"list\", \"ls\", \"outdated\", \"view\", \"whoami\"]);\nconst MUTATING_SHELL_TOKEN_RE =\n\t/(^|\\s)(>|>>|2>|&>|tee\\b|rm\\b|mv\\b|cp\\b|mkdir\\b|touch\\b|chmod\\b|chown\\b|install\\b|commit\\b|push\\b|publish\\b|deploy\\b|apply\\b|add\\b|checkout\\b|switch\\b|reset\\b|clean\\b|stash\\b|merge\\b|rebase\\b|npm\\s+(?:i|install|ci|update|publish|run)\\b|pnpm\\s+(?:i|install|update|publish|run)\\b|yarn\\s+(?:add|install|upgrade|publish|run)\\b)/i;\nconst MUTATING_TOOL_NAME_RE =\n\t/(bash|exec|execute|run|shell|write|edit|patch|replace|delete|remove|move|rename|create|mkdir|touch|install|commit|push|publish|deploy|apply)/i;\n\nfunction getShellCommand(args: unknown): string | undefined {\n\tif (!args || typeof args !== \"object\") return undefined;\n\tconst record = args as Record<string, unknown>;\n\tconst command = record.command ?? record.cmd ?? record.shellCommand;\n\treturn typeof command === \"string\" ? command.trim() : undefined;\n}\n\nfunction commandName(segment: string): string | undefined {\n\tconst first = segment.trim().match(/^[A-Za-z0-9_./-]+/)?.[0];\n\tif (!first) return undefined;\n\tconst parts = first.split(\"/\");\n\treturn parts[parts.length - 1]?.toLowerCase();\n}\n\nfunction commandArg(segment: string, index: number): string | undefined {\n\treturn segment.trim().split(/\\s+/)[index]?.toLowerCase();\n}\n\nfunction isReadOnlyShellSegment(segment: string): boolean {\n\tconst name = commandName(segment);\n\tif (!name || !READ_ONLY_COMMANDS.has(name)) return false;\n\tif (name === \"git\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_GIT_SUBCOMMANDS.has(subcommand));\n\t}\n\tif (name === \"npm\" || name === \"pnpm\" || name === \"yarn\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_NPM_SUBCOMMANDS.has(subcommand));\n\t}\n\treturn true;\n}\n\nfunction isReadOnlyShellCommand(command: string): boolean {\n\tif (!command || MUTATING_SHELL_TOKEN_RE.test(command)) return false;\n\tconst segments = command.split(/\\s*&&\\s*/).map((segment) => segment.trim());\n\treturn segments.length > 0 && segments.every(isReadOnlyShellSegment);\n}\n\nexport function shouldEscalateModelRouterTool(options: { tier: ModelTier; toolName: string; args?: unknown }): boolean {\n\tif (options.tier !== \"cheap\") return false;\n\tconst toolName = options.toolName.trim().toLowerCase();\n\tif (!toolName) return true;\n\tif (READ_ONLY_TOOL_NAMES.has(toolName)) return false;\n\tif (SHELL_TOOL_NAMES.has(toolName)) {\n\t\tconst command = getShellCommand(options.args);\n\t\treturn command ? !isReadOnlyShellCommand(command) : true;\n\t}\n\treturn MUTATING_TOOL_NAME_RE.test(toolName) || !toolName.startsWith(\"read_\");\n}\n"]}
+{"version":3,"file":"tool-escalation.js","sourceRoot":"","sources":["../../../src/core/model-router/tool-escalation.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ModelTier } from \"../autonomy/contracts.ts\";\n\nconst READ_ONLY_TOOL_NAMES = new Set([\n\t\"read\",\n\t\"grep\",\n\t\"find\",\n\t\"ls\",\n\t\"list\",\n\t\"search\",\n\t\"glob\",\n\t\"view_file\",\n\t\"list_dir\",\n\t\"grep_search\",\n\t\"search_web\",\n\t\"read_url_content\",\n\t\"read_browser_page\",\n]);\n\nconst SHELL_TOOL_NAMES = new Set([\"bash\", \"exec\", \"execute\", \"run\", \"run_command\", \"shell\"]);\n\nconst READ_ONLY_COMMANDS = new Set([\n\t\"awk\",\n\t\"cat\",\n\t\"date\",\n\t\"df\",\n\t\"du\",\n\t\"env\",\n\t\"git\",\n\t\"grep\",\n\t\"head\",\n\t\"jq\",\n\t\"ls\",\n\t\"node\",\n\t\"npm\",\n\t\"pnpm\",\n\t\"pwd\",\n\t\"rg\",\n\t\"sed\",\n\t\"tail\",\n\t\"test\",\n\t\"tsc\",\n\t\"wc\",\n\t\"which\",\n\t\"yarn\",\n]);\n\nconst READ_ONLY_GIT_SUBCOMMANDS = new Set([\"branch\", \"diff\", \"log\", \"rev-parse\", \"show\", \"status\", \"tag\"]);\nconst READ_ONLY_NPM_SUBCOMMANDS = new Set([\"info\", \"list\", \"ls\", \"outdated\", \"view\", \"whoami\"]);\nconst MUTATING_SHELL_TOKEN_RE =\n\t/(^|\\s)(>|>>|2>|&>|tee\\b|rm\\b|mv\\b|cp\\b|mkdir\\b|touch\\b|chmod\\b|chown\\b|install\\b|commit\\b|push\\b|publish\\b|deploy\\b|apply\\b|add\\b|checkout\\b|switch\\b|reset\\b|clean\\b|stash\\b|merge\\b|rebase\\b|npm\\s+(?:i|install|ci|update|publish|run)\\b|pnpm\\s+(?:i|install|update|publish|run)\\b|yarn\\s+(?:add|install|upgrade|publish|run)\\b)/i;\nconst MUTATING_TOOL_NAME_RE =\n\t/(bash|exec|execute|run|shell|write|edit|patch|replace|delete|remove|move|rename|create|mkdir|touch|install|commit|push|publish|deploy|apply)/i;\n\nfunction getShellCommand(args: unknown): string | undefined {\n\tif (!args || typeof args !== \"object\") return undefined;\n\tconst record = args as Record<string, unknown>;\n\tconst command = record.command ?? record.cmd ?? record.shellCommand;\n\treturn typeof command === \"string\" ? command.trim() : undefined;\n}\n\nfunction commandName(segment: string): string | undefined {\n\tconst first = segment.trim().match(/^[A-Za-z0-9_./-]+/)?.[0];\n\tif (!first) return undefined;\n\tconst parts = first.split(\"/\");\n\treturn parts[parts.length - 1]?.toLowerCase();\n}\n\nfunction commandArg(segment: string, index: number): string | undefined {\n\treturn segment.trim().split(/\\s+/)[index]?.toLowerCase();\n}\n\nfunction isReadOnlyShellSegment(segment: string): boolean {\n\tconst name = commandName(segment);\n\tif (!name || !READ_ONLY_COMMANDS.has(name)) return false;\n\tif (name === \"git\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_GIT_SUBCOMMANDS.has(subcommand));\n\t}\n\tif (name === \"npm\" || name === \"pnpm\" || name === \"yarn\") {\n\t\tconst subcommand = commandArg(segment, 1);\n\t\treturn Boolean(subcommand && READ_ONLY_NPM_SUBCOMMANDS.has(subcommand));\n\t}\n\treturn true;\n}\n\nfunction isReadOnlyShellCommand(command: string): boolean {\n\tif (!command || MUTATING_SHELL_TOKEN_RE.test(command)) return false;\n\tconst segments = command.split(/\\s*&&\\s*/).map((segment) => segment.trim());\n\treturn segments.length > 0 && segments.every(isReadOnlyShellSegment);\n}\n\nexport function shouldEscalateModelRouterTool(options: {\n\ttier: ModelTier;\n\ttoolName: string;\n\targs?: unknown;\n\t/** The route's reasonCode; executor-lane turns carry \"executor_direct\". */\n\treasonCode?: string;\n}): boolean {\n\tif (options.tier !== \"cheap\") return false;\n\tconst toolName = options.toolName.trim().toLowerCase();\n\t// Executor-lane turns (G16) exist to run exactly one tool: run_toolkit_script, which enforces\n\t// its own safety (danger confirmation, structural exit-code contract). Escalating on it would\n\t// abort every executor turn at the moment it does its job. Any OTHER mutating tool still\n\t// escalates to the expensive model as usual.\n\tif (options.reasonCode === \"executor_direct\" && toolName === \"run_toolkit_script\") return false;\n\tif (!toolName) return true;\n\tif (READ_ONLY_TOOL_NAMES.has(toolName)) return false;\n\tif (SHELL_TOOL_NAMES.has(toolName)) {\n\t\tconst command = getShellCommand(options.args);\n\t\treturn command ? !isReadOnlyShellCommand(command) : true;\n\t}\n\treturn MUTATING_TOOL_NAME_RE.test(toolName) || !toolName.startsWith(\"read_\");\n}\n"]}

package/dist/core/research/research-runner.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityEnvelope, EvidenceBundle, GateOutcome } from "../autonomy/contracts.ts";
+import type { CapabilityEnvelope, EvidenceBundle, EvidenceRef, GateOutcome } from "../autonomy/contracts.ts";
 /**
  * Pure orchestration for one autonomous research pass: gate -> bounded isolated completion ->
  * parse -> evidence bundle. The model executor is injected so this stays provider-free and
@@ -20,6 +20,12 @@ export interface ResearchRunnerOptions {
     context?: string;
     /** Stripped research envelope - never the foreground/architect envelope. */
     envelope: CapabilityEnvelope;
+    /**
+     * Pointer-first workspace sources (repo-relative path + bounded excerpt, never file bodies) that
+     * inform the pass. They are rendered into the user prompt and carried into the evidence bundle;
+     * omitted / empty reproduces the pre-collector behavior exactly.
+     */
+    sources?: readonly EvidenceRef[];
     /** Budget for this pass; a post-hoc breach marks the run budget_exhausted (spend stays visible). */
     maxUsd: number;
     maxSources: number;
@@ -46,6 +52,7 @@ export interface ResearchRunResult {
 export declare function buildResearchUserPrompt(args: {
     query: string;
     context?: string;
+    sources?: readonly EvidenceRef[];
     maxFindings: number;
 }): string;
 export interface ParsedResearchFindings {

package/dist/core/research/research-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"research-runner.d.ts","sourceRoot":"","sources":["../../../src/core/research/research-runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAwB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAItH;;;;;;;GAOG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,2BAA2B,QAM5B,CAAC;AAEb,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpH,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAErG,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAO9G;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAwC3G;AA+BD,wBAAsB,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwD5F","sourcesContent":["import { runBoundedCompletion } from \"../autonomy/bounded-completion.ts\";\nimport type { CapabilityEnvelope, EvidenceBundle, EvidenceRef, Finding, GateOutcome } from \"../autonomy/contracts.ts\";\nimport { createEvidenceBundle } from \"./evidence-bundle.ts\";\nimport { evaluateResearchRequest } from \"./research-gate.ts\";\n\n/**\n * Pure orchestration for one autonomous research pass: gate -> bounded isolated completion ->\n * parse -> evidence bundle. The model executor is injected so this stays provider-free and\n * session-free; production wires `AgentSession.runIsolatedCompletion` in.\n *\n * The lane is read-only by construction: the executor receives text prompts only, and the output\n * is an `EvidenceBundle` whose model-synthesized findings are marked untrusted.\n */\n\n/** Static across calls so callers can use `cacheRetention: \"short\"` and only pay for the variable tail. */\nexport const RESEARCH_LANE_SYSTEM_PROMPT = [\n\t\"You are a read-only research lane for a coding agent.\",\n\t\"You receive a research query plus bounded context and produce findings that help satisfy open goal requirements.\",\n\t\"Respond with STRICT JSON only - no prose, no markdown fences:\",\n\t'{\"findings\":[{\"summary\":\"<one concrete, actionable finding>\",\"confidence\":<0..1>}]}',\n\t\"Base findings only on the provided context. Never invent file paths, APIs, or facts.\",\n].join(\"\\n\");\n\nexport interface ResearchCompletion {\n\ttext: string;\n\tcostUsd: number;\n\tstopReason: string;\n}\n\nexport interface ResearchRunnerOptions {\n\tquery: string;\n\t/** Bounded, pre-redacted context handed to the research model (goal text, open requirements). */\n\tcontext?: string;\n\t/** Stripped research envelope - never the foreground/architect envelope. */\n\tenvelope: CapabilityEnvelope;\n\t/** Budget for this pass; a post-hoc breach marks the run budget_exhausted (spend stays visible). */\n\tmaxUsd: number;\n\tmaxSources: number;\n\tmaxFindings: number;\n\t/** Wall-clock budget in milliseconds; 0 disables. */\n\tmaxWallClockMs: number;\n\t/** Executes one isolated completion. Production: AgentSession.runIsolatedCompletion. */\n\tcomplete: (args: { systemPrompt: string; userPrompt: string; signal?: AbortSignal }) => Promise<ResearchCompletion>;\n\t/** External cancellation (e.g. session disposal). */\n\tsignal?: AbortSignal;\n}\n\nexport type ResearchRunStatus = \"succeeded\" | \"failed\" | \"canceled\" | \"timeout\" | \"budget_exhausted\";\n\nexport interface ResearchRunResult {\n\tstatus: ResearchRunStatus;\n\treasonCode: string;\n\tgateOutcome: GateOutcome;\n\tbundle?: EvidenceBundle;\n\tcostUsd: number;\n}\n\nexport function buildResearchUserPrompt(args: { query: string; context?: string; maxFindings: number }): string {\n\tconst parts = [`Research query: ${args.query}`];\n\tif (args.context && args.context.length > 0) {\n\t\tparts.push(\"\", \"Context:\", args.context);\n\t}\n\tparts.push(\"\", `Return at most ${args.maxFindings} findings.`);\n\treturn parts.join(\"\\n\");\n}\n\nexport interface ParsedResearchFindings {\n\tfindings: Array<{ summary: string; confidence?: number }>;\n}\n\nexport function parseResearchFindings(text: string, maxFindings: number): ParsedResearchFindings | undefined {\n\tconst trimmed = text.trim();\n\tconst candidates: string[] = [trimmed];\n\tconst fenced = /```(?:json)?\\s*([\\s\\S]*?)```/.exec(trimmed);\n\tif (fenced?.[1]) candidates.push(fenced[1].trim());\n\tconst start = trimmed.indexOf(\"{\");\n\tconst end = trimmed.lastIndexOf(\"}\");\n\tif (start >= 0 && end > start) candidates.push(trimmed.slice(start, end + 1));\n\n\tfor (const candidate of candidates) {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(candidate);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) continue;\n\t\tconst findingsRaw = (parsed as { findings?: unknown }).findings;\n\t\tif (!Array.isArray(findingsRaw)) continue;\n\n\t\tconst findings: Array<{ summary: string; confidence?: number }> = [];\n\t\tfor (const item of findingsRaw) {\n\t\t\tif (!item || typeof item !== \"object\" || Array.isArray(item)) continue;\n\t\t\tconst summary = (item as { summary?: unknown }).summary;\n\t\t\tif (typeof summary !== \"string\" || summary.trim().length === 0) continue;\n\t\t\tconst confidenceRaw = (item as { confidence?: unknown }).confidence;\n\t\t\tconst confidence =\n\t\t\t\ttypeof confidenceRaw === \"number\" && Number.isFinite(confidenceRaw)\n\t\t\t\t\t? Math.min(Math.max(confidenceRaw, 0), 1)\n\t\t\t\t\t: undefined;\n\t\t\tfindings.push({ summary: summary.trim(), confidence });\n\t\t\tif (findings.length >= maxFindings) break;\n\t\t}\n\t\t// A well-formed-but-empty findings array is a valid \"nothing found\"; a findings array whose\n\t\t// every item is malformed is not.\n\t\tif (findings.length > 0 || findingsRaw.length === 0) {\n\t\t\treturn { findings };\n\t\t}\n\t}\n\treturn undefined;\n}\n\nfunction truncateExcerpt(text: string, maxChars: number): string {\n\tif (text.length <= maxChars) return text;\n\treturn `${text.slice(0, Math.max(0, maxChars - 1))}…`;\n}\n\nfunction buildBundle(options: ResearchRunnerOptions, parsed: ParsedResearchFindings): EvidenceBundle {\n\tconst contextRef: EvidenceRef = {\n\t\tid: \"src-context\",\n\t\tkind: \"user\",\n\t\ttitle: \"Goal/context provided to the research lane\",\n\t\ttrusted: true,\n\t\texcerpt: truncateExcerpt(options.context && options.context.length > 0 ? options.context : options.query, 2000),\n\t};\n\tconst synthesisRef: EvidenceRef = {\n\t\tid: \"src-synthesis\",\n\t\tkind: \"tool\",\n\t\ttitle: \"Research-model synthesis\",\n\t\ttrusted: false,\n\t};\n\tconst sources = [contextRef, synthesisRef].slice(0, Math.max(1, options.maxSources));\n\tconst findings: Finding[] = parsed.findings.slice(0, options.maxFindings).map((finding, index) => ({\n\t\tid: `finding-${index + 1}`,\n\t\tsummary: finding.summary,\n\t\tevidenceIds: [synthesisRef.id],\n\t\t...(finding.confidence !== undefined ? { confidence: finding.confidence } : {}),\n\t}));\n\treturn createEvidenceBundle({ query: options.query, sources, findings });\n}\n\nexport async function runResearch(options: ResearchRunnerOptions): Promise<ResearchRunResult> {\n\tconst gateOutcome = evaluateResearchRequest({\n\t\tenvelope: options.envelope,\n\t\tsourceKind: \"tool\",\n\t\testimatedUsd: options.maxUsd,\n\t});\n\tif (gateOutcome.outcome !== \"allow\") {\n\t\t// Skip-and-record, never prompt: gate denials inform diagnostics instead of blocking anything.\n\t\tconst status: ResearchRunStatus = gateOutcome.reasonCode === \"over_budget\" ? \"budget_exhausted\" : \"failed\";\n\t\treturn { status, reasonCode: gateOutcome.reasonCode, gateOutcome, costUsd: 0 };\n\t}\n\n\tconst bounded = await runBoundedCompletion({\n\t\tmaxWallClockMs: options.maxWallClockMs,\n\t\tsignal: options.signal,\n\t\texecute: (signal) =>\n\t\t\toptions.complete({\n\t\t\t\tsystemPrompt: RESEARCH_LANE_SYSTEM_PROMPT,\n\t\t\t\tuserPrompt: buildResearchUserPrompt(options),\n\t\t\t\tsignal,\n\t\t\t}),\n\t});\n\tif (bounded.failure) {\n\t\treturn {\n\t\t\tstatus: bounded.failure.status,\n\t\t\treasonCode: bounded.failure.reasonCode,\n\t\t\tgateOutcome,\n\t\t\tcostUsd: bounded.completion?.costUsd ?? 0,\n\t\t};\n\t}\n\tconst completion = bounded.completion;\n\tif (!completion) {\n\t\treturn { status: \"failed\", reasonCode: \"completion_error\", gateOutcome, costUsd: 0 };\n\t}\n\tif (completion.stopReason === \"error\" || completion.stopReason === \"aborted\") {\n\t\treturn { status: \"failed\", reasonCode: \"model_error\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst parsed = parseResearchFindings(completion.text, options.maxFindings);\n\tif (!parsed) {\n\t\treturn { status: \"failed\", reasonCode: \"unparseable_output\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst bundle = buildBundle(options, parsed);\n\tconst overBudget = options.maxUsd > 0 && completion.costUsd > options.maxUsd;\n\treturn {\n\t\tstatus: overBudget ? \"budget_exhausted\" : \"succeeded\",\n\t\treasonCode: overBudget\n\t\t\t? \"cost_budget_exceeded\"\n\t\t\t: parsed.findings.length === 0\n\t\t\t\t? \"no_findings\"\n\t\t\t\t: \"research_completed\",\n\t\tgateOutcome,\n\t\tbundle,\n\t\tcostUsd: completion.costUsd,\n\t};\n}\n"]}
+{"version":3,"file":"research-runner.d.ts","sourceRoot":"","sources":["../../../src/core/research/research-runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,WAAW,EAAW,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAItH;;;;;;;GAOG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,2BAA2B,QAM5B,CAAC;AAEb,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACjC,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpH,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAErG,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAcT;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAwC3G;AAoCD,wBAAsB,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwD5F","sourcesContent":["import { runBoundedCompletion } from \"../autonomy/bounded-completion.ts\";\nimport type { CapabilityEnvelope, EvidenceBundle, EvidenceRef, Finding, GateOutcome } from \"../autonomy/contracts.ts\";\nimport { createEvidenceBundle } from \"./evidence-bundle.ts\";\nimport { evaluateResearchRequest } from \"./research-gate.ts\";\n\n/**\n * Pure orchestration for one autonomous research pass: gate -> bounded isolated completion ->\n * parse -> evidence bundle. The model executor is injected so this stays provider-free and\n * session-free; production wires `AgentSession.runIsolatedCompletion` in.\n *\n * The lane is read-only by construction: the executor receives text prompts only, and the output\n * is an `EvidenceBundle` whose model-synthesized findings are marked untrusted.\n */\n\n/** Static across calls so callers can use `cacheRetention: \"short\"` and only pay for the variable tail. */\nexport const RESEARCH_LANE_SYSTEM_PROMPT = [\n\t\"You are a read-only research lane for a coding agent.\",\n\t\"You receive a research query plus bounded context and produce findings that help satisfy open goal requirements.\",\n\t\"Respond with STRICT JSON only - no prose, no markdown fences:\",\n\t'{\"findings\":[{\"summary\":\"<one concrete, actionable finding>\",\"confidence\":<0..1>}]}',\n\t\"Base findings only on the provided context. Never invent file paths, APIs, or facts.\",\n].join(\"\\n\");\n\nexport interface ResearchCompletion {\n\ttext: string;\n\tcostUsd: number;\n\tstopReason: string;\n}\n\nexport interface ResearchRunnerOptions {\n\tquery: string;\n\t/** Bounded, pre-redacted context handed to the research model (goal text, open requirements). */\n\tcontext?: string;\n\t/** Stripped research envelope - never the foreground/architect envelope. */\n\tenvelope: CapabilityEnvelope;\n\t/**\n\t * Pointer-first workspace sources (repo-relative path + bounded excerpt, never file bodies) that\n\t * inform the pass. They are rendered into the user prompt and carried into the evidence bundle;\n\t * omitted / empty reproduces the pre-collector behavior exactly.\n\t */\n\tsources?: readonly EvidenceRef[];\n\t/** Budget for this pass; a post-hoc breach marks the run budget_exhausted (spend stays visible). */\n\tmaxUsd: number;\n\tmaxSources: number;\n\tmaxFindings: number;\n\t/** Wall-clock budget in milliseconds; 0 disables. */\n\tmaxWallClockMs: number;\n\t/** Executes one isolated completion. Production: AgentSession.runIsolatedCompletion. */\n\tcomplete: (args: { systemPrompt: string; userPrompt: string; signal?: AbortSignal }) => Promise<ResearchCompletion>;\n\t/** External cancellation (e.g. session disposal). */\n\tsignal?: AbortSignal;\n}\n\nexport type ResearchRunStatus = \"succeeded\" | \"failed\" | \"canceled\" | \"timeout\" | \"budget_exhausted\";\n\nexport interface ResearchRunResult {\n\tstatus: ResearchRunStatus;\n\treasonCode: string;\n\tgateOutcome: GateOutcome;\n\tbundle?: EvidenceBundle;\n\tcostUsd: number;\n}\n\nexport function buildResearchUserPrompt(args: {\n\tquery: string;\n\tcontext?: string;\n\tsources?: readonly EvidenceRef[];\n\tmaxFindings: number;\n}): string {\n\tconst parts = [`Research query: ${args.query}`];\n\tif (args.context && args.context.length > 0) {\n\t\tparts.push(\"\", \"Context:\", args.context);\n\t}\n\tif (args.sources && args.sources.length > 0) {\n\t\tparts.push(\"\", \"Workspace sources (pointer-first; open the file to read full context):\");\n\t\tfor (const source of args.sources) {\n\t\t\tconst pointer = source.title ?? source.uri ?? source.id;\n\t\t\tparts.push(source.excerpt ? `- ${pointer}: ${source.excerpt}` : `- ${pointer}`);\n\t\t}\n\t}\n\tparts.push(\"\", `Return at most ${args.maxFindings} findings.`);\n\treturn parts.join(\"\\n\");\n}\n\nexport interface ParsedResearchFindings {\n\tfindings: Array<{ summary: string; confidence?: number }>;\n}\n\nexport function parseResearchFindings(text: string, maxFindings: number): ParsedResearchFindings | undefined {\n\tconst trimmed = text.trim();\n\tconst candidates: string[] = [trimmed];\n\tconst fenced = /```(?:json)?\\s*([\\s\\S]*?)```/.exec(trimmed);\n\tif (fenced?.[1]) candidates.push(fenced[1].trim());\n\tconst start = trimmed.indexOf(\"{\");\n\tconst end = trimmed.lastIndexOf(\"}\");\n\tif (start >= 0 && end > start) candidates.push(trimmed.slice(start, end + 1));\n\n\tfor (const candidate of candidates) {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(candidate);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) continue;\n\t\tconst findingsRaw = (parsed as { findings?: unknown }).findings;\n\t\tif (!Array.isArray(findingsRaw)) continue;\n\n\t\tconst findings: Array<{ summary: string; confidence?: number }> = [];\n\t\tfor (const item of findingsRaw) {\n\t\t\tif (!item || typeof item !== \"object\" || Array.isArray(item)) continue;\n\t\t\tconst summary = (item as { summary?: unknown }).summary;\n\t\t\tif (typeof summary !== \"string\" || summary.trim().length === 0) continue;\n\t\t\tconst confidenceRaw = (item as { confidence?: unknown }).confidence;\n\t\t\tconst confidence =\n\t\t\t\ttypeof confidenceRaw === \"number\" && Number.isFinite(confidenceRaw)\n\t\t\t\t\t? Math.min(Math.max(confidenceRaw, 0), 1)\n\t\t\t\t\t: undefined;\n\t\t\tfindings.push({ summary: summary.trim(), confidence });\n\t\t\tif (findings.length >= maxFindings) break;\n\t\t}\n\t\t// A well-formed-but-empty findings array is a valid \"nothing found\"; a findings array whose\n\t\t// every item is malformed is not.\n\t\tif (findings.length > 0 || findingsRaw.length === 0) {\n\t\t\treturn { findings };\n\t\t}\n\t}\n\treturn undefined;\n}\n\nfunction truncateExcerpt(text: string, maxChars: number): string {\n\tif (text.length <= maxChars) return text;\n\treturn `${text.slice(0, Math.max(0, maxChars - 1))}…`;\n}\n\nfunction buildBundle(options: ResearchRunnerOptions, parsed: ParsedResearchFindings): EvidenceBundle {\n\tconst contextRef: EvidenceRef = {\n\t\tid: \"src-context\",\n\t\tkind: \"user\",\n\t\ttitle: \"Goal/context provided to the research lane\",\n\t\ttrusted: true,\n\t\texcerpt: truncateExcerpt(options.context && options.context.length > 0 ? options.context : options.query, 2000),\n\t};\n\tconst synthesisRef: EvidenceRef = {\n\t\tid: \"src-synthesis\",\n\t\tkind: \"tool\",\n\t\ttitle: \"Research-model synthesis\",\n\t\ttrusted: false,\n\t};\n\t// context + synthesis are the fixed provenance anchors (findings cite src-synthesis); workspace\n\t// sources fill whatever budget is left between them, so the anchors are never squeezed out.\n\tconst budget = Math.max(1, options.maxSources);\n\tconst workspaceRoom = Math.max(0, budget - 2);\n\tconst workspaceSources = (options.sources ?? []).slice(0, workspaceRoom);\n\tconst sources = [contextRef, ...workspaceSources, synthesisRef].slice(0, budget);\n\tconst findings: Finding[] = parsed.findings.slice(0, options.maxFindings).map((finding, index) => ({\n\t\tid: `finding-${index + 1}`,\n\t\tsummary: finding.summary,\n\t\tevidenceIds: [synthesisRef.id],\n\t\t...(finding.confidence !== undefined ? { confidence: finding.confidence } : {}),\n\t}));\n\treturn createEvidenceBundle({ query: options.query, sources, findings });\n}\n\nexport async function runResearch(options: ResearchRunnerOptions): Promise<ResearchRunResult> {\n\tconst gateOutcome = evaluateResearchRequest({\n\t\tenvelope: options.envelope,\n\t\tsourceKind: \"tool\",\n\t\testimatedUsd: options.maxUsd,\n\t});\n\tif (gateOutcome.outcome !== \"allow\") {\n\t\t// Skip-and-record, never prompt: gate denials inform diagnostics instead of blocking anything.\n\t\tconst status: ResearchRunStatus = gateOutcome.reasonCode === \"over_budget\" ? \"budget_exhausted\" : \"failed\";\n\t\treturn { status, reasonCode: gateOutcome.reasonCode, gateOutcome, costUsd: 0 };\n\t}\n\n\tconst bounded = await runBoundedCompletion({\n\t\tmaxWallClockMs: options.maxWallClockMs,\n\t\tsignal: options.signal,\n\t\texecute: (signal) =>\n\t\t\toptions.complete({\n\t\t\t\tsystemPrompt: RESEARCH_LANE_SYSTEM_PROMPT,\n\t\t\t\tuserPrompt: buildResearchUserPrompt(options),\n\t\t\t\tsignal,\n\t\t\t}),\n\t});\n\tif (bounded.failure) {\n\t\treturn {\n\t\t\tstatus: bounded.failure.status,\n\t\t\treasonCode: bounded.failure.reasonCode,\n\t\t\tgateOutcome,\n\t\t\tcostUsd: bounded.completion?.costUsd ?? 0,\n\t\t};\n\t}\n\tconst completion = bounded.completion;\n\tif (!completion) {\n\t\treturn { status: \"failed\", reasonCode: \"completion_error\", gateOutcome, costUsd: 0 };\n\t}\n\tif (completion.stopReason === \"error\" || completion.stopReason === \"aborted\") {\n\t\treturn { status: \"failed\", reasonCode: \"model_error\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst parsed = parseResearchFindings(completion.text, options.maxFindings);\n\tif (!parsed) {\n\t\treturn { status: \"failed\", reasonCode: \"unparseable_output\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst bundle = buildBundle(options, parsed);\n\tconst overBudget = options.maxUsd > 0 && completion.costUsd > options.maxUsd;\n\treturn {\n\t\tstatus: overBudget ? \"budget_exhausted\" : \"succeeded\",\n\t\treasonCode: overBudget\n\t\t\t? \"cost_budget_exceeded\"\n\t\t\t: parsed.findings.length === 0\n\t\t\t\t? \"no_findings\"\n\t\t\t\t: \"research_completed\",\n\t\tgateOutcome,\n\t\tbundle,\n\t\tcostUsd: completion.costUsd,\n\t};\n}\n"]}

package/dist/core/research/research-runner.js

@@ -22,6 +22,13 @@ export function buildResearchUserPrompt(args) {
     if (args.context && args.context.length > 0) {
         parts.push("", "Context:", args.context);
     }
+    if (args.sources && args.sources.length > 0) {
+        parts.push("", "Workspace sources (pointer-first; open the file to read full context):");
+        for (const source of args.sources) {
+            const pointer = source.title ?? source.uri ?? source.id;
+            parts.push(source.excerpt ? `- ${pointer}: ${source.excerpt}` : `- ${pointer}`);
+        }
+    }
     parts.push("", `Return at most ${args.maxFindings} findings.`);
     return parts.join("\n");
 }
@@ -90,7 +97,12 @@ function buildBundle(options, parsed) {
         title: "Research-model synthesis",
         trusted: false,
     };
-    const sources = [contextRef, synthesisRef].slice(0, Math.max(1, options.maxSources));
+    // context + synthesis are the fixed provenance anchors (findings cite src-synthesis); workspace
+    // sources fill whatever budget is left between them, so the anchors are never squeezed out.
+    const budget = Math.max(1, options.maxSources);
+    const workspaceRoom = Math.max(0, budget - 2);
+    const workspaceSources = (options.sources ?? []).slice(0, workspaceRoom);
+    const sources = [contextRef, ...workspaceSources, synthesisRef].slice(0, budget);
     const findings = parsed.findings.slice(0, options.maxFindings).map((finding, index) => ({
         id: `finding-${index + 1}`,
         summary: finding.summary,

package/dist/core/research/research-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"research-runner.js","sourceRoot":"","sources":["../../../src/core/research/research-runner.ts"],"names":[],"mappings":"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","sourcesContent":["import { runBoundedCompletion } from \"../autonomy/bounded-completion.ts\";\nimport type { CapabilityEnvelope, EvidenceBundle, EvidenceRef, Finding, GateOutcome } from \"../autonomy/contracts.ts\";\nimport { createEvidenceBundle } from \"./evidence-bundle.ts\";\nimport { evaluateResearchRequest } from \"./research-gate.ts\";\n\n/**\n * Pure orchestration for one autonomous research pass: gate -> bounded isolated completion ->\n * parse -> evidence bundle. The model executor is injected so this stays provider-free and\n * session-free; production wires `AgentSession.runIsolatedCompletion` in.\n *\n * The lane is read-only by construction: the executor receives text prompts only, and the output\n * is an `EvidenceBundle` whose model-synthesized findings are marked untrusted.\n */\n\n/** Static across calls so callers can use `cacheRetention: \"short\"` and only pay for the variable tail. */\nexport const RESEARCH_LANE_SYSTEM_PROMPT = [\n\t\"You are a read-only research lane for a coding agent.\",\n\t\"You receive a research query plus bounded context and produce findings that help satisfy open goal requirements.\",\n\t\"Respond with STRICT JSON only - no prose, no markdown fences:\",\n\t'{\"findings\":[{\"summary\":\"<one concrete, actionable finding>\",\"confidence\":<0..1>}]}',\n\t\"Base findings only on the provided context. Never invent file paths, APIs, or facts.\",\n].join(\"\\n\");\n\nexport interface ResearchCompletion {\n\ttext: string;\n\tcostUsd: number;\n\tstopReason: string;\n}\n\nexport interface ResearchRunnerOptions {\n\tquery: string;\n\t/** Bounded, pre-redacted context handed to the research model (goal text, open requirements). */\n\tcontext?: string;\n\t/** Stripped research envelope - never the foreground/architect envelope. */\n\tenvelope: CapabilityEnvelope;\n\t/** Budget for this pass; a post-hoc breach marks the run budget_exhausted (spend stays visible). */\n\tmaxUsd: number;\n\tmaxSources: number;\n\tmaxFindings: number;\n\t/** Wall-clock budget in milliseconds; 0 disables. */\n\tmaxWallClockMs: number;\n\t/** Executes one isolated completion. Production: AgentSession.runIsolatedCompletion. */\n\tcomplete: (args: { systemPrompt: string; userPrompt: string; signal?: AbortSignal }) => Promise<ResearchCompletion>;\n\t/** External cancellation (e.g. session disposal). */\n\tsignal?: AbortSignal;\n}\n\nexport type ResearchRunStatus = \"succeeded\" | \"failed\" | \"canceled\" | \"timeout\" | \"budget_exhausted\";\n\nexport interface ResearchRunResult {\n\tstatus: ResearchRunStatus;\n\treasonCode: string;\n\tgateOutcome: GateOutcome;\n\tbundle?: EvidenceBundle;\n\tcostUsd: number;\n}\n\nexport function buildResearchUserPrompt(args: { query: string; context?: string; maxFindings: number }): string {\n\tconst parts = [`Research query: ${args.query}`];\n\tif (args.context && args.context.length > 0) {\n\t\tparts.push(\"\", \"Context:\", args.context);\n\t}\n\tparts.push(\"\", `Return at most ${args.maxFindings} findings.`);\n\treturn parts.join(\"\\n\");\n}\n\nexport interface ParsedResearchFindings {\n\tfindings: Array<{ summary: string; confidence?: number }>;\n}\n\nexport function parseResearchFindings(text: string, maxFindings: number): ParsedResearchFindings | undefined {\n\tconst trimmed = text.trim();\n\tconst candidates: string[] = [trimmed];\n\tconst fenced = /```(?:json)?\\s*([\\s\\S]*?)```/.exec(trimmed);\n\tif (fenced?.[1]) candidates.push(fenced[1].trim());\n\tconst start = trimmed.indexOf(\"{\");\n\tconst end = trimmed.lastIndexOf(\"}\");\n\tif (start >= 0 && end > start) candidates.push(trimmed.slice(start, end + 1));\n\n\tfor (const candidate of candidates) {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(candidate);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) continue;\n\t\tconst findingsRaw = (parsed as { findings?: unknown }).findings;\n\t\tif (!Array.isArray(findingsRaw)) continue;\n\n\t\tconst findings: Array<{ summary: string; confidence?: number }> = [];\n\t\tfor (const item of findingsRaw) {\n\t\t\tif (!item || typeof item !== \"object\" || Array.isArray(item)) continue;\n\t\t\tconst summary = (item as { summary?: unknown }).summary;\n\t\t\tif (typeof summary !== \"string\" || summary.trim().length === 0) continue;\n\t\t\tconst confidenceRaw = (item as { confidence?: unknown }).confidence;\n\t\t\tconst confidence =\n\t\t\t\ttypeof confidenceRaw === \"number\" && Number.isFinite(confidenceRaw)\n\t\t\t\t\t? Math.min(Math.max(confidenceRaw, 0), 1)\n\t\t\t\t\t: undefined;\n\t\t\tfindings.push({ summary: summary.trim(), confidence });\n\t\t\tif (findings.length >= maxFindings) break;\n\t\t}\n\t\t// A well-formed-but-empty findings array is a valid \"nothing found\"; a findings array whose\n\t\t// every item is malformed is not.\n\t\tif (findings.length > 0 || findingsRaw.length === 0) {\n\t\t\treturn { findings };\n\t\t}\n\t}\n\treturn undefined;\n}\n\nfunction truncateExcerpt(text: string, maxChars: number): string {\n\tif (text.length <= maxChars) return text;\n\treturn `${text.slice(0, Math.max(0, maxChars - 1))}…`;\n}\n\nfunction buildBundle(options: ResearchRunnerOptions, parsed: ParsedResearchFindings): EvidenceBundle {\n\tconst contextRef: EvidenceRef = {\n\t\tid: \"src-context\",\n\t\tkind: \"user\",\n\t\ttitle: \"Goal/context provided to the research lane\",\n\t\ttrusted: true,\n\t\texcerpt: truncateExcerpt(options.context && options.context.length > 0 ? options.context : options.query, 2000),\n\t};\n\tconst synthesisRef: EvidenceRef = {\n\t\tid: \"src-synthesis\",\n\t\tkind: \"tool\",\n\t\ttitle: \"Research-model synthesis\",\n\t\ttrusted: false,\n\t};\n\tconst sources = [contextRef, synthesisRef].slice(0, Math.max(1, options.maxSources));\n\tconst findings: Finding[] = parsed.findings.slice(0, options.maxFindings).map((finding, index) => ({\n\t\tid: `finding-${index + 1}`,\n\t\tsummary: finding.summary,\n\t\tevidenceIds: [synthesisRef.id],\n\t\t...(finding.confidence !== undefined ? { confidence: finding.confidence } : {}),\n\t}));\n\treturn createEvidenceBundle({ query: options.query, sources, findings });\n}\n\nexport async function runResearch(options: ResearchRunnerOptions): Promise<ResearchRunResult> {\n\tconst gateOutcome = evaluateResearchRequest({\n\t\tenvelope: options.envelope,\n\t\tsourceKind: \"tool\",\n\t\testimatedUsd: options.maxUsd,\n\t});\n\tif (gateOutcome.outcome !== \"allow\") {\n\t\t// Skip-and-record, never prompt: gate denials inform diagnostics instead of blocking anything.\n\t\tconst status: ResearchRunStatus = gateOutcome.reasonCode === \"over_budget\" ? \"budget_exhausted\" : \"failed\";\n\t\treturn { status, reasonCode: gateOutcome.reasonCode, gateOutcome, costUsd: 0 };\n\t}\n\n\tconst bounded = await runBoundedCompletion({\n\t\tmaxWallClockMs: options.maxWallClockMs,\n\t\tsignal: options.signal,\n\t\texecute: (signal) =>\n\t\t\toptions.complete({\n\t\t\t\tsystemPrompt: RESEARCH_LANE_SYSTEM_PROMPT,\n\t\t\t\tuserPrompt: buildResearchUserPrompt(options),\n\t\t\t\tsignal,\n\t\t\t}),\n\t});\n\tif (bounded.failure) {\n\t\treturn {\n\t\t\tstatus: bounded.failure.status,\n\t\t\treasonCode: bounded.failure.reasonCode,\n\t\t\tgateOutcome,\n\t\t\tcostUsd: bounded.completion?.costUsd ?? 0,\n\t\t};\n\t}\n\tconst completion = bounded.completion;\n\tif (!completion) {\n\t\treturn { status: \"failed\", reasonCode: \"completion_error\", gateOutcome, costUsd: 0 };\n\t}\n\tif (completion.stopReason === \"error\" || completion.stopReason === \"aborted\") {\n\t\treturn { status: \"failed\", reasonCode: \"model_error\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst parsed = parseResearchFindings(completion.text, options.maxFindings);\n\tif (!parsed) {\n\t\treturn { status: \"failed\", reasonCode: \"unparseable_output\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst bundle = buildBundle(options, parsed);\n\tconst overBudget = options.maxUsd > 0 && completion.costUsd > options.maxUsd;\n\treturn {\n\t\tstatus: overBudget ? \"budget_exhausted\" : \"succeeded\",\n\t\treasonCode: overBudget\n\t\t\t? \"cost_budget_exceeded\"\n\t\t\t: parsed.findings.length === 0\n\t\t\t\t? \"no_findings\"\n\t\t\t\t: \"research_completed\",\n\t\tgateOutcome,\n\t\tbundle,\n\t\tcostUsd: completion.costUsd,\n\t};\n}\n"]}
+{"version":3,"file":"research-runner.js","sourceRoot":"","sources":["../../../src/core/research/research-runner.ts"],"names":[],"mappings":"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","sourcesContent":["import { runBoundedCompletion } from \"../autonomy/bounded-completion.ts\";\nimport type { CapabilityEnvelope, EvidenceBundle, EvidenceRef, Finding, GateOutcome } from \"../autonomy/contracts.ts\";\nimport { createEvidenceBundle } from \"./evidence-bundle.ts\";\nimport { evaluateResearchRequest } from \"./research-gate.ts\";\n\n/**\n * Pure orchestration for one autonomous research pass: gate -> bounded isolated completion ->\n * parse -> evidence bundle. The model executor is injected so this stays provider-free and\n * session-free; production wires `AgentSession.runIsolatedCompletion` in.\n *\n * The lane is read-only by construction: the executor receives text prompts only, and the output\n * is an `EvidenceBundle` whose model-synthesized findings are marked untrusted.\n */\n\n/** Static across calls so callers can use `cacheRetention: \"short\"` and only pay for the variable tail. */\nexport const RESEARCH_LANE_SYSTEM_PROMPT = [\n\t\"You are a read-only research lane for a coding agent.\",\n\t\"You receive a research query plus bounded context and produce findings that help satisfy open goal requirements.\",\n\t\"Respond with STRICT JSON only - no prose, no markdown fences:\",\n\t'{\"findings\":[{\"summary\":\"<one concrete, actionable finding>\",\"confidence\":<0..1>}]}',\n\t\"Base findings only on the provided context. Never invent file paths, APIs, or facts.\",\n].join(\"\\n\");\n\nexport interface ResearchCompletion {\n\ttext: string;\n\tcostUsd: number;\n\tstopReason: string;\n}\n\nexport interface ResearchRunnerOptions {\n\tquery: string;\n\t/** Bounded, pre-redacted context handed to the research model (goal text, open requirements). */\n\tcontext?: string;\n\t/** Stripped research envelope - never the foreground/architect envelope. */\n\tenvelope: CapabilityEnvelope;\n\t/**\n\t * Pointer-first workspace sources (repo-relative path + bounded excerpt, never file bodies) that\n\t * inform the pass. They are rendered into the user prompt and carried into the evidence bundle;\n\t * omitted / empty reproduces the pre-collector behavior exactly.\n\t */\n\tsources?: readonly EvidenceRef[];\n\t/** Budget for this pass; a post-hoc breach marks the run budget_exhausted (spend stays visible). */\n\tmaxUsd: number;\n\tmaxSources: number;\n\tmaxFindings: number;\n\t/** Wall-clock budget in milliseconds; 0 disables. */\n\tmaxWallClockMs: number;\n\t/** Executes one isolated completion. Production: AgentSession.runIsolatedCompletion. */\n\tcomplete: (args: { systemPrompt: string; userPrompt: string; signal?: AbortSignal }) => Promise<ResearchCompletion>;\n\t/** External cancellation (e.g. session disposal). */\n\tsignal?: AbortSignal;\n}\n\nexport type ResearchRunStatus = \"succeeded\" | \"failed\" | \"canceled\" | \"timeout\" | \"budget_exhausted\";\n\nexport interface ResearchRunResult {\n\tstatus: ResearchRunStatus;\n\treasonCode: string;\n\tgateOutcome: GateOutcome;\n\tbundle?: EvidenceBundle;\n\tcostUsd: number;\n}\n\nexport function buildResearchUserPrompt(args: {\n\tquery: string;\n\tcontext?: string;\n\tsources?: readonly EvidenceRef[];\n\tmaxFindings: number;\n}): string {\n\tconst parts = [`Research query: ${args.query}`];\n\tif (args.context && args.context.length > 0) {\n\t\tparts.push(\"\", \"Context:\", args.context);\n\t}\n\tif (args.sources && args.sources.length > 0) {\n\t\tparts.push(\"\", \"Workspace sources (pointer-first; open the file to read full context):\");\n\t\tfor (const source of args.sources) {\n\t\t\tconst pointer = source.title ?? source.uri ?? source.id;\n\t\t\tparts.push(source.excerpt ? `- ${pointer}: ${source.excerpt}` : `- ${pointer}`);\n\t\t}\n\t}\n\tparts.push(\"\", `Return at most ${args.maxFindings} findings.`);\n\treturn parts.join(\"\\n\");\n}\n\nexport interface ParsedResearchFindings {\n\tfindings: Array<{ summary: string; confidence?: number }>;\n}\n\nexport function parseResearchFindings(text: string, maxFindings: number): ParsedResearchFindings | undefined {\n\tconst trimmed = text.trim();\n\tconst candidates: string[] = [trimmed];\n\tconst fenced = /```(?:json)?\\s*([\\s\\S]*?)```/.exec(trimmed);\n\tif (fenced?.[1]) candidates.push(fenced[1].trim());\n\tconst start = trimmed.indexOf(\"{\");\n\tconst end = trimmed.lastIndexOf(\"}\");\n\tif (start >= 0 && end > start) candidates.push(trimmed.slice(start, end + 1));\n\n\tfor (const candidate of candidates) {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(candidate);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) continue;\n\t\tconst findingsRaw = (parsed as { findings?: unknown }).findings;\n\t\tif (!Array.isArray(findingsRaw)) continue;\n\n\t\tconst findings: Array<{ summary: string; confidence?: number }> = [];\n\t\tfor (const item of findingsRaw) {\n\t\t\tif (!item || typeof item !== \"object\" || Array.isArray(item)) continue;\n\t\t\tconst summary = (item as { summary?: unknown }).summary;\n\t\t\tif (typeof summary !== \"string\" || summary.trim().length === 0) continue;\n\t\t\tconst confidenceRaw = (item as { confidence?: unknown }).confidence;\n\t\t\tconst confidence =\n\t\t\t\ttypeof confidenceRaw === \"number\" && Number.isFinite(confidenceRaw)\n\t\t\t\t\t? Math.min(Math.max(confidenceRaw, 0), 1)\n\t\t\t\t\t: undefined;\n\t\t\tfindings.push({ summary: summary.trim(), confidence });\n\t\t\tif (findings.length >= maxFindings) break;\n\t\t}\n\t\t// A well-formed-but-empty findings array is a valid \"nothing found\"; a findings array whose\n\t\t// every item is malformed is not.\n\t\tif (findings.length > 0 || findingsRaw.length === 0) {\n\t\t\treturn { findings };\n\t\t}\n\t}\n\treturn undefined;\n}\n\nfunction truncateExcerpt(text: string, maxChars: number): string {\n\tif (text.length <= maxChars) return text;\n\treturn `${text.slice(0, Math.max(0, maxChars - 1))}…`;\n}\n\nfunction buildBundle(options: ResearchRunnerOptions, parsed: ParsedResearchFindings): EvidenceBundle {\n\tconst contextRef: EvidenceRef = {\n\t\tid: \"src-context\",\n\t\tkind: \"user\",\n\t\ttitle: \"Goal/context provided to the research lane\",\n\t\ttrusted: true,\n\t\texcerpt: truncateExcerpt(options.context && options.context.length > 0 ? options.context : options.query, 2000),\n\t};\n\tconst synthesisRef: EvidenceRef = {\n\t\tid: \"src-synthesis\",\n\t\tkind: \"tool\",\n\t\ttitle: \"Research-model synthesis\",\n\t\ttrusted: false,\n\t};\n\t// context + synthesis are the fixed provenance anchors (findings cite src-synthesis); workspace\n\t// sources fill whatever budget is left between them, so the anchors are never squeezed out.\n\tconst budget = Math.max(1, options.maxSources);\n\tconst workspaceRoom = Math.max(0, budget - 2);\n\tconst workspaceSources = (options.sources ?? []).slice(0, workspaceRoom);\n\tconst sources = [contextRef, ...workspaceSources, synthesisRef].slice(0, budget);\n\tconst findings: Finding[] = parsed.findings.slice(0, options.maxFindings).map((finding, index) => ({\n\t\tid: `finding-${index + 1}`,\n\t\tsummary: finding.summary,\n\t\tevidenceIds: [synthesisRef.id],\n\t\t...(finding.confidence !== undefined ? { confidence: finding.confidence } : {}),\n\t}));\n\treturn createEvidenceBundle({ query: options.query, sources, findings });\n}\n\nexport async function runResearch(options: ResearchRunnerOptions): Promise<ResearchRunResult> {\n\tconst gateOutcome = evaluateResearchRequest({\n\t\tenvelope: options.envelope,\n\t\tsourceKind: \"tool\",\n\t\testimatedUsd: options.maxUsd,\n\t});\n\tif (gateOutcome.outcome !== \"allow\") {\n\t\t// Skip-and-record, never prompt: gate denials inform diagnostics instead of blocking anything.\n\t\tconst status: ResearchRunStatus = gateOutcome.reasonCode === \"over_budget\" ? \"budget_exhausted\" : \"failed\";\n\t\treturn { status, reasonCode: gateOutcome.reasonCode, gateOutcome, costUsd: 0 };\n\t}\n\n\tconst bounded = await runBoundedCompletion({\n\t\tmaxWallClockMs: options.maxWallClockMs,\n\t\tsignal: options.signal,\n\t\texecute: (signal) =>\n\t\t\toptions.complete({\n\t\t\t\tsystemPrompt: RESEARCH_LANE_SYSTEM_PROMPT,\n\t\t\t\tuserPrompt: buildResearchUserPrompt(options),\n\t\t\t\tsignal,\n\t\t\t}),\n\t});\n\tif (bounded.failure) {\n\t\treturn {\n\t\t\tstatus: bounded.failure.status,\n\t\t\treasonCode: bounded.failure.reasonCode,\n\t\t\tgateOutcome,\n\t\t\tcostUsd: bounded.completion?.costUsd ?? 0,\n\t\t};\n\t}\n\tconst completion = bounded.completion;\n\tif (!completion) {\n\t\treturn { status: \"failed\", reasonCode: \"completion_error\", gateOutcome, costUsd: 0 };\n\t}\n\tif (completion.stopReason === \"error\" || completion.stopReason === \"aborted\") {\n\t\treturn { status: \"failed\", reasonCode: \"model_error\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst parsed = parseResearchFindings(completion.text, options.maxFindings);\n\tif (!parsed) {\n\t\treturn { status: \"failed\", reasonCode: \"unparseable_output\", gateOutcome, costUsd: completion.costUsd };\n\t}\n\n\tconst bundle = buildBundle(options, parsed);\n\tconst overBudget = options.maxUsd > 0 && completion.costUsd > options.maxUsd;\n\treturn {\n\t\tstatus: overBudget ? \"budget_exhausted\" : \"succeeded\",\n\t\treasonCode: overBudget\n\t\t\t? \"cost_budget_exceeded\"\n\t\t\t: parsed.findings.length === 0\n\t\t\t\t? \"no_findings\"\n\t\t\t\t: \"research_completed\",\n\t\tgateOutcome,\n\t\tbundle,\n\t\tcostUsd: completion.costUsd,\n\t};\n}\n"]}

package/dist/core/research/workspace-collector.d.ts

@@ -0,0 +1,25 @@
+import { type ExecFileException } from "node:child_process";
+/** Structural DI seam: only the callback overload the collector actually uses — demanding
+ * node's full `typeof execFile` (with `__promisify__`) makes plain test mocks unassignable. */
+export type WorkspaceExecFileFn = (command: string, args: readonly string[], options: {
+    cwd?: string;
+    timeout?: number;
+    maxBuffer?: number;
+    encoding?: string;
+    windowsHide?: boolean;
+}, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void) => unknown;
+import type { EvidenceRef } from "../autonomy/contracts.ts";
+export interface CollectWorkspaceSourcesArgs {
+    /** Free text (goal + requirement text) that search terms are derived from. */
+    query: string;
+    /** Session working directory; ripgrep runs here and paths are reported relative to it. */
+    cwd: string;
+    /** Hard cap on returned sources; also the lane's source budget. */
+    maxSources: number;
+    /** Injected for tests; defaults to node's `execFile`. */
+    execFileFn?: WorkspaceExecFileFn;
+}
+/** Split on non-word runs, lowercase, drop stopwords/short/dupes, keep source order, cap at MAX_TERMS. */
+export declare function deriveSearchTerms(query: string): string[];
+export declare function collectWorkspaceSources(args: CollectWorkspaceSourcesArgs): Promise<EvidenceRef[]>;
+//# sourceMappingURL=workspace-collector.d.ts.map