@nathapp/nax-agent 0.3.1 → 0.84.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.84.0] - 2026-10-09
+
+- Versioning: released in lockstep with `@nathapp/nax`, `@nathapp/nax-ai` and the other agent package at one shared version, starting at 0.84.0 (previously 0.3.x).
+
+### Added
+
+- `createTerminalAuthInteraction({ log, style?, openUrl? })`, `PromptCancelledError`, `TerminalStyle` and `PLAIN_STYLE`: the terminal login UI (hidden secret entry, arrow-key picker, browser handoff for OAuth), moved from the nax CLI so `nax-agent login` shares it (S5-4).
+- `loginProviderIds()`: the providers `runLogin` can log in to (S5-4).
+- `displayToolInput` and `toolResultPreview`: the live tool-display masking, for replaying stored transcripts (S5-1).
+- `answerable?: false` on the `approval_requested` and `question` session events, set for profile auto-decisions and noted questions (S5-2).
+- `carryHistoryAcrossModels` (`nativeBackend` option and `OpenSessionOpts`): keep a session's history across a model change; each assistant message records its origin model (S5-3).
+
 ## [0.3.1] - 2026-10-07
 
 ### Added

package/README.md

@@ -37,6 +37,12 @@ Three pieces of host knowledge are passed in as data or functions, because the p
 - **`ProtectedPathsPolicy`** names the paths you own and want kept away from the agent: git pathspecs the Git tool excludes from its default view, gitignore patterns `GitCommit` refuses to stage, the project state directory, the credential directory and the trust-store file the sandbox protects. If you do not supply it, the Git tool excludes nothing from its default view, and `GitCommit` fails closed: it refuses every path and stages nothing until the policy supplies a non-empty `gitIgnorePatterns` (an empty list refuses the same way). Supply it whenever the agent works in a directory that holds files you own. Building a sandboxed session requires it.
 - **`commandInterceptor`** may rewrite a command before it runs (for example to prefix a wrapper binary). Rewrites are validated: an argv rewrite may only prefix the original argv with the provider's own binary, and a shell rewrite goes through the same narrowing. If you do not supply one, commands run unchanged. An interceptor that throws, or returns a rewrite that fails validation, is treated as a decline, and the original command runs.
 
+## Repository instructions
+
+Native sessions load repository-local instructions from the session workdir. In each directory, `AGENTS.override.md` takes precedence over `AGENTS.md`, with `CLAUDE.md` as a fallback. The native adapter's `OpenSessionOpts.instructionDirectories` adds package scopes relative to that workdir; a monorepo session can supply `["apps/api", "packages/client"]` to load each root-to-package chain. `OpenSessionOpts.instructionFileName` selects another Markdown basename, such as `TEAM.md`. A custom name loads only that filename in each directory, with no override or legacy fallback. Names must be nonhidden Markdown basenames without path separators, colon or control characters. More specific directory instructions override ancestor instructions within their scope. Other packages are discovered when authorized file tools enter them.
+
+Local Markdown `@path.md` imports are deduplicated and bounded. Discovery stays inside the active checkout and respects protected paths and denied paths. Each session retains its own instructions outside compactable message history; transcripts record source paths, scopes and hashes. Resume reloads the applicable files from disk using the filename supplied again in the session options. ACP sessions use their CLI's instruction discovery.
+
 ## Conversational sessions
 
 `createAgentSession` gives an embedder (for example a long-running Node service) a multi-turn chat with a person in the loop. Events stream, tools come from the embedder, history lives in a store the embedder supplies, and a turn can be cancelled or answered with an approval.
@@ -79,7 +85,7 @@ Profiles set what a session may do:
 | `ask` | every Write, Edit, Delete, GitCommit and Bash is put to `answer()`; |
 | `full` | no prompts; `bashApproval` and the sandbox floor apply. |
 
-`createAgentSession` takes a `SessionBackend`. `nativeBackend(opts)` takes `model`, `credentials`, `catalogOverrides`, `loopHandlers`, `hostPorts`, `bashApproval` and `allowUnsandboxed`. The ACP backend ships in `@nathapp/nax-agent-acp`.
+`createAgentSession` takes a `SessionBackend`. `nativeBackend(opts)` takes `instructionFileName` (default `AGENTS.md`), `model`, `credentials`, `catalogOverrides`, `loopHandlers`, `hostPorts`, `bashApproval` and `allowUnsandboxed`. The ACP backend ships in `@nathapp/nax-agent-acp`.
 
 `usage.costSource` is `computed` (native), `reported` or `unpriced`; never sum `unpriced` rows as cost.
 

