@nathapp/nax-agent 0.1.0

package/dist/internal.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @nathapp/nax-agent/internal: what nax reaches below the public entry -- shared
+ * helpers, NaxError, deep modules and the _*Deps test seams.
+ *
+ * NAX-ONLY AND OUTSIDE SEMVER. Nothing here is a supported API for any other
+ * consumer: names, shapes and behaviour change in any release, patch included.
+ * It exists because nax bundles this package and its tests patch the seams. It
+ * re-exports the same module instances, so patching a seam here patches the
+ * object the agent reads. `.` exports no "_" name; every seam and reset hook
+ * lives here (S2 spec section 5.3).
+ *
+ * Written by the S1-5 move script; maintained by hand from here on.
+ */
+export * from "#src/coding-tools/coding-tool-bash";
+export * from "#src/coding-tools/coding-tool-sandbox";
+export * from "#src/coding-tools/coding-tool-support";
+export * as codingToolSupportModule from "#src/coding-tools/coding-tool-support";
+export * from "#src/coding-tools/universal-coding-tools";
+export * from "#src/command-interceptor/index";
+export { _commandShadowDeps } from "#src/command-safety/shadow";
+export { _systemOneClientDeps } from "#src/command-safety/systemone-client";
+export * from "#src/config/bash-approval";
+export * from "#src/config/catalog-overrides";
+export * from "#src/config/native-agent/index";
+export * from "#src/config/schemas-sandbox";
+export * as coreModule from "#src/cost/core/index";
+export * from "#src/infra/errors";
+export * from "#src/infra/index";
+export * as infraModule from "#src/infra/index";
+export * from "#src/infra/spin-breaker/index";
+export * from "#src/internal/agent-output-env";
+export * from "#src/internal/argv-exec";
+export * from "#src/internal/command-spec/index";
+export * from "#src/internal/file-lock";
+export * from "#src/internal/git-add";
+export * from "#src/internal/git-env";
+export * from "#src/internal/git-exec";
+export * as gitExecModule from "#src/internal/git-exec";
+export * from "#src/internal/path-file-lock";
+export * from "#src/internal/process-alive";
+export * from "#src/internal/process-kill";
+export * from "#src/internal/realpath";
+export * from "#src/internal/redact";
+export * from "#src/internal/shell-quote";
+export * from "#src/internal/sort";
+export * from "#src/internal/strip-control-chars";
+export * from "#src/internal/thenable";
+export * from "#src/native/adapter-deps";
+export * from "#src/native/auth";
+export * from "#src/native/client";
+export * from "#src/native/credentials/chained-store";
+export * from "#src/native/credentials/change-guard";
+export * from "#src/native/credentials/exec-source";
+export * from "#src/native/credentials/fingerprint";
+export * from "#src/native/credentials/index";
+export * from "#src/native/errors";
+export * from "#src/native/model-resolver";
+export * from "#src/native/models";
+export * from "#src/native/session/compaction";
+export * from "#src/native/session/loop-events/external-handler";
+export * from "#src/native/session/loop-events/index";
+export * from "#src/native/session/loop-events/types";
+export * from "#src/native/session/session";
+export * as sessionModule from "#src/native/session/session";
+export * from "#src/native/session/tool-mapping";
+export * from "#src/native/session/transcript-store";
+export * as transcriptStoreModule from "#src/native/session/transcript-store";
+export * from "#src/native/session/turn-accumulator";
+export * from "#src/native/session/turn-complete-step";
+export * from "#src/native/session/turn-events";
+export * from "#src/native/session/turn-loop";
+export * from "#src/native/session/turn-retry";
+export * from "#src/native/session/turn-types";
+export * from "#src/native/session-affinity";
+export * from "#src/permissions/index";
+export * from "#src/sandbox/index";
+export * as policyInputsModule from "#src/sandbox/policy-inputs";
+export * from "#src/tools/git";
+export * from "#src/tools/git-commit";
+export * from "#src/tools/grep";
+export * from "#src/tools/index";
+export * from "#src/tools/package-managers";
+export * from "#src/tools/policy";
+export * from "#src/tools/provider-grants";
+export * as readFileModule from "#src/tools/read-file";
+export * from "#src/tools/registry";
+export * from "#src/tools/run-command";
+export * from "#src/tools/run-command-exec";
+export * from "#src/tools/runtime";
+export * from "#src/tools/tool-audit";
+export * as truncateModule from "#src/tools/truncate";

