@nathapp/nax-agent 0.1.0

package/dist/native/session-adapter.js

@@ -0,0 +1,369 @@
+/**
+ * The native session adapter: openSession / sendTurn / closeSession over
+ * nax-ai, no subprocess. openSession/closeSession are transcript-file
+ * bookkeeping, and sendTurn maps the native turn loop (session/turn-loop.ts)
+ * over complete() — nax owns the conversation because nax-ai's client is
+ * stateless (ADR-027 section 10, ADR-028).
+ */
+import { randomUUID } from "node:crypto";
+import { priceCall } from "#src/cost/core/index";
+import { getSafeLogger } from "#src/infra/index";
+import { SessionTurnError, } from "#src/session/session-types";
+import { createTurnDeadline } from "#src/session/turn-deadline";
+import { _adapterDeps, authFields, isProtocolStreamError } from "./adapter-deps.js";
+import { getNativeClient } from "./client.js";
+import { toAdapterFailure } from "./errors.js";
+import { buildRateCard, NATIVE_AGENT, parseNativeModel, resolveContextWindow, toThinkingLevel } from "./models.js";
+import { closeNativeSession, markNativeTurnOutcome, nativeSessionCompaction, nativeSessionSpinBreaker, nativeSessionStreamHooks, nativeSessionTimeouts, nativeSessionTranscriptOwners, nativeSessionTransportRetry, openNativeSession, } from "./session/session.js";
+import { buildNativeStreamEvent } from "./session/turn-events.js";
+import { runNativeTurn } from "./session/turn-loop.js";
+import { readNativeTurnFailureUsage } from "./session/turn-types.js";
+import { nativeSessionId } from "./session-affinity.js";
+/**
+ * Fallback whole-turn budget when a session's timeout entry is missing.
+ *
+ * Matches `execution.sessionTimeoutSeconds`' own default. The turn MUST stay
+ * bounded: an absent entry previously degraded to an unbounded deadline with
+ * no per-call timer either, silently removing the guard this module exists to
+ * apply. Bounded-and-logged beats unbounded-and-quiet.
+ */
+const FALLBACK_TURN_TIMEOUT_SECONDS = 3600;
+function summaryPrompt(previousSummary) {
+    const base = "Summarize the conversation above so it can be dropped from context. " +
+        "Record what was attempted, what was rejected and why, any decisions that still bind, " +
+        "and list the files read and the files modified. Be specific: this summary is the only " +
+        "memory of this work that survives.";
+    if (previousSummary === undefined)
+        return base;
+    return (`${base}\n\nAn earlier summary of still-older history follows. Merge it into your summary ` +
+        `rather than repeating or discarding it:\n\n${previousSummary}`);
+}
+/**
+ * US-003: the plugin-contributed loop handlers a turn carries, in the shape
+ * `runNativeTurn` takes them in. Built here rather than inline in `sendTurn`
+ * because those two conditional spreads are what pushed that method past its
+ * recorded cognitive complexity; each field is omitted entirely when the
+ * caller supplied none, so a session that loaded no `loop-handlers` plugin
+ * carries neither key.
+ */
+function loopHandlerDeps(opts) {
+    return {
+        ...(opts.loopHandlers !== undefined ? { loopHandlers: opts.loopHandlers } : {}),
+        ...(opts.loopHandlerContext !== undefined ? { loopHandlerContext: opts.loopHandlerContext } : {}),
+    };
+}
+export class NativeSessionAdapter {
+    catalogOverrides;
+    constructor(catalogOverrides = []) {
+        this.catalogOverrides = catalogOverrides;
+    }
+    /**
+     * Can this agent authenticate to at least one provider?
+     *
+     * Deliberately not "is the provider this run needs satisfied": this method
+     * takes no provider, and it cannot get one. The registry receives the
+     * manager's config slice, and agentManagerConfigSelector excludes
+     * config.models by design (ADR-019). Probing every provider for a specific
+     * answer is not an alternative either — pi's resolve() may execute commands.
+     *
+     * So this prunes exactly one case: nothing stored anywhere and nothing
+     * ambient. That is the real failure — a user who has never run
+     * `nax auth login` and has no provider environment variables — and every
+     * native call is going to fail anyway. A wrong-provider credential still
+     * surfaces per request, through the typed mapping from ProtocolError.kind
+     * "auth" to availability / fail-auth.
+     *
+     * US-004: with `auth.source: "exec"` it answers true without asking anything.
+     * A helper's providers cannot be listed, so an empty credential file says
+     * nothing about whether this run can authenticate — and spawning the helper
+     * here would put a credential read before the run has any reason for one.
+     *
+     * Errors resolve to true. Pruning an agent that would have worked kills a
+     * run; the opposite costs one request-time error that is already handled.
+     */
+    async hasCredentials() {
+        try {
+            if (await _adapterDeps.authSourceIsExec())
+                return true;
+            if ((await _adapterDeps.listStoredProviders()).length > 0)
+                return true;
+            return await _adapterDeps.anyAmbientCredential();
+        }
+        catch {
+            return true;
+        }
+    }
+    openSession(name, opts) {
+        return openNativeSession(name, opts);
+    }
+    async sendTurn(handle, prompt, opts) {
+        const { provider, model, effort } = parseNativeModel(handle.modelDef?.model ?? "");
+        const thinking = toThinkingLevel(effort);
+        const client = await getNativeClient(this.catalogOverrides);
+        const resolved = await client.model(provider, model);
+        const catalog = client.pricing(resolved);
+        const { rates, source: pricingSource } = buildRateCard(catalog, handle.modelDef?.pricing);
+        const storedTimeoutSeconds = nativeSessionTimeouts.get(handle.id);
+        if (storedTimeoutSeconds === undefined) {
+            getSafeLogger()?.warn("native-adapter", "session has no recorded timeout; falling back to the default budget", {
+                sessionName: handle.id,
+                fallbackTimeoutSeconds: FALLBACK_TURN_TIMEOUT_SECONDS,
+            });
+        }
+        const timeoutSeconds = storedTimeoutSeconds ?? FALLBACK_TURN_TIMEOUT_SECONDS;
+        // Keyed on the session, so every turn of one conversation carries the same
+        // id and the provider can keep its cache warm across them.
+        const sessionId = nativeSessionId(handle.id);
+        // One budget for the whole turn, not one per round-trip. Created here
+        // because this is where `timeoutSeconds` is known; consulted by the loop.
+        const deadline = createTurnDeadline(timeoutSeconds);
+        const hooks = nativeSessionStreamHooks.get(handle.id);
+        // One callId per turn, mirroring SpawnAcpSession.prompt(). `runId` is
+        // backfilled by the runtime's forwarding closure, which is the only place
+        // that knows it — see runtime/index.ts.
+        const callId = randomUUID();
+        // The transcript/ledger join key, not a stream id. `nativeSessionTranscriptOwners`
+        // is keyed on this same `handle.id` and already holds the session's
+        // `transcriptOwner` (`scopeId ?? callId` from session-run-hop.ts). Omitted
+        // entirely when the session declared no owner, so an absent key reads as
+        // "unknown" rather than as a wrong one.
+        const owner = nativeSessionTranscriptOwners.get(handle.id);
+        const eventBase = {
+            callId,
+            runId: "",
+            agentName: handle.agentName,
+            sessionName: handle.id,
+            ...(owner !== undefined ? { scopeId: owner } : {}),
+        };
+        const turnController = new AbortController();
+        // The watchdog's cancel handle IS the turn controller, so an idle cancel
+        // and the whole-turn deadline end the same in-flight call. Registering
+        // through the hook (rather than a private registry) is what lets
+        // sendPrompt tell a watchdog cancel from an unrelated process kill.
+        hooks?.onActiveCall?.(callId, async () => turnController.abort());
+        hooks?.onStreamActivity?.({
+            ...eventBase,
+            kind: "agent.call_started",
+            model: handle.modelDef?.model ?? "",
+            timeoutSeconds,
+            timestamp: Date.now(),
+        });
+        // US-002: one per-turn signal, fanned in from the caller's
+        // `opts.signal`, the watchdog's `turnController.signal`, and a
+        // whole-turn deadline timer armed with `deadline.remainingMs()`. The
+        // timer is cleared at turn settlement (finally, below) so the AbortSignal
+        // any(...) does not keep a timer alive past the turn's end. Complete and
+        // summarize retain their per-call timers but combine them with this same
+        // turnSignal so a turn-cancel reaches an in-flight call mid-roundtrip.
+        const deadlineController = new AbortController();
+        const deadlineMs = deadline.remainingMs();
+        const deadlineTimer = deadlineMs !== undefined ? _adapterDeps.setTimeout(() => deadlineController.abort(), deadlineMs) : undefined;
+        const turnSignals = [turnController.signal, deadlineController.signal];
+        if (opts.signal !== undefined)
+            turnSignals.unshift(opts.signal);
+        const turnSignal = AbortSignal.any(turnSignals);
+        let result;
+        try {
+            // US-002: clear the deadline timer at turn settlement, no matter how
+            // the turn ends (clean exit, throw, or any other path). The
+            // `AbortSignal.any` above holds a reference to `deadlineController.signal`,
+            // so a settled turn must drop its timer to avoid keeping it armed past
+            // the turn boundary.
+            result = await runNativeTurn(handle, prompt, opts, {
+                deadline,
+                contextWindow: resolveContextWindow(handle.modelDef?.contextWindow, resolved.contextWindow),
+                ...(nativeSessionCompaction.get(handle.id) !== undefined
+                    ? { compaction: nativeSessionCompaction.get(handle.id) }
+                    : {}),
+                ...(nativeSessionTransportRetry.get(handle.id) !== undefined
+                    ? { transportRetry: nativeSessionTransportRetry.get(handle.id) }
+                    : {}),
+                ...(nativeSessionSpinBreaker.get(handle.id) !== undefined
+                    ? { spinBreaker: nativeSessionSpinBreaker.get(handle.id) }
+                    : {}),
+                ...(opts.loopEvents !== undefined ? { loopEvents: opts.loopEvents } : {}),
+                // US-003: the run's plugin-contributed loop handlers and the facts
+                // their handlers read travel the same way as `loopEvents` — both are
+                // per-turn inputs the loop installs onto its registry rather than
+                // state the adapter owns.
+                ...loopHandlerDeps(opts),
+                // US-002: the one per-turn signal threaded into the batch and the
+                // in-flight coding-tool runtime. When `opts.signal` and the watchdog
+                // and the deadline are all absent, `turnSignal` is a non-aborted
+                // composite that behaves as the no-signal regression guard requires.
+                signal: turnSignal,
+                // US-002 AC14: forward an onWaiting callback the batch can hand to
+                // every coding-tool request. Wired in US-004 to emit the keepalive
+                // activity; today it is a no-op so the field plumbing is real in the
+                // production native path even though the keepalive is not yet
+                // active. The handler copies it onto the tool's `ToolCallContext`
+                // and a tool that blocks on a human approval calls it before the wait.
+                onWaiting: () => { },
+                pricingSource,
+                onActivity: (activity) => {
+                    hooks?.onStreamActivity?.(buildNativeStreamEvent(eventBase, activity, Date.now()));
+                },
+                summarize: async (span, previousSummary) => {
+                    // Same model, same clock, no tools. The prompt asks for what a coding
+                    // agent needs back: what was tried, what was rejected and why, and the
+                    // files touched -- without them the agent re-reads what it already read.
+                    const remainingMs = deadline.remainingMs();
+                    const controller = new AbortController();
+                    const timer = remainingMs !== undefined ? _adapterDeps.setTimeout(() => controller.abort(), remainingMs) : undefined;
+                    // US-002: the per-call signal still combines with the per-turn signal
+                    // (watchdog + deadline + caller), so a turn cancel ends the summary
+                    // even mid-call. The per-call timer is the additional budget on top.
+                    const signal = AbortSignal.any(opts.signal !== undefined
+                        ? [opts.signal, controller.signal, turnController.signal, deadlineController.signal]
+                        : [controller.signal, turnController.signal, deadlineController.signal]);
+                    try {
+                        const res = await client.complete(resolved, {
+                            messages: [...span, { role: "user", content: summaryPrompt(previousSummary) }],
+                            sessionId,
+                            signal,
+                        });
+                        const summaryUsage = res.usage;
+                        const { costUsd, resolvedRates } = priceCall(summaryUsage, rates);
+                        return { text: res.text, usage: summaryUsage, costUsd, rates: resolvedRates };
+                    }
+                    finally {
+                        if (timer !== undefined)
+                            _adapterDeps.clearTimeout(timer);
+                    }
+                },
+                complete: async (messages, tools, requestOptions) => {
+                    // The controller is armed with what is LEFT of the turn, so N
+                    // round-trips can no longer add up to N x timeoutSeconds. Still
+                    // combined with any caller-supplied opts.signal via AbortSignal.any so
+                    // either can end the call. US-002: also combined with the per-turn
+                    // turnController + deadlineController signals so an in-flight call
+                    // observes the same cancellation the batch sees between calls.
+                    const remainingMs = deadline.remainingMs();
+                    const controller = new AbortController();
+                    const timer = remainingMs !== undefined ? _adapterDeps.setTimeout(() => controller.abort(), remainingMs) : undefined;
+                    const signal = AbortSignal.any(opts.signal !== undefined
+                        ? [opts.signal, controller.signal, turnController.signal, deadlineController.signal]
+                        : [controller.signal, turnController.signal, deadlineController.signal]);
+                    // The loop-event bag speaks in booleans: `false` explicitly drops
+                    // the session's inherited thinking level for this request, while
+                    // `true` leaves that resolved level in place. nax-ai accepts a
+                    // thinking LEVEL rather than a boolean, so normalize at this boundary.
+                    const requestThinking = requestOptions?.thinking === false ? undefined : thinking;
+                    try {
+                        const res = await client.complete(resolved, {
+                            messages,
+                            ...(tools.length > 0 ? { tools } : {}),
+                            sessionId,
+                            signal,
+                            ...(requestThinking !== undefined ? { thinking: requestThinking } : {}),
+                            ...(requestOptions?.temperature !== undefined ? { temperature: requestOptions.temperature } : {}),
+                            // nax#1835: "short" is fixed, not config-driven (this repo's
+                            // precedent -- the compaction design -- rejects knobs added
+                            // before evidence). The turn loop's round trips are seconds
+                            // apart, so "short" already hits; "long" would only pay off for
+                            // a later turn and bills more at write time for a window this
+                            // turn does not need. Only this round-trip closure sets it: the
+                            // one-shot complete() and the summarize closure below have no
+                            // successor turn (or, for summarize, a shape unlikely to repeat)
+                            // to reuse the entry, so a cache write there costs more than it
+                            // saves.
+                            cacheRetention: "short",
+                        });
+                        const usage = res.usage;
+                        // Single `priceCall` invocation: `costUsd` and `resolvedRates`
+                        // come from the same call so they cannot diverge — the
+                        // verifiability property the story names ("recorded rates
+                        // reproduce recorded cost") would silently break if tier
+                        // selection ever grew a side channel.
+                        const { costUsd, resolvedRates } = priceCall(usage, rates);
+                        return {
+                            text: res.text,
+                            ...(res.toolCalls !== undefined ? { toolCalls: res.toolCalls } : {}),
+                            ...(res.thinking !== undefined ? { thinking: res.thinking } : {}),
+                            usage,
+                            costUsd,
+                            // US-002: thread the per-call resolved rates back to
+                            // `runNativeTurn` so it can stamp them on the `TurnResult`.
+                            // The last round-trip's rates win — each round-trip re-prices
+                            // on its own usage, and the most recent decision is what
+                            // affected the user's last-mile spend.
+                            rates: resolvedRates,
+                        };
+                    }
+                    finally {
+                        if (timer !== undefined)
+                            _adapterDeps.clearTimeout(timer);
+                    }
+                },
+            });
+        }
+        catch (err) {
+            hooks?.onStreamActivity?.({
+                ...eventBase,
+                kind: "agent.call_ended",
+                status: turnController.signal.aborted ? "cancelled" : "error",
+                timestamp: Date.now(),
+            });
+            markNativeTurnOutcome(handle.id, true);
+            // The same treatment complete() gives a protocol fault, on the path that
+            // was missing it (nax#1838). Rethrowing untouched left build-hop-callback
+            // to synthesise a generic fail-adapter-error, which cost a rate limit its
+            // backoff and an auth failure its unavailable mark.
+            //
+            // nax#1840: classification and cost are read off two different error
+            // classes, and a throw can only be one. SessionTurnError is the carrier
+            // both hop callbacks already read cost off, so it now also carries the
+            // classification (its optional adapterFailure field) — one throw, both
+            // facts. runNativeTurn attaches whatever was already spent on earlier
+            // round trips to this same err before it reaches here; read it back
+            // rather than dropping it as the pre-#1840 SessionFailureError did.
+            //
+            // Only a protocol fault is wrapped. A TypeError from our own code is not a
+            // vendor failure, and dressing it as one would hide the bug.
+            if (isProtocolStreamError(err)) {
+                const adapterFailure = toAdapterFailure(err.protocolError);
+                const usage = readNativeTurnFailureUsage(err);
+                throw new SessionTurnError(err.protocolError.message, false, adapterFailure.retriable, usage?.tokenUsage, usage?.costUsd, undefined, 
+                // pricingSource — the native protocol-fault path has no rate card
+                // to name here; left undefined (SessionTurnError.pricingSource).
+                undefined, adapterFailure);
+            }
+            throw err;
+        }
+        finally {
+            if (deadlineTimer !== undefined)
+                _adapterDeps.clearTimeout(deadlineTimer);
+        }
+        hooks?.onStreamActivity?.({
+            ...eventBase,
+            kind: "agent.call_ended",
+            status: result.timedOut === true ? "timeout" : turnController.signal.aborted ? "cancelled" : "success",
+            timestamp: Date.now(),
+        });
+        markNativeTurnOutcome(handle.id, false);
+        // US-006: the store only observes `provider` while a request is in flight,
+        // so the stamp is read here, after the loop.
+        return { ...result, ...authFields(provider) };
+    }
+    closeSession(handle) {
+        // The adapter interface has no failure signal, so the verdict comes from the
+        // session's last turn (markNativeTurnOutcome) rather than from this call.
+        // Passing a literal false here is what deleted the transcript of a failed
+        // session -- the one the retry reloads and a human reads (nax#1838).
+        return closeNativeSession(handle);
+    }
+    /**
+     * Run teardown addresses a session the process no longer has a handle for,
+     * by id string (execution/session-manager-runtime.ts). Without this the
+     * native maps were unreachable at teardown: every `keepOpen` session was
+     * removed from SessionManager._sessions by closeStory while its nine entries
+     * stayed behind for the process lifetime.
+     *
+     * The ACP contract takes a handle string and closeNativeSession takes a
+     * SessionHandle, but the maps are keyed by the session-name string both
+     * carry, so clear by name rather than synthesising a handle.
+     */
+    async closePhysicalSession(handle, _workdir, _options) {
+        return closeNativeSession({ id: handle, agentName: NATIVE_AGENT });
+    }
+}