package/dist/index.d.ts

@@ -18,11 +18,12 @@ export { isProcessAlive } from "#src/internal/process-alive";
 export { killProcessGroup } from "#src/internal/process-kill";
 export { capStrings, redactSecrets } from "#src/internal/redact";
 export { NaxError } from "#src/infra/nax-error";
+export { createTerminalAuthInteraction, PLAIN_STYLE, PromptCancelledError, type TerminalAuthOptions, type TerminalStyle, } from "#src/terminal-auth/index";
 export type { CredentialSource } from "#src/native/credentials/session-source";
-export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, MAX_RETAINED_TRANSCRIPTS, type MemoryTranscriptStore, NATIVE_AGENT, type NativeCatalogOverrides, type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, NativeSessionAdapter, NativeSessionUnsupportedError, type NativeTierConfig, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, type ResolveResult, type ResolveStatus, removeStoredProvider, resolveNativeId, runLogin, type StoredEntry, servedAuth, type TranscriptAcpRecord, type TranscriptDoc, type TranscriptStore, type TurnMarker, } from "#src/native/index";
+export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, type MemoryTranscriptStore, NATIVE_AGENT, type NativeCatalogOverrides, type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, NativeSessionAdapter, NativeSessionUnsupportedError, type NativeTierConfig, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, type ResolveResult, type ResolveStatus, removeStoredProvider, resolveNativeId, runLogin, type StoredEntry, servedAuth, type TranscriptAcpRecord, type TranscriptDoc, type TranscriptStore, type TurnMarker, } from "#src/native/index";
 export type { NativeSessionAdapterOptions } from "#src/native/session-adapter";
 export type { AfterResponsePatch, AfterResponsePayload, AfterToolPatch, AfterToolPayload, BeforeCompactionPatch, BeforeCompactionPayload, BeforeRequestPatch, BeforeRequestPayload, BeforeToolOutcome, BeforeToolPayload, BeforeTurnEndPatch, BeforeTurnEndPayload, BeforeTurnPatch, BeforeTurnPayload, CompleteCallOptions, ExternalHandlerOf, LoopEvent, LoopEventMap, LoopHandlerContext, LoopHandlerEntry, LoopHandlerSet, PatchOf, PayloadOf, TransformContextPatch, TransformContextPayload, } from "#src/native/session/loop-events/types";
