@caupulican/pi-adaptative 0.81.38 → 0.81.39

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

@@ -1,14 +1,27 @@
-import { cloneWorkerResultForStorage, isWorkerResult } from "./worker-result.js";
+import { cloneWorkerResultForStorage, isParentReviewRequired, isWorkerResult } from "./worker-result.js";
 export const WORKER_RESULT_CUSTOM_TYPE = "worker_result";
-export function appendWorkerResultSnapshot(sessionManager, result, request) {
+export function appendWorkerResultSnapshot(sessionManager, result, request, 
+/** Baseline for relative changedFiles when re-deriving the review marker; forwarded to
+ * `isParentReviewRequired`/`validateWorkerResult`. Defaults to `process.cwd()`, matching the
+ * validator's own documented default for single-cwd-per-process callers. */
+options) {
+    const stored = cloneWorkerResultForStorage(result);
+    // Stamp the parent-review marker here by re-running the SAME gate
+    // (validateWorkerResult, via isParentReviewRequired) that originally decided
+    // ask-user/parent_review_required, so the marker can never drift from the gate's own verdict.
+    // Only computable when `request` is available; callers that omit it (legacy callers) leave the
+    // field unset — "unknown", never falsely "false".
+    if (request) {
+        stored.parentReviewRequired = isParentReviewRequired({ request, result, cwd: options?.cwd });
+    }
     const payload = {
         version: 1,
-        result: cloneWorkerResultForStorage(result),
+        result: stored,
         ...(request ? { request: structuredClone(request) } : {}),
     };
     return sessionManager.appendCustomEntry(WORKER_RESULT_CUSTOM_TYPE, payload);
 }
-/** Requests persisted alongside results (absent for pre-G2 entries). */
+/** Requests persisted alongside results (absent for entries recorded before this field existed). */
 export function getWorkerRequestSnapshots(entries) {
     const requests = [];
     for (const entry of entries) {
@@ -50,4 +63,51 @@ export function getWorkerResultSnapshots(entries) {
     }
     return results;
 }
+/**
+ * Latest persisted snapshot (result + originating request, when available) for one worker
+ * requestId — "latest wins" over the append-only entries, the same collapse `delegate_status`
+ * already performs when it maps results by requestId. Used to read, and durably update, the
+ * parent-review marker.
+ */
+export function getLatestWorkerResultSnapshot(entries, requestId) {
+    let latest;
+    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 || !("result" in payload))
+            continue;
+        const result = payload.result;
+        if (!isWorkerResult(result) || result.requestId !== requestId)
+            continue;
+        const request = payload.request;
+        latest = {
+            version: 1,
+            result: cloneWorkerResultForStorage(result),
+            ...(isPlainRecord(request) && typeof request.id === "string"
+                ? { request: structuredClone(request) }
+                : {}),
+        };
+    }
+    return latest;
+}
+/**
+ * Durably acknowledge an unreviewed worker mutation. Re-appends the latest snapshot for
+ * `requestId` with `parentReviewedAt` set, so the ack is a first-class entry in the same
+ * append-only audit trail as the original result — it survives reload and any future re-read of
+ * `getWorkerResultSnapshots`/`getLatestWorkerResultSnapshot` (both are "latest wins"). Never
+ * write-blocking: this only marks the mutation reviewed, it does not touch the worker's files.
+ */
+export function acknowledgeWorkerResultReview(sessionManager, requestId, now = () => new Date().toISOString()) {
+    const latest = getLatestWorkerResultSnapshot(sessionManager.getEntries(), requestId);
+    if (!latest)
+        return { ok: false, reason: "unknown_worker_result" };
+    if (!latest.result.parentReviewRequired)
+        return { ok: false, reason: "not_flagged" };
+    if (latest.result.parentReviewedAt)
+        return { ok: false, reason: "already_reviewed" };
+    const reviewedAt = now();
+    appendWorkerResultSnapshot(sessionManager, { ...latest.result, parentReviewedAt: reviewedAt }, latest.request);
+    return { ok: true, requestId, reviewedAt };
+}
 //# sourceMappingURL=session-worker-result.js.map

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;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 { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { WorkerRequest, WorkerResult } from \"../autonomy/contracts.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"]}
+{"version":3,"file":"session-worker-result.js","sourceRoot":"","sources":["../../../src/core/delegation/session-worker-result.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { WorkerRequest, WorkerResult } from \"../autonomy/contracts.ts\";\nimport { cloneWorkerResultForStorage, isParentReviewRequired, 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: 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 entries recorded before this field existed. */\n\trequest?: WorkerRequest;\n}\n\nexport function appendWorkerResultSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tresult: WorkerResult,\n\trequest?: WorkerRequest,\n\t/** Baseline for relative changedFiles when re-deriving the review marker; forwarded to\n\t * `isParentReviewRequired`/`validateWorkerResult`. Defaults to `process.cwd()`, matching the\n\t * validator's own documented default for single-cwd-per-process callers. */\n\toptions?: { cwd?: string },\n): string {\n\tconst stored = cloneWorkerResultForStorage(result);\n\t// Stamp the parent-review marker here by re-running the SAME gate\n\t// (validateWorkerResult, via isParentReviewRequired) that originally decided\n\t// ask-user/parent_review_required, so the marker can never drift from the gate's own verdict.\n\t// Only computable when `request` is available; callers that omit it (legacy callers) leave the\n\t// field unset — \"unknown\", never falsely \"false\".\n\tif (request) {\n\t\tstored.parentReviewRequired = isParentReviewRequired({ request, result, cwd: options?.cwd });\n\t}\n\tconst payload: WorkerResultSnapshotPayload = {\n\t\tversion: 1,\n\t\tresult: stored,\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 entries recorded before this field existed). */\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\n/**\n * Latest persisted snapshot (result + originating request, when available) for one worker\n * requestId — \"latest wins\" over the append-only entries, the same collapse `delegate_status`\n * already performs when it maps results by requestId. Used to read, and durably update, the\n * parent-review marker.\n */\nexport function getLatestWorkerResultSnapshot(\n\tentries: readonly SessionEntry[],\n\trequestId: string,\n): WorkerResultSnapshotPayload | undefined {\n\tlet latest: WorkerResultSnapshotPayload | undefined;\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 || !(\"result\" in payload)) continue;\n\t\tconst result = payload.result;\n\t\tif (!isWorkerResult(result) || result.requestId !== requestId) continue;\n\t\tconst request = payload.request;\n\t\tlatest = {\n\t\t\tversion: 1,\n\t\t\tresult: cloneWorkerResultForStorage(result),\n\t\t\t...(isPlainRecord(request) && typeof request.id === \"string\"\n\t\t\t\t? { request: structuredClone(request) as unknown as WorkerRequest }\n\t\t\t\t: {}),\n\t\t};\n\t}\n\treturn latest;\n}\n\nexport type AcknowledgeWorkerReviewReason = \"unknown_worker_result\" | \"not_flagged\" | \"already_reviewed\";\n\nexport type AcknowledgeWorkerReviewResult =\n\t| { ok: true; requestId: string; reviewedAt: string }\n\t| { ok: false; reason: AcknowledgeWorkerReviewReason };\n\n/**\n * Durably acknowledge an unreviewed worker mutation. Re-appends the latest snapshot for\n * `requestId` with `parentReviewedAt` set, so the ack is a first-class entry in the same\n * append-only audit trail as the original result — it survives reload and any future re-read of\n * `getWorkerResultSnapshots`/`getLatestWorkerResultSnapshot` (both are \"latest wins\"). Never\n * write-blocking: this only marks the mutation reviewed, it does not touch the worker's files.\n */\nexport function acknowledgeWorkerResultReview(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\" | \"getEntries\">,\n\trequestId: string,\n\tnow: () => string = () => new Date().toISOString(),\n): AcknowledgeWorkerReviewResult {\n\tconst latest = getLatestWorkerResultSnapshot(sessionManager.getEntries(), requestId);\n\tif (!latest) return { ok: false, reason: \"unknown_worker_result\" };\n\tif (!latest.result.parentReviewRequired) return { ok: false, reason: \"not_flagged\" };\n\tif (latest.result.parentReviewedAt) return { ok: false, reason: \"already_reviewed\" };\n\tconst reviewedAt = now();\n\tappendWorkerResultSnapshot(sessionManager, { ...latest.result, parentReviewedAt: reviewedAt }, latest.request);\n\treturn { ok: true, requestId, reviewedAt };\n}\n"]}

package/dist/core/delegation/worker-result.d.ts

@@ -1,7 +1,20 @@
-import type { GateOutcome, WorkerRequest, WorkerResult } from "../autonomy/contracts.ts";
+import type { CapabilityEnvelope, GateOutcome, WorkerRequest, WorkerResult } from "../autonomy/contracts.ts";
 export declare function cloneWorkerResultForStorage(result: WorkerResult): WorkerResult;
 export declare function isWorkerResult(value: unknown): value is WorkerResult;
 export declare function requiresParentReview(result: WorkerResult): boolean;
