@nathapp/nax-agent 0.91.6 → 0.91.7-canary.10

package/dist/session/session-tool-support.js

@@ -4,12 +4,14 @@
  * buildCodingToolSupport takes, picks the embedder default protected-paths
  * policy, and enforces the sandbox floor for "full".
  */
+import { backgroundToolOptions, unsandboxedToolOptions } from "#src/coding-tools/coding-tool-extras";
 import { resolveSessionSandbox } from "#src/coding-tools/coding-tool-sandbox";
 import { buildCodingToolSupport } from "#src/coding-tools/coding-tool-support";
 import { UNIVERSAL_CODING_TOOLS } from "#src/coding-tools/universal-coding-tools";
 import { DEFAULT_SANDBOX_CONFIG } from "#src/config/schemas-sandbox";
 import { credentialsConfig } from "#src/infra/credentials-config";
 import { EMPTY_OWNED_PATHS_POLICY } from "#src/tools/owned-paths";
+import { renderProviderInstructions } from "#src/tools/provider-instructions";
 import { AgentSessionError } from "./agent-session-errors.js";
 /** The pipeline stage the facade's tool calls and asks carry. */
 export const SESSION_STAGE = "session";
@@ -59,28 +61,71 @@ export function defaultProtectedPaths(ownCredentials) {
     const credentialDir = ownCredentials ? undefined : configuredCredentialDir();
     return credentialDir === undefined ? base : { ...base, credentialDir };
 }