-export { TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES } from "#src/native/session/turn-event-emitter";
+export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { type ApprovalAuditRow, type ApprovalEntry, type ApprovalsFile, type ApprovalsFileRead, type ApprovalsFileState, type ApprovalsTaint, ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, type AskControl, type AskDecidedBy, type AskDecision, type AskLink, type AskLinkOutcome, type AskRequest, type AskResolver, type AskVerdict, appendApproval, appendApprovalAudit, approvalId, approvalsPath, type BashLexResult, type BashRedirect, type BashSegment, type BashSegmentSeparator, type BashToken, type ClearTaintOutcome, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, type MaskResult, maskForPrompt, type PrepareApprovalsStoreOptions, parseRuleList, parseToolExpression, prepareApprovalsStore, type RemovalDecision, type RemovalResult, type ResolvedPermissions, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, type SecretSpan, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { type AgentGlobOptions, type AgentRuntime, type AgentSpawnOptions, type AgentSpawnResult, type AgentSpawnStdin, getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
 export { buildSandboxPolicy, type CommandLauncher, type CommandLauncherOptions, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, type GitLayout, type LaunchRequest, type LaunchResult, type LaunchSpec, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, type ProbeResult, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, type SandboxBackend, type SandboxBackendName, type SandboxNetworkPolicy, type SandboxPolicy, type SandboxPolicyInput, type SandboxRecord, type SandboxState, type SandboxWrapRequest, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";

package/dist/index.js

@@ -16,8 +16,9 @@ export { isProcessAlive } from "#src/internal/process-alive";
 export { killProcessGroup } from "#src/internal/process-kill";
 export { capStrings, redactSecrets } from "#src/internal/redact";
 export { NaxError } from "#src/infra/nax-error";
-export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
-export { TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES } from "#src/native/session/turn-event-emitter";
+export { createTerminalAuthInteraction, PLAIN_STYLE, PromptCancelledError, } from "#src/terminal-auth/index";
+export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
+export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, appendApproval, appendApprovalAudit, approvalId, approvalsPath, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, maskForPrompt, parseRuleList, parseToolExpression, prepareApprovalsStore, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
 export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";

package/dist/internal/atomic-write.d.ts

@@ -0,0 +1,16 @@
+import { rename, rm } from "node:fs/promises";
+/** The one `writeFile` shape this module uses; narrower than the overloaded node signature so stubs type-check. */
+type WriteText = (path: string, content: string, options: {
+    encoding: "utf8";
+    mode?: number;
+}) => Promise<void>;
+/** Injectable for tests that simulate a write dying part-way. */
+export declare const _atomicWriteDeps: {
+    writeFile: WriteText;
+    rename: typeof rename;
+    rm: typeof rm;
+};
+export declare function writeFileAtomic(path: string, content: string, options?: {
+    mode?: number;
+}): Promise<void>;
+export {};

package/dist/internal/atomic-write.js

@@ -0,0 +1,34 @@
+/**
+ * Whole-file writes that a crash cannot tear.
+ *
+ * `writeFile` truncates the target before the new bytes land, so a process
+ * killed mid-write (SIGKILL, OOM, ENOSPC) leaves a partial file and the old
+ * content is gone. Staging the bytes in a sibling and `rename`-ing it over the
+ * target publishes the new content in one step: a reader, or the next run,
+ * sees the old file or the new one. Same-directory staging keeps the rename on
+ * one filesystem, where POSIX makes it atomic. Not fsync'd: this guards against
+ * a killed PROCESS, not a power loss.
+ */
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+/** Injectable for tests that simulate a write dying part-way. */
+export const _atomicWriteDeps = {
+    writeFile: (path, content, options) => writeFile(path, content, options),
+    rename,
+    rm,
+};
+export async function writeFileAtomic(path, content, options = {}) {
+    // Ends in `.tmp`, not `.json`, so directory sweeps that match `*.json` never see it.
+    const staged = `${path}.${randomUUID()}.tmp`;
+    try {
+        await _atomicWriteDeps.writeFile(staged, content, {
+            encoding: "utf8",
+            ...(options.mode !== undefined ? { mode: options.mode } : {}),
+        });
+        await _atomicWriteDeps.rename(staged, path);
+    }
+    catch (error) {
+        await _atomicWriteDeps.rm(staged, { force: true });
+        throw error;
+    }
+}

package/dist/internal/command-spec/index.js

@@ -22,7 +22,7 @@ export function commandSpecIncludes(spec, fragment) {
 }
 /** Apply a literal replacement to every command entry without changing its shape. */
 export function replaceInCommandSpec(spec, searchValue, replacement) {
-    const replace = (command) => command.replaceAll(searchValue, replacement);
+    const replace = (command) => command.replaceAll(searchValue, () => replacement);
     return typeof spec === "string" ? replace(spec) : spec.map(replace);
 }
 /**

package/dist/internal/git-env.d.ts

@@ -50,9 +50,10 @@ export declare function hardenedGitEnv(base: Readonly<Record<string, string | un
 export declare function gitSpawnEnv(overlay?: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
 export declare const IGNORE_DIRTY_SUBMODULES_FLAG = "--ignore-submodules=dirty";
 /**
- * `argv` (argv[0] is the git program) with `--ignore-submodules=dirty` placed
- * right after a `status` / `diff` subcommand. Unlike the config key, the flag
- * overrides a `submodule.<name>.ignore` from `.gitmodules`. A later explicit
+ * `argv` (argv[0] is the git program, or an interceptor token followed by it)
+ * with `--ignore-submodules=dirty` placed right after a `status` / `diff`
+ * subcommand. Unlike the config key, the flag overrides a
+ * `submodule.<name>.ignore` from `.gitmodules`. A later explicit
  * `--ignore-submodules` in `argv` still wins (git takes the last), which the
  * agent-facing git tool cannot supply: it refuses every `-`-leading element.
  */

package/dist/internal/git-env.js

@@ -73,16 +73,23 @@ const SUBMODULE_DIRTY_CHECK_VERBS = new Set(["status", "diff"]);
 /** Global options that consume the next argument (`-C <dir>`, `-c <k=v>`). */
 const GLOBAL_OPTIONS_WITH_VALUE = new Set(["-C", "-c"]);
 export const IGNORE_DIRTY_SUBMODULES_FLAG = "--ignore-submodules=dirty";
+/** `git` or a path ending in `/git`: the program, as opposed to a wrapper in front of it. */
+function isGitProgram(token) {
+    return token === "git" || (token?.endsWith("/git") ?? false);
+}
 /**
- * `argv` (argv[0] is the git program) with `--ignore-submodules=dirty` placed
- * right after a `status` / `diff` subcommand. Unlike the config key, the flag
- * overrides a `submodule.<name>.ignore` from `.gitmodules`. A later explicit
+ * `argv` (argv[0] is the git program, or an interceptor token followed by it)
+ * with `--ignore-submodules=dirty` placed right after a `status` / `diff`
+ * subcommand. Unlike the config key, the flag overrides a
+ * `submodule.<name>.ignore` from `.gitmodules`. A later explicit
  * `--ignore-submodules` in `argv` still wins (git takes the last), which the
  * agent-facing git tool cannot supply: it refuses every `-`-leading element.
  */
 export function hardenedGitArgv(argv) {
     const out = [...argv];
-    let i = 1;
+    // A command interceptor may add exactly ONE leading token (validateRewrite), so a
+    // rewritten argv is `<provider> git <verb> ...`: the walk starts after the git program.
+    let i = !isGitProgram(out[0]) && isGitProgram(out[1]) ? 2 : 1;
     while (i < out.length && out[i].startsWith("-")) {
         i += GLOBAL_OPTIONS_WITH_VALUE.has(out[i]) ? 2 : 1;
     }

package/dist/internal.d.ts

@@ -30,6 +30,7 @@ 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/atomic-write";
 export * from "#src/internal/command-spec/index";
 export * from "#src/internal/file-lock";
 export * from "#src/internal/git-add";
@@ -57,10 +58,12 @@ export * from "#src/native/errors";
 export * from "#src/native/model-resolver";
 export * from "#src/native/models";
 export * from "#src/native/session/compaction";
+export { DEFAULT_INSTRUCTION_FILE_NAME, isInstructionFileName } from "#src/native/session/instruction-file-name";
 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/memory-transcript-store";
+export { _repositoryInstructionDeps } from "#src/native/session/repository-instructions";
 export * from "#src/native/session/session";
 export * as sessionModule from "#src/native/session/session";
 export * from "#src/native/session/tool-mapping";
@@ -80,11 +83,13 @@ export * from "#src/permissions/index";
 export * from "#src/sandbox/index";
 export * as policyInputsModule from "#src/sandbox/policy-inputs";
 export * from "#src/session/agent-session-deps";
+export * from "#src/terminal-auth/index";
 export * from "#src/tools/credential-read-deny";
 export * from "#src/tools/git";
 export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
+export { _instructionAccessDeps } from "#src/tools/instruction-access";
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";
 export * from "#src/tools/policy";

package/dist/internal.js

@@ -30,6 +30,7 @@ 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/atomic-write";
 export * from "#src/internal/command-spec/index";
 export * from "#src/internal/file-lock";
 export * from "#src/internal/git-add";
@@ -57,10 +58,12 @@ export * from "#src/native/errors";
 export * from "#src/native/model-resolver";
 export * from "#src/native/models";
 export * from "#src/native/session/compaction";
+export { DEFAULT_INSTRUCTION_FILE_NAME, isInstructionFileName } from "#src/native/session/instruction-file-name";
 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/memory-transcript-store";
+export { _repositoryInstructionDeps } from "#src/native/session/repository-instructions";
 export * from "#src/native/session/session";
 export * as sessionModule from "#src/native/session/session";
 export * from "#src/native/session/tool-mapping";
@@ -80,11 +83,13 @@ export * from "#src/permissions/index";
 export * from "#src/sandbox/index";
 export * as policyInputsModule from "#src/sandbox/policy-inputs";
 export * from "#src/session/agent-session-deps";
+export * from "#src/terminal-auth/index";
 export * from "#src/tools/credential-read-deny";
 export * from "#src/tools/git";
 export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
+export { _instructionAccessDeps } from "#src/tools/instruction-access";
 // S3-2: the port (nax supplies the policy behind it from its own module).
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";

package/dist/native/auth.d.ts

@@ -72,6 +72,8 @@ export declare function importPiCredentials(options?: {
     force?: boolean;
 }): Promise<ImportOutcome[]>;
 export declare function listStoredProviders(): Promise<StoredEntry[]>;
+/** The providers `runLogin` can log in to: nax-ai's default catalog (S5-4 M-33). */
+export declare function loginProviderIds(): Promise<string[]>;
 /**
  * Removal, not revocation. pi has no revocation anywhere — its own types
  * define logout as deletion — so the provider-side token stays live until it

package/dist/native/auth.js

@@ -167,11 +167,17 @@ export async function importPiCredentials(options) {
             cause: error,
         });
     }
+    // JSON.parse accepts `null`, arrays and scalars; none of them is a provider map.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new NaxError(`The file at ${path} is not a provider credential map.`, "AUTH_IMPORT_SOURCE_UNREADABLE", {
+            path,
+        });
+    }
     const store = naxCredentialStore();
     const outcomes = [];
     for (const providerId of Object.keys(parsed).sort()) {
         const entry = parsed[providerId];
-        const credential = entry === undefined ? undefined : fromPiEntry(entry);
+        const credential = typeof entry === "object" && entry !== null ? fromPiEntry(entry) : undefined;
         if (credential === undefined) {
             outcomes.push({ providerId, status: "unsupported" });
             continue;
@@ -191,6 +197,10 @@ export async function importPiCredentials(options) {
 export async function listStoredProviders() {
     return readStoredEntries();
 }
+/** The providers `runLogin` can log in to: nax-ai's default catalog (S5-4 M-33). */
+export async function loginProviderIds() {
+    return _authDeps.providerIds();
+}
 /**
  * Removal, not revocation. pi has no revocation anywhere — its own types
  * define logout as deletion — so the provider-side token stays live until it

package/dist/native/index.d.ts

@@ -11,7 +11,7 @@
  * cycle fails it.
  */
 export { _adapterDeps } from "./adapter-deps.ts";
-export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, providersWithoutCredentials, removeStoredProvider, runLogin, } from "./auth.ts";
+export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, loginProviderIds, providersWithoutCredentials, removeStoredProvider, runLogin, } from "./auth.ts";
 export type { AuthEvent, AuthInteraction, AuthLink, AuthMethod, AuthOption, AuthPrompt, AuthResult, } from "./auth-types.ts";
 export type { NativeCatalogOverrides } from "./client.ts";
 export { type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, nativeComplete, } from "./complete.ts";

package/dist/native/index.js

@@ -11,7 +11,7 @@
  * cycle fails it.
  */
 export { _adapterDeps } from "./adapter-deps.js";
-export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, providersWithoutCredentials, removeStoredProvider, runLogin, } from "./auth.js";
+export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, loginProviderIds, providersWithoutCredentials, removeStoredProvider, runLogin, } from "./auth.js";
 export { nativeComplete, } from "./complete.js";
 export { credentialFilePath, naxCredentialStore, servedAuth } from "./credentials/index.js";
 export { NativeSessionUnsupportedError } from "./errors.js";