package/dist/native/session-affinity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Session identity for native requests.
+ *
+ * nax owns what a session *is*; nax-ai owns how one reaches a provider. So this
+ * file derives an id and stops there — which header carries it, and for which
+ * vendor, is nax-ai's business (`vendorSessionHeaders`, plus everything pi-ai
+ * already derives from a per-model affinity format and the prompt-cache key).
+ * An earlier revision kept that mapping here, which meant nax had learned a
+ * vendor vocabulary it has no reason to know.
+ *
+ * The id is a hash, never the session name. nax builds session ids from role,
+ * story and feature ("implementer-US-001-auth-system"), so sending one raw
+ * would hand a third party the shape of a private repository's work for no
+ * gain — a provider needs an opaque token it can match, and nothing else.
+ * Hashing also makes the value safe to put on the wire by construction,
+ * whatever the id happened to contain.
+ */
+/**
+ * The session id, independent of who will serve the request.
+ *
+ * Deliberately not memoised: it is a hash of its input, so it is already stable
+ * for a given session, and a cache keyed on session ids would outlive the runs
+ * that created them.
+ */
+export declare function nativeSessionId(sessionKey: string): string;
+/**
+ * A fresh key for a caller that has no session id of its own.
+ *
+ * `complete()` is one call with no successor, so there is nothing to name. A
+ * fresh key per *call* would satisfy the letter of it and defeat the purpose,
+ * since affinity only pays when two requests share an id. The adapter holds one
+ * of these for its own lifetime, which the agent registry's adapter cache
+ * scopes to a run, so the one-shots of a run share a backend while unrelated
+ * runs do not.
+ */
+export declare function newSessionKey(): string;