+/**
+ * True iff {@link validateWorkerResult}'s gate would flag this result "ask-user" /
+ * "parent_review_required" (the two branches at :110 and :178 below) — an otherwise-completed
+ * result the parent must explicitly look at because it reports blockers, or reports file mutations
+ * that passed path-scope validation. Reuses `validateWorkerResult` itself rather than a
+ * separately-maintained heuristic, so a persisted review marker can never drift from the
+ * gate's actual verdict.
+ */
+export declare function isParentReviewRequired(args: {
+    request: WorkerRequest;
+    result: WorkerResult;
+    cwd?: string;
+}): boolean;
 export declare function validateWorkerResult(args: {
     request: WorkerRequest;
     result: WorkerResult;
@@ -12,4 +25,32 @@ export declare function validateWorkerResult(args: {
      */
     cwd?: string;
 }): GateOutcome;
+/**
+ * Path-scope-only re-review for a SELF-REPORTED (out-of-process) worker's claimed `changedFiles`
+ * -- e.g. a tmux worker's own completion report, which (unlike an in-process worker's) never
+ * passed through this process's `applyWorkerActions` envelope enforcement before the write
+ * happened; the tmux worker's tool loop runs in a separate process this session does not gate.
+ * Reuses {@link validateWorkerResult}'s exact symlink-safe scope check verbatim -- never
+ * reimplement path resolution: synthesizes a minimal, always-"completed" request/result pair
+ * carrying only the reported `changedFiles` and the scope's `allowedPaths`/`deniedPaths`, so the
+ * ONLY thing that can vary the verdict is the path-scope branch.
+ *
+ * Deliberately broader than {@link isParentReviewRequired}: that helper only flags the gate's
+ * "ask-user" branch, which is correct for an in-process worker (a write that would have been
+ * "block"-worthy was already refused before it could happen, by the SAME envelope, via
+ * `applyWorkerActions`). A self-reported claim has no such backstop -- an out-of-scope or denied
+ * path already happened on the real filesystem whether or not this gate would allow it, so here
+ * ANY non-"allow" verdict (in scope, out of scope, or no scope configured at all) means a human
+ * must look, not "the write didn't happen".
+ */
+export declare function reviewManagedLaneChangedFiles(args: {
+    changedFiles: readonly string[];
+    /** The scope to validate against -- e.g. the session's active `CapabilityEnvelope`, until a
+     * per-launch tmux standing grant envelope lands in a later wave (documented follow-up). */
+    envelope: Pick<CapabilityEnvelope, "allowedPaths" | "deniedPaths">;
+    cwd?: string;
+}): {
+    reviewRequired: boolean;
+    reasonCode: string;
+};
 //# sourceMappingURL=worker-result.d.ts.map

package/dist/core/delegation/worker-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-result.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-result.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAIzF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAQ9E;AAQD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CA4BpE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAWlE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,WAAW,CAmHd","sourcesContent":["import path from \"node:path\";\nimport type { GateOutcome, WorkerRequest, WorkerResult } from \"../autonomy/contracts.ts\";\nimport { checkPathScope } from \"../autonomy/path-scope.ts\";\nimport { cloneEvidenceBundleForStorage, isEvidenceBundle } from \"../research/evidence-bundle.ts\";\n\nexport function cloneWorkerResultForStorage(result: WorkerResult): WorkerResult {\n\treturn {\n\t\t...result,\n\t\t...(result.outputFormat ? { outputFormat: result.outputFormat } : {}),\n\t\tchangedFiles: [...result.changedFiles],\n\t\tblockers: result.blockers ? [...result.blockers] : undefined,\n\t\tevidence: result.evidence ? cloneEvidenceBundleForStorage(result.evidence) : undefined,\n\t};\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 isWorkerResult(value: unknown): value is WorkerResult {\n\tif (!isPlainRecord(value)) return false;\n\tconst obj = value as Record<string, unknown>;\n\n\tif (typeof obj.requestId !== \"string\") return false;\n\tif (typeof obj.status !== \"string\" || ![\"completed\", \"blocked\", \"failed\", \"cancelled\"].includes(obj.status)) {\n\t\treturn false;\n\t}\n\tif (typeof obj.summary !== \"string\") return false;\n\tif (obj.outputFormat !== undefined && obj.outputFormat !== \"structured\" && obj.outputFormat !== \"plain_text\")\n\t\treturn false;\n\n\tif (!Array.isArray(obj.changedFiles) || !obj.changedFiles.every((f) => typeof f === \"string\")) {\n\t\treturn false;\n\t}\n\n\tif (obj.blockers !== undefined) {\n\t\tif (!Array.isArray(obj.blockers) || !obj.blockers.every((b) => typeof b === \"string\")) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tif (obj.usageReportId !== undefined && typeof obj.usageReportId !== \"string\") return false;\n\tif (obj.createdAt !== undefined && typeof obj.createdAt !== \"string\") return false;\n\n\tif (obj.evidence !== undefined && !isEvidenceBundle(obj.evidence)) return false;\n\n\treturn true;\n}\n\nexport function requiresParentReview(result: WorkerResult): boolean {\n\tif (result.status !== \"completed\") {\n\t\treturn true;\n\t}\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn true;\n\t}\n\tif (result.changedFiles.length > 0) {\n\t\treturn true;\n\t}\n\treturn false;\n}\n\nexport function validateWorkerResult(args: {\n\trequest: WorkerRequest;\n\tresult: WorkerResult;\n\t/**\n\t * Baseline for relative paths — BOTH the runner's cwd-relative `changedFiles` and the\n\t * envelope's possibly-relative path scopes resolve against this. Defaults to process.cwd()\n\t * for callers whose session cwd is the process cwd.\n\t */\n\tcwd?: string;\n}): GateOutcome {\n\tconst { request, result } = args;\n\tconst baseDir = args.cwd ?? process.cwd();\n\n\tif (result.requestId !== request.id) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"request_id_mismatch\",\n\t\t\tmessage: `Result requestId '${result.requestId}' does not match request id '${request.id}'.`,\n\t\t};\n\t}\n\n\tif (result.status !== \"completed\") {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"worker_not_completed\",\n\t\t\tmessage: `Worker finished with status '${result.status}'.`,\n\t\t\tdetails: result.blockers && result.blockers.length > 0 ? { blockers: [...result.blockers] } : undefined,\n\t\t};\n\t}\n\n\tif (!result.usageReportId) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"missing_usage_report\",\n\t\t\tmessage: \"Completed worker result is missing usageReportId.\",\n\t\t};\n\t}\n\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Completed worker result includes blockers and requires parent review.\",\n\t\t\tdetails: { blockers: [...result.blockers] },\n\t\t};\n\t}\n\n\tif (result.changedFiles.length > 0) {\n\t\tif (!request.envelope.allowedPaths || request.envelope.allowedPaths.length === 0) {\n\t\t\treturn {\n\t\t\t\toutcome: \"block\",\n\t\t\t\tgate: \"worker_result\",\n\t\t\t\treasonCode: \"missing_path_scope\",\n\t\t\t\tmessage: \"Worker changed files but no allowedPaths are configured in the envelope.\",\n\t\t\t};\n\t\t}\n\n\t\t// The runner reports changed files relative to the session cwd — resolve file and scope\n\t\t// roots against the SAME baseline. Resolving per-root double-prefixed nested names and\n\t\t// let a denied subtree slip past the deny rule.\n\t\tconst resolvedAllowed = request.envelope.allowedPaths.map((p) => path.resolve(baseDir, p));\n\t\tconst resolvedDenied = request.envelope.deniedPaths?.map((p) => path.resolve(baseDir, p));\n\t\tfor (const changedFile of result.changedFiles) {\n\t\t\tlet isInsideAny = false;\n\t\t\tlet isDenied = false;\n\n\t\t\tconst scopedChangedFile = path.resolve(baseDir, changedFile);\n\t\t\tfor (const root of resolvedAllowed) {\n\t\t\t\tconst decision = checkPathScope(\n\t\t\t\t\t{\n\t\t\t\t\t\troot,\n\t\t\t\t\t\tallowedPaths: resolvedAllowed,\n\t\t\t\t\t\tdeniedPaths: resolvedDenied,\n\t\t\t\t\t},\n\t\t\t\t\tscopedChangedFile,\n\t\t\t\t);\n\n\t\t\t\tif (decision.kind === \"denied\") {\n\t\t\t\t\tisDenied = true;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (decision.kind === \"inside\") {\n\t\t\t\t\tisInsideAny = true;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (isDenied) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_denied\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' which matches a denied path.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (!isInsideAny) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_outside_scope\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' outside allowed scope.`,\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\t// Files are inside scope, but worker output is untrusted\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Worker changed files require parent review.\",\n\t\t};\n\t}\n\n\treturn {\n\t\toutcome: \"allow\",\n\t\tgate: \"worker_result\",\n\t\treasonCode: \"allowed\",\n\t\tmessage: \"Worker result is read-only and allowed.\",\n\t};\n}\n"]}
+{"version":3,"file":"worker-result.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-result.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7G,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAQ9E;AAQD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CA8BpE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAWlE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAGpH;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,WAAW,CAmHd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IACnD,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;+FAC2F;IAC3F,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAiClD","sourcesContent":["import path from \"node:path\";\nimport type { CapabilityEnvelope, GateOutcome, WorkerRequest, WorkerResult } from \"../autonomy/contracts.ts\";\nimport { checkPathScope } from \"../autonomy/path-scope.ts\";\nimport { cloneEvidenceBundleForStorage, isEvidenceBundle } from \"../research/evidence-bundle.ts\";\n\nexport function cloneWorkerResultForStorage(result: WorkerResult): WorkerResult {\n\treturn {\n\t\t...result,\n\t\t...(result.outputFormat ? { outputFormat: result.outputFormat } : {}),\n\t\tchangedFiles: [...result.changedFiles],\n\t\tblockers: result.blockers ? [...result.blockers] : undefined,\n\t\tevidence: result.evidence ? cloneEvidenceBundleForStorage(result.evidence) : undefined,\n\t};\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 isWorkerResult(value: unknown): value is WorkerResult {\n\tif (!isPlainRecord(value)) return false;\n\tconst obj = value as Record<string, unknown>;\n\n\tif (typeof obj.requestId !== \"string\") return false;\n\tif (typeof obj.status !== \"string\" || ![\"completed\", \"blocked\", \"failed\", \"cancelled\"].includes(obj.status)) {\n\t\treturn false;\n\t}\n\tif (typeof obj.summary !== \"string\") return false;\n\tif (obj.outputFormat !== undefined && obj.outputFormat !== \"structured\" && obj.outputFormat !== \"plain_text\")\n\t\treturn false;\n\n\tif (!Array.isArray(obj.changedFiles) || !obj.changedFiles.every((f) => typeof f === \"string\")) {\n\t\treturn false;\n\t}\n\n\tif (obj.blockers !== undefined) {\n\t\tif (!Array.isArray(obj.blockers) || !obj.blockers.every((b) => typeof b === \"string\")) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tif (obj.usageReportId !== undefined && typeof obj.usageReportId !== \"string\") return false;\n\tif (obj.createdAt !== undefined && typeof obj.createdAt !== \"string\") return false;\n\tif (obj.parentReviewRequired !== undefined && typeof obj.parentReviewRequired !== \"boolean\") return false;\n\tif (obj.parentReviewedAt !== undefined && typeof obj.parentReviewedAt !== \"string\") return false;\n\n\tif (obj.evidence !== undefined && !isEvidenceBundle(obj.evidence)) return false;\n\n\treturn true;\n}\n\nexport function requiresParentReview(result: WorkerResult): boolean {\n\tif (result.status !== \"completed\") {\n\t\treturn true;\n\t}\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn true;\n\t}\n\tif (result.changedFiles.length > 0) {\n\t\treturn true;\n\t}\n\treturn false;\n}\n\n/**\n * True iff {@link validateWorkerResult}'s gate would flag this result \"ask-user\" /\n * \"parent_review_required\" (the two branches at :110 and :178 below) — an otherwise-completed\n * result the parent must explicitly look at because it reports blockers, or reports file mutations\n * that passed path-scope validation. Reuses `validateWorkerResult` itself rather than a\n * separately-maintained heuristic, so a persisted review marker can never drift from the\n * gate's actual verdict.\n */\nexport function isParentReviewRequired(args: { request: WorkerRequest; result: WorkerResult; cwd?: string }): boolean {\n\tconst acceptance = validateWorkerResult(args);\n\treturn acceptance.outcome === \"ask-user\" && acceptance.reasonCode === \"parent_review_required\";\n}\n\nexport function validateWorkerResult(args: {\n\trequest: WorkerRequest;\n\tresult: WorkerResult;\n\t/**\n\t * Baseline for relative paths — BOTH the runner's cwd-relative `changedFiles` and the\n\t * envelope's possibly-relative path scopes resolve against this. Defaults to process.cwd()\n\t * for callers whose session cwd is the process cwd.\n\t */\n\tcwd?: string;\n}): GateOutcome {\n\tconst { request, result } = args;\n\tconst baseDir = args.cwd ?? process.cwd();\n\n\tif (result.requestId !== request.id) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"request_id_mismatch\",\n\t\t\tmessage: `Result requestId '${result.requestId}' does not match request id '${request.id}'.`,\n\t\t};\n\t}\n\n\tif (result.status !== \"completed\") {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"worker_not_completed\",\n\t\t\tmessage: `Worker finished with status '${result.status}'.`,\n\t\t\tdetails: result.blockers && result.blockers.length > 0 ? { blockers: [...result.blockers] } : undefined,\n\t\t};\n\t}\n\n\tif (!result.usageReportId) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"missing_usage_report\",\n\t\t\tmessage: \"Completed worker result is missing usageReportId.\",\n\t\t};\n\t}\n\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Completed worker result includes blockers and requires parent review.\",\n\t\t\tdetails: { blockers: [...result.blockers] },\n\t\t};\n\t}\n\n\tif (result.changedFiles.length > 0) {\n\t\tif (!request.envelope.allowedPaths || request.envelope.allowedPaths.length === 0) {\n\t\t\treturn {\n\t\t\t\toutcome: \"block\",\n\t\t\t\tgate: \"worker_result\",\n\t\t\t\treasonCode: \"missing_path_scope\",\n\t\t\t\tmessage: \"Worker changed files but no allowedPaths are configured in the envelope.\",\n\t\t\t};\n\t\t}\n\n\t\t// The runner reports changed files relative to the session cwd — resolve file and scope\n\t\t// roots against the SAME baseline. Resolving per-root double-prefixed nested names and\n\t\t// let a denied subtree slip past the deny rule.\n\t\tconst resolvedAllowed = request.envelope.allowedPaths.map((p) => path.resolve(baseDir, p));\n\t\tconst resolvedDenied = request.envelope.deniedPaths?.map((p) => path.resolve(baseDir, p));\n\t\tfor (const changedFile of result.changedFiles) {\n\t\t\tlet isInsideAny = false;\n\t\t\tlet isDenied = false;\n\n\t\t\tconst scopedChangedFile = path.resolve(baseDir, changedFile);\n\t\t\tfor (const root of resolvedAllowed) {\n\t\t\t\tconst decision = checkPathScope(\n\t\t\t\t\t{\n\t\t\t\t\t\troot,\n\t\t\t\t\t\tallowedPaths: resolvedAllowed,\n\t\t\t\t\t\tdeniedPaths: resolvedDenied,\n\t\t\t\t\t},\n\t\t\t\t\tscopedChangedFile,\n\t\t\t\t);\n\n\t\t\t\tif (decision.kind === \"denied\") {\n\t\t\t\t\tisDenied = true;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (decision.kind === \"inside\") {\n\t\t\t\t\tisInsideAny = true;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (isDenied) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_denied\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' which matches a denied path.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (!isInsideAny) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_outside_scope\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' outside allowed scope.`,\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\t// Files are inside scope, but worker output is untrusted\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Worker changed files require parent review.\",\n\t\t};\n\t}\n\n\treturn {\n\t\toutcome: \"allow\",\n\t\tgate: \"worker_result\",\n\t\treasonCode: \"allowed\",\n\t\tmessage: \"Worker result is read-only and allowed.\",\n\t};\n}\n\n/**\n * Path-scope-only re-review for a SELF-REPORTED (out-of-process) worker's claimed `changedFiles`\n * -- e.g. a tmux worker's own completion report, which (unlike an in-process worker's) never\n * passed through this process's `applyWorkerActions` envelope enforcement before the write\n * happened; the tmux worker's tool loop runs in a separate process this session does not gate.\n * Reuses {@link validateWorkerResult}'s exact symlink-safe scope check verbatim -- never\n * reimplement path resolution: synthesizes a minimal, always-\"completed\" request/result pair\n * carrying only the reported `changedFiles` and the scope's `allowedPaths`/`deniedPaths`, so the\n * ONLY thing that can vary the verdict is the path-scope branch.\n *\n * Deliberately broader than {@link isParentReviewRequired}: that helper only flags the gate's\n * \"ask-user\" branch, which is correct for an in-process worker (a write that would have been\n * \"block\"-worthy was already refused before it could happen, by the SAME envelope, via\n * `applyWorkerActions`). A self-reported claim has no such backstop -- an out-of-scope or denied\n * path already happened on the real filesystem whether or not this gate would allow it, so here\n * ANY non-\"allow\" verdict (in scope, out of scope, or no scope configured at all) means a human\n * must look, not \"the write didn't happen\".\n */\nexport function reviewManagedLaneChangedFiles(args: {\n\tchangedFiles: readonly string[];\n\t/** The scope to validate against -- e.g. the session's active `CapabilityEnvelope`, until a\n\t * per-launch tmux standing grant envelope lands in a later wave (documented follow-up). */\n\tenvelope: Pick<CapabilityEnvelope, \"allowedPaths\" | \"deniedPaths\">;\n\tcwd?: string;\n}): { reviewRequired: boolean; reasonCode: string } {\n\tif (args.changedFiles.length === 0) {\n\t\treturn { reviewRequired: false, reasonCode: \"no_changed_files\" };\n\t}\n\tconst syntheticId = \"managed-lane-review\";\n\tconst acceptance = validateWorkerResult({\n\t\trequest: {\n\t\t\tid: syntheticId,\n\t\t\tinstructions: \"\",\n\t\t\troute: {\n\t\t\t\ttier: \"cheap\",\n\t\t\t\trisk: \"scoped-write\",\n\t\t\t\tconfidence: 1,\n\t\t\t\treasonCode: \"managed_lane_review\",\n\t\t\t\treasons: [],\n\t\t\t},\n\t\t\tenvelope: {\n\t\t\t\tid: syntheticId,\n\t\t\t\tcapabilities: [\"write_files\"],\n\t\t\t\tallowedPaths: args.envelope.allowedPaths,\n\t\t\t\tdeniedPaths: args.envelope.deniedPaths,\n\t\t\t},\n\t\t},\n\t\tresult: {\n\t\t\trequestId: syntheticId,\n\t\t\tstatus: \"completed\",\n\t\t\tsummary: \"\",\n\t\t\tchangedFiles: [...args.changedFiles],\n\t\t\tusageReportId: syntheticId,\n\t\t},\n\t\tcwd: args.cwd,\n\t});\n\treturn { reviewRequired: acceptance.outcome !== \"allow\", reasonCode: acceptance.reasonCode };\n}\n"]}

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

@@ -41,6 +41,10 @@ export function isWorkerResult(value) {
         return false;
     if (obj.createdAt !== undefined && typeof obj.createdAt !== "string")
         return false;
+    if (obj.parentReviewRequired !== undefined && typeof obj.parentReviewRequired !== "boolean")
+        return false;
+    if (obj.parentReviewedAt !== undefined && typeof obj.parentReviewedAt !== "string")
+        return false;
     if (obj.evidence !== undefined && !isEvidenceBundle(obj.evidence))
         return false;
     return true;
@@ -57,6 +61,18 @@ export function requiresParentReview(result) {
     }
     return false;
 }
+/**
+ * True iff {@link validateWorkerResult}'s gate would flag this result "ask-user" /
+ * "parent_review_required" (the two branches at :110 and :178 below) — an otherwise-completed
+ * result the parent must explicitly look at because it reports blockers, or reports file mutations
+ * that passed path-scope validation. Reuses `validateWorkerResult` itself rather than a
+ * separately-maintained heuristic, so a persisted review marker can never drift from the
+ * gate's actual verdict.
+ */
+export function isParentReviewRequired(args) {
+    const acceptance = validateWorkerResult(args);
+    return acceptance.outcome === "ask-user" && acceptance.reasonCode === "parent_review_required";
+}
 export function validateWorkerResult(args) {
     const { request, result } = args;
     const baseDir = args.cwd ?? process.cwd();
@@ -158,4 +174,56 @@ export function validateWorkerResult(args) {
         message: "Worker result is read-only and allowed.",
     };
 }
+/**
+ * Path-scope-only re-review for a SELF-REPORTED (out-of-process) worker's claimed `changedFiles`
+ * -- e.g. a tmux worker's own completion report, which (unlike an in-process worker's) never
+ * passed through this process's `applyWorkerActions` envelope enforcement before the write
+ * happened; the tmux worker's tool loop runs in a separate process this session does not gate.
+ * Reuses {@link validateWorkerResult}'s exact symlink-safe scope check verbatim -- never
+ * reimplement path resolution: synthesizes a minimal, always-"completed" request/result pair
+ * carrying only the reported `changedFiles` and the scope's `allowedPaths`/`deniedPaths`, so the
+ * ONLY thing that can vary the verdict is the path-scope branch.
+ *
+ * Deliberately broader than {@link isParentReviewRequired}: that helper only flags the gate's
+ * "ask-user" branch, which is correct for an in-process worker (a write that would have been
+ * "block"-worthy was already refused before it could happen, by the SAME envelope, via
+ * `applyWorkerActions`). A self-reported claim has no such backstop -- an out-of-scope or denied
+ * path already happened on the real filesystem whether or not this gate would allow it, so here
+ * ANY non-"allow" verdict (in scope, out of scope, or no scope configured at all) means a human
+ * must look, not "the write didn't happen".
+ */
+export function reviewManagedLaneChangedFiles(args) {
+    if (args.changedFiles.length === 0) {
+        return { reviewRequired: false, reasonCode: "no_changed_files" };
+    }
+    const syntheticId = "managed-lane-review";
+    const acceptance = validateWorkerResult({
+        request: {
+            id: syntheticId,
+            instructions: "",
+            route: {
+                tier: "cheap",
+                risk: "scoped-write",
+                confidence: 1,
+                reasonCode: "managed_lane_review",
+                reasons: [],
+            },
+            envelope: {
+                id: syntheticId,
+                capabilities: ["write_files"],
+                allowedPaths: args.envelope.allowedPaths,
+                deniedPaths: args.envelope.deniedPaths,
+            },
+        },
+        result: {
+            requestId: syntheticId,
+            status: "completed",
+            summary: "",
+            changedFiles: [...args.changedFiles],
+            usageReportId: syntheticId,
+        },
+        cwd: args.cwd,
+    });
+    return { reviewRequired: acceptance.outcome !== "allow", reasonCode: acceptance.reasonCode };
+}
 //# sourceMappingURL=worker-result.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"worker-result.js","sourceRoot":"","sources":["../../../src/core/delegation/worker-result.ts"],"names":[],"mappings":"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","sourcesContent":["import path from \"node:path\";\nimport type { GateOutcome, WorkerRequest, WorkerResult } from \"../autonomy/contracts.ts\";\nimport { checkPathScope } from \"../autonomy/path-scope.ts\";\nimport { cloneEvidenceBundleForStorage, isEvidenceBundle } from \"../research/evidence-bundle.ts\";\n\nexport function cloneWorkerResultForStorage(result: WorkerResult): WorkerResult {\n\treturn {\n\t\t...result,\n\t\t...(result.outputFormat ? { outputFormat: result.outputFormat } : {}),\n\t\tchangedFiles: [...result.changedFiles],\n\t\tblockers: result.blockers ? [...result.blockers] : undefined,\n\t\tevidence: result.evidence ? cloneEvidenceBundleForStorage(result.evidence) : undefined,\n\t};\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 isWorkerResult(value: unknown): value is WorkerResult {\n\tif (!isPlainRecord(value)) return false;\n\tconst obj = value as Record<string, unknown>;\n\n\tif (typeof obj.requestId !== \"string\") return false;\n\tif (typeof obj.status !== \"string\" || ![\"completed\", \"blocked\", \"failed\", \"cancelled\"].includes(obj.status)) {\n\t\treturn false;\n\t}\n\tif (typeof obj.summary !== \"string\") return false;\n\tif (obj.outputFormat !== undefined && obj.outputFormat !== \"structured\" && obj.outputFormat !== \"plain_text\")\n\t\treturn false;\n\n\tif (!Array.isArray(obj.changedFiles) || !obj.changedFiles.every((f) => typeof f === \"string\")) {\n\t\treturn false;\n\t}\n\n\tif (obj.blockers !== undefined) {\n\t\tif (!Array.isArray(obj.blockers) || !obj.blockers.every((b) => typeof b === \"string\")) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tif (obj.usageReportId !== undefined && typeof obj.usageReportId !== \"string\") return false;\n\tif (obj.createdAt !== undefined && typeof obj.createdAt !== \"string\") return false;\n\n\tif (obj.evidence !== undefined && !isEvidenceBundle(obj.evidence)) return false;\n\n\treturn true;\n}\n\nexport function requiresParentReview(result: WorkerResult): boolean {\n\tif (result.status !== \"completed\") {\n\t\treturn true;\n\t}\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn true;\n\t}\n\tif (result.changedFiles.length > 0) {\n\t\treturn true;\n\t}\n\treturn false;\n}\n\nexport function validateWorkerResult(args: {\n\trequest: WorkerRequest;\n\tresult: WorkerResult;\n\t/**\n\t * Baseline for relative paths — BOTH the runner's cwd-relative `changedFiles` and the\n\t * envelope's possibly-relative path scopes resolve against this. Defaults to process.cwd()\n\t * for callers whose session cwd is the process cwd.\n\t */\n\tcwd?: string;\n}): GateOutcome {\n\tconst { request, result } = args;\n\tconst baseDir = args.cwd ?? process.cwd();\n\n\tif (result.requestId !== request.id) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"request_id_mismatch\",\n\t\t\tmessage: `Result requestId '${result.requestId}' does not match request id '${request.id}'.`,\n\t\t};\n\t}\n\n\tif (result.status !== \"completed\") {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"worker_not_completed\",\n\t\t\tmessage: `Worker finished with status '${result.status}'.`,\n\t\t\tdetails: result.blockers && result.blockers.length > 0 ? { blockers: [...result.blockers] } : undefined,\n\t\t};\n\t}\n\n\tif (!result.usageReportId) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"missing_usage_report\",\n\t\t\tmessage: \"Completed worker result is missing usageReportId.\",\n\t\t};\n\t}\n\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Completed worker result includes blockers and requires parent review.\",\n\t\t\tdetails: { blockers: [...result.blockers] },\n\t\t};\n\t}\n\n\tif (result.changedFiles.length > 0) {\n\t\tif (!request.envelope.allowedPaths || request.envelope.allowedPaths.length === 0) {\n\t\t\treturn {\n\t\t\t\toutcome: \"block\",\n\t\t\t\tgate: \"worker_result\",\n\t\t\t\treasonCode: \"missing_path_scope\",\n\t\t\t\tmessage: \"Worker changed files but no allowedPaths are configured in the envelope.\",\n\t\t\t};\n\t\t}\n\n\t\t// The runner reports changed files relative to the session cwd — resolve file and scope\n\t\t// roots against the SAME baseline. Resolving per-root double-prefixed nested names and\n\t\t// let a denied subtree slip past the deny rule.\n\t\tconst resolvedAllowed = request.envelope.allowedPaths.map((p) => path.resolve(baseDir, p));\n\t\tconst resolvedDenied = request.envelope.deniedPaths?.map((p) => path.resolve(baseDir, p));\n\t\tfor (const changedFile of result.changedFiles) {\n\t\t\tlet isInsideAny = false;\n\t\t\tlet isDenied = false;\n\n\t\t\tconst scopedChangedFile = path.resolve(baseDir, changedFile);\n\t\t\tfor (const root of resolvedAllowed) {\n\t\t\t\tconst decision = checkPathScope(\n\t\t\t\t\t{\n\t\t\t\t\t\troot,\n\t\t\t\t\t\tallowedPaths: resolvedAllowed,\n\t\t\t\t\t\tdeniedPaths: resolvedDenied,\n\t\t\t\t\t},\n\t\t\t\t\tscopedChangedFile,\n\t\t\t\t);\n\n\t\t\t\tif (decision.kind === \"denied\") {\n\t\t\t\t\tisDenied = true;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (decision.kind === \"inside\") {\n\t\t\t\t\tisInsideAny = true;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (isDenied) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_denied\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' which matches a denied path.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (!isInsideAny) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_outside_scope\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' outside allowed scope.`,\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\t// Files are inside scope, but worker output is untrusted\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Worker changed files require parent review.\",\n\t\t};\n\t}\n\n\treturn {\n\t\toutcome: \"allow\",\n\t\tgate: \"worker_result\",\n\t\treasonCode: \"allowed\",\n\t\tmessage: \"Worker result is read-only and allowed.\",\n\t};\n}\n"]}