package/dist/native/session/handle-invalid-tool-call.js

@@ -113,6 +113,7 @@ export function rewriteToolCallInput(messages, callId, input) {
             content: lastAssistant.content,
             toolCalls,
             ...(lastAssistant.thinking !== undefined ? { thinking: lastAssistant.thinking } : {}),
+            ...(lastAssistant.origin !== undefined ? { origin: lastAssistant.origin } : {}),
         },
         ...messages.slice(lastAssistantIndex + 1),
     ];

package/dist/native/session/instruction-file-name.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_INSTRUCTION_FILE_NAME = "AGENTS.md";
+/** A plain, nonhidden Markdown basename, never a path or URI. */
+export declare function isInstructionFileName(value: unknown): value is string;
+export declare function instructionFileNameFor(value: unknown): string;

package/dist/native/session/instruction-file-name.js

@@ -0,0 +1,21 @@
+import { NaxError } from "#src/infra/nax-error";
+export const DEFAULT_INSTRUCTION_FILE_NAME = "AGENTS.md";
+/** A plain, nonhidden Markdown basename, never a path or URI. */
+export function isInstructionFileName(value) {
+    return (typeof value === "string" &&
+        !value.startsWith(".") &&
+        value.slice(0, -3).trim().length > 0 &&
+        /\.md$/i.test(value) &&
+        !/[\\/:]/.test(value) &&
+        ![...value].some((char) => {
+            const code = char.charCodeAt(0);
+            return code <= 31 || (code >= 127 && code <= 159);
+        }));
+}
+export function instructionFileNameFor(value) {
+    if (value === undefined)
+        return DEFAULT_INSTRUCTION_FILE_NAME;
+    if (isInstructionFileName(value))
+        return value;
+    throw new NaxError("instructionFileName must be a nonhidden Markdown basename without path separators, colon or control characters", "INVALID_INSTRUCTION_FILE_NAME", { stage: "native-session" });
+}

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

