clinkx 0.2.3 → 1.0.0

package/dist/context-builder/lifecycle-reconcile.js

@@ -0,0 +1,191 @@
+import { randomBytes } from "node:crypto";
+import { hostname as osHostname } from "node:os";
+import { readdir as fsReaddir, readFile as fsReadFile } from "node:fs/promises";
+import { open as fsOpen, rename as fsRename, rm as fsRm, } from "node:fs/promises";
+import { join } from "node:path";
+import { logger } from "../logger.js";
+import { CONTEXT_BUILDER_LIFECYCLE_DIRECTORY, MAX_CONTEXT_BUILDER_LIFECYCLE_DURATION_MS, isContextBuilderOperationId, isLegalContextBuilderLifecycleTransition, isTerminalContextBuilderLifecycleStatus, parseContextBuilderLifecycleStateV1, resolveContextBuilderLifecycleLocation, } from "./lifecycle-contract.js";
+import { resolveContextBuilderRunsDir } from "./config.js";
+import { cleanupContextBuilderIncompleteRun, resolveContextBuilderRunPaths, } from "./storage.js";
+/**
+ * Terminalize standalone/refine journals frozen as pending/running whose
+ * same-host `.building.json` pid is dead. Foreign-host and missing/unparseable
+ * pid evidence is `unknown` and is never touched — same asymmetry as workflow
+ * `reconcileStaleRunDirectories`. Does not invent a dedicated worker lock;
+ * liveness is the building-json pid probe only.
+ *
+ * Writes `failed`/`terminal` + `internal_failure`. Never `cancelled`. Never
+ * rewrites curator/finalizer outcomes. Best-effort incomplete-artifact cleanup
+ * after the journal write. Idempotent. Log-and-continue on malformed rows.
+ */
+export async function reconcileStaleContextBuilderJournals(options = {}) {
+    const runsDir = await resolveContextBuilderRunsDir(options.runsDir);
+    const now = options.now ?? (() => new Date());
+    const hostname = options.hostname ?? osHostname();
+    const isAlive = options.isProcessAlive ?? isProcessAlive;
+    const journalDir = join(runsDir, CONTEXT_BUILDER_LIFECYCLE_DIRECTORY);
+    let entries = [];
+    try {
+        entries = await fsReaddir(journalDir);
+    }
+    catch {
+        return { scanned: 0, reconciled: 0, skipped: 0, failed: 0 };
+    }
+    let scanned = 0;
+    let reconciled = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (const name of entries) {
+        if (!isContextBuilderOperationId(name))
+            continue;
+        scanned += 1;
+        try {
+            const location = resolveContextBuilderLifecycleLocation(runsDir, name);
+            const raw = await fsReadFile(location.state_json, "utf8");
+            const previous = parseContextBuilderLifecycleStateV1(JSON.parse(raw));
+            if (isTerminalContextBuilderLifecycleStatus(previous.status)) {
+                skipped += 1;
+                continue;
+            }
+            const observation = await observeContextRunWorker({
+                runsDir,
+                state: previous,
+                hostname,
+                isProcessAlive: isAlive,
+            });
+            if (observation !== "dead") {
+                skipped += 1;
+                continue;
+            }
+            const next = buildReconciledFailureSnapshot(previous, now());
+            if (!isLegalContextBuilderLifecycleTransition(previous, next)) {
+                logger.warn({ contextRunId: name }, "stale context run reconcile produced an illegal transition");
+                failed += 1;
+                continue;
+            }
+            await writeAtomicLifecycleSnapshot(location.state_json, next);
+            reconciled += 1;
+            await cleanupReconciledArtifact(runsDir, previous).catch((error) => {
+                logger.warn({
+                    contextRunId: name,
+                    err: error instanceof Error ? error.message : String(error),
+                }, "stale context run artifact cleanup failed");
+            });
+        }
+        catch (error) {
+            failed += 1;
+            logger.warn({
+                contextRunId: name,
+                err: error instanceof Error ? error.message : String(error),
+            }, "stale context run reconcile skipped a malformed journal");
+        }
+    }
+    return { scanned, reconciled, skipped, failed };
+}
+export async function observeContextRunWorker(input) {
+    const artifactRunId = input.state.artifact_run_id;
+    if (artifactRunId == null)
+        return "unknown";
+    let buildingRaw;
+    try {
+        const paths = resolveContextBuilderRunPaths(input.runsDir, artifactRunId);
+        buildingRaw = await fsReadFile(paths.buildingJson, "utf8");
+    }
+    catch {
+        return "unknown";
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(buildingRaw);
+    }
+    catch {
+        return "unknown";
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return "unknown";
+    const building = parsed;
+    if (typeof building.hostname !== "string" || typeof building.pid !== "number") {
+        return "unknown";
+    }
+    if (!Number.isInteger(building.pid) || building.pid <= 0)
+        return "unknown";
+    if (building.hostname !== input.hostname)
+        return "unknown";
+    return input.isProcessAlive(building.pid) ? "live" : "dead";
+}
+function buildReconciledFailureSnapshot(previous, now) {
+    const completedAt = monotonicTimestamp(now.toISOString(), previous.updated_at);
+    return parseContextBuilderLifecycleStateV1({
+        ...previous,
+        status: "failed",
+        phase: "terminal",
+        updated_at: completedAt,
+        completed_at: completedAt,
+        duration_ms: boundedDuration(previous.created_at, completedAt),
+        reason_codes: [...new Set([...previous.reason_codes, "internal_failure"])],
+    });
+}
+async function cleanupReconciledArtifact(runsDir, state) {
+    const artifactRunId = state.artifact_run_id;
+    if (artifactRunId == null)
+        return;
+    const paths = resolveContextBuilderRunPaths(runsDir, artifactRunId);
+    let ownerNonce;
+    try {
+        const parsed = JSON.parse(await fsReadFile(paths.buildingJson, "utf8"));
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            typeof parsed.owner_nonce === "string") {
+            ownerNonce = parsed.owner_nonce;
+        }
+    }
+    catch {
+        return;
+    }
+    if (ownerNonce == null)
+        return;
+    await cleanupContextBuilderIncompleteRun(paths, ownerNonce);
+}
+async function writeAtomicLifecycleSnapshot(finalPath, snapshot) {
+    const tempPath = `${finalPath}.${randomBytes(8).toString("hex")}.tmp`;
+    let handle;
+    let renamed = false;
+    try {
+        handle = await fsOpen(tempPath, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify(snapshot)}\n`, { encoding: "utf8" });
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fsRename(tempPath, finalPath);
+        renamed = true;
+    }
+    finally {
+        if (handle !== undefined) {
+            await handle.close().catch(() => { });
+        }
+        if (!renamed) {
+            await fsRm(tempPath, { force: true }).catch(() => { });
+        }
+    }
+}
+function monotonicTimestamp(candidate, floor) {
+    return Date.parse(candidate) < Date.parse(floor) ? floor : candidate;
+}
+function boundedDuration(createdAt, completedAt) {
+    return Math.min(MAX_CONTEXT_BUILDER_LIFECYCLE_DURATION_MS, Math.max(0, Date.parse(completedAt) - Date.parse(createdAt)));
+}
+function isProcessAlive(pid) {
+    if (pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ESRCH");
+    }
+}
+//# sourceMappingURL=lifecycle-reconcile.js.map

package/dist/context-builder/lifecycle-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-reconcile.js","sourceRoot":"","sources":["../../src/context-builder/lifecycle-reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EACL,IAAI,IAAI,MAAM,EACd,MAAM,IAAI,QAAQ,EAClB,EAAE,IAAI,IAAI,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EACL,mCAAmC,EACnC,yCAAyC,EACzC,2BAA2B,EAC3B,wCAAwC,EACxC,uCAAuC,EACvC,mCAAmC,EACnC,sCAAsC,GAEvC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,kCAAkC,EAClC,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AAkBtB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oCAAoC,CACxD,UAAuD,EAAE;IAEzD,MAAM,OAAO,GAAG,MAAM,4BAA4B,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,UAAU,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,IAAI,cAAc,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,mCAAmC,CAAC,CAAC;IAEtE,IAAI,OAAO,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,SAAS,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAC9D,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,2BAA2B,CAAC,IAAI,CAAC;YAAE,SAAS;QACjD,OAAO,IAAI,CAAC,CAAC;QACb,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,sCAAsC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACvE,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAC1D,MAAM,QAAQ,GAAG,mCAAmC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACtE,IAAI,uCAAuC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7D,OAAO,IAAI,CAAC,CAAC;gBACb,SAAS;YACX,CAAC;YACD,MAAM,WAAW,GAAG,MAAM,uBAAuB,CAAC;gBAChD,OAAO;gBACP,KAAK,EAAE,QAAQ;gBACf,QAAQ;gBACR,cAAc,EAAE,OAAO;aACxB,CAAC,CAAC;YACH,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;gBAC3B,OAAO,IAAI,CAAC,CAAC;gBACb,SAAS;YACX,CAAC;YAED,MAAM,IAAI,GAAG,8BAA8B,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;YAC7D,IAAI,CAAC,wCAAwC,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC9D,MAAM,CAAC,IAAI,CACT,EAAE,YAAY,EAAE,IAAI,EAAE,EACtB,4DAA4D,CAC7D,CAAC;gBACF,MAAM,IAAI,CAAC,CAAC;gBACZ,SAAS;YACX,CAAC;YACD,MAAM,4BAA4B,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAC9D,UAAU,IAAI,CAAC,CAAC;YAEhB,MAAM,yBAAyB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC1E,MAAM,CAAC,IAAI,CACT;oBACE,YAAY,EAAE,IAAI;oBAClB,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC5D,EACD,2CAA2C,CAC5C,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,CAAC;YACZ,MAAM,CAAC,IAAI,CACT;gBACE,YAAY,EAAE,IAAI;gBAClB,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC5D,EACD,yDAAyD,CAC1D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,KAK7C;IACC,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC;IAClD,IAAI,aAAa,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IAE5C,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,6BAA6B,CAAC,KAAK,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAC1E,WAAW,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,QAAQ,GAAG,MAA+C,CAAC;IACjE,IAAI,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,QAAQ,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC9E,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,GAAG,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3E,IAAI,QAAQ,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC3D,OAAO,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAC9D,CAAC;AAED,SAAS,8BAA8B,CACrC,QAAwC,EACxC,GAAS;IAET,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC/E,OAAO,mCAAmC,CAAC;QACzC,GAAG,QAAQ;QACX,MAAM,EAAE,QAAQ;QAChB,KAAK,EAAE,UAAU;QACjB,UAAU,EAAE,WAAW;QACvB,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,eAAe,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;QAC9D,YAAY,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC,CAAC;KAC3E,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,yBAAyB,CACtC,OAAe,EACf,KAAqC;IAErC,MAAM,aAAa,GAAG,KAAK,CAAC,eAAe,CAAC;IAC5C,IAAI,aAAa,IAAI,IAAI;QAAE,OAAO;IAClC,MAAM,KAAK,GAAG,6BAA6B,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACpE,IAAI,UAA8B,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,MAAM,UAAU,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;QACjF,IACE,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,KAAK,QAAQ;YAC1B,OAAQ,MAAoC,CAAC,WAAW,KAAK,QAAQ,EACrE,CAAC;YACD,UAAU,GAAI,MAAkC,CAAC,WAAW,CAAC;QAC/D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,IAAI,UAAU,IAAI,IAAI;QAAE,OAAO;IAC/B,MAAM,kCAAkC,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AAC9D,CAAC;AAED,KAAK,UAAU,4BAA4B,CACzC,SAAiB,EACjB,QAAwC;IAExC,MAAM,QAAQ,GAAG,GAAG,SAAS,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;IACtE,IAAI,MAAsD,CAAC;IAC3D,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7C,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9E,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,GAAG,SAAS,CAAC;QACnB,MAAM,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACpC,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;YAAS,CAAC;QACT,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,SAAiB,EAAE,KAAa;IAC1D,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC;AAED,SAAS,eAAe,CAAC,SAAiB,EAAE,WAAmB;IAC7D,OAAO,IAAI,CAAC,GAAG,CACb,yCAAyC,EACzC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAC7D,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,CACN,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,MAAM,IAAI,KAAK;YACd,KAA4B,CAAC,IAAI,KAAK,OAAO,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/context-builder/lifecycle-recovery.d.ts

@@ -0,0 +1,2 @@
+import type { ContextBuilderReceipt } from "./receipt.js";
+export declare function appendLifecycleCompletionWarning(receipt: ContextBuilderReceipt, maxWarnings: number): ContextBuilderReceipt;

package/dist/context-builder/lifecycle-recovery.js

@@ -0,0 +1,14 @@
+export function appendLifecycleCompletionWarning(receipt, maxWarnings) {
+    const warning = {
+        code: "lifecycle_completion_unavailable",
+        message: "Context Run completion could not be persisted after two attempts.",
+    };
+    return {
+        ...receipt,
+        warnings: [
+            ...receipt.warnings.slice(0, Math.max(0, maxWarnings - 1)),
+            warning,
+        ],
+    };
+}
+//# sourceMappingURL=lifecycle-recovery.js.map

package/dist/context-builder/lifecycle-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-recovery.js","sourceRoot":"","sources":["../../src/context-builder/lifecycle-recovery.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gCAAgC,CAC9C,OAA8B,EAC9B,WAAmB;IAEnB,MAAM,OAAO,GAAG;QACd,IAAI,EAAE,kCAAkC;QACxC,OAAO,EAAE,mEAAmE;KAC7E,CAAC;IACF,OAAO;QACL,GAAG,OAAO;QACV,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC;YAC1D,OAAO;SACR;KACF,CAAC;AACJ,CAAC"}

package/dist/context-builder/path-signals.d.ts

@@ -0,0 +1,7 @@
+export declare function isTestPath(relativePath: string): boolean;
+export declare function isGenericConfigPath(relativePath: string): boolean;
+export declare function isExtensionSourcePath(relativePath: string): boolean;
+export declare function genericPathKind(relativePath: string): "source" | "test" | "config" | "other";
+export declare function normalizedPathStem(relativePath: string): string;
+export declare function directoryDistance(leftPath: string, rightPath: string): number;
+export declare function pathDirectorySegments(relativePath: string): string[];

package/dist/context-builder/path-signals.js

@@ -0,0 +1,70 @@
+// Single source of truth for generic root-relative path classification shared
+// by discovery (dependency adjacency) and selection (ranking priors). These
+// helpers previously had divergent copies in both modules; unify here so the
+// two can never silently re-diverge.
+export function isTestPath(relativePath) {
+    return (
+    // A `test/` or `tests/` path SEGMENT anywhere (leading or nested) — e.g.
+    // `tests/foo`, `pkg/test/bar`, `<anyrepo>/tests/baz`. Repo-agnostic: no
+    // hardcoded top-level prefixes tied to a particular project layout.
+    /(?:^|\/)tests?\//.test(relativePath) ||
+        // A `__tests__/` directory segment anywhere (leading or nested).
+        /(?:^|\/)__tests__\//.test(relativePath) ||
+        // `.test.`/`.spec.` JS/TS filename suffix.
+        /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(relativePath) ||
+        // Python `test_*.py` filename.
+        /(?:^|\/)test_[^/]+\.py$/.test(relativePath));
+}
+export function isGenericConfigPath(relativePath) {
+    const basename = pathBasename(relativePath).toLowerCase();
+    return (/\.(?:json|ya?ml|toml|ini|env)$/.test(basename) ||
+        /(?:^|[.-])config\.[cm]?[jt]s$/.test(basename) ||
+        /^\.[a-z0-9-]+rc(?:\.[cm]?[jt]s|\.json)?$/.test(basename));
+}
+// Extension-based "is this a source-code file" predicate. Used for dependency
+// adjacency, which cares about "is it code" rather than "is it under src/".
+export function isExtensionSourcePath(relativePath) {
+    if (isTestPath(relativePath) || isGenericConfigPath(relativePath)) {
+        return false;
+    }
+    return /\.(?:[cm]?[jt]sx?|py|rs)$/.test(relativePath);
+}
+// Adjacency-oriented classification. MUST behave identically in both modules;
+// source-ness is decided by the extension-based predicate.
+export function genericPathKind(relativePath) {
+    if (isTestPath(relativePath)) {
+        return "test";
+    }
+    if (isGenericConfigPath(relativePath)) {
+        return "config";
+    }
+    if (isExtensionSourcePath(relativePath)) {
+        return "source";
+    }
+    return "other";
+}
+export function normalizedPathStem(relativePath) {
+    return pathBasename(relativePath)
+        .replace(/\.(?:test|spec)\.[^.]+$/, "")
+        .replace(/\.[^.]+$/, "")
+        .replace(/^test_/, "")
+        .toLowerCase();
+}
+export function directoryDistance(leftPath, rightPath) {
+    const left = pathDirectorySegments(leftPath);
+    const right = pathDirectorySegments(rightPath);
+    let shared = 0;
+    while (left[shared] != null && left[shared] === right[shared]) {
+        shared++;
+    }
+    return left.length + right.length - 2 * shared;
+}
+export function pathDirectorySegments(relativePath) {
+    const parts = relativePath.split("/");
+    parts.pop();
+    return parts.filter((part) => part.length > 0);
+}
+function pathBasename(relativePath) {
+    return relativePath.split("/").pop() ?? relativePath;
+}
+//# sourceMappingURL=path-signals.js.map

package/dist/context-builder/path-signals.js.map

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

package/dist/context-builder/paths.d.ts

@@ -0,0 +1,30 @@
+import { stat as fsStat } from "node:fs/promises";
+import { type ContextBuilderOmission } from "./diagnostics.js";
+export type ContextBuilderResolvedRoot = {
+    root_index: number;
+    input_index: number;
+    input_path: string;
+    path: string;
+};
+export type ContextBuilderResolvedFocusPath = {
+    root_index: number;
+    input_index: number;
+    input_path: string;
+    root_relative_path: string;
+    absolute_path: string;
+    kind: "file" | "directory";
+};
+export type ContextBuilderRootResolutionResult = {
+    roots: ContextBuilderResolvedRoot[];
+    omissions: ContextBuilderOmission[];
+};
+export type ContextBuilderPathOps = {
+    realpath?: (input: string) => Promise<string>;
+    stat?: typeof fsStat;
+    cwd?: string;
+    allowedRoots?: string[];
+};
+export declare function resolveContextBuilderRoots(inputRoots: readonly string[], options?: ContextBuilderPathOps): Promise<ContextBuilderRootResolutionResult>;
+export declare function resolveContextBuilderFocusPaths(focusPaths: readonly string[], roots: readonly ContextBuilderResolvedRoot[], options?: Pick<ContextBuilderPathOps, "realpath" | "stat" | "cwd">): Promise<ContextBuilderResolvedFocusPath[]>;
+export declare function normalizeContextBuilderRootRelativePath(input: string): string;
+export declare function rootRelativePathForAbsolutePath(root: ContextBuilderResolvedRoot, absolutePath: string): string;

package/dist/context-builder/paths.js

@@ -0,0 +1,153 @@
+import { realpath as fsRealpath, stat as fsStat } from "node:fs/promises";
+import path from "node:path";
+import { isPathWithinAllowedRoots, isSamePathOrDescendant, } from "../allowed-roots.js";
+import { InvalidParamsError } from "../errors.js";
+import { getCurrentAllowedRoots } from "../paths.js";
+import { boundContextBuilderOmissions, } from "./diagnostics.js";
+export async function resolveContextBuilderRoots(inputRoots, options = {}) {
+    const realpath = options.realpath ?? fsRealpath;
+    const stat = options.stat ?? fsStat;
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const allowedRoots = options.allowedRoots ?? getCurrentAllowedRoots();
+    const roots = [];
+    const omissions = [];
+    const seen = new Map();
+    for (const [inputIndex, inputPath] of inputRoots.entries()) {
+        const lexicalPath = path.resolve(cwd, inputPath);
+        const resolvedPath = await realpath(lexicalPath).catch(() => {
+            throw new InvalidParamsError(`context_builder root does not exist or is not accessible: ${inputPath}`);
+        });
+        if (!isPathWithinAllowedRoots(resolvedPath, allowedRoots)) {
+            throw new InvalidParamsError(`context_builder root is outside allowed roots: ${inputPath}`);
+        }
+        const stats = await stat(resolvedPath).catch(() => {
+            throw new InvalidParamsError(`context_builder root does not exist or is not accessible: ${inputPath}`);
+        });
+        if (!stats.isDirectory()) {
+            throw new InvalidParamsError(`context_builder root is not a directory: ${inputPath}`);
+        }
+        const duplicateOf = seen.get(resolvedPath);
+        if (duplicateOf != null) {
+            omissions.push({
+                root_index: duplicateOf,
+                reason: "duplicate_root",
+                message: `Duplicate root omitted; same realpath as root_index ${duplicateOf}`,
+                paths: [inputPath],
+            });
+            continue;
+        }
+        const root_index = roots.length;
+        seen.set(resolvedPath, root_index);
+        roots.push({
+            root_index,
+            input_index: inputIndex,
+            input_path: inputPath,
+            path: resolvedPath,
+        });
+    }
+    return {
+        roots,
+        omissions: boundContextBuilderOmissions(omissions),
+    };
+}
+export async function resolveContextBuilderFocusPaths(focusPaths, roots, options = {}) {
+    const realpath = options.realpath ?? fsRealpath;
+    const stat = options.stat ?? fsStat;
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const resolved = [];
+    for (const [inputIndex, focusPath] of focusPaths.entries()) {
+        if (path.isAbsolute(focusPath)) {
+            const focus = await resolveOneFocusPath({
+                focusPath,
+                inputIndex,
+                lexicalPath: focusPath,
+                roots,
+                realpath,
+                stat,
+            });
+            resolved.push(focus);
+            continue;
+        }
+        const matches = [];
+        for (const root of roots) {
+            const lexicalPath = path.resolve(root.path, focusPath);
+            const resolvedFocus = await realpath(lexicalPath).catch(() => undefined);
+            if (resolvedFocus == null) {
+                continue;
+            }
+            if (!isSamePathOrDescendant(resolvedFocus, root.path)) {
+                continue;
+            }
+            matches.push(await buildResolvedFocusPath({
+                focusPath,
+                inputIndex,
+                root,
+                resolvedFocus,
+                stat,
+            }));
+        }
+        if (matches.length === 0) {
+            throw new InvalidParamsError(`context_builder relative focus path did not match any root: ${focusPath}`);
+        }
+        resolved.push(...matches);
+    }
+    return resolved.sort(compareFocusPaths);
+}
+export function normalizeContextBuilderRootRelativePath(input) {
+    const slashNormalized = input.replaceAll("\\", "/").replace(/\/+/g, "/");
+    const normalized = path.posix.normalize(slashNormalized).replace(/^\.\//, "");
+    if (normalized === ".." ||
+        normalized.split("/").includes("..") ||
+        path.posix.isAbsolute(normalized)) {
+        throw new InvalidParamsError(`context_builder root-relative path escapes root: ${input}`);
+    }
+    return normalized === "." ? "" : normalized;
+}
+export function rootRelativePathForAbsolutePath(root, absolutePath) {
+    if (!isSamePathOrDescendant(absolutePath, root.path)) {
+        throw new InvalidParamsError(`context_builder path escapes root_index ${root.root_index}`);
+    }
+    return normalizeContextBuilderRootRelativePath(path.relative(root.path, absolutePath));
+}
+async function resolveOneFocusPath(input) {
+    const resolvedFocus = await input.realpath(input.lexicalPath).catch(() => {
+        throw new InvalidParamsError(`context_builder focus path does not exist or is not accessible: ${input.focusPath}`);
+    });
+    const matchingRoots = input.roots.filter((root) => isSamePathOrDescendant(resolvedFocus, root.path));
+    if (matchingRoots.length !== 1) {
+        throw new InvalidParamsError(`context_builder absolute focus path must resolve inside exactly one root: ${input.focusPath}`);
+    }
+    const root = matchingRoots[0];
+    if (root == null) {
+        throw new InvalidParamsError(`context_builder absolute focus path is outside roots: ${input.focusPath}`);
+    }
+    return buildResolvedFocusPath({
+        focusPath: input.focusPath,
+        inputIndex: input.inputIndex,
+        root,
+        resolvedFocus,
+        stat: input.stat,
+    });
+}
+async function buildResolvedFocusPath(input) {
+    const stats = await input.stat(input.resolvedFocus).catch(() => {
+        throw new InvalidParamsError(`context_builder focus path does not exist or is not accessible: ${input.focusPath}`);
+    });
+    if (!stats.isFile() && !stats.isDirectory()) {
+        throw new InvalidParamsError(`context_builder focus path must be a file or directory: ${input.focusPath}`);
+    }
+    return {
+        root_index: input.root.root_index,
+        input_index: input.inputIndex,
+        input_path: input.focusPath,
+        root_relative_path: rootRelativePathForAbsolutePath(input.root, input.resolvedFocus),
+        absolute_path: input.resolvedFocus,
+        kind: stats.isDirectory() ? "directory" : "file",
+    };
+}
+function compareFocusPaths(left, right) {
+    return (left.input_index - right.input_index ||
+        left.root_index - right.root_index ||
+        left.root_relative_path.localeCompare(right.root_relative_path));
+}
+//# sourceMappingURL=paths.js.map

package/dist/context-builder/paths.js.map

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

package/dist/context-builder/progress.d.ts

@@ -0,0 +1,17 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ContextBuilderLifecycleObserver } from "./lifecycle-observer.js";
+export type ContextBuilderProgressStage = "validating" | "scanning" | "searching" | "selecting" | "curating" | "finalizing" | "writing" | "complete";
+export type ContextBuilderProgressTarget = {
+    server: Server;
+    token: string | number;
+};
+export declare class ContextBuilderProgressReporter {
+    private readonly target;
+    private highestEmitted;
+    private chain;
+    constructor(target: ContextBuilderProgressTarget);
+    observe: ContextBuilderLifecycleObserver;
+    private emit;
+    private emitNow;
+}
+export declare function createContextBuilderProgressReporter(target: ContextBuilderProgressTarget | undefined): ContextBuilderProgressReporter | undefined;

package/dist/context-builder/progress.js

@@ -0,0 +1,93 @@
+import { logger } from "../logger.js";
+import { sanitizeProgressMessage } from "./diagnostics.js";
+const STAGE_PROGRESS = Object.freeze({
+    validating: 5,
+    scanning: 20,
+    searching: 40,
+    selecting: 60,
+    curating: 72,
+    finalizing: 84,
+    writing: 94,
+    complete: 100,
+});
+const STAGE_ORDER = Object.freeze({
+    validating: 0,
+    scanning: 1,
+    searching: 2,
+    selecting: 3,
+    curating: 4,
+    finalizing: 5,
+    writing: 6,
+    complete: 7,
+});
+const STAGE_MESSAGES = Object.freeze({
+    validating: "context_builder validating",
+    scanning: "context_builder scanning",
+    searching: "context_builder searching",
+    selecting: "context_builder selecting",
+    curating: "context_builder curating",
+    finalizing: "context_builder finalizing",
+    writing: "context_builder writing",
+    complete: "context_builder complete",
+});
+export class ContextBuilderProgressReporter {
+    target;
+    highestEmitted = -1;
+    chain = Promise.resolve();
+    constructor(target) {
+        this.target = target;
+    }
+    observe = (transition) => {
+        const stage = progressStageForTransition(transition);
+        return stage == null ? Promise.resolve() : this.emit(stage);
+    };
+    emit(stage) {
+        const next = this.chain.then(() => this.emitNow(stage));
+        this.chain = next.catch(() => { });
+        return next;
+    }
+    async emitNow(stage) {
+        const order = STAGE_ORDER[stage];
+        if (order <= this.highestEmitted) {
+            return;
+        }
+        try {
+            await this.target.server.notification({
+                method: "notifications/progress",
+                params: {
+                    progressToken: this.target.token,
+                    progress: STAGE_PROGRESS[stage],
+                    total: 100,
+                    message: sanitizeProgressMessage(STAGE_MESSAGES[stage]),
+                },
+            });
+            this.highestEmitted = order;
+        }
+        catch (err) {
+            logger.warn({ err, stage }, "failed to send context_builder progress");
+        }
+    }
+}
+function progressStageForTransition(transition) {
+    switch (transition.snapshot.phase) {
+        case "validating":
+        case "scanning":
+        case "searching":
+        case "selecting":
+        case "curating":
+        case "finalizing":
+        case "writing":
+        case "complete":
+            return transition.snapshot.phase;
+        case "resolving":
+        case "cache_lookup":
+        case "materializing":
+        case "committing":
+        case "terminal":
+            return undefined;
+    }
+}
+export function createContextBuilderProgressReporter(target) {
+    return target == null ? undefined : new ContextBuilderProgressReporter(target);
+}
+//# sourceMappingURL=progress.js.map

package/dist/context-builder/progress.js.map

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