package/dist/native/session-affinity.js

@@ -0,0 +1,43 @@
+/**
+ * Session identity for native requests.
+ *
+ * nax owns what a session *is*; nax-ai owns how one reaches a provider. So this
+ * file derives an id and stops there — which header carries it, and for which
+ * vendor, is nax-ai's business (`vendorSessionHeaders`, plus everything pi-ai
+ * already derives from a per-model affinity format and the prompt-cache key).
+ * An earlier revision kept that mapping here, which meant nax had learned a
+ * vendor vocabulary it has no reason to know.
+ *
+ * The id is a hash, never the session name. nax builds session ids from role,
+ * story and feature ("implementer-US-001-auth-system"), so sending one raw
+ * would hand a third party the shape of a private repository's work for no
+ * gain — a provider needs an opaque token it can match, and nothing else.
+ * Hashing also makes the value safe to put on the wire by construction,
+ * whatever the id happened to contain.
+ */
+import { createHash, randomUUID } from "node:crypto";
+/** 128 bits of a SHA-256, far past collision concerns for routing. */
+const ID_LENGTH = 32;
+/**
+ * The session id, independent of who will serve the request.
+ *
+ * Deliberately not memoised: it is a hash of its input, so it is already stable
+ * for a given session, and a cache keyed on session ids would outlive the runs
+ * that created them.
+ */
+export function nativeSessionId(sessionKey) {
+    return createHash("sha256").update(sessionKey).digest("hex").slice(0, ID_LENGTH);
+}
+/**
+ * A fresh key for a caller that has no session id of its own.
+ *
+ * `complete()` is one call with no successor, so there is nothing to name. A
+ * fresh key per *call* would satisfy the letter of it and defeat the purpose,
+ * since affinity only pays when two requests share an id. The adapter holds one
+ * of these for its own lifetime, which the agent registry's adapter cache
+ * scopes to a run, so the one-shots of a run share a backend while unrelated
+ * runs do not.
+ */
+export function newSessionKey() {
+    return randomUUID();
+}