@@ -0,0 +1,7 @@
+import type { InteractionHandler } from "#src/session/interaction-handler";
+import type { RepositoryInstructions } from "./repository-instructions.ts";
+/** Scope discovery runs in the authorized coding runtime without coupling host handlers to native. */
+export declare function createInstructionInteraction(instructions: RepositoryInstructions | undefined, handler: InteractionHandler): {
+    handler: InteractionHandler;
+    acknowledge: () => void;
+};

package/dist/native/session/instruction-interaction.js

@@ -0,0 +1,22 @@
+import { dirname } from "node:path";
+import { withInstructionAccess } from "#src/tools/instruction-access";
+/** Scope discovery runs in the authorized coding runtime without coupling host handlers to native. */
+export function createInstructionInteraction(instructions, handler) {
+    let acknowledged = instructions?.render() ?? "";
+    return {
+        acknowledge: () => {
+            acknowledged = instructions?.render() ?? "";
+        },
+        handler: {
+            onInteraction: (request) => withInstructionAccess(async (paths, canRead, protectedPaths) => {
+                if (instructions === undefined)
+                    return undefined;
+                for (const path of paths)
+                    await instructions.discover(dirname(path), canRead, protectedPaths);
+                if (instructions.render() === acknowledged)
+                    return undefined;
+                return "Repository instructions were discovered before this mutation. No files were changed. Review the directory-scoped instructions in your updated system context and retry the tool call.";
+            }, () => handler.onInteraction(request)),
+        },
+    };
+}

