@nathapp/nax-agent 0.1.0 → 0.2.0

package/dist/session/agent-session.js

@@ -0,0 +1,223 @@
+/**
+ * createAgentSession: the conversational session facade (S3 spec 4, 5.1).
+ * One NativeSessionAdapter per session. The facade fills the S1
+ * OpenSessionOpts itself and talks to the backend through the S1 contract
+ * only (openSession, sendTurn, closeSession), so the acpx backend (S4) slots
+ * in behind the same API. resumeAgentSession reopens a stored session
+ * (spec 4.2, 6.4).
+ */
+import { DEFAULT_SPIN_BREAKER_SETTINGS } from "#src/infra/spin-breaker/index";
+import { NATIVE_AGENT } from "#src/native/models";
+import { NativeSessionAdapter } from "#src/native/session-adapter";
+import { _agentSessionDeps } from "./agent-session-deps.js";
+import { AgentSessionError } from "./agent-session-errors.js";
+import { resolveAgentSessionOptions } from "./agent-session-options.js";
+import { interruptedTurnOf, loadResumable, resumeInput } from "./agent-session-resume.js";
+import { claimTurn } from "./agent-session-turn.js";
+import { createPendingAskTable } from "./pending-asks.js";
+import { createSessionAskLink, createSessionAskResolver } from "./session-ask-link.js";
+import { createSessionInteractionHandler, embedderToolDescriptor } from "./session-interaction.js";
+import { buildSessionToolSupport, defaultProtectedPaths, resolveSessionLauncher } from "./session-tool-support.js";
+/** The handler's turn signal between turns: never aborts. */
+const IDLE_SIGNAL = new AbortController().signal;
+/**
+ * nax's `agent.native.transportRetry` default. The loop retries a transport,
+ * overloaded or rate-limit fault that arrives after events have streamed, and
+ * emits `stream_reset` so the consumer voids that round's deltas (spec 5.3).
+ */
+const SESSION_TRANSPORT_RETRY = { maxAttempts: 3, baseDelayMs: 2000 };
+class NativeAgentSession {
+    parts;
+    active;
+    last;
+    closing;
+    constructor(parts, last) {
+        this.parts = parts;
+        this.last = last;
+    }
+    get id() {
+        return this.parts.ctx.sessionId;
+    }
+    get lastTurn() {
+        return this.last;
+    }
+    send(message) {
+        if (this.closing !== undefined) {
+            throw new AgentSessionError(`Session "${this.id}" is closed`, "AGENT_SESSION_CLOSED", { sessionId: this.id });
+        }
+        if (this.active !== undefined) {
+            throw new AgentSessionError(`Session "${this.id}" already has a turn in flight`, "AGENT_SESSION_BUSY", {
+                sessionId: this.id,
+            });
+        }
+        const turn = claimTurn(this.parts.ctx, message, {
+            onStart: (live) => {
+                this.parts.slot.turn = live;
+            },
+            onSettle: (turnId, status) => {
+                this.active = undefined;
+                this.parts.slot.turn = undefined;
+                if (status !== undefined)
+                    this.last = { turnId, status };
+            },
+        });
+        this.active = turn;
+        return turn.iterable;
+    }
+    answer(requestId, reply) {
+        return this.parts.table.answer(requestId, reply);
+    }
+    cancel(reason = "cancelled") {
+        this.active?.cancel(reason);
+    }
+    close() {
+        this.closing ??= this.shutdown();
+        return this.closing;
+    }
+    async shutdown() {
+        const active = this.active;
+        this.parts.table.close();
+        active?.cancel("session closed");
+        await active?.settled;
+        try {
+            await this.parts.ctx.adapter.closeSession(this.parts.ctx.handle);
+        }
+        finally {
+            await this.parts.cleanup();
+        }
+    }
+}
+async function sessionRoot(options) {
+    const workdir = options.raw.workdir;
+    if (workdir === undefined) {
+        const dir = await _agentSessionDeps.makeScratchRoot();
+        return { dir, cleanup: () => _agentSessionDeps.removeScratchRoot(dir) };
+    }
+    if (!(await _agentSessionDeps.isDirectory(workdir))) {
+        throw new AgentSessionError(`Invalid agent session options: workdir "${workdir}" is not a directory`, "AGENT_SESSION_INVALID_OPTIONS", { path: "workdir" });
+    }
+    return { dir: workdir, cleanup: async () => { } };
+}
+function createAdapter(options) {
+    const overrides = options.raw.catalogOverrides ?? [];
+    const credentials = options.raw.credentials;
+    // A session with its own catalog or credentials owns its client; the rest share the process memo.
+    const owns = overrides.length > 0 || credentials !== undefined;
+    return new NativeSessionAdapter(overrides, {
+        ...(credentials !== undefined ? { credentials } : {}),
+        ...(owns ? { ownClient: true } : {}),
+    });
+}
+async function assemble(options, sessionId, root, opening) {
+    const raw = options.raw;
+    // A supplied policy is merged over the default, so enabling GitCommit never drops the credential read-deny.
+    const protectedPaths = { ...defaultProtectedPaths(raw.credentials !== undefined), ...raw.hostPorts?.protectedPaths };
+    const launcher = await resolveSessionLauncher({
+        profile: raw.profile,
+        root: root.dir,
+        protectedPaths,
+        bashApproval: options.bashApproval,
+        allowUnsandboxed: options.allowUnsandboxed,
+    });
+    const table = createPendingAskTable(options.approvalTimeoutMs);
+    const slot = { turn: undefined, callId: undefined };
+    const asks = { table, emit: (body) => slot.turn?.emit(body), currentCallId: () => slot.callId };
+    const { support, grants } = buildSessionToolSupport({
+        profile: raw.profile,
+        root: root.dir,
+        sessionName: sessionId,
+        protectedPaths,
+        bashApproval: options.bashApproval,
+        launcher,
+        askResolver: createSessionAskResolver(createSessionAskLink(asks)),
+        interceptor: raw.hostPorts?.commandInterceptor,
+    });
+    const interactionHandler = createSessionInteractionHandler({
+        sessionId,
+        runtime: support.runtime,
+        embedderTools: new Map(options.tools.map((tool) => [tool.name, tool])),
+        asks,
+        turnSignal: () => slot.turn?.signal ?? IDLE_SIGNAL,
+        setCurrentCallId: (callId) => {
+            slot.callId = callId;
+        },
+    });
+    const adapter = createAdapter(options);
+    const handle = await adapter.openSession(sessionId, {
+        agentName: NATIVE_AGENT,
+        workdir: root.dir,
+        resolvedPermissions: { mode: "default", toolGrants: grants, bashApproval: options.bashApproval },
+        modelDef: { provider: options.provider, model: raw.model },
+        timeoutSeconds: options.turnTimeoutSeconds,
+        transcriptStore: raw.transcriptStore,
+        retainOnClose: true,
+        resume: opening.resume,
+        spinBreaker: DEFAULT_SPIN_BREAKER_SETTINGS,
+        transportRetry: SESSION_TRANSPORT_RETRY,
+        // An empty instructions is no system prompt: `system: ""` on the wire invites provider quirks.
+        ...(raw.instructions !== undefined && raw.instructions !== "" ? { systemPrompt: raw.instructions } : {}),
+    });
+    const ctx = {
+        sessionId,
+        adapter,
+        handle,
+        store: raw.transcriptStore,
+        codingTools: [...support.tools, ...options.tools.map(embedderToolDescriptor)],
+        interactionHandler,
+        loopHandlers: raw.loopHandlers,
+        loopHandlerContext: { sessionName: sessionId, workdir: root.dir, model: raw.model, provider: options.provider },
+        turnTimeoutSeconds: options.turnTimeoutSeconds,
+        metadata: options.metadata,
+    };
+    return new NativeAgentSession({ ctx, table, slot, cleanup: root.cleanup }, opening.lastTurn);
+}
+/** Opens the backend session under a fresh root; a failure removes the root. */
+async function open(options, sessionId, opening) {
+    const root = await sessionRoot(options);
+    try {
+        return await assemble(options, sessionId, root, opening);
+    }
+    catch (err) {
+        await root.cleanup();
+        throw err;
+    }
+}
+export async function createAgentSession(input) {
+    const options = resolveAgentSessionOptions(input);
+    const sessionId = options.raw.sessionId ?? _agentSessionDeps.randomUUID();
+    if ((await options.raw.transcriptStore.load(sessionId)) !== null) {
+        throw new AgentSessionError(`Session "${sessionId}" already exists in the transcript store; resume it instead`, "AGENT_SESSION_EXISTS", { sessionId });
+    }
+    return open(options, sessionId, { resume: false, lastTurn: undefined });
+}
+/**
+ * Spec 6.4: the turn a dead process left running is marked ended, so the next
+ * send starts clean. A failure closes the session and rethrows the store's
+ * error; a close failure would only mask it.
+ */
+async function endInterruptedTurn(session, store, sessionId, turnId) {
+    try {
+        await store.markTurn(sessionId, { turnId, state: "ended" });
+    }
+    catch (err) {
+        await session.close().catch(() => undefined);
+        throw err;
+    }
+}
+/**
+ * Reopens a stored session (spec 4.2). `options` are a create's options; the
+ * session id is the argument. Instructions, tools and profile are not stored:
+ * pass them again.
+ */
+export async function resumeAgentSession(sessionId, input) {
+    const options = resolveAgentSessionOptions(resumeInput(sessionId, input));
+    const store = options.raw.transcriptStore;
+    const interrupted = interruptedTurnOf(await loadResumable(store, sessionId, options.raw.model));
+    const session = await open(options, sessionId, {
+        resume: true,
+        lastTurn: interrupted === undefined ? undefined : { turnId: interrupted, status: "interrupted" },
+    });
+    if (interrupted !== undefined)
+        await endInterruptedTurn(session, store, sessionId, interrupted);
+    return session;
+}