-/** The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox unless gated + allowUnsandboxed. */
+/**
+ * The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox,
+ * unless the session explicitly allows running without one — under `gated` (every
+ * call still goes to the person) or under `raw` (the person's own standing choice).
+ * The resolved state rides back beside the launcher, so the session can report
+ * what its commands actually run under.
+ */
 export async function resolveSessionLauncher(args) {
-    if (args.profile !== "full" && args.profile !== "ask" && args.profile !== "review")
-        return undefined;
+    if (args.profile !== "full" && args.profile !== "ask" && args.profile !== "review") {
+        return { launcher: undefined, sandbox: { kind: "disabled" } };
+    }
     const launcher = await resolveSessionSandbox({
-        config: DEFAULT_SANDBOX_CONFIG,
+        config: args.config ?? DEFAULT_SANDBOX_CONFIG,
         root: args.root,
         needsLauncher: true,
         protectedPaths: args.protectedPaths,
         ownedPaths: EMPTY_OWNED_PATHS_POLICY,
     });
     if (launcher.state.kind === "available")
-        return launcher;
-    if (args.bashApproval === "gated" && args.allowUnsandboxed)
-        return undefined;
+        return { launcher, sandbox: launcher.state };
+    if (args.allowUnsandboxed)
+        return { launcher: undefined, sandbox: launcher.state };
     const reason = launcher.state.kind === "unavailable" ? launcher.state.reason : "the sandbox is disabled";
-    throw new AgentSessionError(`Profile "${args.profile}" needs a usable sandbox (${reason}). Pass bashApproval "gated" with allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
+    throw new AgentSessionError(`Profile "${args.profile}" needs a usable sandbox (${reason}). Pass allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
+}
+/**
+ * The `admits` predicate for `resolveProviderTools`: a tool `<id>__<local>` is
+ * admitted when `allowedTools` names it exactly or names `<id>__*`.
+ */
+export function providerAdmits(allowedTools) {
+    const allowed = new Set(allowedTools);
+    return (providerId, localName) => allowed.has(`${providerId}__${localName}`) || allowed.has(`${providerId}__*`);
+}
+/** The profile's built-ins narrowed by `allowedTools`; the scratchpad trio always survives. */
+function narrowBuiltIns(profileTools, allowedTools) {
+    if (allowedTools === undefined)
+        return profileTools;
+    const allowed = new Set(allowedTools);
+    return profileTools.filter((tool) => UNIVERSAL_CODING_TOOLS.includes(tool) || allowed.has(tool));
+}
+/** Optional overlays share one forwarding point for future posture knobs. */
+function postureToolOptions(args) {
+    return {
+        ...(args.denyRules !== undefined ? { denyRules: args.denyRules } : {}),
+        ...(args.askOnUnsandboxed !== undefined ? { askOnUnsandboxed: args.askOnUnsandboxed } : {}),
+        ...(args.commandShadow !== undefined ? { commandShadow: args.commandShadow } : {}),
+    };
 }
 export function buildSessionToolSupport(args) {
-    const declared = declaredToolsFor(args.profile, args.protectedPaths);
-    const grants = grantsFor(declared);
-    const askRules = askRulesFor(declared, args.bashApproval, args.profile);
+    const profileTools = narrowBuiltIns(declaredToolsFor(args.profile, args.protectedPaths), args.allowedTools);
+    // CodingToolName enumerates built-ins, but the runtime also accepts provider names.
+    const declared = [
+        ...new Set([...profileTools, ...(args.providerTools?.tools.map((tool) => tool.name) ?? [])]),
+    ];
+    const grants = [...grantsFor(profileTools), ...(args.providerTools?.grants ?? [])];
+    // Provider asks remain opt-in outside "ask"; configured rules follow them.
+    const askRules = [
+        ...askRulesFor(profileTools, args.bashApproval, args.profile),
+        ...(args.profile === "ask" || args.askDiscoveredTools ? (args.providerTools?.askTools ?? []) : []).map((tool) => ({
+            tool: tool,
+            patterns: ["*"],
+        })),
+        ...(args.askRules ?? []),
+    ];
+    const providerInstructions = renderProviderInstructions(args.providerTools?.instructions ?? []);
     const support = buildCodingToolSupport({
         root: args.root,
         commandCwd: args.root,
@@ -88,6 +133,13 @@ export function buildSessionToolSupport(args) {
         sessionName: args.sessionName,
         declared,
         grants,
+        ...(args.providerTools !== undefined
+            ? {
+                extraTools: args.providerTools.tools,
+                providerIdByTool: args.providerTools.providerIdByTool,
+            }
+            : {}),
+        ...(providerInstructions !== undefined ? { providerInstructions } : {}),
         bashApproval: args.bashApproval,
         protectedPaths: args.protectedPaths,
         ownedPaths: EMPTY_OWNED_PATHS_POLICY,
@@ -95,6 +147,9 @@ export function buildSessionToolSupport(args) {
         ...(askRules.length > 0 ? { askRules } : {}),
         ...(args.interceptor !== undefined ? { interceptor: args.interceptor } : {}),
         ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+        ...unsandboxedToolOptions(args),
+        ...backgroundToolOptions(args),
+        ...postureToolOptions(args),
     });
     // Unreachable while the scratchpad trio is always declared and granted; kept for the type.
     if (support === undefined) {

package/dist/session-store/index.d.ts

@@ -0,0 +1,3 @@
+export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
+export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, type SessionMeta, type SessionMetaMode, } from "./session-meta.ts";
+export { createSessionStorage, LIST_PAGE_SIZE, processAlive, type SessionListEntry, type SessionListPage, type SessionLockHolder, type SessionLockHolderState, type SessionStorage, type SessionStorageDeps, } from "./storage.ts";

package/dist/session-store/index.js

@@ -0,0 +1,3 @@
+export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.js";
+export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, } from "./session-meta.js";
+export { createSessionStorage, LIST_PAGE_SIZE, processAlive, } from "./storage.js";

package/dist/session-store/session-lock-guard.d.ts

@@ -0,0 +1,6 @@
+import { NaxError } from "#src/infra/nax-error";
+/** Distinguishes retryable mutex contention from mutation and filesystem failures. */
+export declare class SessionLockGuardBusy extends NaxError {
+    constructor();
+}
+export declare function withSessionLockGuard(path: string, mutate: () => void): void;

package/dist/session-store/session-lock-guard.js

@@ -0,0 +1,85 @@
+/** Short interprocess mutex for lock-file mutations, never stolen from a live process. */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { NaxError } from "#src/infra/nax-error";
+/** Distinguishes retryable mutex contention from mutation and filesystem failures. */
+export class SessionLockGuardBusy extends NaxError {
+    constructor() {
+        super("session in use by another process", "SESSION_LOCKED", { stage: "session-store" });
+    }
+}
+function codeOf(error) {
+    return typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+}
+function removeMarker(guard, marker) {
+    try {
+        unlinkSync(`${guard}/${marker}`);
+    }
+    catch (error) {
+        if (codeOf(error) !== "ENOENT")
+            throw error;
+    }
+    try {
+        // A contender can replace the now-empty directory. rmdir cannot remove its
+        // non-empty replacement; never recursively delete the shared guard path.
+        rmdirSync(guard);
+    }
+    catch (error) {
+        if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(String(codeOf(error))))
+            throw error;
+    }
+}
+function reapDeadGuard(guard) {
+    let markers;
+    try {
+        markers = readdirSync(guard);
+    }
+    catch (error) {
+        if (codeOf(error) === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const marker of markers) {
+        const pid = /^(\d+)\.[0-9a-f-]+$/.exec(marker)?.[1];
+        if (pid === undefined)
+            continue; // Unrecognized guards fail closed.
+        try {
+            process.kill(Number(pid), 0);
+        }
+        catch (error) {
+            // Only proven death permits recovery, never heartbeat age or EPERM.
+            // The unique marker path prevents two reapers from deleting a new owner.
+            if (codeOf(error) === "ESRCH")
+                removeMarker(guard, marker);
+        }
+    }
+}
+export function withSessionLockGuard(path, mutate) {
+    const guard = `${path}.guard`;
+    const marker = `${process.pid}.${randomUUID()}`;
+    const prepared = `${guard}.${marker}.tmp`;
+    mkdirSync(prepared);
+    try {
+        writeFileSync(`${prepared}/${marker}`, "", { flag: "wx" });
+        reapDeadGuard(guard);
+        try {
+            // Publish an already non-empty directory atomically. rename can replace
+            // an empty (released/reaped) guard, but never a live non-empty guard.
+            renameSync(prepared, guard);
+        }
+        catch (error) {
+            if (["ENOTEMPTY", "EEXIST"].includes(String(codeOf(error))))
+                throw new SessionLockGuardBusy();
+            throw error;
+        }
+        try {
+            mutate();
+        }
+        finally {
+            removeMarker(guard, marker);
+        }
+    }
+    finally {
+        removeMarker(prepared, marker);
+    }
+}

package/dist/session-store/session-lock.d.ts

@@ -0,0 +1,39 @@
+import { linkSync, renameSync, rmSync } from "node:fs";
+import { z } from "zod";
+import type { AgentLogger } from "#src/infra/index";
+export interface SessionStorageDeps {
+    readonly dir: string;
+    readonly pid: number;
+    readonly now: () => Date;
+    readonly logger: AgentLogger;
+    readonly setInterval?: (callback: () => void, ms: number) => ReturnType<typeof setInterval>;
+    readonly isAlive?: (pid: number) => boolean;
+}
+export type SessionLockHolderState = "live" | "stale" | "own";
+export declare const LOCK_HEARTBEAT_MS = 30000;
+export declare const LOCK_STALE_MS = 120000;
+declare const LockSchema: z.ZodUnion<readonly [z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+    nonce: z.ZodString;
+    heartbeatAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+    nonce: z.ZodUndefined;
+    heartbeatAt: z.ZodUndefined;
+}, z.core.$strip>]>;
+type Body = z.infer<typeof LockSchema>;
+export declare const _lockDeps: {
+    rename: typeof renameSync;
+    link: typeof linkSync;
+    remove: typeof rmSync;
+};
+declare function read(path: string): {
+    text?: string;
+    body?: Body;
+};
+export { read as readSessionLock };
+/** Shared snapshot classification; ownership takes precedence over liveness. */
+export declare function holderState(body: Body, deps: SessionStorageDeps, isAlive: (pid: number) => boolean): SessionLockHolderState;
+export declare function acquireSessionLock(path: string, deps: SessionStorageDeps, isAlive: (pid: number) => boolean): () => Promise<void>;

package/dist/session-store/session-lock.js

@@ -0,0 +1,178 @@
+/** Local-filesystem ownership protocol. All lock mutations share an exclusive directory guard. */
+import { randomUUID } from "node:crypto";
+import { linkSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+import { z } from "zod";
+import { NaxError } from "#src/infra/nax-error";
+import { withSessionLockGuard as guarded, SessionLockGuardBusy } from "./session-lock-guard.js";
+export const LOCK_HEARTBEAT_MS = 30_000;
+export const LOCK_STALE_MS = 120_000;
+const LockSchema = z.union([
+    z.object({
+        pid: z.number().int().positive(),
+        startedAt: z.string(),
+        nonce: z.string(),
+        heartbeatAt: z.string().datetime(),
+    }),
+    z.object({
+        pid: z.number().int().positive(),
+        startedAt: z.string(),
+        nonce: z.undefined(),
+        heartbeatAt: z.undefined(),
+    }),
+]);
+export const _lockDeps = { rename: renameSync, link: linkSync, remove: rmSync };
+function codeOf(error) {
+    return typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+}
+function read(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+        const parsed = LockSchema.safeParse(JSON.parse(text));
+        return parsed.success ? { text, body: parsed.data } : { text };
+    }
+    catch {
+        return text === undefined ? {} : { text };
+    }
+}
+// Internal shared reader: snapshots and mutation decisions accept the same lock bodies.
+export { read as readSessionLock };
+function same(a, b) {
+    if (a.body?.nonce !== undefined)
+        return a.body.nonce === b.body?.nonce;
+    if (a.body !== undefined)
+        return b.body?.nonce === undefined && a.body.pid === b.body?.pid && a.body.startedAt === b.body.startedAt;
+    return a.text === b.text;
+}
+const refused = (pid) => new NaxError(`session in use by ${pid === undefined ? "another process" : `pid ${pid}`}`, "SESSION_LOCKED", {
+    stage: "session-store",
+    ...(pid !== undefined ? { pid } : {}),
+});
+function create(path, body) {
+    const temp = `${path}.${body.nonce}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify(body), { flag: "wx" });
+        _lockDeps.link(temp, path);
+        return true;
+    }
+    catch (error) {
+        if (codeOf(error) === "EEXIST")
+            return false;
+        throw error;
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+/** Shared snapshot classification; ownership takes precedence over liveness. */
+export function holderState(body, deps, isAlive) {
+    if (body.pid === deps.pid)
+        return "own";
+    if (isAlive(body.pid) &&
+        (body.heartbeatAt === undefined || deps.now().getTime() - Date.parse(body.heartbeatAt) <= LOCK_STALE_MS)) {
+        return "live";
+    }
+    return "stale";
+}
+function takeover(path, body, deps, isAlive) {
+    const old = read(path);
+    const holder = old.body;
+    if (holder !== undefined && holderState(holder, deps, isAlive) === "live")
+        throw refused(holder.pid);
+    const stale = `${path}.${body.nonce}.stale`;
+    try {
+        _lockDeps.rename(path, stale);
+    }
+    catch (error) {
+        if (codeOf(error) !== "ENOENT")
+            throw error;
+        // A failed rename is not permission to overwrite the winner.
+        const raced = read(path);
+        if (raced.body !== undefined || !create(path, body))
+            throw refused(raced.body?.pid);
+        return;
+    }
+    if (!same(old, read(stale))) {
+        // Never discard another owner's renamed file if restoration is blocked.
+        try {
+            _lockDeps.link(stale, path);
+        }
+        catch (error) {
+            if (codeOf(error) !== "EEXIST")
+                throw error;
+            throw refused();
+        }
+        rmSync(stale, { force: true });
+        throw refused();
+    }
+    try {
+        deps.logger.info("session", "taking over a stale session lock", { pid: holder?.pid });
+        if (!create(path, body))
+            throw refused();
+    }
+    finally {
+        rmSync(stale, { force: true });
+    }
+}
+async function releaseOwnedLock(path, nonce) {
+    for (;;) {
+        try {
+            guarded(path, () => {
+                if (read(path).body?.nonce === nonce)
+                    _lockDeps.remove(path, { force: true });
+            });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof SessionLockGuardBusy))
+                throw error;
+            // Release owns cleanup until it can check the nonce under the guard.
+            // Yield to the holder rather than abandoning a fresh lock on contention.
+            // Unref'd: a deferred release after bounded shutdown never keeps the process alive.
+            await sleep(10, undefined, { ref: false });
+        }
+    }
+}
+export function acquireSessionLock(path, deps, isAlive) {
+    const stamp = deps.now().toISOString();
+    const body = { pid: deps.pid, startedAt: stamp, nonce: randomUUID(), heartbeatAt: stamp };
+    guarded(path, () => {
+        if (!create(path, body))
+            takeover(path, body, deps, isAlive);
+    });
+    const timer = (deps.setInterval ?? setInterval)(() => {
+        const temp = `${path}.${body.nonce}.tmp`;
+        try {
+            guarded(path, () => {
+                if (read(path).body?.nonce !== body.nonce) {
+                    clearInterval(timer);
+                    return;
+                }
+                body.heartbeatAt = deps.now().toISOString();
+                writeFileSync(temp, JSON.stringify(body));
+                _lockDeps.rename(temp, path);
+            });
+        }
+        catch (error) {
+            deps.logger.warn("session", "lock heartbeat failed", { path, error: String(error) });
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }, LOCK_HEARTBEAT_MS);
+    // Bun returns a number and Node a Timeout; only the latter can be unref'd, and only it
+    // needs to be (a number handle never holds the loop open on its own).
+    if (typeof timer !== "number")
+        timer.unref();
+    return async () => {
+        try {
+            // The heartbeat stays live while release waits out contention.
+            await releaseOwnedLock(path, body.nonce);
+        }
+        finally {
+            // A terminal release failure must let the lock age into stale recovery.
+            clearInterval(timer);
+        }
+    };
+}

package/dist/session-store/session-meta.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const SESSION_META_MODES: readonly ["none", "read", "ask", "full"];
+export type SessionMetaMode = (typeof SESSION_META_MODES)[number];
+export declare const SESSION_ID_PATTERN: RegExp;
+export declare function defaultSessionsDir(configDir: string): string;
+export declare const MetaSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    cwd: z.ZodString;
+    mode: z.ZodEnum<{
+        ask: "ask";
+        full: "full";
+        none: "none";
+        read: "read";
+    }>;
+    model: z.ZodString;
+    bashApproval: z.ZodEnum<{
+        escalate: "escalate";
+        gated: "gated";
+        raw: "raw";
+    }>;
+    title: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodNullable<z.ZodString>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SessionMeta = Readonly<z.infer<typeof MetaSchema>>;

package/dist/session-store/session-meta.js

@@ -0,0 +1,20 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { BashApprovalModeSchema } from "#src/config/bash-approval";
+export const SESSION_META_MODES = ["none", "read", "ask", "full"];
+export const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+export function defaultSessionsDir(configDir) {
+    return join(configDir, ".agent-server", "sessions");
+}
+export const MetaSchema = z.object({
+    schemaVersion: z.literal(1),
+    sessionId: z.string().min(1),
+    cwd: z.string().min(1),
+    mode: z.enum(SESSION_META_MODES),
+    model: z.string().min(1),
+    bashApproval: BashApprovalModeSchema,
+    title: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string().nullable(),
+    costUsd: z.number().optional(),
+});

package/dist/session-store/storage.d.ts

@@ -0,0 +1,39 @@
+import { type SessionLockHolderState, type SessionStorageDeps } from "./session-lock.ts";
+import { type SessionMeta } from "./session-meta.ts";
+export type { SessionLockHolderState, SessionStorageDeps } from "./session-lock.ts";
+export interface SessionLockHolder {
+    readonly pid: number;
+    readonly startedAt: string;
+    readonly heartbeatAt: string | null;
+    readonly state: SessionLockHolderState;
+}
+export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
+export declare const LIST_PAGE_SIZE = 50;
+export interface SessionListEntry {
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly title: string | null;
+    readonly updatedAt: string;
+}
+export interface SessionListPage {
+    sessions: SessionListEntry[];
+    nextCursor?: string;
+}
+export interface SessionStorage {
+    readonly dir: string;
+    readMeta(sessionId: string): Promise<SessionMeta | null>;
+    writeMeta(meta: SessionMeta): Promise<void>;
+    hasMeta(sessionId: string): Promise<boolean>;
+    removeMeta(sessionId: string): Promise<void>;
+    /** Resolves to the release function; refuses with SESSION_LOCKED when another live process holds it. */
+    acquireLock(sessionId: string): Promise<() => Promise<void>>;
+    /** Unguarded, read-only snapshot; only acquireLock decides ownership. A concurrent rename may yield null. */
+    readLockHolder(sessionId: string): Promise<SessionLockHolder | null>;
+    list(query: {
+        readonly cwd?: string | null;
+        readonly cursor?: string | null;
+    }): Promise<SessionListPage>;
+}
+/** Signal 0 checks existence only. EPERM means the process exists under another user. */
+export declare function processAlive(pid: number): boolean;
+export declare function createSessionStorage(deps: SessionStorageDeps): SessionStorage;