package/dist/native/tier-providers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The two config fields this reads, declared here so the move set needs no nax
+ * config type (S1 spec section 4.2, port 4). nax's `PrecheckConfig` satisfies it.
+ */
+export interface NativeTierConfig {
+    readonly agent?: {
+        readonly native?: {
+            readonly catalogOverrides?: readonly {
+                readonly provider: string;
+            }[];
+        };
+    };
+    readonly models?: Readonly<Record<string, Readonly<Record<string, string | {
+        readonly model: string;
+    } | undefined>> | undefined>>;
+}
+/** provider -> tiers, for the `models.native` map, skipping catalog-override providers. */
+export declare function nativeTierProviders(config: NativeTierConfig): Map<string, string[]>;

package/dist/native/tier-providers.js

@@ -0,0 +1,20 @@
+import { NATIVE_AGENT } from "./models.js";
+/** The provider prefix of a native id, or undefined when it has none (never guessed). */
+function providerOf(id) {
+    const slash = id.indexOf("/");
+    return slash > 0 ? id.slice(0, slash) : undefined;
+}
+/** provider -> tiers, for the `models.native` map, skipping catalog-override providers. */
+export function nativeTierProviders(config) {
+    const overridden = new Set((config.agent?.native?.catalogOverrides ?? []).map((override) => override.provider));
+    const byProvider = new Map();
+    for (const [tier, entry] of Object.entries(config.models?.[NATIVE_AGENT] ?? {})) {
+        if (entry === undefined)
+            continue;
+        const provider = providerOf(typeof entry === "string" ? entry : entry.model);
+        if (provider === undefined || overridden.has(provider))
+            continue;
+        byProvider.set(provider, [...(byProvider.get(provider) ?? []), tier]);
+    }
+    return byProvider;
+}