package/dist/internal.js

@@ -0,0 +1,91 @@
+/**
+ * @nathapp/nax-agent/internal: what nax reaches below the public entry -- shared
+ * helpers, NaxError, deep modules and the _*Deps test seams.
+ *
+ * NAX-ONLY AND OUTSIDE SEMVER. Nothing here is a supported API for any other
+ * consumer: names, shapes and behaviour change in any release, patch included.
+ * It exists because nax bundles this package and its tests patch the seams. It
+ * re-exports the same module instances, so patching a seam here patches the
+ * object the agent reads. `.` exports no "_" name; every seam and reset hook
+ * lives here (S2 spec section 5.3).
+ *
+ * Written by the S1-5 move script; maintained by hand from here on.
+ */
+export * from "#src/coding-tools/coding-tool-bash";
+export * from "#src/coding-tools/coding-tool-sandbox";
+export * from "#src/coding-tools/coding-tool-support";
+export * as codingToolSupportModule from "#src/coding-tools/coding-tool-support";
+export * from "#src/coding-tools/universal-coding-tools";
+export * from "#src/command-interceptor/index";
+export { _commandShadowDeps } from "#src/command-safety/shadow";
+export { _systemOneClientDeps } from "#src/command-safety/systemone-client";
+export * from "#src/config/bash-approval";
+export * from "#src/config/catalog-overrides";
+export * from "#src/config/native-agent/index";
+export * from "#src/config/schemas-sandbox";
+export * as coreModule from "#src/cost/core/index";
+export * from "#src/infra/errors";
+export * from "#src/infra/index";
+export * as infraModule from "#src/infra/index";
+export * from "#src/infra/spin-breaker/index";
+export * from "#src/internal/agent-output-env";
+export * from "#src/internal/argv-exec";
+export * from "#src/internal/command-spec/index";
+export * from "#src/internal/file-lock";
+export * from "#src/internal/git-add";
+export * from "#src/internal/git-env";
+export * from "#src/internal/git-exec";
+export * as gitExecModule from "#src/internal/git-exec";
+export * from "#src/internal/path-file-lock";
+export * from "#src/internal/process-alive";
+export * from "#src/internal/process-kill";
+export * from "#src/internal/realpath";
+export * from "#src/internal/redact";
+export * from "#src/internal/shell-quote";
+export * from "#src/internal/sort";
+export * from "#src/internal/strip-control-chars";
+export * from "#src/internal/thenable";
+export * from "#src/native/adapter-deps";
+export * from "#src/native/auth";
+export * from "#src/native/client";
+export * from "#src/native/credentials/chained-store";
+export * from "#src/native/credentials/change-guard";
+export * from "#src/native/credentials/exec-source";
+export * from "#src/native/credentials/fingerprint";
+export * from "#src/native/credentials/index";
+export * from "#src/native/errors";
+export * from "#src/native/model-resolver";
+export * from "#src/native/models";
+export * from "#src/native/session/compaction";
+export * from "#src/native/session/loop-events/external-handler";
+export * from "#src/native/session/loop-events/index";
+export * from "#src/native/session/loop-events/types";
+export * from "#src/native/session/session";
+export * as sessionModule from "#src/native/session/session";
+export * from "#src/native/session/tool-mapping";
+export * from "#src/native/session/transcript-store";
+export * as transcriptStoreModule from "#src/native/session/transcript-store";
+export * from "#src/native/session/turn-accumulator";
+export * from "#src/native/session/turn-complete-step";
+export * from "#src/native/session/turn-events";
+export * from "#src/native/session/turn-loop";
+export * from "#src/native/session/turn-retry";
+export * from "#src/native/session/turn-types";
+export * from "#src/native/session-affinity";
+export * from "#src/permissions/index";
+export * from "#src/sandbox/index";
+export * as policyInputsModule from "#src/sandbox/policy-inputs";
+export * from "#src/tools/git";
+export * from "#src/tools/git-commit";
+export * from "#src/tools/grep";
+export * from "#src/tools/index";
+export * from "#src/tools/package-managers";
+export * from "#src/tools/policy";
+export * from "#src/tools/provider-grants";
+export * as readFileModule from "#src/tools/read-file";
+export * from "#src/tools/registry";
+export * from "#src/tools/run-command";
+export * from "#src/tools/run-command-exec";
+export * from "#src/tools/runtime";
+export * from "#src/tools/tool-audit";
+export * as truncateModule from "#src/tools/truncate";

