@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/src/engine/sdkruntime.js

@@ -0,0 +1,340 @@
+// sdkRuntime: the runtime port (port.ts) hosted in-process on the pi SDK, through
+// PiHost (pisdk.ts, the only module that builds an SDK session).
+//
+// One session is one live AgentSession. Turns run one at a time, in order: the
+// first is `prompt`, each later one a `followUp` that waits behind the turn in
+// flight, and a `steer` goes into the turn in flight through pi's own steering
+// queue (the one thing a process runtime cannot do).
+//
+// The main session is file-backed: with `sessionFile` in the spec the JSONL is
+// written at exactly that path (or under `sessionDir`, where pi names the file),
+// so a finished session opens in pi and resumes by id. Without either it is in
+// memory and `sessionFile` is null.
+//
+// `subscribe` and the events file carry the stream a `pi --mode json` child
+// prints, line for line: the session header first, then every session event as
+// JSON, with the `message_update` and `tool_execution_update` re-emissions left
+// out (they restate a whole transcript on each update). The spend and the dollar cap read the same events, so
+// bench/aacr.ts parses a file from either runtime unchanged. What pi itself
+// prints to stdout in that mode is only this stream; nothing else is faked.
+import { appendFileSync, closeSync, createWriteStream, existsSync, openSync, readFileSync, } from "node:fs";
+import { splitModelSpec } from "../reviewconfig.js";
+import { TurnBudget } from "./budget.js";
+import { trackSession } from "./livesessions.js";
+import { RuntimeUnsupportedError, } from "./port.js";
+/** Grace between a hit limit's abort and the dispose that follows it. */
+const GRACE_MS = { cap: 5_000, timeout: 15_000 };
+/** The lines `pi --mode json` writes that carry no information a reader wants and
+ * grow with the transcript. */
+function isUpdate(event) {
+    return event.type === "message_update" || event.type === "tool_execution_update";
+}
+const stripBom = (s) => (s.charCodeAt(0) === 0xfeff ? s.slice(1) : s);
+class SdkSession {
+    spec;
+    session;
+    resumed;
+    backstop;
+    listeners = new Set();
+    /** The listeners that also hear the update events. */
+    updateListeners = new Set();
+    events;
+    unsubscribe;
+    /** The turn in flight and everything queued behind it. */
+    tail = Promise.resolve();
+    pending = 0;
+    prompted = false;
+    disposed = false;
+    turns = 0;
+    spentUsd = 0;
+    last = null;
+    budget = null;
+    stopped = false;
+    streamError = null;
+    /** The error text of the turn's last assistant message when the provider
+     * ended it as an error (pi resolves the prompt for that, it does not throw). */
+    providerError = null;
+    headerWritten = false;
+    /** Forgets this session in the live registry (a signal handler stops what is there). */
+    untrack;
+    constructor(spec, session, 
+    /** A reopened session: its history is the first turn, so a message may
+     * follow it with no prompt. */
+    resumed = false, backstop = () => { }) {
+        this.spec = spec;
+        this.session = session;
+        this.resumed = resumed;
+        this.backstop = backstop;
+        this.events = createWriteStream(spec.eventsFile, { flags: "a" });
+        // A full disk must end THIS turn as a recorded failure, not throw out of the
+        // process: the same contract runPi has.
+        this.events.on("error", (e) => {
+            this.streamError = String(e);
+            void this.abort();
+        });
+        this.unsubscribe = session.subscribe((event) => this.onEvent(event));
+        this.untrack = trackSession(this);
+    }
+    get id() {
+        return this.session.sessionId;
+    }
+    get sessionFile() {
+        const file = this.session.sessionFile;
+        // pi writes the file from the first user message on.
+        return file !== undefined && existsSync(file) ? file : null;
+    }
+    async prompt(text, options) {
+        if (this.prompted)
+            throw new RuntimeUnsupportedError("a second prompt (a session continues by followUp)");
+        this.prompted = true;
+        // The process runtime hands the first message to pi on stdin, and pi trims
+        // piped stdin (main.js readPipedStdin): the provider sees the trimmed text.
+        // A follow-up rides `-p`, which pi does not trim, so only this one is.
+        return this.turn(text.trim(), options);
+    }
+    async followUp(text, options) {
+        if (!this.prompted && !this.resumed)
+            throw new Error("followUp before the first prompt");
+        this.prompted = true;
+        const run = this.turn(text, options);
+        if (this.pending > 1) {
+            // A turn is in flight: this one runs behind it. Its result lands in stats().
+            run.catch(() => { });
+            return { status: "queued" };
+        }
+        return { status: "handled", result: await run };
+    }
+    async steer(text, options) {
+        // Nothing running: there is no turn to steer, so the message starts one.
+        if (this.pending === 0 || this.disposed)
+            return this.followUp(text, options);
+        await this.session.steer(text);
+        return { status: "queued" };
+    }
+    async compact() {
+        if (this.disposed)
+            return { status: "failed", reason: "session disposed" };
+        // Behind the turn in flight and everything queued after it: pi refuses a
+        // prompt while it compacts, and a compaction under a running turn is not
+        // what a caller means.
+        await this.tail.catch(() => { });
+        if (this.disposed)
+            return { status: "failed", reason: "session disposed" };
+        try {
+            const result = await this.session.compact();
+            return { status: "compacted", tokensBefore: result.tokensBefore };
+        }
+        catch (e) {
+            return { status: "failed", reason: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    async abort() {
+        if (this.pending === 0)
+            return;
+        this.stopped = true;
+        await this.session.abort().catch(() => { });
+    }
+    subscribe(listener, options) {
+        this.listeners.add(listener);
+        if (options?.updates)
+            this.updateListeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+            this.updateListeners.delete(listener);
+        };
+    }
+    stats() {
+        return { turns: this.turns, busy: this.pending > 0, spentUsd: this.spentUsd, last: this.last };
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.untrack();
+        // Queued follow-ups fail fast (disposed); the running turn is aborted.
+        if (this.pending > 0) {
+            this.stopped = true;
+            await this.session.abort().catch(() => { });
+        }
+        await this.tail.catch(() => { });
+        this.unsubscribe();
+        try {
+            this.session.dispose();
+        }
+        catch {
+            // already disposed (the host's own sweep, a budget's dispose step)
+        }
+        await new Promise((resolve) => this.events.end(resolve));
+    }
+    /** Queue one turn behind whatever is in flight. */
+    turn(text, options) {
+        if (this.disposed)
+            return Promise.reject(new Error("session disposed"));
+        const spec = this.spec;
+        this.pending++;
+        const run = this.tail.then(async () => {
+            if (this.disposed)
+                return { code: null, timedOut: false, streamError: "disposed" };
+            const r = await this.runTurn(text, options?.timeoutMs ?? spec.limits.timeoutMs, options?.capUsd ?? spec.limits.capUsd);
+            this.turns++;
+            this.spentUsd += r.spentUsd ?? 0;
+            this.last = r;
+            return r;
+        });
+        const settled = () => {
+            this.pending--;
+        };
+        this.tail = run.then(settled, settled);
+        return run;
+    }
+    async runTurn(text, timeoutMs, capUsd) {
+        this.stopped = false;
+        this.providerError = null;
+        const budget = new TurnBudget({
+            abort: () => this.session.abort(),
+            dispose: async () => this.session.dispose(),
+        }, { timeoutMs, capUsd, graceMs: GRACE_MS, backstop: this.backstop });
+        this.budget = budget;
+        this.writeHeader();
+        let failure = null;
+        try {
+            await this.session.prompt(text);
+        }
+        catch (e) {
+            failure = e instanceof Error ? e.message : String(e);
+            appendFileSync(this.spec.stderrFile, `${failure}\n`);
+        }
+        finally {
+            budget.end();
+            this.budget = null;
+        }
+        // Callers read the events file the moment the turn resolves: every line
+        // written so far must be on disk by then.
+        await new Promise((resolve) => this.events.write("", () => resolve()));
+        const tripped = budget.tripped;
+        if (failure === null && this.providerError !== null) {
+            failure = this.providerError;
+            appendFileSync(this.spec.stderrFile, `${String(failure)}\n`);
+        }
+        return {
+            // No exit status in process: 0 when the turn ran to its end, null when it
+            // was stopped (by us, or a limit), 1 when pi refused or failed it.
+            code: tripped !== null || this.stopped ? null : failure !== null ? 1 : 0,
+            timedOut: tripped === "timeout",
+            streamError: this.streamError,
+            spentUsd: budget.spentUsd,
+            capped: tripped === "cap",
+        };
+    }
+    /** The session header leads the stream, as it leads `pi --mode json`'s stdout. */
+    writeHeader() {
+        if (this.headerWritten)
+            return;
+        this.headerWritten = true;
+        const header = this.session.sessionManager.getHeader();
+        if (header)
+            this.write(JSON.stringify(header));
+    }
+    onEvent(event) {
+        // The cap reads the lens children's spend off the updates, so it sees them;
+        // the file and the listeners do not.
+        this.budget?.observe(event);
+        if (event.type === "message_end") {
+            const m = event.message;
+            if (m.role === "assistant")
+                this.providerError =
+                    m.stopReason === "error"
+                        ? typeof m.errorMessage === "string" && m.errorMessage !== ""
+                            ? m.errorMessage
+                            : "the provider returned an error"
+                        : null;
+        }
+        if (isUpdate(event)) {
+            // Not written, and not parsed: an update listener reads the event itself.
+            for (const l of this.updateListeners) {
+                try {
+                    l(event);
+                }
+                catch {
+                    // a listener's failure is not the session's
+                }
+            }
+            return;
+        }
+        this.write(JSON.stringify(event));
+    }
+    write(line) {
+        this.events.write(line + "\n");
+        if (this.listeners.size === 0)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        for (const l of this.listeners) {
+            try {
+                l(parsed);
+            }
+            catch {
+                // a listener's failure is not the session's
+            }
+        }
+    }
+}
+/** The runtime that hosts a session in this process, on `host`'s pi SDK. */
+export function sdkRuntime(host, options = {}) {
+    /** One session from a spec, new or reopened. `persist` is the one place the
+     * two differ. */
+    async function open(spec, persist, resumed) {
+        if (!options.extras && spec.extensions && spec.extensions.length > 0)
+            // An SDK session loads extension factories, which a route hands it; a
+            // path would mean an unrelated loader. Refused, never dropped.
+            throw new RuntimeUnsupportedError("extension paths on an SDK session (pass factories)");
+        // The two files exist from the start, as they do for a spawned pi.
+        for (const f of [spec.eventsFile, spec.stderrFile])
+            closeSync(openSync(f, "a"));
+        // `provider/id:level` is pi's spelling of a model and its thinking level
+        // (--model takes it whole); the host takes them apart.
+        const { model, thinking } = splitModelSpec(spec.model);
+        const hostSpec = {
+            cwd: spec.cwd,
+            env: spec.env,
+            model,
+            ...(thinking ? { thinkingLevel: thinking } : {}),
+            ...(spec.systemPromptFile !== undefined
+                ? { systemPrompt: stripBom(readFileSync(spec.systemPromptFile, "utf8")) }
+                : {}),
+            ...(spec.agentsFiles ? { agentsFiles: spec.agentsFiles } : {}),
+            ...(spec.tools ? { tools: spec.tools } : {}),
+            ...(persist ? { persist } : {}),
+            onExtensionError: (e) => appendFileSync(spec.stderrFile, `Extension error (${e.extensionPath}): ${e.error}\n`),
+            ...options.extras?.(spec),
+        };
+        return new SdkSession(spec, await host.makeSession(hostSpec), resumed, options.backstop);
+    }
+    return {
+        create(spec) {
+            if (spec.sessionFile !== undefined && spec.sessionDir !== undefined)
+                return Promise.reject(new Error("a spec names a sessionFile or a sessionDir, not both"));
+            return open(spec, spec.sessionFile !== undefined
+                ? { sessionFile: spec.sessionFile }
+                : spec.sessionDir !== undefined
+                    ? { sessionDir: spec.sessionDir }
+                    : undefined, false);
+        },
+        resume(sessionFile, spec) {
+            // SessionManager.open on the existing JSONL: the same id (the provider's
+            // cache key), later turns appended to the same file. The file is named by
+            // the argument; a spec that names another one, or a directory, is a bug.
+            if (spec.sessionDir !== undefined)
+                return Promise.reject(new Error("a resume names its file, not a sessionDir"));
+            if (spec.sessionFile !== undefined && spec.sessionFile !== sessionFile)
+                return Promise.reject(new Error(`a resume of ${sessionFile} cannot name another sessionFile`));
+            return open(spec, { resumeFile: sessionFile }, true);
+        },
+    };
+}
+//# sourceMappingURL=sdkruntime.js.map

package/dist/src/engine/sdkruntime.js.map

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

package/dist/src/engine/select.d.ts

@@ -0,0 +1,16 @@
+import type { EngineRuntimeKind, LensRuntimeKind } from "../reviewconfig.js";
+import type { Runtime } from "./port.js";
+/** Read a runtime kind. Throws on anything but `sdk`. */
+export declare function parseRuntimeKind(v: string): EngineRuntimeKind;
+/** `[pi] lens_runtime = engine` (the only kind) needs the engine's lens tool and
+ * discovery wave, which a route passes in as `engine` once it has them; a route
+ * without them refuses the key, not ignores it. */
+export declare function checkLensRuntime(kind: LensRuntimeKind, route: string, engine?: boolean): void;
+/**
+ * The runtime to inject into a route.
+ *
+ * @param route  names the route in the refusal ("review", "bench", "scan")
+ * @param sdk    builds the route's SDK runtime; absent while the route has none
+ */
+export declare function selectRuntime(kind: EngineRuntimeKind, route: string, sdk?: () => Runtime): Runtime;
+//# sourceMappingURL=select.d.ts.map

package/dist/src/engine/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/engine/select.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAM7D;AAED;;mDAEmD;AACnD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,IAAI,CAG3F;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,OAAO,GAClB,OAAO,CAKT"}

package/dist/src/engine/select.js

@@ -0,0 +1,32 @@
+// Which runtime a route hosts its pi sessions on: `[engine] runtime` (or a
+// route's own override). `sdk` is the only kind: the process runtime is
+// retired. It needs a host the route builds itself (PiHost, auth, extension
+// factories), so a route passes `sdk` only once it has one; a route that does
+// not refuses the key rather than quietly running something else.
+import { ENGINE_RUNTIME_KINDS } from "../reviewconfig.js";
+/** Read a runtime kind. Throws on anything but `sdk`. */
+export function parseRuntimeKind(v) {
+    if (!ENGINE_RUNTIME_KINDS.includes(v))
+        throw new Error(`runtime must be ${ENGINE_RUNTIME_KINDS.join(" | ")} (got ${JSON.stringify(v)})`);
+    return v;
+}
+/** `[pi] lens_runtime = engine` (the only kind) needs the engine's lens tool and
+ * discovery wave, which a route passes in as `engine` once it has them; a route
+ * without them refuses the key, not ignores it. */
+export function checkLensRuntime(kind, route, engine = false) {
+    if (kind === "engine" && !engine)
+        throw new Error(`[pi] lens_runtime = engine is not available on the ${route} route yet`);
+}
+/**
+ * The runtime to inject into a route.
+ *
+ * @param route  names the route in the refusal ("review", "bench", "scan")
+ * @param sdk    builds the route's SDK runtime; absent while the route has none
+ */
+export function selectRuntime(kind, route, sdk) {
+    void kind;
+    if (sdk === undefined)
+        throw new Error(`[engine] runtime = sdk is not available on the ${route} route yet`);
+    return sdk();
+}
+//# sourceMappingURL=select.js.map

package/dist/src/engine/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/engine/select.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wEAAwE;AACxE,4EAA4E;AAC5E,8EAA8E;AAC9E,kEAAkE;AAGlE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1D,yDAAyD;AACzD,MAAM,UAAU,gBAAgB,CAAC,CAAS;IACxC,IAAI,CAAE,oBAA0C,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,mBAAmB,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CACjF,CAAC;IACJ,OAAO,CAAsB,CAAC;AAChC,CAAC;AAED;;mDAEmD;AACnD,MAAM,UAAU,gBAAgB,CAAC,IAAqB,EAAE,KAAa,EAAE,MAAM,GAAG,KAAK;IACnF,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM;QAC9B,MAAM,IAAI,KAAK,CAAC,sDAAsD,KAAK,YAAY,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAuB,EACvB,KAAa,EACb,GAAmB;IAEnB,KAAK,IAAI,CAAC;IACV,IAAI,GAAG,KAAK,SAAS;QACnB,MAAM,IAAI,KAAK,CAAC,kDAAkD,KAAK,YAAY,CAAC,CAAC;IACvF,OAAO,GAAG,EAAE,CAAC;AACf,CAAC"}

package/dist/src/engine/sessionwrap.d.ts

@@ -0,0 +1,4 @@
+import type { RuntimeSession } from "./port.js";
+/** A session that runs `after` once, when it is disposed. */
+export declare function releasing(session: RuntimeSession, after: () => void): RuntimeSession;
+//# sourceMappingURL=sessionwrap.d.ts.map

package/dist/src/engine/sessionwrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionwrap.d.ts","sourceRoot":"","sources":["../../../src/engine/sessionwrap.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,cAAc,CA2BpF"}

package/dist/src/engine/sessionwrap.js

@@ -0,0 +1,31 @@
+/** A session that runs `after` once, when it is disposed. */
+export function releasing(session, after) {
+    let released = false;
+    return {
+        get id() {
+            return session.id;
+        },
+        get sessionFile() {
+            return session.sessionFile;
+        },
+        prompt: (text, options) => session.prompt(text, options),
+        followUp: (text, options) => session.followUp(text, options),
+        steer: (text, options) => session.steer(text, options),
+        abort: () => session.abort(),
+        subscribe: (listener, options) => session.subscribe(listener, options),
+        ...(session.compact ? { compact: () => session.compact() } : {}),
+        stats: () => session.stats(),
+        dispose: async () => {
+            try {
+                await session.dispose();
+            }
+            finally {
+                if (!released) {
+                    released = true;
+                    after();
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=sessionwrap.js.map

package/dist/src/engine/sessionwrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionwrap.js","sourceRoot":"","sources":["../../../src/engine/sessionwrap.ts"],"names":[],"mappings":"AAKA,6DAA6D;AAC7D,MAAM,UAAU,SAAS,CAAC,OAAuB,EAAE,KAAiB;IAClE,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO;QACL,IAAI,EAAE;YACJ,OAAO,OAAO,CAAC,EAAE,CAAC;QACpB,CAAC;QACD,IAAI,WAAW;YACb,OAAO,OAAO,CAAC,WAAW,CAAC;QAC7B,CAAC;QACD,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC;QACxD,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAC5D,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC;QACtD,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;QAC5B,SAAS,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC;QACtE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YAC1B,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,QAAQ,GAAG,IAAI,CAAC;oBAChB,KAAK,EAAE,CAAC;gBACV,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/engine/toolfence.d.ts

@@ -0,0 +1,90 @@
+import type { EditOperations, GrepOperations, LsOperations, ReadOperations, ToolDefinition, WriteOperations } from "@earendil-works/pi-coding-agent";
+/** What no file tool may reach, besides the run's agent dirs. `/qcr-login` is
+ * where the wrapper and the Action mount the owner's login volume: its
+ * auth.json holds the long-lived refresh token and is group-readable by the
+ * run uid, whose group the in-process file tools (unlike the tool uid's bash)
+ * keep. */
+export declare const FENCED_PATHS: readonly string[];
+/** The directories `env` names as the login's source: the process's own pi
+ * agent dir (`PI_CODING_AGENT_DIR`, which a review copies into its private
+ * agent dir) and the scan's `QCR_SCAN_AUTH_SRC`. The round's copy is the
+ * host's agent dir, fenced separately. */
+export declare function loginSourceDirs(env: NodeJS.ProcessEnv): string[];
+/**
+ * The credentials an `env` points at, which no file tool may reach:
+ *
+ *   - every secrets dir this install could be using: the App's private key, the
+ *     webhook secret and the OpenViking keys live there. The list is the bash
+ *     guard's own (`defaultSecretPathContext`, which mirrors the install
+ *     locator: `$QCR_SECRETS_MOUNT`, the container mount, `$QC_SECRETS_DIR`,
+ *     `<config home>/secrets`, a `[github] secrets_dir` read from
+ *     `$QCR_CONFIG`, and the legacy dir), so the shell belt and this fence
+ *     name the same places;
+ *   - the daemon's IPC run dirs (the socket and the capability launch files);
+ *   - the memory CLI config the env names (`OPENVIKING_CLI_CONFIG_FILE`, the
+ *     sessions' ovcli.conf): it holds the reviewer key, which the in-process
+ *     memory extension reads itself and the model has no use for.
+ *
+ * Our own code reads these with plain fs calls, never through the tools, so
+ * fencing them takes nothing away from it. Every absolute path, deduplicated;
+ * a path that does not exist is fenced lexically and by its resolved prefix.
+ */
+export declare function credentialPaths(...envs: NodeJS.ProcessEnv[]): string[];
+/** The names of the file tools behind the fence. */
+export declare const FENCED_TOOLS: readonly ["read", "grep", "find", "ls", "edit", "write"];
+export type FencedTool = (typeof FENCED_TOOLS)[number];
+/** A path the fence refuses; `message` is what the model reads. */
+export declare class ToolFenceError extends Error {
+    constructor(path: string);
+}
+export interface ToolFence {
+    /** Throws a ToolFenceError for a path that is, or leads to, a fenced one. */
+    check(path: string): void;
+    /** `check`, and for a search root that ripgrep or fd walk: also refuses a
+     * root with a fenced path below it, which the walk would reach. */
+    checkTree(path: string): void;
+    /** For a file already opened: refuses when the descriptor is a fenced file,
+     * whatever path it was opened by. A no-op where /proc/self/fd does not exist. */
+    checkOpened(fd: number, path: string): void;
+    /** `check`, and for a write: refuses a path that LEADS, through a symlink,
+     * onto a protected write target (`protectedWrite`). A path that is itself the
+     * target is the write veto's to judge as spelled (bash-guard), so only a real
+     * path that differs from the one given is held to the predicate here. */
+    checkWrite(path: string): void;
+    /** `checkOpened`, and the same symlink rule for the descriptor a write opened. */
+    checkWriteOpened(fd: number, path: string): void;
+}
+/** A fence over the fixed paths and the given directories. */
+export declare function createToolFence(o?: {
+    dirs?: readonly string[];
+    /** The write veto's predicate (bash-guard `isProtectedWriteTarget`): git's
+     * config and hook surface, the policy surface, the memory scope, the wake
+     * delivery files. Applied to where a write really lands when a symlink
+     * moved it: the in-process write tools run in the uid that runs the
+     * daemon's git and reads its policy, so a link committed in a PR, or one
+     * the tool uid planted in a directory it shares, must not carry a write
+     * there. */
+    protectedWrite?: (realPath: string) => boolean;
+}): ToolFence;
+/** A tool's `path` argument as pi resolves it (utils/paths.js resolvePath with
+ * unicode spaces and the `@` prefix normalised, `~` and file: URLs expanded).
+ * `home` is the home pi expands `~` against, as the host resolved it; without
+ * one a `~` path cannot be shown clear of the fence and is refused. */
+export declare function toolPath(input: string, cwd: string, home?: string): string;
+/** Tells an image from its first bytes: its mime type, or null. */
+export type ImageSniffer = (head: Buffer) => string | null | undefined;
+/** The `operations` of each file tool that takes them, every file opened through
+ * the fence. `sniff` tells images from their first bytes; without it a file is
+ * always read as text. find has none: it starts fd on its search root. */
+export declare function fencedOperations(fence: ToolFence, sniff: ImageSniffer | null): {
+    read: ReadOperations;
+    grep: GrepOperations;
+    ls: LsOperations;
+    edit: EditOperations;
+    write: WriteOperations;
+};
+/** `def` with a check of its `path` argument ahead of its execution: the
+ * refusal says what it is, and the tools that start ripgrep and fd (which
+ * `operations` does not reach) are covered. */
+export declare function guardedTool(def: ToolDefinition, fence: ToolFence, cwd: string, home?: string): ToolDefinition;
+//# sourceMappingURL=toolfence.d.ts.map

package/dist/src/engine/toolfence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolfence.d.ts","sourceRoot":"","sources":["../../../src/engine/toolfence.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,iCAAiC,CAAC;AAGzC;;;;WAIW;AACX,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAsD,CAAC;AAEjG;;;0CAG0C;AAC1C,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,EAAE,CAIhE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,MAAM,EAAE,CAStE;AAED,oDAAoD;AACpD,eAAO,MAAM,YAAY,0DAA2D,CAAC;AACrF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,mEAAmE;AACnE,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,IAAI,EAAE,MAAM;CAIzB;AA8BD,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;uEACmE;IACnE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;qFACiF;IACjF,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;6EAGyE;IACzE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAClD;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,CAAC,GAAE;IACD,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB;;;;;;gBAMY;IACZ,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C,GACL,SAAS,CAoEX;AAiBD;;;uEAGuE;AACvE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1E;AAMD,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAsHvE;;0EAE0E;AAC1E,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,YAAY,GAAG,IAAI,GACzB;IACD,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,YAAY,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;CACxB,CAQA;AAED;;+CAE+C;AAC/C,wBAAgB,WAAW,CACzB,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CAiBhB"}