package/dist/session/pending-asks.d.ts

@@ -0,0 +1,24 @@
+import type { AnswerReply, AnswerStatus } from "./agent-session-types.ts";
+export type PendingAskKind = "approval" | "question";
+export type AskSettlement = {
+    readonly by: "human";
+    readonly reply: AnswerReply;
+} | {
+    readonly by: "timeout";
+} | {
+    readonly by: "cancelled";
+};
+export interface IssuedAsk {
+    readonly requestId: string;
+    readonly expiresAt: string;
+    readonly settled: Promise<AskSettlement>;
+}
+export interface PendingAskTable {
+    issue(kind: PendingAskKind, signal: AbortSignal | undefined): IssuedAsk;
+    answer(requestId: string, reply: AnswerReply): AnswerStatus;
+    /** Settles every pending request as cancelled. */
+    cancelAll(): void;
+    /** cancelAll; afterwards every answer() returns "unknown" and every issue() settles cancelled. */
+    close(): void;
+}
+export declare function createPendingAskTable(timeoutMs: number): PendingAskTable;

package/dist/session/pending-asks.js

@@ -0,0 +1,77 @@
+/**
+ * The session's pending approvals and questions (spec 4.2 answer, 6.1). Each
+ * request settles once: by answer(), by its deadline, or by its turn signal.
+ * Ids are kept for the session's lifetime, so a late click gets a status
+ * rather than a throw; only a never-issued id or a kind mismatch throws.
+ */
+import { _agentSessionDeps } from "./agent-session-deps.js";
+import { AgentSessionError } from "./agent-session-errors.js";
+/** The kind a reply answers, or undefined for a malformed reply (callers may be plain JS). */
+function replyKind(reply) {
+    const value = reply;
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    if ("decision" in value)
+        return value.decision === "allow" || value.decision === "deny" ? "approval" : undefined;
+    return "text" in value && typeof value.text === "string" ? "question" : undefined;
+}
+function kindMismatch(requestId, kind) {
+    const expected = kind === "approval" ? "an approval: reply with { decision }" : "a question: reply with { text }";
+    return new AgentSessionError(`Request "${requestId}" is ${expected}`, "AGENT_SESSION_INVALID_ANSWER", {
+        requestId,
+        kind,
+    });
+}
+export function createPendingAskTable(timeoutMs) {
+    const entries = new Map();
+    let closed = false;
+    function issue(kind, signal) {
+        const requestId = _agentSessionDeps.randomUUID();
+        const expiresAt = new Date(_agentSessionDeps.now() + timeoutMs).toISOString();
+        const settled = new Promise((resolve) => {
+            let timer;
+            const onAbort = () => finish({ by: "cancelled" });
+            function finish(settlement) {
+                if (entries.get(requestId)?.state !== "pending")
+                    return;
+                _agentSessionDeps.clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                entries.set(requestId, { kind, state: settlement.by });
+                resolve(settlement);
+            }
+            entries.set(requestId, { kind, state: "pending", finish });
+            timer = _agentSessionDeps.setTimeout(() => finish({ by: "timeout" }), timeoutMs);
+            if (closed || signal?.aborted === true)
+                finish({ by: "cancelled" });
+            else
+                signal?.addEventListener("abort", onAbort, { once: true });
+        });
+        return { requestId, expiresAt, settled };
+    }
+    function answer(requestId, reply) {
+        if (closed)
+            return "unknown";
+        const entry = entries.get(requestId);
+        if (entry === undefined) {
+            throw new AgentSessionError(`No request "${requestId}" was issued by this session`, "AGENT_SESSION_INVALID_ANSWER", {
+                requestId,
+            });
+        }
+        if (replyKind(reply) !== entry.kind)
+            throw kindMismatch(requestId, entry.kind);
+        if (entry.state === "pending") {
+            entry.finish?.({ by: "human", reply });
+            return "accepted";
+        }
+        return entry.state === "cancelled" ? "cancelled" : "expired";
+    }
+    function cancelAll() {
+        for (const entry of [...entries.values()])
+            entry.finish?.({ by: "cancelled" });
+    }
+    function close() {
+        cancelAll();
+        closed = true;
+    }
+    return { issue, answer, cancelAll, close };
+}