package/dist/native/adapter-deps.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Seams and small helpers shared by the native session adapter and
+ * `nativeComplete` (S1 port 2). `_adapterDeps` is the test seam the adapter
+ * tests patch; both callers read it from here, so one patch reaches both.
+ */
+import type { AuthStamp } from "#src/session/session-types";
+import { anyAmbientCredential, listStoredProviders } from "./auth.ts";
+import { authSourceIsExec, servedAuth } from "./credentials/index.ts";
+export declare function isProtocolStreamError(err: unknown): err is {
+    protocolError: {
+        kind: string;
+        message: string;
+    };
+};
+/** Test seam, following the _clientDeps precedent. */
+export declare const _adapterDeps: {
+    listStoredProviders: typeof listStoredProviders;
+    anyAmbientCredential: typeof anyAmbientCredential;
+    /**
+     * US-004: whether the global auth config points at an exec helper. Injectable
+     * so a test can pin the credential-source decision without writing
+     * `~/.nax/config.json`.
+     */
+    authSourceIsExec: typeof authSourceIsExec;
+    /** US-006: the identity the store observed for a provider — injectable like its siblings. */
+    servedAuth: typeof servedAuth;
+    /**
+     * Injectable timer pair — lets the whole-turn deadline test (US-002 AC12)
+     * drive the abort off a virtual clock instead of waiting the schema
+     * minimum. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps` / `_authDeps`.
+     *
+     * @internal
+     */
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (id: unknown) => void;
+};
+/**
+ * US-006: `{ auth }` for the identity the credential store observed for
+ * `provider`, `{}` otherwise — so the key stays absent, never `undefined`. A
+ * helper because `sendTurn` cannot carry another branch on the complexity
+ * ratchet; it reads the `_adapterDeps` seam so a unit test can pin the stamp
+ * without assembling a real store.
+ */
+export declare function authFields(provider: string): {
+    auth?: AuthStamp;
+};

package/dist/native/adapter-deps.js

@@ -0,0 +1,43 @@
+/**
+ * Seams and small helpers shared by the native session adapter and
+ * `nativeComplete` (S1 port 2). `_adapterDeps` is the test seam the adapter
+ * tests patch; both callers read it from here, so one patch reaches both.
+ */
+import { anyAmbientCredential, listStoredProviders } from "./auth.js";
+import { authSourceIsExec, servedAuth } from "./credentials/index.js";
+export function isProtocolStreamError(err) {
+    return typeof err === "object" && err !== null && "protocolError" in err;
+}
+/** Test seam, following the _clientDeps precedent. */
+export const _adapterDeps = {
+    listStoredProviders,
+    anyAmbientCredential,
+    /**
+     * US-004: whether the global auth config points at an exec helper. Injectable
+     * so a test can pin the credential-source decision without writing
+     * `~/.nax/config.json`.
+     */
+    authSourceIsExec,
+    /** US-006: the identity the store observed for a provider — injectable like its siblings. */
+    servedAuth,
+    /**
+     * Injectable timer pair — lets the whole-turn deadline test (US-002 AC12)
+     * drive the abort off a virtual clock instead of waiting the schema
+     * minimum. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps` / `_authDeps`.
+     *
+     * @internal
+     */
+    setTimeout: ((fn, ms) => setTimeout(fn, ms)),
+    clearTimeout: ((id) => clearTimeout(id)),
+};
+/**
+ * US-006: `{ auth }` for the identity the credential store observed for
+ * `provider`, `{}` otherwise — so the key stays absent, never `undefined`. A
+ * helper because `sendTurn` cannot carry another branch on the complexity
+ * ratchet; it reads the `_adapterDeps` seam so a unit test can pin the stamp
+ * without assembling a real store.
+ */
+export function authFields(provider) {
+    const auth = _adapterDeps.servedAuth(provider);
+    return auth === undefined ? {} : { auth };
+}