package/dist/permissions/approval-audit.d.ts

@@ -0,0 +1,10 @@
+import type { AskDecidedBy } from "./ask-chain.ts";
+import type { AskRequest } from "./types.ts";
+export interface ApprovalAuditRow {
+    readonly request: AskRequest;
+    readonly decision: "allow" | "deny";
+    readonly decidedBy: AskDecidedBy;
+    readonly latencyMs: number;
+    readonly at: string;
+}
+export declare function appendApprovalAudit(dir: string, runId: string, row: ApprovalAuditRow): Promise<void>;

package/dist/permissions/approval-audit.js

@@ -0,0 +1,22 @@
+/**
+ * Corpus of resolved permission asks (P2 design 7.2).
+ *
+ * One row is appended for EVERY resolved ask -- allow or deny, whichever link
+ * answered. `decidedBy` distinguishes a human decision from the rest (cache,
+ * model, timeout, unavailable, unshowable), so P5's classifier can select the
+ * human-labelled ground-truth rows -- from the actual decision-maker, on the
+ * real distribution -- out of the same file. P5's design records that such a
+ * corpus does not exist; writing it now means P5 starts with labels rather
+ * than bootstrapping them.
+ *
+ * One JSON object per line, mirroring finish-audit (src/finish/audit.ts:42).
+ * String leaves pass through redactRowStrings so a secret in the request never
+ * reaches the local corpus.
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { redactRowStrings } from "./secret-spans.js";
+export async function appendApprovalAudit(dir, runId, row) {
+    await mkdir(dir, { recursive: true });
+    await appendFile(join(dir, `${runId}.jsonl`), `${JSON.stringify(redactRowStrings(row))}\n`, "utf8");
+}

package/dist/permissions/approvals-link.d.ts

@@ -0,0 +1,20 @@
+import type { AskLink } from "./ask-chain.ts";
+export declare function createApprovalsLink(opts: {
+    readonly approvalsFile: string;
+    readonly repoRoot: string;
+    /**
+     * The project root (`ctx.projectDir`). An entry is honoured only when its
+     * `root` is this root or lies inside it, as worktrees and package dirs do.
+     */
+    readonly projectRoot: string;
+    /** Every stage's resolved bashApproval mode in this run. */
+    readonly stageModes: readonly string[];
+    /**
+     * `execution.sandbox.enabled` (P4). With the sandbox enabled a raw stage is
+     * either wrapped -- and the approvals file is ALWAYS in its denyWrite, even
+     * when outputDir puts it inside a write root -- or refused outright, so it
+     * cannot forge this file DURING THIS RUN. What earlier runs wrote is
+     * precondition 3's job. Config-only by design: no dependency on the probe.
+     */
+    readonly sandboxEnabled: boolean;
+}): AskLink;