package/dist/session/session-ask-link.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Raises approvals to the person through the session's events (spec 6.1).
+ * askPerson is shared by the coding tools' AskLink and by embedder tools
+ * whose approval is "always". Asks are serial in practice: the tool batch
+ * runs one call at a time.
+ */
+import { type AskLink, type AskLinkOutcome, type AskResolver } from "#src/permissions/index";
+import type { SessionEventBody } from "./agent-session-types.ts";
+import type { PendingAskTable } from "./pending-asks.ts";
+export interface SessionAskDeps {
+    readonly table: PendingAskTable;
+    /** Emits on the running turn's event stream. */
+    readonly emit: (body: SessionEventBody) => void;
+    /** The tool call being answered right now, if any. */
+    readonly currentCallId: () => string | undefined;
+}
+export interface ApprovalAsk {
+    readonly tool: string;
+    readonly summary: string;
+    readonly command?: string;
+    readonly reason: string;
+    readonly callId?: string;
+}
+export declare function askPerson(deps: SessionAskDeps, ask: ApprovalAsk, signal: AbortSignal | undefined): Promise<AskLinkOutcome>;
+export declare function createSessionAskLink(deps: SessionAskDeps): AskLink;
+export declare function createSessionAskResolver(link: AskLink): AskResolver;