+{"version":3,"file":"worker-result.js","sourceRoot":"","sources":["../../../src/core/delegation/worker-result.ts"],"names":[],"mappings":"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","sourcesContent":["import path from \"node:path\";\nimport type { CapabilityEnvelope, GateOutcome, WorkerRequest, WorkerResult } from \"../autonomy/contracts.ts\";\nimport { checkPathScope } from \"../autonomy/path-scope.ts\";\nimport { cloneEvidenceBundleForStorage, isEvidenceBundle } from \"../research/evidence-bundle.ts\";\n\nexport function cloneWorkerResultForStorage(result: WorkerResult): WorkerResult {\n\treturn {\n\t\t...result,\n\t\t...(result.outputFormat ? { outputFormat: result.outputFormat } : {}),\n\t\tchangedFiles: [...result.changedFiles],\n\t\tblockers: result.blockers ? [...result.blockers] : undefined,\n\t\tevidence: result.evidence ? cloneEvidenceBundleForStorage(result.evidence) : undefined,\n\t};\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 isWorkerResult(value: unknown): value is WorkerResult {\n\tif (!isPlainRecord(value)) return false;\n\tconst obj = value as Record<string, unknown>;\n\n\tif (typeof obj.requestId !== \"string\") return false;\n\tif (typeof obj.status !== \"string\" || ![\"completed\", \"blocked\", \"failed\", \"cancelled\"].includes(obj.status)) {\n\t\treturn false;\n\t}\n\tif (typeof obj.summary !== \"string\") return false;\n\tif (obj.outputFormat !== undefined && obj.outputFormat !== \"structured\" && obj.outputFormat !== \"plain_text\")\n\t\treturn false;\n\n\tif (!Array.isArray(obj.changedFiles) || !obj.changedFiles.every((f) => typeof f === \"string\")) {\n\t\treturn false;\n\t}\n\n\tif (obj.blockers !== undefined) {\n\t\tif (!Array.isArray(obj.blockers) || !obj.blockers.every((b) => typeof b === \"string\")) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tif (obj.usageReportId !== undefined && typeof obj.usageReportId !== \"string\") return false;\n\tif (obj.createdAt !== undefined && typeof obj.createdAt !== \"string\") return false;\n\tif (obj.parentReviewRequired !== undefined && typeof obj.parentReviewRequired !== \"boolean\") return false;\n\tif (obj.parentReviewedAt !== undefined && typeof obj.parentReviewedAt !== \"string\") return false;\n\n\tif (obj.evidence !== undefined && !isEvidenceBundle(obj.evidence)) return false;\n\n\treturn true;\n}\n\nexport function requiresParentReview(result: WorkerResult): boolean {\n\tif (result.status !== \"completed\") {\n\t\treturn true;\n\t}\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn true;\n\t}\n\tif (result.changedFiles.length > 0) {\n\t\treturn true;\n\t}\n\treturn false;\n}\n\n/**\n * True iff {@link validateWorkerResult}'s gate would flag this result \"ask-user\" /\n * \"parent_review_required\" (the two branches at :110 and :178 below) — an otherwise-completed\n * result the parent must explicitly look at because it reports blockers, or reports file mutations\n * that passed path-scope validation. Reuses `validateWorkerResult` itself rather than a\n * separately-maintained heuristic, so a persisted review marker can never drift from the\n * gate's actual verdict.\n */\nexport function isParentReviewRequired(args: { request: WorkerRequest; result: WorkerResult; cwd?: string }): boolean {\n\tconst acceptance = validateWorkerResult(args);\n\treturn acceptance.outcome === \"ask-user\" && acceptance.reasonCode === \"parent_review_required\";\n}\n\nexport function validateWorkerResult(args: {\n\trequest: WorkerRequest;\n\tresult: WorkerResult;\n\t/**\n\t * Baseline for relative paths — BOTH the runner's cwd-relative `changedFiles` and the\n\t * envelope's possibly-relative path scopes resolve against this. Defaults to process.cwd()\n\t * for callers whose session cwd is the process cwd.\n\t */\n\tcwd?: string;\n}): GateOutcome {\n\tconst { request, result } = args;\n\tconst baseDir = args.cwd ?? process.cwd();\n\n\tif (result.requestId !== request.id) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"request_id_mismatch\",\n\t\t\tmessage: `Result requestId '${result.requestId}' does not match request id '${request.id}'.`,\n\t\t};\n\t}\n\n\tif (result.status !== \"completed\") {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"worker_not_completed\",\n\t\t\tmessage: `Worker finished with status '${result.status}'.`,\n\t\t\tdetails: result.blockers && result.blockers.length > 0 ? { blockers: [...result.blockers] } : undefined,\n\t\t};\n\t}\n\n\tif (!result.usageReportId) {\n\t\treturn {\n\t\t\toutcome: \"block\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"missing_usage_report\",\n\t\t\tmessage: \"Completed worker result is missing usageReportId.\",\n\t\t};\n\t}\n\n\tif (result.blockers && result.blockers.length > 0) {\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Completed worker result includes blockers and requires parent review.\",\n\t\t\tdetails: { blockers: [...result.blockers] },\n\t\t};\n\t}\n\n\tif (result.changedFiles.length > 0) {\n\t\tif (!request.envelope.allowedPaths || request.envelope.allowedPaths.length === 0) {\n\t\t\treturn {\n\t\t\t\toutcome: \"block\",\n\t\t\t\tgate: \"worker_result\",\n\t\t\t\treasonCode: \"missing_path_scope\",\n\t\t\t\tmessage: \"Worker changed files but no allowedPaths are configured in the envelope.\",\n\t\t\t};\n\t\t}\n\n\t\t// The runner reports changed files relative to the session cwd — resolve file and scope\n\t\t// roots against the SAME baseline. Resolving per-root double-prefixed nested names and\n\t\t// let a denied subtree slip past the deny rule.\n\t\tconst resolvedAllowed = request.envelope.allowedPaths.map((p) => path.resolve(baseDir, p));\n\t\tconst resolvedDenied = request.envelope.deniedPaths?.map((p) => path.resolve(baseDir, p));\n\t\tfor (const changedFile of result.changedFiles) {\n\t\t\tlet isInsideAny = false;\n\t\t\tlet isDenied = false;\n\n\t\t\tconst scopedChangedFile = path.resolve(baseDir, changedFile);\n\t\t\tfor (const root of resolvedAllowed) {\n\t\t\t\tconst decision = checkPathScope(\n\t\t\t\t\t{\n\t\t\t\t\t\troot,\n\t\t\t\t\t\tallowedPaths: resolvedAllowed,\n\t\t\t\t\t\tdeniedPaths: resolvedDenied,\n\t\t\t\t\t},\n\t\t\t\t\tscopedChangedFile,\n\t\t\t\t);\n\n\t\t\t\tif (decision.kind === \"denied\") {\n\t\t\t\t\tisDenied = true;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (decision.kind === \"inside\") {\n\t\t\t\t\tisInsideAny = true;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (isDenied) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_denied\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' which matches a denied path.`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (!isInsideAny) {\n\t\t\t\treturn {\n\t\t\t\t\toutcome: \"block\",\n\t\t\t\t\tgate: \"worker_result\",\n\t\t\t\t\treasonCode: \"changed_file_outside_scope\",\n\t\t\t\t\tmessage: `Worker changed file '${changedFile}' outside allowed scope.`,\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\t// Files are inside scope, but worker output is untrusted\n\t\treturn {\n\t\t\toutcome: \"ask-user\",\n\t\t\tgate: \"worker_result\",\n\t\t\treasonCode: \"parent_review_required\",\n\t\t\tmessage: \"Worker changed files require parent review.\",\n\t\t};\n\t}\n\n\treturn {\n\t\toutcome: \"allow\",\n\t\tgate: \"worker_result\",\n\t\treasonCode: \"allowed\",\n\t\tmessage: \"Worker result is read-only and allowed.\",\n\t};\n}\n\n/**\n * Path-scope-only re-review for a SELF-REPORTED (out-of-process) worker's claimed `changedFiles`\n * -- e.g. a tmux worker's own completion report, which (unlike an in-process worker's) never\n * passed through this process's `applyWorkerActions` envelope enforcement before the write\n * happened; the tmux worker's tool loop runs in a separate process this session does not gate.\n * Reuses {@link validateWorkerResult}'s exact symlink-safe scope check verbatim -- never\n * reimplement path resolution: synthesizes a minimal, always-\"completed\" request/result pair\n * carrying only the reported `changedFiles` and the scope's `allowedPaths`/`deniedPaths`, so the\n * ONLY thing that can vary the verdict is the path-scope branch.\n *\n * Deliberately broader than {@link isParentReviewRequired}: that helper only flags the gate's\n * \"ask-user\" branch, which is correct for an in-process worker (a write that would have been\n * \"block\"-worthy was already refused before it could happen, by the SAME envelope, via\n * `applyWorkerActions`). A self-reported claim has no such backstop -- an out-of-scope or denied\n * path already happened on the real filesystem whether or not this gate would allow it, so here\n * ANY non-\"allow\" verdict (in scope, out of scope, or no scope configured at all) means a human\n * must look, not \"the write didn't happen\".\n */\nexport function reviewManagedLaneChangedFiles(args: {\n\tchangedFiles: readonly string[];\n\t/** The scope to validate against -- e.g. the session's active `CapabilityEnvelope`, until a\n\t * per-launch tmux standing grant envelope lands in a later wave (documented follow-up). */\n\tenvelope: Pick<CapabilityEnvelope, \"allowedPaths\" | \"deniedPaths\">;\n\tcwd?: string;\n}): { reviewRequired: boolean; reasonCode: string } {\n\tif (args.changedFiles.length === 0) {\n\t\treturn { reviewRequired: false, reasonCode: \"no_changed_files\" };\n\t}\n\tconst syntheticId = \"managed-lane-review\";\n\tconst acceptance = validateWorkerResult({\n\t\trequest: {\n\t\t\tid: syntheticId,\n\t\t\tinstructions: \"\",\n\t\t\troute: {\n\t\t\t\ttier: \"cheap\",\n\t\t\t\trisk: \"scoped-write\",\n\t\t\t\tconfidence: 1,\n\t\t\t\treasonCode: \"managed_lane_review\",\n\t\t\t\treasons: [],\n\t\t\t},\n\t\t\tenvelope: {\n\t\t\t\tid: syntheticId,\n\t\t\t\tcapabilities: [\"write_files\"],\n\t\t\t\tallowedPaths: args.envelope.allowedPaths,\n\t\t\t\tdeniedPaths: args.envelope.deniedPaths,\n\t\t\t},\n\t\t},\n\t\tresult: {\n\t\t\trequestId: syntheticId,\n\t\t\tstatus: \"completed\",\n\t\t\tsummary: \"\",\n\t\t\tchangedFiles: [...args.changedFiles],\n\t\t\tusageReportId: syntheticId,\n\t\t},\n\t\tcwd: args.cwd,\n\t});\n\treturn { reviewRequired: acceptance.outcome !== \"allow\", reasonCode: acceptance.reasonCode };\n}\n"]}