package/dist/permissions/approvals-link.js

@@ -0,0 +1,62 @@
+/**
+ * The approvals cache as the FIRST link of the ask chain (P2 design 4.3, 6.6).
+ *
+ * TRUST BOUNDARY. Living outside repoRoot protects this file from the TYPED
+ * path-bearing tools, but NOT from Bash: nax-owned-writes.ts:52-58 excludes
+ * Bash by design, and under `raw` mode screenRawBashCommand's protectedHit
+ * skips every path outside the root (policy-bash-raw.ts:84), so the file is
+ * never screened. A raw shell can forge entries.
+ *
+ * That is not a new vulnerability -- a raw shell needs no forged permission to
+ * run a command -- but it IS a cross-stage escalation in a MIXED-mode run,
+ * where a raw stage poisons the cache an escalate stage later trusts. Hence
+ * precondition 1. P4's sandbox closes the underlying hole when enabled: see
+ * `sandboxEnabled`.
+ *
+ * The file is project-scoped and OUTLIVES the run, so precondition 1 covers
+ * only THIS run: an EARLIER forge-capable run could have written it (#2199).
+ * Precondition 3 covers that history: a tainted store is never trusted (see
+ * approvals-taint.ts, which also states the residual risk). Entry `root` is
+ * compared with the project root too, but only as hygiene -- a forger
+ * controls `root`.
+ *
+ * Every precondition fails by ABSTAINING, which escalates to the human, so a
+ * failure costs prompts rather than safety.
+ */
+import { relative, resolve } from "node:path";
+import { getSafeLogger } from "#src/infra/index";
+import { findApproval, readApprovalsFile } from "./approvals-store.js";
+import { isForgeCapable } from "./approvals-taint.js";
+const ABSTAIN = { decision: "abstain", decidedBy: "cache" };
+function insideRepo(repoRoot, file) {
+    const rel = relative(resolve(repoRoot), resolve(file));
+    return rel !== "" && !rel.startsWith("..");
+}
+export function createApprovalsLink(opts) {
+    const rawStage = isForgeCapable(opts.stageModes, opts.sandboxEnabled);
+    const inRepo = insideRepo(opts.repoRoot, opts.approvalsFile);
+    const disabled = rawStage || inRepo;
+    if (disabled) {
+        getSafeLogger()?.warn("permissions", "[approvals] cache disabled; every ask reaches the human", {
+            reason: rawStage
+                ? "a stage resolves to bashApproval:raw without the sandbox, which can forge this file"
+                : "approvals file is inside repoRoot",
+            approvalsFile: opts.approvalsFile,
+        });
+    }
+    return {
+        name: "approvals-cache",
+        async resolve(req) {
+            if (disabled)
+                return ABSTAIN;
+            if (req.command === undefined)
+                return ABSTAIN;
+            // Read per ask: a concurrent forge-capable run can taint the store mid-run.
+            const store = await readApprovalsFile(opts.approvalsFile);
+            if (store.taint !== undefined)
+                return ABSTAIN;
+            const hit = findApproval(store.entries, req.stage, req.command, opts.projectRoot);
+            return hit === undefined ? ABSTAIN : { decision: "allow", decidedBy: "cache" };
+        },
+    };
+}