package/dist/session/session-ask-link.js

@@ -0,0 +1,52 @@
+/**
+ * Raises approvals to the person through the session's events (spec 6.1).
+ * askPerson is shared by the coding tools' AskLink and by embedder tools
+ * whose approval is "always". Asks are serial in practice: the tool batch
+ * runs one call at a time.
+ */
+import { chainAskLinks, maskForPrompt, } from "#src/permissions/index";
+export async function askPerson(deps, ask, signal) {
+    const { requestId, expiresAt, settled } = deps.table.issue("approval", signal);
+    deps.emit({
+        type: "approval_requested",
+        requestId,
+        ...(ask.callId !== undefined ? { callId: ask.callId } : {}),
+        tool: ask.tool,
+        summary: ask.summary,
+        ...(ask.command !== undefined ? { command: ask.command } : {}),
+        reason: ask.reason,
+        expiresAt,
+    });
+    const settlement = await settled;
+    const allowed = settlement.by === "human" && "decision" in settlement.reply && settlement.reply.decision === "allow";
+    const decision = allowed ? "allow" : "deny";
+    deps.emit({ type: "approval_resolved", requestId, decision, decidedBy: settlement.by });
+    return { decision, decidedBy: settlement.by };
+}
+const UNSHOWABLE = { decision: "deny", decidedBy: "unshowable" };
+export function createSessionAskLink(deps) {
+    return {
+        name: "agent-session",
+        resolve(req, control) {
+            // A request whose text could not be shown safely is never put in front of a person.
+            if (req.unshowable === true)
+                return Promise.resolve(UNSHOWABLE);
+            // As nax's human link: the command is masked, and one whose secret cannot be masked safely is unshowable.
+            const masked = req.command === undefined ? undefined : maskForPrompt(req.command);
+            if (masked !== undefined && !masked.ok)
+                return Promise.resolve(UNSHOWABLE);
+            const callId = deps.currentCallId();
+            return askPerson(deps, {
+                tool: req.tool,
+                summary: req.summary,
+                ...(masked !== undefined ? { command: masked.masked } : {}),
+                reason: req.reason ?? `matched ${req.rule}`,
+                ...(callId !== undefined ? { callId } : {}),
+            }, control?.signal);
+        },
+    };
+}
+export function createSessionAskResolver(link) {
+    const chain = chainAskLinks([link]);
+    return { humanReachable: true, resolve: (req, control) => chain.resolve(req, control) };
+}