package/dist/native/session/instruction-render.d.ts

@@ -0,0 +1,6 @@
+import type { InstructionSource } from "./repository-instructions.ts";
+export declare const MIN_INSTRUCTION_NOTICE_BYTES: number;
+/** Keep whole guidance sources: partial instructions could reverse a requirement. */
+export declare function renderRepositoryInstructions(sources: readonly (InstructionSource & {
+    readonly text: string;
+})[], limited: boolean, maxBytes: number): string;

package/dist/native/session/instruction-render.js

@@ -0,0 +1,22 @@
+const BUDGET_NOTICE = "Repository instruction budget reached; some sources were omitted. Read applicable instruction files before further changes.";
+export const MIN_INSTRUCTION_NOTICE_BYTES = Buffer.byteLength(BUDGET_NOTICE, "utf8") + 32;
+/** Keep whole guidance sources: partial instructions could reverse a requirement. */
+export function renderRepositoryInstructions(sources, limited, maxBytes) {
+    const parts = [];
+    let used = 0;
+    let omitted = 0;
+    const contentBudget = Math.max(0, maxBytes - MIN_INSTRUCTION_NOTICE_BYTES);
+    for (const source of sources) {
+        const body = `Repository instructions: ${source.path} (scope: ${source.scope}; sha256: ${source.hash})\nApply these instructions only within their directory scope. On conflicts, instructions from a deeper directory override ancestor instructions.\n${source.text}`;
+        const bytes = Buffer.byteLength(body, "utf8") + 2;
+        if (used + bytes > contentBudget) {
+            omitted++;
+            continue;
+        }
+        parts.push(body);
+        used += bytes;
+    }
+    if (limited || omitted > 0)
+        parts.push(`${BUDGET_NOTICE} (${omitted} loaded sources omitted.)`);
+    return parts.join("\n\n");
+}

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

@@ -0,0 +1,4 @@
+import type { OpenSessionOpts } from "#src/session/session-types";
+import { RepositoryInstructions } from "./repository-instructions.ts";
+import type { TranscriptStore } from "./transcript-types.ts";
+export declare function openRepositoryInstructions(name: string, opts: OpenSessionOpts, store: TranscriptStore): Promise<RepositoryInstructions>;