package/dist/native/auth-types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * nax's own login vocabulary.
+ *
+ * A deliberate mirror of nax-ai's LoginInteraction family. It exists so the
+ * CLI can implement a terminal interaction without importing nax-ai, which
+ * packages/repo-tooling/scripts/check-nax-ai-imports.ts confines to this directory. The mapper in
+ * auth.ts is the only translation point, so a rename upstream is a one-file
+ * change here.
+ *
+ * This module imports nothing. That is what keeps it a leaf, so the barrel can
+ * re-export it without creating an import cycle.
+ */
+export type AuthMethod = "api-key" | "oauth";
+export interface AuthOption {
+    id: string;
+    label: string;
+    description?: string;
+}
+export type AuthPrompt = {
+    signal?: AbortSignal;
+} & ({
+    type: "text";
+    message: string;
+    placeholder?: string;
+} | {
+    type: "secret";
+    message: string;
+    placeholder?: string;
+} | {
+    type: "select";
+    message: string;
+    options: readonly AuthOption[];
+} | {
+    type: "manual-code";
+    message: string;
+    placeholder?: string;
+});
+export interface AuthLink {
+    url: string;
+    label?: string;
+}
+export type AuthEvent = {
+    type: "info";
+    message: string;
+    links?: readonly AuthLink[];
+} | {
+    type: "auth-url";
+    url: string;
+    instructions?: string;
+} | {
+    type: "device-code";
+    userCode: string;
+    verificationUri: string;
+    intervalSeconds?: number;
+    expiresInSeconds?: number;
+} | {
+    type: "progress";
+    message: string;
+};
+/** `prompt` returns the entered text, or for `select` the chosen option id. Reject to cancel. */
+export interface AuthInteraction {
+    prompt(prompt: AuthPrompt): Promise<string>;
+    notify(event: AuthEvent): void;
+}
+/** Metadata only. The credential is written to the store and never returned. */
+export interface AuthResult {
+    providerId: string;
+    method: AuthMethod;
+    kind: "api-key" | "oauth";
+}

package/dist/native/auth-types.js

@@ -0,0 +1,13 @@
+/**
+ * nax's own login vocabulary.
+ *
+ * A deliberate mirror of nax-ai's LoginInteraction family. It exists so the
+ * CLI can implement a terminal interaction without importing nax-ai, which
+ * packages/repo-tooling/scripts/check-nax-ai-imports.ts confines to this directory. The mapper in
+ * auth.ts is the only translation point, so a rename upstream is a one-file
+ * change here.
+ *
+ * This module imports nothing. That is what keeps it a leaf, so the barrel can
+ * re-export it without creating an import cycle.
+ */
+export {};