package/dist/session/session-event-channel.d.ts

@@ -0,0 +1,17 @@
+import type { SessionEvent } from "./agent-session-types.ts";
+export interface SessionEventChannelOptions {
+    /** Undelivered control events tolerated before onStall fires. */
+    readonly controlCap: number;
+    /** The consumer's first next(): the turn starts here. May push synchronously. */
+    readonly onFirstPull: () => void;
+    /** The consumer called return() before the channel ended. */
+    readonly onReturn: () => void;
+    readonly onStall: () => void;
+}
+export interface SessionEventChannel {
+    push(event: SessionEvent): void;
+    /** No more events: the iterator completes once the buffer drains. */
+    end(): void;
+    readonly iterator: AsyncIterator<SessionEvent>;
+}
+export declare function createSessionEventChannel(options: SessionEventChannelOptions): SessionEventChannel;

package/dist/session/session-event-channel.js

@@ -0,0 +1,132 @@
+/**
+ * The push-to-pull channel behind send()'s iterator (spec 4.4). The turn
+ * pushes; one consumer pulls. While the consumer lags, adjacent deltas of the
+ * same type and round merge. Control events are never merged or dropped; past
+ * `controlCap` undelivered ones the channel reports a stall, once. One
+ * consumer only: a second next() while one is pending rejects (for await
+ * never makes one). return() before the first next() never starts the turn.
+ *
+ * The buffer is two slots: a `queue` of non-mergeable events (FIFO, indexed)
+ * and a `tail` that is always a delta the next push can merge into. push is
+ * amortized O(1) — a `queue.push` and the `tail` swap are O(1), and the
+ * merge's string concat is O(merged-text length), which is the same cost the
+ * old design paid, just without the per-merge buffer copy. The pop is a
+ * `queue[head++]` read, not an `Array.shift()`. The old implementation
+ * copied the whole buffer on every merge (`[...buffer.slice(0, -1), combined]`),
+ * which made a high-rate delta stream quadratic.
+ */
+import { AgentSessionError } from "./agent-session-errors.js";
+const DONE = { done: true, value: undefined };
+function isDelta(event) {
+    return event !== undefined && (event.type === "text_delta" || event.type === "thinking_delta");
+}
+function canMergeInto(into, next) {
+    return into.type === next.type && into.round === next.round;
+}
+export function createSessionEventChannel(options) {
+    let queue = [];
+    let head = 0;
+    let tail;
+    let waiter;
+    let undeliveredControl = 0;
+    let ended = false;
+    let consumerGone = false;
+    let pulled = false;
+    let stalled = false;
+    function deliver(result) {
+        if (waiter === undefined)
+            return false;
+        const resolve = waiter;
+        waiter = undefined;
+        resolve(result);
+        return true;
+    }
+    /** Drop the consumed prefix; O(1) when the buffer is fully drained. */
+    function compact() {
+        if (head > 0 && head === queue.length) {
+            queue = [];
+            head = 0;
+        }
+    }
+    function enqueue(event) {
+        if (isDelta(event)) {
+            if (tail !== undefined && canMergeInto(tail, event)) {
+                // Replace, don't mutate: DeltaEvent.text is readonly. O(1) — a
+                // string concat, not a buffer copy.
+                tail = { ...tail, text: tail.text + event.text };
+                return;
+            }
+            if (tail !== undefined)
+                queue.push(tail);
+            tail = event;
+            return;
+        }
+        // Control events: never held in `tail` (so a later delta sees no merge
+        // partner and the cap math stays correct).
+        if (tail !== undefined) {
+            queue.push(tail);
+            tail = undefined;
+        }
+        queue.push(event);
+        undeliveredControl += 1;
+        if (!stalled && undeliveredControl > options.controlCap) {
+            stalled = true;
+            options.onStall();
+        }
+    }
+    function push(event) {
+        if (ended || consumerGone)
+            return;
+        if (deliver({ value: event, done: false }))
+            return;
+        enqueue(event);
+    }
+    function end() {
+        if (ended)
+            return;
+        ended = true;
+        if (queue.length === head && tail === undefined)
+            deliver(DONE);
+    }
+    async function next() {
+        if (consumerGone)
+            return DONE;
+        if (waiter !== undefined) {
+            throw new AgentSessionError("send() iterables support one next() at a time", "AGENT_SESSION_BUSY");
+        }
+        if (!pulled) {
+            pulled = true;
+            options.onFirstPull();
+        }
+        if (head < queue.length) {
+            const event = queue[head++];
+            compact();
+            if (!isDelta(event))
+                undeliveredControl -= 1;
+            return { value: event, done: false };
+        }
+        if (tail !== undefined) {
+            const event = tail;
+            tail = undefined;
+            return { value: event, done: false };
+        }
+        if (ended)
+            return DONE;
+        return new Promise((resolve) => {
+            waiter = resolve;
+        });
+    }
+    async function leave() {
+        if (consumerGone)
+            return DONE;
+        consumerGone = true;
+        queue = [];
+        head = 0;
+        tail = undefined;
+        deliver(DONE);
+        if (!ended)
+            options.onReturn();
+        return DONE;
+    }
+    return { push, end, iterator: { next, return: leave } };
+}