package/dist/core/extensions/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EACX,SAAS,EAET,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EAKpB,MAAM,YAAY,CAAC;AAkJpB;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAiEzD;AA2SD;;;;;GAKG;AACH,wBAAsB,kCAAkC,CACvD,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,IAAI,CAAC,CAuCf;AA4CD,wBAAsB,aAAa,CAClC,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,gBAAgB,EACzB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAyBhE;AA2GD;;GAEG;AACH,wBAAsB,wBAAwB,CAC7C,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,gBAAgB,EACzB,aAAa,SAAa,EAC1B,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACzC,OAAO,CAAC,SAAS,CAAC,CAapB;AAED;;GAEG;AACH,wBAAsB,cAAc,CACnC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,iBAAiB,CAAC,EACxC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,oBAAoB,CAAC,CA0C/B;AAED,UAAU,gBAAgB;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAaD,UAAU,iBAAiB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AA2ID;;GAEG;AACH,wBAAsB,yBAAyB,CAC9C,eAAe,EAAE,MAAM,EAAE,EACzB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAsB,EAChC,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,oBAAoB,CAAC,CA4C/B","sourcesContent":["/**\n * Extension loader - loads TypeScript extension modules using jiti.\n *\n */\n\nimport * as fs from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport * as _bundledPiAgentCore from \"@caupulican/pi-agent-core\";\nimport * as _bundledPiAi from \"@caupulican/pi-ai\";\nimport * as _bundledPiAiOauth from \"@caupulican/pi-ai/oauth\";\nimport type { KeyId } from \"@caupulican/pi-tui\";\nimport * as _bundledPiTui from \"@caupulican/pi-tui\";\nimport { createJiti } from \"jiti/static\";\n// Static imports of packages that extensions may use.\n// These MUST be static so Bun bundles them into the compiled binary.\n// The virtualModules option then makes them available to extensions.\nimport * as _bundledTypebox from \"typebox\";\nimport * as _bundledTypeboxCompile from \"typebox/compile\";\nimport * as _bundledTypeboxValue from \"typebox/value\";\nimport { CONFIG_DIR_NAME, getAgentDir, isBunBinary } from \"../../config.ts\";\n// NOTE: This import works because loader.ts exports are NOT re-exported from index.ts,\n// avoiding a circular dependency. Extensions can import from @caupulican/pi-adaptative.\nimport * as _bundledPiCodingAgent from \"../../index.ts\";\nimport { resolvePath } from \"../../utils/paths.ts\";\nimport { createEventBus, type EventBus } from \"../event-bus.ts\";\nimport type { ExecOptions } from \"../exec.ts\";\nimport { execCommand } from \"../exec.ts\";\nimport { createSyntheticSourceInfo } from \"../source-info.ts\";\nimport type {\n\tExtension,\n\tExtensionAPI,\n\tExtensionFactory,\n\tExtensionRuntime,\n\tLoadExtensionsResult,\n\tMessageRenderer,\n\tProviderConfig,\n\tRegisteredCommand,\n\tToolDefinition,\n} from \"./types.ts\";\n\nconst EXTENSION_FACTORY_TIMEOUT_MS = 30_000;\nconst EXTENSION_DISPOSAL_TIMEOUT_MS = 5_000;\nconst inactiveExtensions = new WeakSet<Extension>();\n\nclass ExtensionFactoryTimeoutError extends Error {}\n\n/** Modules available to extensions via virtualModules (for compiled Bun binary) */\nconst VIRTUAL_MODULES: Record<string, unknown> = {\n\ttypebox: _bundledTypebox,\n\t\"typebox/compile\": _bundledTypeboxCompile,\n\t\"typebox/value\": _bundledTypeboxValue,\n\t\"@sinclair/typebox\": _bundledTypebox,\n\t\"@sinclair/typebox/compile\": _bundledTypeboxCompile,\n\t\"@sinclair/typebox/value\": _bundledTypeboxValue,\n\t\"@caupulican/pi-agent-core\": _bundledPiAgentCore,\n\t\"@caupulican/pi-tui\": _bundledPiTui,\n\t\"@caupulican/pi-ai\": _bundledPiAi,\n\t\"@caupulican/pi-ai/oauth\": _bundledPiAiOauth,\n\t\"@caupulican/pi-adaptative\": _bundledPiCodingAgent,\n\t\"@earendil-works/pi-agent-core\": _bundledPiAgentCore,\n\t\"@earendil-works/pi-tui\": _bundledPiTui,\n\t\"@earendil-works/pi-ai\": _bundledPiAi,\n\t\"@earendil-works/pi-ai/oauth\": _bundledPiAiOauth,\n\t\"@earendil-works/pi-coding-agent\": _bundledPiCodingAgent,\n\t\"@mariozechner/pi-agent-core\": _bundledPiAgentCore,\n\t\"@mariozechner/pi-tui\": _bundledPiTui,\n\t\"@mariozechner/pi-ai\": _bundledPiAi,\n\t\"@mariozechner/pi-ai/oauth\": _bundledPiAiOauth,\n\t\"@mariozechner/pi-coding-agent\": _bundledPiCodingAgent,\n};\n\nfunction uniquePaths(paths: string[]): string[] {\n\treturn [...new Set(paths)];\n}\n\nfunction safeRealpath(filePath: string): string {\n\ttry {\n\t\treturn fs.realpathSync(filePath);\n\t} catch {\n\t\treturn filePath;\n\t}\n}\n\n/**\n * Get aliases for jiti (used in Node.js/development mode).\n * In Bun binary mode, virtualModules is used instead.\n */\nlet _aliases: Record<string, string> | null = null;\n\nfunction getAliases(): Record<string, string> {\n\tif (_aliases) return _aliases;\n\n\tconst loaderFile = fileURLToPath(import.meta.url);\n\tconst realLoaderFile = safeRealpath(loaderFile);\n\tconst __dirname = path.dirname(loaderFile);\n\tconst realDirname = path.dirname(realLoaderFile);\n\tconst packageIndex = [\n\t\tpath.resolve(__dirname, \"../..\", \"index.ts\"),\n\t\tpath.resolve(__dirname, \"../..\", \"index.js\"),\n\t].find((candidate) => fs.existsSync(candidate));\n\tif (!packageIndex) throw new Error(\"Unable to resolve the coding-agent package entry\");\n\n\tconst moduleRequires = uniquePaths([loaderFile, realLoaderFile]).map((file) => createRequire(file));\n\tconst resolveModule = (specifier: string): string => {\n\t\tfor (const moduleRequire of moduleRequires) {\n\t\t\ttry {\n\t\t\t\treturn moduleRequire.resolve(specifier);\n\t\t\t} catch {\n\t\t\t\t// Try the next resolution base. Linked global installs may resolve the\n\t\t\t\t// loader through the global symlink path while workspace dependencies are\n\t\t\t\t// hoisted beside the real source path.\n\t\t\t}\n\t\t}\n\t\treturn fileURLToPath(import.meta.resolve(specifier));\n\t};\n\n\tconst typeboxEntry = resolveModule(\"typebox\");\n\tconst typeboxCompileEntry = resolveModule(\"typebox/compile\");\n\tconst typeboxValueEntry = resolveModule(\"typebox/value\");\n\n\tconst packagesRoots = uniquePaths([\n\t\tpath.resolve(__dirname, \"../../../../\"),\n\t\tpath.resolve(realDirname, \"../../../../\"),\n\t]);\n\tconst resolveWorkspaceOrImport = (workspaceRelativePath: string, specifier: string): string => {\n\t\tfor (const packagesRoot of packagesRoots) {\n\t\t\tconst workspacePath = path.join(packagesRoot, workspaceRelativePath);\n\t\t\tif (fs.existsSync(workspacePath)) {\n\t\t\t\treturn workspacePath;\n\t\t\t}\n\t\t}\n\t\treturn resolveModule(specifier);\n\t};\n\n\tconst piCodingAgentEntry = packageIndex;\n\tconst piAgentCoreEntry = resolveWorkspaceOrImport(\"agent/src/index.ts\", \"@caupulican/pi-agent-core\");\n\tconst piAgentCoreNodeEntry = resolveWorkspaceOrImport(\"agent/src/node.ts\", \"@caupulican/pi-agent-core/node\");\n\tconst piAgentCorePathsEntry = resolveWorkspaceOrImport(\n\t\t\"agent/src/utils/paths.ts\",\n\t\t\"@caupulican/pi-agent-core/paths\",\n\t);\n\tconst piTuiEntry = resolveWorkspaceOrImport(\"tui/src/index.ts\", \"@caupulican/pi-tui\");\n\tconst piAiEntry = resolveWorkspaceOrImport(\"ai/src/index.ts\", \"@caupulican/pi-ai\");\n\tconst piAiOauthEntry = resolveWorkspaceOrImport(\"ai/src/oauth.ts\", \"@caupulican/pi-ai/oauth\");\n\n\t_aliases = {\n\t\t\"@caupulican/pi-agent-core/node\": piAgentCoreNodeEntry,\n\t\t\"@caupulican/pi-agent-core/paths\": piAgentCorePathsEntry,\n\t\t\"@caupulican/pi-ai/oauth\": piAiOauthEntry,\n\t\t\"@caupulican/pi-adaptative\": piCodingAgentEntry,\n\t\t\"@caupulican/pi-agent-core\": piAgentCoreEntry,\n\t\t\"@caupulican/pi-tui\": piTuiEntry,\n\t\t\"@caupulican/pi-ai\": piAiEntry,\n\t\t\"@earendil-works/pi-agent-core/node\": piAgentCoreNodeEntry,\n\t\t\"@earendil-works/pi-agent-core/paths\": piAgentCorePathsEntry,\n\t\t\"@earendil-works/pi-ai/oauth\": piAiOauthEntry,\n\t\t\"@earendil-works/pi-coding-agent\": piCodingAgentEntry,\n\t\t\"@earendil-works/pi-agent-core\": piAgentCoreEntry,\n\t\t\"@earendil-works/pi-tui\": piTuiEntry,\n\t\t\"@earendil-works/pi-ai\": piAiEntry,\n\t\t\"@mariozechner/pi-agent-core/node\": piAgentCoreNodeEntry,\n\t\t\"@mariozechner/pi-agent-core/paths\": piAgentCorePathsEntry,\n\t\t\"@mariozechner/pi-ai/oauth\": piAiOauthEntry,\n\t\t\"@mariozechner/pi-coding-agent\": piCodingAgentEntry,\n\t\t\"@mariozechner/pi-agent-core\": piAgentCoreEntry,\n\t\t\"@mariozechner/pi-tui\": piTuiEntry,\n\t\t\"@mariozechner/pi-ai\": piAiEntry,\n\t\ttypebox: typeboxEntry,\n\t\t\"typebox/compile\": typeboxCompileEntry,\n\t\t\"typebox/value\": typeboxValueEntry,\n\t\t\"@sinclair/typebox\": typeboxEntry,\n\t\t\"@sinclair/typebox/compile\": typeboxCompileEntry,\n\t\t\"@sinclair/typebox/value\": typeboxValueEntry,\n\t};\n\n\treturn _aliases;\n}\n\ntype HandlerFn = (...args: unknown[]) => Promise<unknown>;\n\nfunction yieldToEventLoop(): Promise<void> {\n\treturn new Promise((resolve) => setImmediate(resolve));\n}\n\n/**\n * Create a runtime with throwing stubs for action methods.\n * Runner.bindCore() replaces these with real implementations.\n */\nexport function createExtensionRuntime(): ExtensionRuntime {\n\tconst notInitialized = () => {\n\t\tthrow new Error(\"Extension runtime not initialized. Action methods cannot be called during extension loading.\");\n\t};\n\tconst state: { staleMessage?: string } = {};\n\tconst assertActive = () => {\n\t\tif (state.staleMessage) {\n\t\t\tthrow new Error(state.staleMessage);\n\t\t}\n\t};\n\n\tconst providersByExtension = new Map<string, Set<string>>();\n\tconst providerRegistrations = new Map<string, { config: ProviderConfig; extensionPath?: string }>();\n\tconst memoryProvidersByExtension = new Map<string, Set<Parameters<ExtensionRuntime[\"registerMemoryProvider\"]>[0]>>();\n\tconst contextMemoryProvidersByExtension = new Map<\n\t\tstring,\n\t\tSet<Parameters<ExtensionRuntime[\"registerContextMemoryProvider\"]>[0]>\n\t>();\n\n\tconst runtime: ExtensionRuntime = {\n\t\tsendMessage: notInitialized,\n\t\tsendUserMessage: notInitialized,\n\t\tappendEntry: notInitialized,\n\t\tsetSessionName: notInitialized,\n\t\tgetSessionName: notInitialized,\n\t\tsetLabel: notInitialized,\n\t\tgetActiveTools: notInitialized,\n\t\tgetAllTools: notInitialized,\n\t\tsetActiveTools: notInitialized,\n\t\t// registerTool() is valid during extension load; refresh is only needed post-bind.\n\t\trefreshTools: () => {},\n\t\tgetCommands: notInitialized,\n\t\tsetModel: notInitialized,\n\t\tgetThinkingLevel: notInitialized,\n\t\tsetThinkingLevel: notInitialized,\n\t\tgetExternalResourceRoots: notInitialized,\n\t\tregisterMemoryProvider: notInitialized,\n\t\tregisterContextMemoryProvider: notInitialized,\n\t\treportSpawnedUsage: notInitialized,\n\t\tflagValues: new Map(),\n\t\tpendingProviderRegistrations: [],\n\t\tassertActive,\n\t\tinvalidate: (message) => {\n\t\t\tstate.staleMessage ??=\n\t\t\t\tmessage ??\n\t\t\t\t\"This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().\";\n\t\t},\n\t\t// Pre-bind: queue registrations so bindCore() can flush them once the\n\t\t// model registry is available. bindCore() replaces both with direct calls.\n\t\tregisterProvider: (name, config, extensionPath = \"<unknown>\") => {\n\t\t\truntime.pendingProviderRegistrations.push({ name, config, extensionPath });\n\t\t},\n\t\tunregisterProvider: (name) => {\n\t\t\truntime.pendingProviderRegistrations = runtime.pendingProviderRegistrations.filter((r) => r.name !== name);\n\t\t},\n\t\tprovidersByExtension,\n\t\tproviderRegistrations,\n\t\tgetProvidersForExtension: (extensionPath: string) => {\n\t\t\treturn [...(providersByExtension.get(extensionPath) ?? [])];\n\t\t},\n\t\tmemoryProvidersByExtension,\n\t\tcontextMemoryProvidersByExtension,\n\t};\n\n\treturn runtime;\n}\n\n/**\n * Create the ExtensionAPI for an extension.\n * Registration methods write to the extension object.\n * Action methods delegate to the shared runtime.\n */\nfunction createExtensionAPI(\n\textension: Extension,\n\truntime: ExtensionRuntime,\n\tcwd: string,\n\teventBus: EventBus,\n): ExtensionAPI {\n\t// A factory can time out while its promise continues running. Route every later API call through\n\t// an extension-generation guard so stale async work cannot register tools, handlers, or providers.\n\tconst sharedRuntime = runtime;\n\truntime = new Proxy(sharedRuntime, {\n\t\tget(target, property, receiver) {\n\t\t\tif (property === \"assertActive\") {\n\t\t\t\treturn () => {\n\t\t\t\t\ttarget.assertActive();\n\t\t\t\t\tif (inactiveExtensions.has(extension)) {\n\t\t\t\t\t\tthrow new Error(`Extension generation is no longer active: ${extension.path}`);\n\t\t\t\t\t}\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn Reflect.get(target, property, receiver);\n\t\t},\n\t});\n\n\tconst api = {\n\t\t// Registration methods - write to extension\n\t\ton(event: string, handler: HandlerFn): void {\n\t\t\truntime.assertActive();\n\t\t\tconst list = extension.handlers.get(event) ?? [];\n\t\t\tlist.push(handler);\n\t\t\textension.handlers.set(event, list);\n\t\t},\n\n\t\tregisterTool(tool: ToolDefinition): void {\n\t\t\truntime.assertActive();\n\t\t\textension.tools.set(tool.name, {\n\t\t\t\tdefinition: tool,\n\t\t\t\tsourceInfo: extension.sourceInfo,\n\t\t\t});\n\t\t\truntime.refreshTools();\n\t\t},\n\n\t\tregisterCommand(name: string, options: Omit<RegisteredCommand, \"name\" | \"sourceInfo\">): void {\n\t\t\truntime.assertActive();\n\t\t\textension.commands.set(name, {\n\t\t\t\tname,\n\t\t\t\tsourceInfo: extension.sourceInfo,\n\t\t\t\t...options,\n\t\t\t});\n\t\t},\n\n\t\tregisterShortcut(\n\t\t\tshortcut: KeyId,\n\t\t\toptions: {\n\t\t\t\tdescription?: string;\n\t\t\t\thandler: (ctx: import(\"./types.ts\").ExtensionContext) => Promise<void> | void;\n\t\t\t},\n\t\t): void {\n\t\t\truntime.assertActive();\n\t\t\textension.shortcuts.set(shortcut, { shortcut, extensionPath: extension.path, ...options });\n\t\t},\n\n\t\tregisterFlag(\n\t\t\tname: string,\n\t\t\toptions: { description?: string; type: \"boolean\" | \"string\"; default?: boolean | string },\n\t\t): void {\n\t\t\truntime.assertActive();\n\t\t\textension.flags.set(name, { name, extensionPath: extension.path, ...options });\n\t\t\tif (options.default !== undefined && !runtime.flagValues.has(name)) {\n\t\t\t\truntime.flagValues.set(name, options.default);\n\t\t\t}\n\t\t},\n\n\t\tregisterMessageRenderer<T>(customType: string, renderer: MessageRenderer<T>): void {\n\t\t\truntime.assertActive();\n\t\t\textension.messageRenderers.set(customType, renderer as MessageRenderer);\n\t\t},\n\n\t\t// Flag access - checks extension registered it, reads from runtime\n\t\tgetFlag(name: string): boolean | string | undefined {\n\t\t\truntime.assertActive();\n\t\t\tif (!extension.flags.has(name)) return undefined;\n\t\t\treturn runtime.flagValues.get(name);\n\t\t},\n\n\t\t// Action methods - delegate to shared runtime\n\t\tsendMessage(message, options): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.sendMessage(message, options);\n\t\t},\n\n\t\tsendUserMessage(content, options): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.sendUserMessage(content, options);\n\t\t},\n\n\t\tappendEntry(customType: string, data?: unknown): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.appendEntry(customType, data);\n\t\t},\n\n\t\tsetSessionName(name: string): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.setSessionName(name);\n\t\t},\n\n\t\tgetSessionName(): string | undefined {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getSessionName();\n\t\t},\n\n\t\tsetLabel(entryId: string, label: string | undefined): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.setLabel(entryId, label);\n\t\t},\n\n\t\texec(command: string, args: string[], options?: ExecOptions) {\n\t\t\truntime.assertActive();\n\t\t\treturn execCommand(command, args, options?.cwd ?? cwd, options);\n\t\t},\n\n\t\tgetActiveTools(): string[] {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getActiveTools();\n\t\t},\n\n\t\tgetAllTools() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getAllTools();\n\t\t},\n\n\t\tsetActiveTools(toolNames: string[]): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.setActiveTools(toolNames);\n\t\t},\n\n\t\tgetCommands() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getCommands();\n\t\t},\n\n\t\tgetExternalResourceRoots() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getExternalResourceRoots();\n\t\t},\n\n\t\tregisterMemoryProvider(provider) {\n\t\t\truntime.assertActive();\n\t\t\truntime.registerMemoryProvider(provider);\n\t\t\tconst providers = runtime.memoryProvidersByExtension.get(extension.path) ?? new Set();\n\t\t\tproviders.add(provider);\n\t\t\truntime.memoryProvidersByExtension.set(extension.path, providers);\n\t\t},\n\n\t\tregisterContextMemoryProvider(provider) {\n\t\t\truntime.assertActive();\n\t\t\truntime.registerContextMemoryProvider(provider);\n\t\t\tconst providers = runtime.contextMemoryProvidersByExtension.get(extension.path) ?? new Set();\n\t\t\tproviders.add(provider);\n\t\t\truntime.contextMemoryProvidersByExtension.set(extension.path, providers);\n\t\t},\n\n\t\treportSpawnedUsage(usage, opts) {\n\t\t\truntime.assertActive();\n\t\t\truntime.reportSpawnedUsage(usage, opts);\n\t\t},\n\n\t\tsetModel(model) {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.setModel(model);\n\t\t},\n\n\t\tgetThinkingLevel() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getThinkingLevel();\n\t\t},\n\n\t\tsetThinkingLevel(level) {\n\t\t\truntime.assertActive();\n\t\t\truntime.setThinkingLevel(level);\n\t\t},\n\n\t\tregisterProvider(name: string, config: ProviderConfig) {\n\t\t\truntime.assertActive();\n\t\t\truntime.registerProvider(name, config, extension.path);\n\t\t},\n\n\t\tunregisterProvider(name: string) {\n\t\t\truntime.assertActive();\n\t\t\truntime.unregisterProvider(name, extension.path);\n\t\t},\n\n\t\tonDispose(fn: () => void | Promise<void>): void {\n\t\t\truntime.assertActive();\n\t\t\textension.disposers.push(fn);\n\t\t},\n\n\t\t// Track bus subscriptions per extension generation so hot reloads can\n\t\t// unsubscribe replaced generations (see disposeExtensionEventSubscriptions).\n\t\tevents: {\n\t\t\temit: (channel: string, data: unknown) => {\n\t\t\t\truntime.assertActive();\n\t\t\t\teventBus.emit(channel, data);\n\t\t\t},\n\t\t\ton: (channel: string, handler: (data: unknown) => void) => {\n\t\t\t\truntime.assertActive();\n\t\t\t\tconst unsubscribe = eventBus.on(channel, handler);\n\t\t\t\textension.eventUnsubscribes.push(unsubscribe);\n\t\t\t\treturn unsubscribe;\n\t\t\t},\n\t\t},\n\t} as ExtensionAPI;\n\n\treturn api;\n}\n\nasync function runExtensionFactory(\n\tfactory: ExtensionFactory,\n\tapi: ExtensionAPI,\n\ttimeoutMs: number = EXTENSION_FACTORY_TIMEOUT_MS,\n): Promise<void> {\n\tlet timeout: ReturnType<typeof setTimeout> | undefined;\n\tconst completion = Promise.resolve().then(() => factory(api));\n\ttry {\n\t\tawait Promise.race([\n\t\t\tcompletion,\n\t\t\tnew Promise<never>((_resolve, reject) => {\n\t\t\t\ttimeout = setTimeout(\n\t\t\t\t\t() => reject(new ExtensionFactoryTimeoutError(`Extension factory timed out after ${timeoutMs}ms`)),\n\t\t\t\t\tMath.max(0, timeoutMs),\n\t\t\t\t);\n\t\t\t}),\n\t\t]);\n\t} finally {\n\t\tif (timeout) clearTimeout(timeout);\n\t}\n}\n\nasync function loadExtensionModule(extensionPath: string, opts?: { fresh?: boolean; moduleTimeoutMs?: number }) {\n\tconst jiti = createJiti(import.meta.url, {\n\t\tmoduleCache: false,\n\t\t// In Bun binary: use virtualModules for bundled packages (no filesystem resolution)\n\t\t// Also disable tryNative so jiti handles ALL imports (not just the entry point)\n\t\t// In Node.js/dev: use aliases to resolve to node_modules paths\n\t\t...(isBunBinary ? { virtualModules: VIRTUAL_MODULES, tryNative: false } : { alias: getAliases() }),\n\t});\n\n\t// Every call gets a fresh jiti instance with moduleCache disabled. Do not append a query string:\n\t// jiti's Windows path resolver treats it as part of the .ts filename.\n\tconst timeoutMs = opts?.moduleTimeoutMs ?? EXTENSION_FACTORY_TIMEOUT_MS;\n\tlet timeout: ReturnType<typeof setTimeout> | undefined;\n\ttry {\n\t\tconst module = await Promise.race([\n\t\t\tjiti.import(extensionPath, { default: true }),\n\t\t\tnew Promise<never>((_resolve, reject) => {\n\t\t\t\ttimeout = setTimeout(\n\t\t\t\t\t() => reject(new Error(`Extension module import timed out after ${timeoutMs}ms: ${extensionPath}`)),\n\t\t\t\t\tMath.max(0, timeoutMs),\n\t\t\t\t);\n\t\t\t}),\n\t\t]);\n\t\tconst factory = module as ExtensionFactory;\n\t\treturn typeof factory !== \"function\" ? undefined : factory;\n\t} finally {\n\t\tif (timeout) clearTimeout(timeout);\n\t}\n}\n\n/**\n * Create an Extension object with empty collections.\n */\nfunction createExtension(extensionPath: string, resolvedPath: string): Extension {\n\tconst source =\n\t\textensionPath.startsWith(\"<\") && extensionPath.endsWith(\">\")\n\t\t\t? extensionPath.slice(1, -1).split(\":\")[0] || \"temporary\"\n\t\t\t: \"local\";\n\tconst baseDir = extensionPath.startsWith(\"<\") ? undefined : path.dirname(resolvedPath);\n\n\treturn {\n\t\tpath: extensionPath,\n\t\tresolvedPath,\n\t\tsourceInfo: createSyntheticSourceInfo(extensionPath, { source, baseDir }),\n\t\thandlers: new Map(),\n\t\ttools: new Map(),\n\t\tmessageRenderers: new Map(),\n\t\tcommands: new Map(),\n\t\tflags: new Map(),\n\t\tshortcuts: new Map(),\n\t\teventUnsubscribes: [],\n\t\tdisposers: [],\n\t};\n}\n\n/**\n * Unsubscribe a replaced extension generation's pi.events handlers from the shared\n * event bus and invoke cleanup callbacks. Without this, every hot reload leaves the\n * previous generation's handlers subscribed, pinning the old module graph in memory\n * and double-processing events.\n */\nexport async function disposeExtensionEventSubscriptions(\n\textensions: Extension[],\n\toptions: { deactivate?: boolean; timeoutMs?: number } = {},\n): Promise<void> {\n\tconst deadline = Date.now() + (options.timeoutMs ?? EXTENSION_DISPOSAL_TIMEOUT_MS);\n\tfor (const extension of extensions) {\n\t\tif (options.deactivate ?? true) inactiveExtensions.add(extension);\n\t\t// Unsubscribe event listeners\n\t\tfor (const unsubscribe of extension.eventUnsubscribes) {\n\t\t\ttry {\n\t\t\t\tunsubscribe();\n\t\t\t} catch {\n\t\t\t\t// Disposal must never break a reload.\n\t\t\t}\n\t\t}\n\t\textension.eventUnsubscribes.length = 0;\n\n\t\t// Invoke every cleanup callback, but never let one unresolved async disposer block reload or\n\t\t// shutdown indefinitely. Late continuations retain rejection handlers and the inactive API guard.\n\t\tfor (const disposer of extension.disposers) {\n\t\t\ttry {\n\t\t\t\tconst result = disposer();\n\t\t\t\tif (result !== undefined) {\n\t\t\t\t\tconst completion = Promise.resolve(result).catch(() => undefined);\n\t\t\t\t\tconst remainingMs = Math.max(0, deadline - Date.now());\n\t\t\t\t\tif (remainingMs > 0) {\n\t\t\t\t\t\tlet timeout: ReturnType<typeof setTimeout> | undefined;\n\t\t\t\t\t\tawait Promise.race([\n\t\t\t\t\t\t\tcompletion,\n\t\t\t\t\t\t\tnew Promise<void>((resolve) => {\n\t\t\t\t\t\t\t\ttimeout = setTimeout(resolve, remainingMs);\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t]);\n\t\t\t\t\t\tif (timeout) clearTimeout(timeout);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Disposal must never break a reload.\n\t\t\t}\n\t\t}\n\t\textension.disposers.length = 0;\n\t}\n}\n\ninterface ExtensionLoadRuntimeSnapshot {\n\tpendingProviderRegistrations: ExtensionRuntime[\"pendingProviderRegistrations\"];\n\tflagValues: Map<string, boolean | string>;\n\tproviderRegistrations: ExtensionRuntime[\"providerRegistrations\"];\n}\n\nfunction snapshotExtensionLoadRuntime(runtime: ExtensionRuntime): ExtensionLoadRuntimeSnapshot {\n\treturn {\n\t\tpendingProviderRegistrations: [...runtime.pendingProviderRegistrations],\n\t\tflagValues: new Map(runtime.flagValues),\n\t\tproviderRegistrations: new Map(runtime.providerRegistrations),\n\t};\n}\n\nfunction restoreExtensionLoadRuntime(runtime: ExtensionRuntime, snapshot: ExtensionLoadRuntimeSnapshot): void {\n\tfor (const [name, current] of runtime.providerRegistrations) {\n\t\tconst previous = snapshot.providerRegistrations.get(name);\n\t\tif (!previous || previous.config !== current.config || previous.extensionPath !== current.extensionPath) {\n\t\t\ttry {\n\t\t\t\truntime.unregisterProvider(name, current.extensionPath);\n\t\t\t} catch {\n\t\t\t\t// Preserve the original factory failure; reload rollback remains the outer safety net.\n\t\t\t}\n\t\t}\n\t}\n\tfor (const [name, previous] of snapshot.providerRegistrations) {\n\t\tconst current = runtime.providerRegistrations.get(name);\n\t\tif (current?.config === previous.config && current.extensionPath === previous.extensionPath) continue;\n\t\ttry {\n\t\t\truntime.registerProvider(name, previous.config, previous.extensionPath);\n\t\t} catch {\n\t\t\t// Preserve the original factory failure; reload rollback remains the outer safety net.\n\t\t}\n\t}\n\n\truntime.pendingProviderRegistrations = snapshot.pendingProviderRegistrations;\n\truntime.flagValues.clear();\n\tfor (const [name, value] of snapshot.flagValues) {\n\t\truntime.flagValues.set(name, value);\n\t}\n}\n\nexport async function loadExtension(\n\textensionPath: string,\n\tcwd: string,\n\teventBus: EventBus,\n\truntime: ExtensionRuntime,\n\topts?: { fresh?: boolean; factoryTimeoutMs?: number; moduleTimeoutMs?: number },\n): Promise<{ extension: Extension | null; error: string | null }> {\n\tconst resolvedPath = resolvePath(extensionPath, cwd, { normalizeUnicodeSpaces: true });\n\n\ttry {\n\t\tconst factory = await loadExtensionModule(resolvedPath, opts);\n\t\tif (!factory) {\n\t\t\treturn { extension: null, error: `Extension does not export a valid factory function: ${extensionPath}` };\n\t\t}\n\n\t\tconst extension = createExtension(extensionPath, resolvedPath);\n\t\tconst api = createExtensionAPI(extension, runtime, cwd, eventBus);\n\t\tconst runtimeSnapshot = snapshotExtensionLoadRuntime(runtime);\n\t\ttry {\n\t\t\tawait runExtensionFactory(factory, api, opts?.factoryTimeoutMs);\n\t\t} catch (err) {\n\t\t\tawait disposeExtensionEventSubscriptions([extension]);\n\t\t\trestoreExtensionLoadRuntime(runtime, runtimeSnapshot);\n\t\t\tthrow err;\n\t\t}\n\n\t\treturn { extension, error: null };\n\t} catch (err) {\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\treturn { extension: null, error: `Failed to load extension: ${message}` };\n\t}\n}\n\nfunction createLazyToolDefinition(\n\textension: Extension,\n\tmanifest: LazyToolManifest,\n\tload: () => Promise<void>,\n): ToolDefinition {\n\tconst name = String(manifest.name).trim();\n\tconst definition: ToolDefinition = {\n\t\tname,\n\t\tlabel: typeof manifest.label === \"string\" && manifest.label.trim() ? manifest.label : name,\n\t\tdescription:\n\t\t\ttypeof manifest.description === \"string\" && manifest.description.trim()\n\t\t\t\t? manifest.description\n\t\t\t\t: `Lazy extension tool ${name}`,\n\t\tparameters: (manifest.parameters ?? defaultLazyToolParameters()) as ToolDefinition[\"parameters\"],\n\t\tpromptSnippet: typeof manifest.promptSnippet === \"string\" ? manifest.promptSnippet : undefined,\n\t\tpromptGuidelines: Array.isArray(manifest.promptGuidelines)\n\t\t\t? manifest.promptGuidelines.filter((item): item is string => typeof item === \"string\")\n\t\t\t: undefined,\n\t\ttoolGroup: typeof manifest.toolGroup === \"string\" ? manifest.toolGroup : undefined,\n\t\texecutionMode:\n\t\t\tmanifest.executionMode === \"parallel\" || manifest.executionMode === \"sequential\"\n\t\t\t\t? manifest.executionMode\n\t\t\t\t: undefined,\n\t\texecute: async (toolCallId, params, signal, onUpdate, ctx) => {\n\t\t\tawait load();\n\t\t\tconst loadedDefinition = extension.tools.get(name)?.definition;\n\t\t\tif (!loadedDefinition || loadedDefinition === definition) {\n\t\t\t\tthrow new Error(`Lazy extension ${extension.path} did not register tool ${name}`);\n\t\t\t}\n\t\t\treturn loadedDefinition.execute(toolCallId, params, signal, onUpdate, ctx);\n\t\t},\n\t};\n\treturn definition;\n}\n\nfunction createLazyExtension(\n\textensionPath: string,\n\tresolvedPath: string,\n\tcwd: string,\n\teventBus: EventBus,\n\truntime: ExtensionRuntime,\n\tlazyTools: LazyToolManifest[],\n): Extension {\n\tconst extension = createExtension(extensionPath, resolvedPath);\n\tlet restoreLazyToolPlaceholders = (): void => {};\n\tconst load = async (): Promise<void> => {\n\t\tif (inactiveExtensions.has(extension)) {\n\t\t\tthrow new Error(`Lazy extension generation is no longer active: ${extension.path}`);\n\t\t}\n\t\tif (extension.lazy?.loaded) return;\n\t\tif (extension.lazy?.loading) return extension.lazy.loading;\n\n\t\tconst loading = (async () => {\n\t\t\tconst factory = await loadExtensionModule(resolvedPath);\n\t\t\tif (!factory) {\n\t\t\t\tthrow new Error(`Extension does not export a valid factory function: ${extensionPath}`);\n\t\t\t}\n\t\t\tconst api = createExtensionAPI(extension, runtime, cwd, eventBus);\n\t\t\tconst runtimeSnapshot = snapshotExtensionLoadRuntime(runtime);\n\t\t\ttry {\n\t\t\t\tawait runExtensionFactory(factory, api);\n\t\t\t} catch (error) {\n\t\t\t\tawait disposeExtensionEventSubscriptions([extension], { deactivate: false });\n\t\t\t\trestoreExtensionLoadRuntime(runtime, runtimeSnapshot);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (extension.lazy) {\n\t\t\t\textension.lazy.loaded = true;\n\t\t\t\textension.lazy.loading = undefined;\n\t\t\t}\n\t\t})();\n\n\t\tif (extension.lazy) extension.lazy.loading = loading;\n\t\ttry {\n\t\t\tawait loading;\n\t\t} catch (err) {\n\t\t\tawait disposeExtensionEventSubscriptions([extension], {\n\t\t\t\tdeactivate: err instanceof ExtensionFactoryTimeoutError,\n\t\t\t});\n\t\t\textension.handlers.clear();\n\t\t\textension.messageRenderers.clear();\n\t\t\textension.commands.clear();\n\t\t\textension.flags.clear();\n\t\t\textension.shortcuts.clear();\n\t\t\textension.tools.clear();\n\t\t\trestoreLazyToolPlaceholders();\n\t\t\tif (extension.lazy) extension.lazy.loading = undefined;\n\t\t\tthrow err;\n\t\t}\n\t};\n\n\textension.lazy = { loaded: false, load };\n\trestoreLazyToolPlaceholders = () => {\n\t\tfor (const tool of lazyTools) {\n\t\t\tconst name = String(tool.name).trim();\n\t\t\textension.tools.set(name, {\n\t\t\t\tdefinition: createLazyToolDefinition(extension, tool, load),\n\t\t\t\tsourceInfo: extension.sourceInfo,\n\t\t\t});\n\t\t}\n\t};\n\trestoreLazyToolPlaceholders();\n\treturn extension;\n}\n\n/**\n * Create an Extension from an inline factory function.\n */\nexport async function loadExtensionFromFactory(\n\tfactory: ExtensionFactory,\n\tcwd: string,\n\teventBus: EventBus,\n\truntime: ExtensionRuntime,\n\textensionPath = \"<inline>\",\n\toptions: { factoryTimeoutMs?: number } = {},\n): Promise<Extension> {\n\tconst extension = createExtension(extensionPath, extensionPath);\n\tconst resolvedCwd = resolvePath(cwd);\n\tconst api = createExtensionAPI(extension, runtime, resolvedCwd, eventBus);\n\tconst runtimeSnapshot = snapshotExtensionLoadRuntime(runtime);\n\ttry {\n\t\tawait runExtensionFactory(factory, api, options.factoryTimeoutMs);\n\t} catch (err) {\n\t\tawait disposeExtensionEventSubscriptions([extension]);\n\t\trestoreExtensionLoadRuntime(runtime, runtimeSnapshot);\n\t\tthrow err;\n\t}\n\treturn extension;\n}\n\n/**\n * Load extensions from paths.\n */\nexport async function loadExtensions(\n\tpaths: Array<string | ExtensionLoadSpec>,\n\tcwd: string,\n\teventBus?: EventBus,\n): Promise<LoadExtensionsResult> {\n\tconst extensions: Extension[] = [];\n\tconst errors: Array<{ path: string; error: string }> = [];\n\tconst resolvedCwd = resolvePath(cwd);\n\tconst resolvedEventBus = eventBus ?? createEventBus();\n\tconst runtime = createExtensionRuntime();\n\n\tfor (const spec of paths) {\n\t\tconst normalized = typeof spec === \"string\" ? { path: spec } : spec;\n\t\tconst extPath = normalized.path;\n\t\tconst resolvedPath = resolvePath(extPath, resolvedCwd, { normalizeUnicodeSpaces: true });\n\t\tconst lazyTools = (normalized.lazyTools ?? inferLazyToolsForExtensionPath(resolvedPath))?.filter(\n\t\t\t(tool) => typeof tool.name === \"string\" && tool.name.trim(),\n\t\t);\n\t\t// Extension imports can be CPU-heavy under jiti. Yield around each load so\n\t\t// interactive reloads can repaint/status-update instead of freezing the TUI\n\t\t// for the whole extension set. Lazy tool manifests skip import entirely here.\n\t\tawait yieldToEventLoop();\n\t\tif (lazyTools?.length) {\n\t\t\textensions.push(createLazyExtension(extPath, resolvedPath, resolvedCwd, resolvedEventBus, runtime, lazyTools));\n\t\t\tawait yieldToEventLoop();\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst { extension, error } = await loadExtension(extPath, resolvedCwd, resolvedEventBus, runtime);\n\t\tawait yieldToEventLoop();\n\n\t\tif (error) {\n\t\t\terrors.push({ path: extPath, error });\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (extension) {\n\t\t\textensions.push(extension);\n\t\t}\n\t}\n\n\treturn {\n\t\textensions,\n\t\terrors,\n\t\truntime,\n\t};\n}\n\ninterface LazyToolManifest {\n\tname?: unknown;\n\tlabel?: unknown;\n\tdescription?: unknown;\n\tparameters?: unknown;\n\tpromptSnippet?: unknown;\n\tpromptGuidelines?: unknown;\n\ttoolGroup?: unknown;\n\texecutionMode?: unknown;\n\t/** Optional extension entry this tool belongs to when a package declares multiple entries. */\n\textension?: unknown;\n}\n\ninterface PiManifest {\n\textensions?: string[];\n\tthemes?: string[];\n\tskills?: string[];\n\tprompts?: string[];\n\t/** Tool metadata for opt-in lazy extension loading. Factories stay unloaded until one of these tools runs. */\n\tlazyTools?: LazyToolManifest[];\n\t/** Alternate nested spelling: { tools: [...] }. */\n\tlazy?: { tools?: LazyToolManifest[] } | boolean;\n}\n\ninterface ExtensionLoadSpec {\n\tpath: string;\n\tlazyTools?: LazyToolManifest[];\n}\n\nfunction getManifestLazyTools(manifest: PiManifest | null): LazyToolManifest[] | undefined {\n\tif (!manifest) return undefined;\n\tconst tools = Array.isArray(manifest.lazyTools)\n\t\t? manifest.lazyTools\n\t\t: typeof manifest.lazy === \"object\" && Array.isArray(manifest.lazy.tools)\n\t\t\t? manifest.lazy.tools\n\t\t\t: undefined;\n\treturn tools?.filter((tool) => tool && typeof tool.name === \"string\" && tool.name.trim());\n}\n\nfunction defaultLazyToolParameters(): ToolDefinition[\"parameters\"] {\n\treturn { type: \"object\", properties: {}, additionalProperties: false } as ToolDefinition[\"parameters\"];\n}\n\nfunction lazyToolsForEntry(tools: LazyToolManifest[] | undefined, dir: string, entryPath: string, entryCount: number) {\n\tif (!tools?.length) return undefined;\n\tconst selected = tools.filter((tool) => {\n\t\tif (typeof tool.extension !== \"string\" || !tool.extension.trim()) {\n\t\t\treturn entryCount === 1;\n\t\t}\n\t\treturn path.resolve(dir, tool.extension) === entryPath;\n\t});\n\treturn selected.length > 0 ? selected : undefined;\n}\n\nfunction inferLazyToolsForExtensionPath(resolvedPath: string): LazyToolManifest[] | undefined {\n\tconst dir = path.dirname(resolvedPath);\n\tconst manifest = readPiManifest(path.join(dir, \"package.json\"));\n\tconst lazyTools = getManifestLazyTools(manifest);\n\tif (!manifest?.extensions?.length || !lazyTools?.length) return undefined;\n\tconst resolvedEntries = manifest.extensions.map((extPath) => path.resolve(dir, extPath));\n\tif (!resolvedEntries.includes(resolvedPath)) return undefined;\n\treturn lazyToolsForEntry(lazyTools, dir, resolvedPath, resolvedEntries.length);\n}\n\nfunction readPiManifest(packageJsonPath: string): PiManifest | null {\n\ttry {\n\t\tconst content = fs.readFileSync(packageJsonPath, \"utf-8\");\n\t\tconst pkg = JSON.parse(content);\n\t\tif (pkg.pi && typeof pkg.pi === \"object\") {\n\t\t\treturn pkg.pi as PiManifest;\n\t\t}\n\t\treturn null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nfunction isExtensionFile(name: string): boolean {\n\treturn name.endsWith(\".ts\") || name.endsWith(\".js\");\n}\n\n/**\n * Resolve extension entry points from a directory.\n *\n * Checks for:\n * 1. package.json with \"pi.extensions\" field -> returns declared paths\n * 2. index.ts or index.js -> returns the index file\n *\n * Returns resolved paths or null if no entry points found.\n */\nfunction resolveExtensionEntries(dir: string): ExtensionLoadSpec[] | null {\n\t// Check for package.json with \"pi\" field first\n\tconst packageJsonPath = path.join(dir, \"package.json\");\n\tif (fs.existsSync(packageJsonPath)) {\n\t\tconst manifest = readPiManifest(packageJsonPath);\n\t\tif (manifest?.extensions?.length) {\n\t\t\tconst resolvedEntries = manifest.extensions\n\t\t\t\t.map((extPath) => path.resolve(dir, extPath))\n\t\t\t\t.filter((resolvedExtPath) => fs.existsSync(resolvedExtPath));\n\t\t\tif (resolvedEntries.length > 0) {\n\t\t\t\tconst lazyTools = getManifestLazyTools(manifest);\n\t\t\t\treturn resolvedEntries.map((entryPath) => ({\n\t\t\t\t\tpath: entryPath,\n\t\t\t\t\tlazyTools: lazyToolsForEntry(lazyTools, dir, entryPath, resolvedEntries.length),\n\t\t\t\t}));\n\t\t\t}\n\t\t}\n\t}\n\n\t// Check for index.ts or index.js\n\tconst indexTs = path.join(dir, \"index.ts\");\n\tconst indexJs = path.join(dir, \"index.js\");\n\tif (fs.existsSync(indexTs)) {\n\t\treturn [{ path: indexTs }];\n\t}\n\tif (fs.existsSync(indexJs)) {\n\t\treturn [{ path: indexJs }];\n\t}\n\n\treturn null;\n}\n\n/**\n * Discover extensions in a directory.\n *\n * Discovery rules:\n * 1. Direct files: `extensions/*.ts` or `*.js` → load\n * 2. Subdirectory with index: `extensions/* /index.ts` or `index.js` → load\n * 3. Subdirectory with package.json: `extensions/* /package.json` with \"pi\" field → load what it declares\n *\n * No recursion beyond one level. Complex packages must use package.json manifest.\n */\nfunction discoverExtensionsInDir(dir: string): ExtensionLoadSpec[] {\n\tif (!fs.existsSync(dir)) {\n\t\treturn [];\n\t}\n\n\tconst discovered: ExtensionLoadSpec[] = [];\n\n\ttry {\n\t\tconst entries = fs.readdirSync(dir, { withFileTypes: true });\n\n\t\tfor (const entry of entries) {\n\t\t\tconst entryPath = path.join(dir, entry.name);\n\n\t\t\t// 1. Direct files: *.ts or *.js\n\t\t\tif ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {\n\t\t\t\tdiscovered.push({ path: entryPath });\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\t// 2 & 3. Subdirectories\n\t\t\tif (entry.isDirectory() || entry.isSymbolicLink()) {\n\t\t\t\tconst entries = resolveExtensionEntries(entryPath);\n\t\t\t\tif (entries) {\n\t\t\t\t\tdiscovered.push(...entries);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t} catch {\n\t\treturn [];\n\t}\n\n\treturn discovered;\n}\n\n/**\n * Discover and load extensions from standard locations.\n */\nexport async function discoverAndLoadExtensions(\n\tconfiguredPaths: string[],\n\tcwd: string,\n\tagentDir: string = getAgentDir(),\n\teventBus?: EventBus,\n): Promise<LoadExtensionsResult> {\n\tconst resolvedCwd = resolvePath(cwd);\n\tconst resolvedAgentDir = resolvePath(agentDir);\n\tconst allPaths: ExtensionLoadSpec[] = [];\n\tconst seen = new Set<string>();\n\n\tconst addPaths = (paths: Array<string | ExtensionLoadSpec>) => {\n\t\tfor (const spec of paths) {\n\t\t\tconst normalized = typeof spec === \"string\" ? { path: spec } : spec;\n\t\t\tconst resolved = path.resolve(normalized.path);\n\t\t\tif (!seen.has(resolved)) {\n\t\t\t\tseen.add(resolved);\n\t\t\t\tallPaths.push(normalized);\n\t\t\t}\n\t\t}\n\t};\n\n\t// 1. Project-local extensions: cwd/${CONFIG_DIR_NAME}/extensions/\n\tconst localExtDir = path.join(resolvedCwd, CONFIG_DIR_NAME, \"extensions\");\n\taddPaths(discoverExtensionsInDir(localExtDir));\n\n\t// 2. Global extensions: agentDir/extensions/\n\tconst globalExtDir = path.join(resolvedAgentDir, \"extensions\");\n\taddPaths(discoverExtensionsInDir(globalExtDir));\n\n\t// 3. Explicitly configured paths\n\tfor (const p of configuredPaths) {\n\t\tconst resolved = resolvePath(p, resolvedCwd, { normalizeUnicodeSpaces: true });\n\t\tif (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {\n\t\t\t// Check for package.json with pi manifest or index.ts\n\t\t\tconst entries = resolveExtensionEntries(resolved);\n\t\t\tif (entries) {\n\t\t\t\taddPaths(entries);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\t// No explicit entries - discover individual files in directory\n\t\t\taddPaths(discoverExtensionsInDir(resolved));\n\t\t\tcontinue;\n\t\t}\n\n\t\taddPaths([resolved]);\n\t}\n\n\treturn loadExtensions(allPaths, resolvedCwd, eventBus);\n}\n"]}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwBH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EACX,SAAS,EAET,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EAKpB,MAAM,YAAY,CAAC;AAkJpB;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAkEzD;AA8TD;;;;;GAKG;AACH,wBAAsB,kCAAkC,CACvD,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,IAAI,CAAC,CAuCf;AA4CD,wBAAsB,aAAa,CAClC,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,gBAAgB,EACzB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAyBhE;AA2GD;;GAEG;AACH,wBAAsB,wBAAwB,CAC7C,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,gBAAgB,EACzB,aAAa,SAAa,EAC1B,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACzC,OAAO,CAAC,SAAS,CAAC,CAapB;AAED;;GAEG;AACH,wBAAsB,cAAc,CACnC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,iBAAiB,CAAC,EACxC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,oBAAoB,CAAC,CA0C/B;AAED,UAAU,gBAAgB;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAaD,UAAU,iBAAiB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AA2ID;;GAEG;AACH,wBAAsB,yBAAyB,CAC9C,eAAe,EAAE,MAAM,EAAE,EACzB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAsB,EAChC,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,oBAAoB,CAAC,CA4C/B","sourcesContent":["/**\n * Extension loader - loads TypeScript extension modules using jiti.\n *\n */\n\nimport * as fs from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport * as _bundledPiAgentCore from \"@caupulican/pi-agent-core\";\nimport * as _bundledPiAi from \"@caupulican/pi-ai\";\nimport * as _bundledPiAiOauth from \"@caupulican/pi-ai/oauth\";\nimport type { KeyId } from \"@caupulican/pi-tui\";\nimport * as _bundledPiTui from \"@caupulican/pi-tui\";\nimport { createJiti } from \"jiti/static\";\n// Static imports of packages that extensions may use.\n// These MUST be static so Bun bundles them into the compiled binary.\n// The virtualModules option then makes them available to extensions.\nimport * as _bundledTypebox from \"typebox\";\nimport * as _bundledTypeboxCompile from \"typebox/compile\";\nimport * as _bundledTypeboxValue from \"typebox/value\";\nimport { CONFIG_DIR_NAME, getAgentDir, isBunBinary } from \"../../config.ts\";\n// NOTE: This import works because loader.ts exports are NOT re-exported from index.ts,\n// avoiding a circular dependency. Extensions can import from @caupulican/pi-adaptative.\nimport * as _bundledPiCodingAgent from \"../../index.ts\";\nimport { resolvePath } from \"../../utils/paths.ts\";\nimport { cacheFile } from \"../agent-paths.ts\";\nimport { createEventBus, type EventBus } from \"../event-bus.ts\";\nimport type { ExecOptions } from \"../exec.ts\";\nimport { execCommand } from \"../exec.ts\";\nimport { createSyntheticSourceInfo } from \"../source-info.ts\";\nimport type {\n\tExtension,\n\tExtensionAPI,\n\tExtensionFactory,\n\tExtensionRuntime,\n\tLoadExtensionsResult,\n\tMessageRenderer,\n\tProviderConfig,\n\tRegisteredCommand,\n\tToolDefinition,\n} from \"./types.ts\";\n\nconst EXTENSION_FACTORY_TIMEOUT_MS = 30_000;\nconst EXTENSION_DISPOSAL_TIMEOUT_MS = 5_000;\nconst inactiveExtensions = new WeakSet<Extension>();\n\nclass ExtensionFactoryTimeoutError extends Error {}\n\n/** Modules available to extensions via virtualModules (for compiled Bun binary) */\nconst VIRTUAL_MODULES: Record<string, unknown> = {\n\ttypebox: _bundledTypebox,\n\t\"typebox/compile\": _bundledTypeboxCompile,\n\t\"typebox/value\": _bundledTypeboxValue,\n\t\"@sinclair/typebox\": _bundledTypebox,\n\t\"@sinclair/typebox/compile\": _bundledTypeboxCompile,\n\t\"@sinclair/typebox/value\": _bundledTypeboxValue,\n\t\"@caupulican/pi-agent-core\": _bundledPiAgentCore,\n\t\"@caupulican/pi-tui\": _bundledPiTui,\n\t\"@caupulican/pi-ai\": _bundledPiAi,\n\t\"@caupulican/pi-ai/oauth\": _bundledPiAiOauth,\n\t\"@caupulican/pi-adaptative\": _bundledPiCodingAgent,\n\t\"@earendil-works/pi-agent-core\": _bundledPiAgentCore,\n\t\"@earendil-works/pi-tui\": _bundledPiTui,\n\t\"@earendil-works/pi-ai\": _bundledPiAi,\n\t\"@earendil-works/pi-ai/oauth\": _bundledPiAiOauth,\n\t\"@earendil-works/pi-coding-agent\": _bundledPiCodingAgent,\n\t\"@mariozechner/pi-agent-core\": _bundledPiAgentCore,\n\t\"@mariozechner/pi-tui\": _bundledPiTui,\n\t\"@mariozechner/pi-ai\": _bundledPiAi,\n\t\"@mariozechner/pi-ai/oauth\": _bundledPiAiOauth,\n\t\"@mariozechner/pi-coding-agent\": _bundledPiCodingAgent,\n};\n\nfunction uniquePaths(paths: string[]): string[] {\n\treturn [...new Set(paths)];\n}\n\nfunction safeRealpath(filePath: string): string {\n\ttry {\n\t\treturn fs.realpathSync(filePath);\n\t} catch {\n\t\treturn filePath;\n\t}\n}\n\n/**\n * Get aliases for jiti (used in Node.js/development mode).\n * In Bun binary mode, virtualModules is used instead.\n */\nlet _aliases: Record<string, string> | null = null;\n\nfunction getAliases(): Record<string, string> {\n\tif (_aliases) return _aliases;\n\n\tconst loaderFile = fileURLToPath(import.meta.url);\n\tconst realLoaderFile = safeRealpath(loaderFile);\n\tconst __dirname = path.dirname(loaderFile);\n\tconst realDirname = path.dirname(realLoaderFile);\n\tconst packageIndex = [\n\t\tpath.resolve(__dirname, \"../..\", \"index.ts\"),\n\t\tpath.resolve(__dirname, \"../..\", \"index.js\"),\n\t].find((candidate) => fs.existsSync(candidate));\n\tif (!packageIndex) throw new Error(\"Unable to resolve the coding-agent package entry\");\n\n\tconst moduleRequires = uniquePaths([loaderFile, realLoaderFile]).map((file) => createRequire(file));\n\tconst resolveModule = (specifier: string): string => {\n\t\tfor (const moduleRequire of moduleRequires) {\n\t\t\ttry {\n\t\t\t\treturn moduleRequire.resolve(specifier);\n\t\t\t} catch {\n\t\t\t\t// Try the next resolution base. Linked global installs may resolve the\n\t\t\t\t// loader through the global symlink path while workspace dependencies are\n\t\t\t\t// hoisted beside the real source path.\n\t\t\t}\n\t\t}\n\t\treturn fileURLToPath(import.meta.resolve(specifier));\n\t};\n\n\tconst typeboxEntry = resolveModule(\"typebox\");\n\tconst typeboxCompileEntry = resolveModule(\"typebox/compile\");\n\tconst typeboxValueEntry = resolveModule(\"typebox/value\");\n\n\tconst packagesRoots = uniquePaths([\n\t\tpath.resolve(__dirname, \"../../../../\"),\n\t\tpath.resolve(realDirname, \"../../../../\"),\n\t]);\n\tconst resolveWorkspaceOrImport = (workspaceRelativePath: string, specifier: string): string => {\n\t\tfor (const packagesRoot of packagesRoots) {\n\t\t\tconst workspacePath = path.join(packagesRoot, workspaceRelativePath);\n\t\t\tif (fs.existsSync(workspacePath)) {\n\t\t\t\treturn workspacePath;\n\t\t\t}\n\t\t}\n\t\treturn resolveModule(specifier);\n\t};\n\n\tconst piCodingAgentEntry = packageIndex;\n\tconst piAgentCoreEntry = resolveWorkspaceOrImport(\"agent/src/index.ts\", \"@caupulican/pi-agent-core\");\n\tconst piAgentCoreNodeEntry = resolveWorkspaceOrImport(\"agent/src/node.ts\", \"@caupulican/pi-agent-core/node\");\n\tconst piAgentCorePathsEntry = resolveWorkspaceOrImport(\n\t\t\"agent/src/utils/paths.ts\",\n\t\t\"@caupulican/pi-agent-core/paths\",\n\t);\n\tconst piTuiEntry = resolveWorkspaceOrImport(\"tui/src/index.ts\", \"@caupulican/pi-tui\");\n\tconst piAiEntry = resolveWorkspaceOrImport(\"ai/src/index.ts\", \"@caupulican/pi-ai\");\n\tconst piAiOauthEntry = resolveWorkspaceOrImport(\"ai/src/oauth.ts\", \"@caupulican/pi-ai/oauth\");\n\n\t_aliases = {\n\t\t\"@caupulican/pi-agent-core/node\": piAgentCoreNodeEntry,\n\t\t\"@caupulican/pi-agent-core/paths\": piAgentCorePathsEntry,\n\t\t\"@caupulican/pi-ai/oauth\": piAiOauthEntry,\n\t\t\"@caupulican/pi-adaptative\": piCodingAgentEntry,\n\t\t\"@caupulican/pi-agent-core\": piAgentCoreEntry,\n\t\t\"@caupulican/pi-tui\": piTuiEntry,\n\t\t\"@caupulican/pi-ai\": piAiEntry,\n\t\t\"@earendil-works/pi-agent-core/node\": piAgentCoreNodeEntry,\n\t\t\"@earendil-works/pi-agent-core/paths\": piAgentCorePathsEntry,\n\t\t\"@earendil-works/pi-ai/oauth\": piAiOauthEntry,\n\t\t\"@earendil-works/pi-coding-agent\": piCodingAgentEntry,\n\t\t\"@earendil-works/pi-agent-core\": piAgentCoreEntry,\n\t\t\"@earendil-works/pi-tui\": piTuiEntry,\n\t\t\"@earendil-works/pi-ai\": piAiEntry,\n\t\t\"@mariozechner/pi-agent-core/node\": piAgentCoreNodeEntry,\n\t\t\"@mariozechner/pi-agent-core/paths\": piAgentCorePathsEntry,\n\t\t\"@mariozechner/pi-ai/oauth\": piAiOauthEntry,\n\t\t\"@mariozechner/pi-coding-agent\": piCodingAgentEntry,\n\t\t\"@mariozechner/pi-agent-core\": piAgentCoreEntry,\n\t\t\"@mariozechner/pi-tui\": piTuiEntry,\n\t\t\"@mariozechner/pi-ai\": piAiEntry,\n\t\ttypebox: typeboxEntry,\n\t\t\"typebox/compile\": typeboxCompileEntry,\n\t\t\"typebox/value\": typeboxValueEntry,\n\t\t\"@sinclair/typebox\": typeboxEntry,\n\t\t\"@sinclair/typebox/compile\": typeboxCompileEntry,\n\t\t\"@sinclair/typebox/value\": typeboxValueEntry,\n\t};\n\n\treturn _aliases;\n}\n\ntype HandlerFn = (...args: unknown[]) => Promise<unknown>;\n\nfunction yieldToEventLoop(): Promise<void> {\n\treturn new Promise((resolve) => setImmediate(resolve));\n}\n\n/**\n * Create a runtime with throwing stubs for action methods.\n * Runner.bindCore() replaces these with real implementations.\n */\nexport function createExtensionRuntime(): ExtensionRuntime {\n\tconst notInitialized = () => {\n\t\tthrow new Error(\"Extension runtime not initialized. Action methods cannot be called during extension loading.\");\n\t};\n\tconst state: { staleMessage?: string } = {};\n\tconst assertActive = () => {\n\t\tif (state.staleMessage) {\n\t\t\tthrow new Error(state.staleMessage);\n\t\t}\n\t};\n\n\tconst providersByExtension = new Map<string, Set<string>>();\n\tconst providerRegistrations = new Map<string, { config: ProviderConfig; extensionPath?: string }>();\n\tconst memoryProvidersByExtension = new Map<string, Set<Parameters<ExtensionRuntime[\"registerMemoryProvider\"]>[0]>>();\n\tconst contextMemoryProvidersByExtension = new Map<\n\t\tstring,\n\t\tSet<Parameters<ExtensionRuntime[\"registerContextMemoryProvider\"]>[0]>\n\t>();\n\n\tconst runtime: ExtensionRuntime = {\n\t\tsendMessage: notInitialized,\n\t\tsendUserMessage: notInitialized,\n\t\tappendEntry: notInitialized,\n\t\tsetSessionName: notInitialized,\n\t\tgetSessionName: notInitialized,\n\t\tsetLabel: notInitialized,\n\t\tgetActiveTools: notInitialized,\n\t\tgetAllTools: notInitialized,\n\t\tsetActiveTools: notInitialized,\n\t\t// registerTool() is valid during extension load; refresh is only needed post-bind.\n\t\trefreshTools: () => {},\n\t\tgetCommands: notInitialized,\n\t\tsetModel: notInitialized,\n\t\tgetThinkingLevel: notInitialized,\n\t\tsetThinkingLevel: notInitialized,\n\t\tgetExternalResourceRoots: notInitialized,\n\t\tregisterMemoryProvider: notInitialized,\n\t\tregisterContextMemoryProvider: notInitialized,\n\t\treportSpawnedUsage: notInitialized,\n\t\treportManagedLane: notInitialized,\n\t\tflagValues: new Map(),\n\t\tpendingProviderRegistrations: [],\n\t\tassertActive,\n\t\tinvalidate: (message) => {\n\t\t\tstate.staleMessage ??=\n\t\t\t\tmessage ??\n\t\t\t\t\"This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().\";\n\t\t},\n\t\t// Pre-bind: queue registrations so bindCore() can flush them once the\n\t\t// model registry is available. bindCore() replaces both with direct calls.\n\t\tregisterProvider: (name, config, extensionPath = \"<unknown>\") => {\n\t\t\truntime.pendingProviderRegistrations.push({ name, config, extensionPath });\n\t\t},\n\t\tunregisterProvider: (name) => {\n\t\t\truntime.pendingProviderRegistrations = runtime.pendingProviderRegistrations.filter((r) => r.name !== name);\n\t\t},\n\t\tprovidersByExtension,\n\t\tproviderRegistrations,\n\t\tgetProvidersForExtension: (extensionPath: string) => {\n\t\t\treturn [...(providersByExtension.get(extensionPath) ?? [])];\n\t\t},\n\t\tmemoryProvidersByExtension,\n\t\tcontextMemoryProvidersByExtension,\n\t};\n\n\treturn runtime;\n}\n\n/**\n * Create the ExtensionAPI for an extension.\n * Registration methods write to the extension object.\n * Action methods delegate to the shared runtime.\n */\nfunction createExtensionAPI(\n\textension: Extension,\n\truntime: ExtensionRuntime,\n\tcwd: string,\n\teventBus: EventBus,\n): ExtensionAPI {\n\t// A factory can time out while its promise continues running. Route every later API call through\n\t// an extension-generation guard so stale async work cannot register tools, handlers, or providers.\n\tconst sharedRuntime = runtime;\n\truntime = new Proxy(sharedRuntime, {\n\t\tget(target, property, receiver) {\n\t\t\tif (property === \"assertActive\") {\n\t\t\t\treturn () => {\n\t\t\t\t\ttarget.assertActive();\n\t\t\t\t\tif (inactiveExtensions.has(extension)) {\n\t\t\t\t\t\tthrow new Error(`Extension generation is no longer active: ${extension.path}`);\n\t\t\t\t\t}\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn Reflect.get(target, property, receiver);\n\t\t},\n\t});\n\n\tconst api = {\n\t\t// Registration methods - write to extension\n\t\ton(event: string, handler: HandlerFn): void {\n\t\t\truntime.assertActive();\n\t\t\tconst list = extension.handlers.get(event) ?? [];\n\t\t\tlist.push(handler);\n\t\t\textension.handlers.set(event, list);\n\t\t},\n\n\t\tregisterTool(tool: ToolDefinition): void {\n\t\t\truntime.assertActive();\n\t\t\textension.tools.set(tool.name, {\n\t\t\t\tdefinition: tool,\n\t\t\t\tsourceInfo: extension.sourceInfo,\n\t\t\t});\n\t\t\truntime.refreshTools();\n\t\t},\n\n\t\tregisterCommand(name: string, options: Omit<RegisteredCommand, \"name\" | \"sourceInfo\">): void {\n\t\t\truntime.assertActive();\n\t\t\textension.commands.set(name, {\n\t\t\t\tname,\n\t\t\t\tsourceInfo: extension.sourceInfo,\n\t\t\t\t...options,\n\t\t\t});\n\t\t},\n\n\t\tregisterShortcut(\n\t\t\tshortcut: KeyId,\n\t\t\toptions: {\n\t\t\t\tdescription?: string;\n\t\t\t\thandler: (ctx: import(\"./types.ts\").ExtensionContext) => Promise<void> | void;\n\t\t\t},\n\t\t): void {\n\t\t\truntime.assertActive();\n\t\t\textension.shortcuts.set(shortcut, { shortcut, extensionPath: extension.path, ...options });\n\t\t},\n\n\t\tregisterFlag(\n\t\t\tname: string,\n\t\t\toptions: { description?: string; type: \"boolean\" | \"string\"; default?: boolean | string },\n\t\t): void {\n\t\t\truntime.assertActive();\n\t\t\textension.flags.set(name, { name, extensionPath: extension.path, ...options });\n\t\t\tif (options.default !== undefined && !runtime.flagValues.has(name)) {\n\t\t\t\truntime.flagValues.set(name, options.default);\n\t\t\t}\n\t\t},\n\n\t\tregisterMessageRenderer<T>(customType: string, renderer: MessageRenderer<T>): void {\n\t\t\truntime.assertActive();\n\t\t\textension.messageRenderers.set(customType, renderer as MessageRenderer);\n\t\t},\n\n\t\t// Flag access - checks extension registered it, reads from runtime\n\t\tgetFlag(name: string): boolean | string | undefined {\n\t\t\truntime.assertActive();\n\t\t\tif (!extension.flags.has(name)) return undefined;\n\t\t\treturn runtime.flagValues.get(name);\n\t\t},\n\n\t\t// Action methods - delegate to shared runtime\n\t\tsendMessage(message, options): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.sendMessage(message, options);\n\t\t},\n\n\t\tsendUserMessage(content, options): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.sendUserMessage(content, options);\n\t\t},\n\n\t\tappendEntry(customType: string, data?: unknown): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.appendEntry(customType, data);\n\t\t},\n\n\t\tsetSessionName(name: string): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.setSessionName(name);\n\t\t},\n\n\t\tgetSessionName(): string | undefined {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getSessionName();\n\t\t},\n\n\t\tsetLabel(entryId: string, label: string | undefined): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.setLabel(entryId, label);\n\t\t},\n\n\t\texec(command: string, args: string[], options?: ExecOptions) {\n\t\t\truntime.assertActive();\n\t\t\treturn execCommand(command, args, options?.cwd ?? cwd, options);\n\t\t},\n\n\t\tgetActiveTools(): string[] {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getActiveTools();\n\t\t},\n\n\t\tgetAllTools() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getAllTools();\n\t\t},\n\n\t\tsetActiveTools(toolNames: string[]): void {\n\t\t\truntime.assertActive();\n\t\t\truntime.setActiveTools(toolNames);\n\t\t},\n\n\t\tgetCommands() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getCommands();\n\t\t},\n\n\t\tgetExternalResourceRoots() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getExternalResourceRoots();\n\t\t},\n\n\t\tregisterMemoryProvider(provider) {\n\t\t\truntime.assertActive();\n\t\t\truntime.registerMemoryProvider(provider);\n\t\t\tconst providers = runtime.memoryProvidersByExtension.get(extension.path) ?? new Set();\n\t\t\tproviders.add(provider);\n\t\t\truntime.memoryProvidersByExtension.set(extension.path, providers);\n\t\t},\n\n\t\tregisterContextMemoryProvider(provider) {\n\t\t\truntime.assertActive();\n\t\t\truntime.registerContextMemoryProvider(provider);\n\t\t\tconst providers = runtime.contextMemoryProvidersByExtension.get(extension.path) ?? new Set();\n\t\t\tproviders.add(provider);\n\t\t\truntime.contextMemoryProvidersByExtension.set(extension.path, providers);\n\t\t},\n\n\t\treportSpawnedUsage(usage, opts) {\n\t\t\truntime.assertActive();\n\t\t\truntime.reportSpawnedUsage(usage, opts);\n\t\t},\n\n\t\treportManagedLane(event) {\n\t\t\truntime.assertActive();\n\t\t\truntime.reportManagedLane(event);\n\t\t},\n\n\t\tsetModel(model) {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.setModel(model);\n\t\t},\n\n\t\tgetThinkingLevel() {\n\t\t\truntime.assertActive();\n\t\t\treturn runtime.getThinkingLevel();\n\t\t},\n\n\t\tsetThinkingLevel(level) {\n\t\t\truntime.assertActive();\n\t\t\truntime.setThinkingLevel(level);\n\t\t},\n\n\t\tregisterProvider(name: string, config: ProviderConfig) {\n\t\t\truntime.assertActive();\n\t\t\truntime.registerProvider(name, config, extension.path);\n\t\t},\n\n\t\tunregisterProvider(name: string) {\n\t\t\truntime.assertActive();\n\t\t\truntime.unregisterProvider(name, extension.path);\n\t\t},\n\n\t\tonDispose(fn: () => void | Promise<void>): void {\n\t\t\truntime.assertActive();\n\t\t\textension.disposers.push(fn);\n\t\t},\n\n\t\t// Track bus subscriptions per extension generation so hot reloads can\n\t\t// unsubscribe replaced generations (see disposeExtensionEventSubscriptions).\n\t\tevents: {\n\t\t\temit: (channel: string, data: unknown) => {\n\t\t\t\truntime.assertActive();\n\t\t\t\teventBus.emit(channel, data);\n\t\t\t},\n\t\t\ton: (channel: string, handler: (data: unknown) => void) => {\n\t\t\t\truntime.assertActive();\n\t\t\t\tconst unsubscribe = eventBus.on(channel, handler);\n\t\t\t\textension.eventUnsubscribes.push(unsubscribe);\n\t\t\t\treturn unsubscribe;\n\t\t\t},\n\t\t},\n\t} as ExtensionAPI;\n\n\treturn api;\n}\n\nasync function runExtensionFactory(\n\tfactory: ExtensionFactory,\n\tapi: ExtensionAPI,\n\ttimeoutMs: number = EXTENSION_FACTORY_TIMEOUT_MS,\n): Promise<void> {\n\tlet timeout: ReturnType<typeof setTimeout> | undefined;\n\tconst completion = Promise.resolve().then(() => factory(api));\n\ttry {\n\t\tawait Promise.race([\n\t\t\tcompletion,\n\t\t\tnew Promise<never>((_resolve, reject) => {\n\t\t\t\ttimeout = setTimeout(\n\t\t\t\t\t() => reject(new ExtensionFactoryTimeoutError(`Extension factory timed out after ${timeoutMs}ms`)),\n\t\t\t\t\tMath.max(0, timeoutMs),\n\t\t\t\t);\n\t\t\t}),\n\t\t]);\n\t} finally {\n\t\tif (timeout) clearTimeout(timeout);\n\t}\n}\n\nasync function loadExtensionModule(extensionPath: string, opts?: { fresh?: boolean; moduleTimeoutMs?: number }) {\n\tconst jiti = createJiti(import.meta.url, {\n\t\t// A fresh jiti instance is created on every call and moduleCache is disabled so each load\n\t\t// evaluates the module from scratch, producing a genuinely new instance with reset top-level\n\t\t// state and closures. This is required for hot reload (/reload, /new, /resume, /fork, profile\n\t\t// switch): a previous extension generation's module state must never leak into the next one.\n\t\t//\n\t\t// This is orthogonal to the Babel *transform* step. jiti has its own on-disk fsCache that\n\t\t// caches transformed output keyed by a content hash of the source, independent of\n\t\t// moduleCache. Pointing it at an explicit, durable directory under the agent dir (instead of\n\t\t// jiti's default heuristic, which falls back to a shared OS tmp dir when no node_modules\n\t\t// sibling exists next to the extension file) makes unchanged extensions skip Babel on repeat\n\t\t// loads while still isolating module state, and edits are still detected automatically via\n\t\t// the content hash. Do not hand-roll a second in-memory transform cache on top of this: it\n\t\t// would duplicate jiti's own content-hash-validated cache for no benefit.\n\t\tmoduleCache: false,\n\t\tfsCache: cacheFile(getAgentDir(), \"jiti-transforms\"),\n\t\t// In Bun binary: use virtualModules for bundled packages (no filesystem resolution)\n\t\t// Also disable tryNative so jiti handles ALL imports (not just the entry point)\n\t\t// In Node.js/dev: use aliases to resolve to node_modules paths\n\t\t...(isBunBinary ? { virtualModules: VIRTUAL_MODULES, tryNative: false } : { alias: getAliases() }),\n\t});\n\n\t// Every call gets a fresh jiti instance with moduleCache disabled. Do not append a query string:\n\t// jiti's Windows path resolver treats it as part of the .ts filename.\n\tconst timeoutMs = opts?.moduleTimeoutMs ?? EXTENSION_FACTORY_TIMEOUT_MS;\n\tlet timeout: ReturnType<typeof setTimeout> | undefined;\n\ttry {\n\t\tconst module = await Promise.race([\n\t\t\tjiti.import(extensionPath, { default: true }),\n\t\t\tnew Promise<never>((_resolve, reject) => {\n\t\t\t\ttimeout = setTimeout(\n\t\t\t\t\t() => reject(new Error(`Extension module import timed out after ${timeoutMs}ms: ${extensionPath}`)),\n\t\t\t\t\tMath.max(0, timeoutMs),\n\t\t\t\t);\n\t\t\t}),\n\t\t]);\n\t\tconst factory = module as ExtensionFactory;\n\t\treturn typeof factory !== \"function\" ? undefined : factory;\n\t} finally {\n\t\tif (timeout) clearTimeout(timeout);\n\t}\n}\n\n/**\n * Create an Extension object with empty collections.\n */\nfunction createExtension(extensionPath: string, resolvedPath: string): Extension {\n\tconst source =\n\t\textensionPath.startsWith(\"<\") && extensionPath.endsWith(\">\")\n\t\t\t? extensionPath.slice(1, -1).split(\":\")[0] || \"temporary\"\n\t\t\t: \"local\";\n\tconst baseDir = extensionPath.startsWith(\"<\") ? undefined : path.dirname(resolvedPath);\n\n\treturn {\n\t\tpath: extensionPath,\n\t\tresolvedPath,\n\t\tsourceInfo: createSyntheticSourceInfo(extensionPath, { source, baseDir }),\n\t\thandlers: new Map(),\n\t\ttools: new Map(),\n\t\tmessageRenderers: new Map(),\n\t\tcommands: new Map(),\n\t\tflags: new Map(),\n\t\tshortcuts: new Map(),\n\t\teventUnsubscribes: [],\n\t\tdisposers: [],\n\t};\n}\n\n/**\n * Unsubscribe a replaced extension generation's pi.events handlers from the shared\n * event bus and invoke cleanup callbacks. Without this, every hot reload leaves the\n * previous generation's handlers subscribed, pinning the old module graph in memory\n * and double-processing events.\n */\nexport async function disposeExtensionEventSubscriptions(\n\textensions: Extension[],\n\toptions: { deactivate?: boolean; timeoutMs?: number } = {},\n): Promise<void> {\n\tconst deadline = Date.now() + (options.timeoutMs ?? EXTENSION_DISPOSAL_TIMEOUT_MS);\n\tfor (const extension of extensions) {\n\t\tif (options.deactivate ?? true) inactiveExtensions.add(extension);\n\t\t// Unsubscribe event listeners\n\t\tfor (const unsubscribe of extension.eventUnsubscribes) {\n\t\t\ttry {\n\t\t\t\tunsubscribe();\n\t\t\t} catch {\n\t\t\t\t// Disposal must never break a reload.\n\t\t\t}\n\t\t}\n\t\textension.eventUnsubscribes.length = 0;\n\n\t\t// Invoke every cleanup callback, but never let one unresolved async disposer block reload or\n\t\t// shutdown indefinitely. Late continuations retain rejection handlers and the inactive API guard.\n\t\tfor (const disposer of extension.disposers) {\n\t\t\ttry {\n\t\t\t\tconst result = disposer();\n\t\t\t\tif (result !== undefined) {\n\t\t\t\t\tconst completion = Promise.resolve(result).catch(() => undefined);\n\t\t\t\t\tconst remainingMs = Math.max(0, deadline - Date.now());\n\t\t\t\t\tif (remainingMs > 0) {\n\t\t\t\t\t\tlet timeout: ReturnType<typeof setTimeout> | undefined;\n\t\t\t\t\t\tawait Promise.race([\n\t\t\t\t\t\t\tcompletion,\n\t\t\t\t\t\t\tnew Promise<void>((resolve) => {\n\t\t\t\t\t\t\t\ttimeout = setTimeout(resolve, remainingMs);\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t]);\n\t\t\t\t\t\tif (timeout) clearTimeout(timeout);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Disposal must never break a reload.\n\t\t\t}\n\t\t}\n\t\textension.disposers.length = 0;\n\t}\n}\n\ninterface ExtensionLoadRuntimeSnapshot {\n\tpendingProviderRegistrations: ExtensionRuntime[\"pendingProviderRegistrations\"];\n\tflagValues: Map<string, boolean | string>;\n\tproviderRegistrations: ExtensionRuntime[\"providerRegistrations\"];\n}\n\nfunction snapshotExtensionLoadRuntime(runtime: ExtensionRuntime): ExtensionLoadRuntimeSnapshot {\n\treturn {\n\t\tpendingProviderRegistrations: [...runtime.pendingProviderRegistrations],\n\t\tflagValues: new Map(runtime.flagValues),\n\t\tproviderRegistrations: new Map(runtime.providerRegistrations),\n\t};\n}\n\nfunction restoreExtensionLoadRuntime(runtime: ExtensionRuntime, snapshot: ExtensionLoadRuntimeSnapshot): void {\n\tfor (const [name, current] of runtime.providerRegistrations) {\n\t\tconst previous = snapshot.providerRegistrations.get(name);\n\t\tif (!previous || previous.config !== current.config || previous.extensionPath !== current.extensionPath) {\n\t\t\ttry {\n\t\t\t\truntime.unregisterProvider(name, current.extensionPath);\n\t\t\t} catch {\n\t\t\t\t// Preserve the original factory failure; reload rollback remains the outer safety net.\n\t\t\t}\n\t\t}\n\t}\n\tfor (const [name, previous] of snapshot.providerRegistrations) {\n\t\tconst current = runtime.providerRegistrations.get(name);\n\t\tif (current?.config === previous.config && current.extensionPath === previous.extensionPath) continue;\n\t\ttry {\n\t\t\truntime.registerProvider(name, previous.config, previous.extensionPath);\n\t\t} catch {\n\t\t\t// Preserve the original factory failure; reload rollback remains the outer safety net.\n\t\t}\n\t}\n\n\truntime.pendingProviderRegistrations = snapshot.pendingProviderRegistrations;\n\truntime.flagValues.clear();\n\tfor (const [name, value] of snapshot.flagValues) {\n\t\truntime.flagValues.set(name, value);\n\t}\n}\n\nexport async function loadExtension(\n\textensionPath: string,\n\tcwd: string,\n\teventBus: EventBus,\n\truntime: ExtensionRuntime,\n\topts?: { fresh?: boolean; factoryTimeoutMs?: number; moduleTimeoutMs?: number },\n): Promise<{ extension: Extension | null; error: string | null }> {\n\tconst resolvedPath = resolvePath(extensionPath, cwd, { normalizeUnicodeSpaces: true });\n\n\ttry {\n\t\tconst factory = await loadExtensionModule(resolvedPath, opts);\n\t\tif (!factory) {\n\t\t\treturn { extension: null, error: `Extension does not export a valid factory function: ${extensionPath}` };\n\t\t}\n\n\t\tconst extension = createExtension(extensionPath, resolvedPath);\n\t\tconst api = createExtensionAPI(extension, runtime, cwd, eventBus);\n\t\tconst runtimeSnapshot = snapshotExtensionLoadRuntime(runtime);\n\t\ttry {\n\t\t\tawait runExtensionFactory(factory, api, opts?.factoryTimeoutMs);\n\t\t} catch (err) {\n\t\t\tawait disposeExtensionEventSubscriptions([extension]);\n\t\t\trestoreExtensionLoadRuntime(runtime, runtimeSnapshot);\n\t\t\tthrow err;\n\t\t}\n\n\t\treturn { extension, error: null };\n\t} catch (err) {\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\treturn { extension: null, error: `Failed to load extension: ${message}` };\n\t}\n}\n\nfunction createLazyToolDefinition(\n\textension: Extension,\n\tmanifest: LazyToolManifest,\n\tload: () => Promise<void>,\n): ToolDefinition {\n\tconst name = String(manifest.name).trim();\n\tconst definition: ToolDefinition = {\n\t\tname,\n\t\tlabel: typeof manifest.label === \"string\" && manifest.label.trim() ? manifest.label : name,\n\t\tdescription:\n\t\t\ttypeof manifest.description === \"string\" && manifest.description.trim()\n\t\t\t\t? manifest.description\n\t\t\t\t: `Lazy extension tool ${name}`,\n\t\tparameters: (manifest.parameters ?? defaultLazyToolParameters()) as ToolDefinition[\"parameters\"],\n\t\tpromptSnippet: typeof manifest.promptSnippet === \"string\" ? manifest.promptSnippet : undefined,\n\t\tpromptGuidelines: Array.isArray(manifest.promptGuidelines)\n\t\t\t? manifest.promptGuidelines.filter((item): item is string => typeof item === \"string\")\n\t\t\t: undefined,\n\t\ttoolGroup: typeof manifest.toolGroup === \"string\" ? manifest.toolGroup : undefined,\n\t\texecutionMode:\n\t\t\tmanifest.executionMode === \"parallel\" || manifest.executionMode === \"sequential\"\n\t\t\t\t? manifest.executionMode\n\t\t\t\t: undefined,\n\t\texecute: async (toolCallId, params, signal, onUpdate, ctx) => {\n\t\t\tawait load();\n\t\t\tconst loadedDefinition = extension.tools.get(name)?.definition;\n\t\t\tif (!loadedDefinition || loadedDefinition === definition) {\n\t\t\t\tthrow new Error(`Lazy extension ${extension.path} did not register tool ${name}`);\n\t\t\t}\n\t\t\treturn loadedDefinition.execute(toolCallId, params, signal, onUpdate, ctx);\n\t\t},\n\t};\n\treturn definition;\n}\n\nfunction createLazyExtension(\n\textensionPath: string,\n\tresolvedPath: string,\n\tcwd: string,\n\teventBus: EventBus,\n\truntime: ExtensionRuntime,\n\tlazyTools: LazyToolManifest[],\n): Extension {\n\tconst extension = createExtension(extensionPath, resolvedPath);\n\tlet restoreLazyToolPlaceholders = (): void => {};\n\tconst load = async (): Promise<void> => {\n\t\tif (inactiveExtensions.has(extension)) {\n\t\t\tthrow new Error(`Lazy extension generation is no longer active: ${extension.path}`);\n\t\t}\n\t\tif (extension.lazy?.loaded) return;\n\t\tif (extension.lazy?.loading) return extension.lazy.loading;\n\n\t\tconst loading = (async () => {\n\t\t\tconst factory = await loadExtensionModule(resolvedPath);\n\t\t\tif (!factory) {\n\t\t\t\tthrow new Error(`Extension does not export a valid factory function: ${extensionPath}`);\n\t\t\t}\n\t\t\tconst api = createExtensionAPI(extension, runtime, cwd, eventBus);\n\t\t\tconst runtimeSnapshot = snapshotExtensionLoadRuntime(runtime);\n\t\t\ttry {\n\t\t\t\tawait runExtensionFactory(factory, api);\n\t\t\t} catch (error) {\n\t\t\t\tawait disposeExtensionEventSubscriptions([extension], { deactivate: false });\n\t\t\t\trestoreExtensionLoadRuntime(runtime, runtimeSnapshot);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (extension.lazy) {\n\t\t\t\textension.lazy.loaded = true;\n\t\t\t\textension.lazy.loading = undefined;\n\t\t\t}\n\t\t})();\n\n\t\tif (extension.lazy) extension.lazy.loading = loading;\n\t\ttry {\n\t\t\tawait loading;\n\t\t} catch (err) {\n\t\t\tawait disposeExtensionEventSubscriptions([extension], {\n\t\t\t\tdeactivate: err instanceof ExtensionFactoryTimeoutError,\n\t\t\t});\n\t\t\textension.handlers.clear();\n\t\t\textension.messageRenderers.clear();\n\t\t\textension.commands.clear();\n\t\t\textension.flags.clear();\n\t\t\textension.shortcuts.clear();\n\t\t\textension.tools.clear();\n\t\t\trestoreLazyToolPlaceholders();\n\t\t\tif (extension.lazy) extension.lazy.loading = undefined;\n\t\t\tthrow err;\n\t\t}\n\t};\n\n\textension.lazy = { loaded: false, load };\n\trestoreLazyToolPlaceholders = () => {\n\t\tfor (const tool of lazyTools) {\n\t\t\tconst name = String(tool.name).trim();\n\t\t\textension.tools.set(name, {\n\t\t\t\tdefinition: createLazyToolDefinition(extension, tool, load),\n\t\t\t\tsourceInfo: extension.sourceInfo,\n\t\t\t});\n\t\t}\n\t};\n\trestoreLazyToolPlaceholders();\n\treturn extension;\n}\n\n/**\n * Create an Extension from an inline factory function.\n */\nexport async function loadExtensionFromFactory(\n\tfactory: ExtensionFactory,\n\tcwd: string,\n\teventBus: EventBus,\n\truntime: ExtensionRuntime,\n\textensionPath = \"<inline>\",\n\toptions: { factoryTimeoutMs?: number } = {},\n): Promise<Extension> {\n\tconst extension = createExtension(extensionPath, extensionPath);\n\tconst resolvedCwd = resolvePath(cwd);\n\tconst api = createExtensionAPI(extension, runtime, resolvedCwd, eventBus);\n\tconst runtimeSnapshot = snapshotExtensionLoadRuntime(runtime);\n\ttry {\n\t\tawait runExtensionFactory(factory, api, options.factoryTimeoutMs);\n\t} catch (err) {\n\t\tawait disposeExtensionEventSubscriptions([extension]);\n\t\trestoreExtensionLoadRuntime(runtime, runtimeSnapshot);\n\t\tthrow err;\n\t}\n\treturn extension;\n}\n\n/**\n * Load extensions from paths.\n */\nexport async function loadExtensions(\n\tpaths: Array<string | ExtensionLoadSpec>,\n\tcwd: string,\n\teventBus?: EventBus,\n): Promise<LoadExtensionsResult> {\n\tconst extensions: Extension[] = [];\n\tconst errors: Array<{ path: string; error: string }> = [];\n\tconst resolvedCwd = resolvePath(cwd);\n\tconst resolvedEventBus = eventBus ?? createEventBus();\n\tconst runtime = createExtensionRuntime();\n\n\tfor (const spec of paths) {\n\t\tconst normalized = typeof spec === \"string\" ? { path: spec } : spec;\n\t\tconst extPath = normalized.path;\n\t\tconst resolvedPath = resolvePath(extPath, resolvedCwd, { normalizeUnicodeSpaces: true });\n\t\tconst lazyTools = (normalized.lazyTools ?? inferLazyToolsForExtensionPath(resolvedPath))?.filter(\n\t\t\t(tool) => typeof tool.name === \"string\" && tool.name.trim(),\n\t\t);\n\t\t// Extension imports can be CPU-heavy under jiti. Yield around each load so\n\t\t// interactive reloads can repaint/status-update instead of freezing the TUI\n\t\t// for the whole extension set. Lazy tool manifests skip import entirely here.\n\t\tawait yieldToEventLoop();\n\t\tif (lazyTools?.length) {\n\t\t\textensions.push(createLazyExtension(extPath, resolvedPath, resolvedCwd, resolvedEventBus, runtime, lazyTools));\n\t\t\tawait yieldToEventLoop();\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst { extension, error } = await loadExtension(extPath, resolvedCwd, resolvedEventBus, runtime);\n\t\tawait yieldToEventLoop();\n\n\t\tif (error) {\n\t\t\terrors.push({ path: extPath, error });\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (extension) {\n\t\t\textensions.push(extension);\n\t\t}\n\t}\n\n\treturn {\n\t\textensions,\n\t\terrors,\n\t\truntime,\n\t};\n}\n\ninterface LazyToolManifest {\n\tname?: unknown;\n\tlabel?: unknown;\n\tdescription?: unknown;\n\tparameters?: unknown;\n\tpromptSnippet?: unknown;\n\tpromptGuidelines?: unknown;\n\ttoolGroup?: unknown;\n\texecutionMode?: unknown;\n\t/** Optional extension entry this tool belongs to when a package declares multiple entries. */\n\textension?: unknown;\n}\n\ninterface PiManifest {\n\textensions?: string[];\n\tthemes?: string[];\n\tskills?: string[];\n\tprompts?: string[];\n\t/** Tool metadata for opt-in lazy extension loading. Factories stay unloaded until one of these tools runs. */\n\tlazyTools?: LazyToolManifest[];\n\t/** Alternate nested spelling: { tools: [...] }. */\n\tlazy?: { tools?: LazyToolManifest[] } | boolean;\n}\n\ninterface ExtensionLoadSpec {\n\tpath: string;\n\tlazyTools?: LazyToolManifest[];\n}\n\nfunction getManifestLazyTools(manifest: PiManifest | null): LazyToolManifest[] | undefined {\n\tif (!manifest) return undefined;\n\tconst tools = Array.isArray(manifest.lazyTools)\n\t\t? manifest.lazyTools\n\t\t: typeof manifest.lazy === \"object\" && Array.isArray(manifest.lazy.tools)\n\t\t\t? manifest.lazy.tools\n\t\t\t: undefined;\n\treturn tools?.filter((tool) => tool && typeof tool.name === \"string\" && tool.name.trim());\n}\n\nfunction defaultLazyToolParameters(): ToolDefinition[\"parameters\"] {\n\treturn { type: \"object\", properties: {}, additionalProperties: false } as ToolDefinition[\"parameters\"];\n}\n\nfunction lazyToolsForEntry(tools: LazyToolManifest[] | undefined, dir: string, entryPath: string, entryCount: number) {\n\tif (!tools?.length) return undefined;\n\tconst selected = tools.filter((tool) => {\n\t\tif (typeof tool.extension !== \"string\" || !tool.extension.trim()) {\n\t\t\treturn entryCount === 1;\n\t\t}\n\t\treturn path.resolve(dir, tool.extension) === entryPath;\n\t});\n\treturn selected.length > 0 ? selected : undefined;\n}\n\nfunction inferLazyToolsForExtensionPath(resolvedPath: string): LazyToolManifest[] | undefined {\n\tconst dir = path.dirname(resolvedPath);\n\tconst manifest = readPiManifest(path.join(dir, \"package.json\"));\n\tconst lazyTools = getManifestLazyTools(manifest);\n\tif (!manifest?.extensions?.length || !lazyTools?.length) return undefined;\n\tconst resolvedEntries = manifest.extensions.map((extPath) => path.resolve(dir, extPath));\n\tif (!resolvedEntries.includes(resolvedPath)) return undefined;\n\treturn lazyToolsForEntry(lazyTools, dir, resolvedPath, resolvedEntries.length);\n}\n\nfunction readPiManifest(packageJsonPath: string): PiManifest | null {\n\ttry {\n\t\tconst content = fs.readFileSync(packageJsonPath, \"utf-8\");\n\t\tconst pkg = JSON.parse(content);\n\t\tif (pkg.pi && typeof pkg.pi === \"object\") {\n\t\t\treturn pkg.pi as PiManifest;\n\t\t}\n\t\treturn null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nfunction isExtensionFile(name: string): boolean {\n\treturn name.endsWith(\".ts\") || name.endsWith(\".js\");\n}\n\n/**\n * Resolve extension entry points from a directory.\n *\n * Checks for:\n * 1. package.json with \"pi.extensions\" field -> returns declared paths\n * 2. index.ts or index.js -> returns the index file\n *\n * Returns resolved paths or null if no entry points found.\n */\nfunction resolveExtensionEntries(dir: string): ExtensionLoadSpec[] | null {\n\t// Check for package.json with \"pi\" field first\n\tconst packageJsonPath = path.join(dir, \"package.json\");\n\tif (fs.existsSync(packageJsonPath)) {\n\t\tconst manifest = readPiManifest(packageJsonPath);\n\t\tif (manifest?.extensions?.length) {\n\t\t\tconst resolvedEntries = manifest.extensions\n\t\t\t\t.map((extPath) => path.resolve(dir, extPath))\n\t\t\t\t.filter((resolvedExtPath) => fs.existsSync(resolvedExtPath));\n\t\t\tif (resolvedEntries.length > 0) {\n\t\t\t\tconst lazyTools = getManifestLazyTools(manifest);\n\t\t\t\treturn resolvedEntries.map((entryPath) => ({\n\t\t\t\t\tpath: entryPath,\n\t\t\t\t\tlazyTools: lazyToolsForEntry(lazyTools, dir, entryPath, resolvedEntries.length),\n\t\t\t\t}));\n\t\t\t}\n\t\t}\n\t}\n\n\t// Check for index.ts or index.js\n\tconst indexTs = path.join(dir, \"index.ts\");\n\tconst indexJs = path.join(dir, \"index.js\");\n\tif (fs.existsSync(indexTs)) {\n\t\treturn [{ path: indexTs }];\n\t}\n\tif (fs.existsSync(indexJs)) {\n\t\treturn [{ path: indexJs }];\n\t}\n\n\treturn null;\n}\n\n/**\n * Discover extensions in a directory.\n *\n * Discovery rules:\n * 1. Direct files: `extensions/*.ts` or `*.js` → load\n * 2. Subdirectory with index: `extensions/* /index.ts` or `index.js` → load\n * 3. Subdirectory with package.json: `extensions/* /package.json` with \"pi\" field → load what it declares\n *\n * No recursion beyond one level. Complex packages must use package.json manifest.\n */\nfunction discoverExtensionsInDir(dir: string): ExtensionLoadSpec[] {\n\tif (!fs.existsSync(dir)) {\n\t\treturn [];\n\t}\n\n\tconst discovered: ExtensionLoadSpec[] = [];\n\n\ttry {\n\t\tconst entries = fs.readdirSync(dir, { withFileTypes: true });\n\n\t\tfor (const entry of entries) {\n\t\t\tconst entryPath = path.join(dir, entry.name);\n\n\t\t\t// 1. Direct files: *.ts or *.js\n\t\t\tif ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {\n\t\t\t\tdiscovered.push({ path: entryPath });\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\t// 2 & 3. Subdirectories\n\t\t\tif (entry.isDirectory() || entry.isSymbolicLink()) {\n\t\t\t\tconst entries = resolveExtensionEntries(entryPath);\n\t\t\t\tif (entries) {\n\t\t\t\t\tdiscovered.push(...entries);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t} catch {\n\t\treturn [];\n\t}\n\n\treturn discovered;\n}\n\n/**\n * Discover and load extensions from standard locations.\n */\nexport async function discoverAndLoadExtensions(\n\tconfiguredPaths: string[],\n\tcwd: string,\n\tagentDir: string = getAgentDir(),\n\teventBus?: EventBus,\n): Promise<LoadExtensionsResult> {\n\tconst resolvedCwd = resolvePath(cwd);\n\tconst resolvedAgentDir = resolvePath(agentDir);\n\tconst allPaths: ExtensionLoadSpec[] = [];\n\tconst seen = new Set<string>();\n\n\tconst addPaths = (paths: Array<string | ExtensionLoadSpec>) => {\n\t\tfor (const spec of paths) {\n\t\t\tconst normalized = typeof spec === \"string\" ? { path: spec } : spec;\n\t\t\tconst resolved = path.resolve(normalized.path);\n\t\t\tif (!seen.has(resolved)) {\n\t\t\t\tseen.add(resolved);\n\t\t\t\tallPaths.push(normalized);\n\t\t\t}\n\t\t}\n\t};\n\n\t// 1. Project-local extensions: cwd/${CONFIG_DIR_NAME}/extensions/\n\tconst localExtDir = path.join(resolvedCwd, CONFIG_DIR_NAME, \"extensions\");\n\taddPaths(discoverExtensionsInDir(localExtDir));\n\n\t// 2. Global extensions: agentDir/extensions/\n\tconst globalExtDir = path.join(resolvedAgentDir, \"extensions\");\n\taddPaths(discoverExtensionsInDir(globalExtDir));\n\n\t// 3. Explicitly configured paths\n\tfor (const p of configuredPaths) {\n\t\tconst resolved = resolvePath(p, resolvedCwd, { normalizeUnicodeSpaces: true });\n\t\tif (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {\n\t\t\t// Check for package.json with pi manifest or index.ts\n\t\t\tconst entries = resolveExtensionEntries(resolved);\n\t\t\tif (entries) {\n\t\t\t\taddPaths(entries);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\t// No explicit entries - discover individual files in directory\n\t\t\taddPaths(discoverExtensionsInDir(resolved));\n\t\t\tcontinue;\n\t\t}\n\n\t\taddPaths([resolved]);\n\t}\n\n\treturn loadExtensions(allPaths, resolvedCwd, eventBus);\n}\n"]}