package/dist/native/auth.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Obtaining and managing credentials, in nax's vocabulary.
+ *
+ * This file and its siblings are the only place in src/ permitted to import
+ * nax-ai (packages/repo-tooling/scripts/check-nax-ai-imports.ts). Nothing it exports carries a
+ * nax-ai type, so src/cli/auth.ts can consume it without breaching that gate.
+ */
+import { ambientAuthAvailable, type LoginInteraction, login } from "@nathapp/nax-ai";
+import type { AuthInteraction, AuthMethod, AuthResult } from "./auth-types.ts";
+import { type StoredEntry } from "./credentials/index.ts";
+/**
+ * Deliberately dumb: the two vocabularies are one-for-one by design, so this
+ * is a rename boundary rather than a translation with opinions. Both sides use
+ * kebab-case, so the names pass straight through.
+ */
+export declare function toLoginInteraction(interaction: AuthInteraction): LoginInteraction;
+/**
+ * Cancellation is not a failure, and the CLI needs to tell them apart to exit
+ * 130 silently. A marker class rather than a code match: an exit status should
+ * not depend on message text.
+ */
+export declare class AuthCancelledError extends Error {
+    readonly providerId: string;
+    constructor(providerId: string);
+}
+/** Test seam, following the _clientDeps precedent. */
+export declare const _authDeps: {
+    login: typeof login;
+    ambientAuthAvailable: typeof ambientAuthAvailable;
+    providerIds: () => Promise<string[]>;
+    /**
+     * Injectable timer pair — lets tests drive `anyAmbientCredential`'s
+     * expiry branch off a virtual clock instead of waiting the full 2s
+     * production timeout. Mirrors `_heartbeatDeps` / `_idleWatchdogDeps`.
+     *
+     * @internal
+     */
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (id: unknown) => void;
+};
+/**
+ * Obtain a credential and write it to the store.
+ *
+ * `method` is forwarded, not interpreted: nax-ai owns the table of what each
+ * provider offers and rejects an unavailable choice itself. Omitted, it runs
+ * its own selection prompt. Deciding here is how the two drift apart.
+ *
+ * The result is reported exactly as returned. kind is never derived from
+ * method — M5's design predicted openrouter would report kind "api-key" and
+ * its live run reported "oauth".
+ */
+export declare function runLogin(providerId: string, interaction: AuthInteraction, method?: AuthMethod): Promise<AuthResult>;
+export declare const DEFAULT_PI_AUTH_PATH: string;
+export interface ImportOutcome {
+    providerId: string;
+    status: "imported" | "skipped" | "unsupported";
+}
+/**
+ * Bring pi's credentials across.
+ *
+ * Existing entries are skipped rather than overwritten: import plausibly runs
+ * after a fresh login, and silently replacing a credential just obtained would
+ * be the worst kind of quiet data loss.
+ *
+ * The presence check happens inside modify()'s callback, not before it: that
+ * is what holds the store's cross-process lock across the whole
+ * read-modify-write. Deciding "already present" from a separate, unlocked
+ * read would race a concurrent login completing between the two calls.
+ */
+export declare function importPiCredentials(options?: {
+    from?: string;
+    force?: boolean;
+}): Promise<ImportOutcome[]>;
+export declare function listStoredProviders(): Promise<StoredEntry[]>;
+/**
+ * Removal, not revocation. pi has no revocation anywhere — its own types
+ * define logout as deletion — so the provider-side token stays live until it
+ * expires. Callers must not describe this as logging out.
+ */
+export declare function removeStoredProvider(providerId: string): Promise<void>;
+export declare function authImportOutcomeLabel(status: ImportOutcome["status"]): string;
+/**
+ * Of these providers, which would ambient auth satisfy on its own?
+ *
+ * A stored credential owns its provider in pi's resolution order, so any
+ * provider named here has a working environment variable that the stored
+ * credential is shadowing. This only ever decorates a diagnostic, so a failing
+ * probe reports nothing rather than breaking the command around it.
+ */
+export declare function ambientShadows(providerIds: readonly string[]): Promise<string[]>;
+/**
+ * Of these providers, which have NO credential at all — neither stored nor
+ * ambient?
+ *
+ * Asked for the providers the default native tier map names, so an install
+ * whose only credential belongs to another provider fails before a billed call
+ * rather than at the first request.
+ *
+ * What counts as "has a credential": a credential the assembled store serves
+ * for that provider, or nax-ai's ambient probe answering true. That probe
+ * swallows its own check/resolve errors and answers false, so a provider whose
+ * resolution fails IS reported missing — the caller must exclude providers it
+ * knows authenticate some other way (catalog overrides). The two cases here
+ * that do not guess "no" are the ones this function can see: an unreadable
+ * store, and a sweep that outlives AMBIENT_PROBE_TIMEOUT_MS (pi's resolve()
+ * "may execute commands") — both report nothing missing.
+ *
+ * US-004: "has a stored credential" is a read through `naxCredentialStore()`,
+ * per provider, rather than a listing of the file. With an exec helper
+ * configured only the store knows which source serves a provider, and a helper
+ * failure (CREDENTIAL_HELPER_FAILED, CREDENTIAL_HELPER_INVALID) or a refused
+ * change (CREDENTIAL_CHANGED) is a run-level fault, not a missing credential —
+ * it propagates and refuses the run. The reads also record each provider's
+ * baseline (`credential.resolved`) before any story starts, which is what the
+ * guard later compares against. They happen before, and outside, the ambient
+ * sweep's race below, so a helper slower than the sweep's timeout is still
+ * asked — and they are issued as one batch, so N helper-served providers cost
+ * the slowest helper rather than the sum of all of them.
+ */
+export declare function providersWithoutCredentials(providerIds: readonly string[]): Promise<string[]>;
+/**
+ * Is ANY provider satisfied by ambient auth alone?
+ *
+ * Deliberately not "is provider X satisfied": the caller
+ * (NativeAgentAdapter.hasCredentials) has no provider to ask about, because
+ * the model — and so the provider — is chosen per request.
+ *
+ * Expiry resolves TRUE, not false. Pruning an agent that would have worked
+ * kills a run; reporting one that cannot authenticate costs a single
+ * request-time auth error that is already mapped and handled. Where this
+ * cannot answer, it must not guess "no".
+ */
+export declare function anyAmbientCredential(): Promise<boolean>;