package/dist/session/session-interaction.d.ts

@@ -0,0 +1,20 @@
+import type { CodingTool } from "#src/tools/registry";
+import type { CodingToolRuntime } from "#src/tools/runtime";
+import type { EmbedderTool } from "./agent-session-types.ts";
+import type { InteractionHandler } from "./interaction-handler.ts";
+import { type SessionAskDeps } from "./session-ask-link.ts";
+/** Byte cap on an embedder approval's default summary. */
+export declare const EMBEDDER_SUMMARY_BYTES = 1024;
+export interface SessionInteractionDeps {
+    readonly sessionId: string;
+    readonly runtime: CodingToolRuntime;
+    readonly embedderTools: ReadonlyMap<string, EmbedderTool>;
+    readonly asks: SessionAskDeps;
+    /** The running turn's signal (a never-aborting one between turns). */
+    readonly turnSignal: () => AbortSignal;
+    readonly setCurrentCallId: (callId: string | undefined) => void;
+}
+/** What the model sees of an embedder tool. The facade's handler runs it; this run is never reached. */
+export declare function embedderToolDescriptor(tool: EmbedderTool): CodingTool;
+export declare function defaultSummary(input: unknown): string;
+export declare function createSessionInteractionHandler(deps: SessionInteractionDeps): InteractionHandler;