package/dist/native/session/instruction-session.js

@@ -0,0 +1,31 @@
+import { RepositoryInstructions } from "./repository-instructions.js";
+import { transcriptModelIdentity } from "./transcript-identity.js";
+export async function openRepositoryInstructions(name, opts, store) {
+    const instructions = new RepositoryInstructions(opts.workdir, opts.instructionProtectedPaths, opts.instructionDenyPaths, opts.instructionFileName);
+    for (const directory of [".", ...(opts.instructionDirectories ?? [])])
+        await instructions.discover(directory);
+    if (opts.resume !== true)
+        return instructions;
+    // Open historically performs no history I/O that can fail the session. The
+    // turn loop remains the authoritative load/error boundary; unavailable
+    // provenance simply leaves the explicitly supplied scopes in place.
+    const doc = await Promise.resolve()
+        .then(() => store.load(name))
+        .catch(() => null);
+    if (doc === null || (doc.schemaVersion !== undefined && doc.schemaVersion !== 1) || !Array.isArray(doc.messages))
+        return instructions;
+    const ownerMatches = opts.transcriptOwner === undefined || doc?.owner === opts.transcriptOwner;
+    const modelMatches = opts.carryHistoryAcrossModels === true ||
+        doc?.model === undefined ||
+        doc.model === transcriptModelIdentity(opts.modelDef?.model);
+    if (ownerMatches && modelMatches) {
+        const directories = doc?.instructionDirectories;
+        if (Array.isArray(directories)) {
+            for (const directory of directories.slice(0, 64)) {
+                if (typeof directory === "string")
+                    await instructions.discover(directory);
+            }
+        }
+    }
+    return instructions;
+}

package/dist/native/session/instruction-transcript.d.ts

@@ -0,0 +1,4 @@
+import type { RepositoryInstructions } from "./repository-instructions.ts";
+import type { TranscriptStore } from "./transcript-types.ts";
+/** Preserve instruction provenance alongside history, including compacted snapshots. */
+export declare function instructionTranscriptStore(store: TranscriptStore, instructions: RepositoryInstructions): TranscriptStore;

package/dist/native/session/instruction-transcript.js

@@ -0,0 +1,14 @@
+/** Preserve instruction provenance alongside history, including compacted snapshots. */
+export function instructionTranscriptStore(store, instructions) {
+    return {
+        load: (id) => store.load(id),
+        save: (id, doc) => store.save(id, {
+            ...doc,
+            instructionSources: instructions.sources,
+            instructionDirectories: instructions.directories,
+        }),
+        delete: (id) => store.delete(id),
+        retainFailed: (id) => store.retainFailed(id),
+        markTurn: (id, marker) => store.markTurn(id, marker),
+    };
+}

package/dist/native/session/repository-instructions.d.ts

@@ -0,0 +1,35 @@
+import { realpath } from "node:fs/promises";
+import { readPrefix } from "#src/internal/bounded-io";
+import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
+export declare const _repositoryInstructionDeps: {
+    realpath: typeof realpath;
+    readPrefix: typeof readPrefix;
+};
+export interface InstructionSource {
+    readonly path: string;
+    readonly scope: string;
+    readonly hash: string;
+}
+export declare class RepositoryInstructions {
+    private readonly workdir;
+    private readonly protectedPaths?;
+    private readonly denyPaths?;
+    private readonly loaded;
+    private readonly visited;
+    private readonly scopes;
+    private bytes;
+    private root;
+    private limited;
+    private pending;
+    private renderMaxBytes;
+    private readonly fileNames;
+    constructor(workdir: string, protectedPaths?: ProtectedPathsPolicy | undefined, denyPaths?: readonly string[] | undefined, fileName?: string);
+    get directories(): readonly string[];
+    get sources(): readonly InstructionSource[];
+    /** Bytes conservatively upper-bound token count; host instructions consume the same system reserve. */
+    setContextBudget(contextWindow: number | undefined, hostPrompt: string | undefined): void;
+    render(): string;
+    discover(directory: string, canRead?: (path: string) => boolean, protectedPaths?: ProtectedPathsPolicy | undefined): Promise<void>;
+    private discoverScope;
+    private load;
+}