@nathapp/nax-agent 0.3.1 → 0.85.0

package/dist/mcp/transport.js

@@ -0,0 +1,41 @@
+/**
+ * The SDK transport for one McpTransportConfig (S5-5 spec §3.1). The only file
+ * besides connect.ts that imports the SDK. stdio: the env is an overlay on the
+ * SDK's default environment (SDK 1.30.0 already merges; passing it explicitly
+ * keeps PATH if a later SDK stops), and stderr is piped with a bounded tail
+ * kept for connect-failure messages, never inherited (stdout may carry ACP
+ * frames). http: streamable HTTP with the configured headers.
+ */
+import { getDefaultEnvironment, StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export const STDERR_TAIL_BYTES = 512;
+function stdioHandle(config) {
+    const transport = new StdioClientTransport({
+        command: config.command,
+        args: [...config.args],
+        env: { ...getDefaultEnvironment(), ...config.env },
+        cwd: config.cwd,
+        stderr: "pipe",
+    });
+    let tail = Buffer.alloc(0);
+    transport.stderr?.on("data", (chunk) => {
+        const joined = Buffer.concat([tail, chunk]);
+        tail = joined.subarray(Math.max(0, joined.length - STDERR_TAIL_BYTES));
+    });
+    return { transport, pid: () => transport.pid, stderrTail: () => tail.toString("utf8") };
+}
+function httpHandle(config) {
+    const transport = new StreamableHTTPClientTransport(new URL(config.url), {
+        requestInit: { headers: { ...config.headers } },
+    });
+    return {
+        transport,
+        pid: () => null,
+        stderrTail: () => "",
+        terminate: () => transport.terminateSession().catch(() => undefined),
+    };
+}
+/** Injectable seam: unit tests return an in-memory transport. */
+export const _mcpTransportDeps = {
+    create: (config) => config.kind === "stdio" ? stdioHandle(config) : httpHandle(config),
+};

package/dist/mcp/types.d.ts

@@ -0,0 +1,48 @@
+/** Vocabulary of the shared MCP connection layer (S5-5 spec §3.1). Free of SDK types. */
+import type { JSONSchema } from "#src/session/tool-descriptor";
+export type McpTransportConfig = {
+    readonly kind: "stdio";
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly cwd: string;
+} | {
+    readonly kind: "http";
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+};
+export interface McpToolInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JSONSchema;
+}
+export interface McpCallResult {
+    readonly text: string;
+    readonly isError: boolean;
+    readonly bytesBeforeCap: number;
+}
+export interface McpCallOptions {
+    readonly signal: AbortSignal;
+    readonly timeoutMs: number;
+    readonly maxBytes: number;
+}
+export interface McpConnection {
+    readonly kind: "stdio" | "http";
+    readonly tools: readonly McpToolInfo[];
+    /** Server-side tool errors are `isError` results; transport failures throw McpCallError. */
+    call(name: string, input: unknown, opts: McpCallOptions): Promise<McpCallResult>;
+    /** stdio only: called once when the process exits without close() having been called. */
+    onClose(listener: (reason: string) => void): void;
+    /** Idempotent. Resolves when the transport, and for stdio the process, is gone. */
+    close(): Promise<void>;
+}
+export interface ConnectMcpOptions {
+    readonly signal: AbortSignal;
+    readonly timeoutMs: number;
+    readonly clientInfo: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** stdio: how long close() waits for the process before SIGKILL. Default 3000. */
+    readonly closeGraceMs?: number;
+}

package/dist/mcp/types.js

@@ -0,0 +1 @@
+export {};

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";
@@ -19,6 +19,7 @@ export { credentialFilePath, naxCredentialStore, type StoredEntry, servedAuth }
 export { NativeSessionUnsupportedError } from "./errors.ts";
 export { type ResolveResult, type ResolveStatus, resolveNativeId, } from "./model-resolver.ts";
 export { NATIVE_AGENT } from "./models.ts";
+export { listProviderModels, type ProviderModel } from "./provider-models.ts";
 export { createMemoryTranscriptStore, type MemoryTranscriptStore } from "./session/memory-transcript-store.ts";
 export { createFileTranscriptStore, MAX_RETAINED_TRANSCRIPTS, pruneRetainedTranscripts, } from "./session/transcript-store.ts";
 export type { TranscriptAcpRecord, TranscriptDoc, TranscriptStore, TurnMarker } from "./session/transcript-types.ts";

package/dist/native/index.js

@@ -11,12 +11,13 @@
  * 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";
 export { resolveNativeId, } from "./model-resolver.js";
 export { NATIVE_AGENT } from "./models.js";
+export { listProviderModels } from "./provider-models.js";
 export { createMemoryTranscriptStore } from "./session/memory-transcript-store.js";
 export { createFileTranscriptStore, MAX_RETAINED_TRANSCRIPTS, pruneRetainedTranscripts, } from "./session/transcript-store.js";
 export { NativeSessionAdapter } from "./session-adapter.js";

package/dist/native/provider-models.d.ts

@@ -0,0 +1,13 @@
+import { type NativeCatalogOverrides } from "./client.ts";
+export interface ProviderModel {
+    /** The model id without its provider prefix; the config string is `<provider>/<id>`. */
+    readonly id: string;
+    readonly contextWindow: number;
+    /** The output ceiling, when the catalog states one. */
+    readonly maxTokens?: number;
+}
+/**
+ * Tool-capable models for `providerId`, sorted by id. An unknown provider gives
+ * an empty list. A catalog that cannot load rejects.
+ */
+export declare function listProviderModels(providerId: string, catalogOverrides?: NativeCatalogOverrides): Promise<readonly ProviderModel[]>;

package/dist/native/provider-models.js

@@ -0,0 +1,22 @@
+/**
+ * The models the catalog offers for one provider, as plain data. The catalog is
+ * nax-ai's; nothing here carries a nax-ai type (see check-nax-ai-imports).
+ */
+import { byCodePoint } from "#src/internal/sort";
+import { getNativeClient } from "./client.js";
+/**
+ * Tool-capable models for `providerId`, sorted by id. An unknown provider gives
+ * an empty list. A catalog that cannot load rejects.
+ */
+export async function listProviderModels(providerId, catalogOverrides = []) {
+    const client = await getNativeClient(catalogOverrides);
+    const models = await client.listModels(providerId);
+    return models
+        .filter((model) => model.supportsTools)
+        .map((model) => ({
+        id: model.id,
+        contextWindow: model.contextWindow,
+        ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+    }))
+        .sort((a, b) => byCodePoint(a.id, b.id));
+}

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;
+}

package/dist/native/session/repository-instructions.js

@@ -0,0 +1,155 @@
+/** Bounded, repository-local instruction discovery. Each instance belongs to one session. */
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { readPrefix } from "#src/internal/bounded-io";
+import { credentialReadRefusal } from "#src/tools/credential-read-deny";
+import { matchesDenyPaths } from "#src/tools/deny-paths";
+import { DEFAULT_INSTRUCTION_FILE_NAME, instructionFileNameFor } from "./instruction-file-name.js";
+import { MIN_INSTRUCTION_NOTICE_BYTES, renderRepositoryInstructions } from "./instruction-render.js";
+export const _repositoryInstructionDeps = { realpath, readPrefix };
+const MAX_FILE_BYTES = 32_768;
+const MAX_TOTAL_BYTES = 131_072;
+const MAX_FILES = 64;
+const MAX_DEPTH = 8;
+function contained(root, path) {
+    const rel = relative(root, path);
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function safeMarkdown(root, path) {
+    const rel = relative(root, path);
+    return (contained(root, path) &&
+        /\.md$/i.test(path) &&
+        !rel.split(sep).some((part) => part.startsWith(".") || /(?:credential|secret|trust[-_]?store)/i.test(part)));
+}
+export class RepositoryInstructions {
+    workdir;
+    protectedPaths;
+    denyPaths;
+    loaded = new Map();
+    visited = new Set();
+    scopes = new Set();
+    bytes = 0;
+    root;
+    limited = false;
+    pending = Promise.resolve();
+    renderMaxBytes = Number.POSITIVE_INFINITY;
+    fileNames;
+    constructor(workdir, protectedPaths, denyPaths, fileName) {
+        this.workdir = workdir;
+        this.protectedPaths = protectedPaths;
+        this.denyPaths = denyPaths;
+        const selected = instructionFileNameFor(fileName);
+        this.fileNames =
+            selected === DEFAULT_INSTRUCTION_FILE_NAME
+                ? ["AGENTS.override.md", DEFAULT_INSTRUCTION_FILE_NAME, "CLAUDE.md"]
+                : [selected];
+    }
+    get directories() {
+        return [...this.scopes];
+    }
+    get sources() {
+        return [...this.loaded.values()].map(({ path, scope, hash }) => ({
+            path,
+            scope,
+            hash,
+        }));
+    }
+    /** Bytes conservatively upper-bound token count; host instructions consume the same system reserve. */
+    setContextBudget(contextWindow, hostPrompt) {
+        const reserve = Math.floor((contextWindow ?? 16_384) / 4);
+        const hostBytes = Buffer.byteLength(hostPrompt ?? "", "utf8") + 2;
+        // The caller owns its host prompt. When that already consumes the reserve,
+        // retain only the explicit omission notice rather than silently losing guides.
+        this.renderMaxBytes = Math.max(MIN_INSTRUCTION_NOTICE_BYTES, reserve - hostBytes);
+    }
+    render() {
+        return renderRepositoryInstructions([...this.loaded.values()], this.limited, this.renderMaxBytes);
+    }
+    discover(directory, canRead = () => true, protectedPaths = this.protectedPaths) {
+        const next = this.pending.then(() => this.discoverScope(directory, canRead, protectedPaths));
+        this.pending = next.catch(() => { });
+        return next;
+    }
+    async discoverScope(directory, canRead, protectedPaths) {
+        this.root ??= await _repositoryInstructionDeps.realpath(this.workdir).catch(() => resolve(this.workdir));
+        const lexical = resolve(this.workdir, directory);
+        if (!contained(resolve(this.workdir), lexical) && !contained(this.root, lexical))
+            return;
+        const target = await _repositoryInstructionDeps.realpath(lexical).catch(() => lexical);
+        if (!contained(this.root, target))
+            return;
+        const rel = relative(this.root, target);
+        if (rel.split(sep).some((part) => part.startsWith(".") && part !== ""))
+            return;
+        const parts = rel === "" ? [] : rel.split(sep);
+        if (parts.length > 32) {
+            this.limited = true;
+            return;
+        }
+        this.scopes.add(rel || ".");
+        let dir = this.root;
+        for (const part of ["", ...parts]) {
+            if (part !== "")
+                dir = resolve(dir, part);
+            for (const name of this.fileNames) {
+                const found = await this.load(resolve(dir, name), relative(this.root, dir) || ".", 0, canRead, protectedPaths);
+                if (found)
+                    break;
+            }
+        }
+    }
+    async load(path, scope, depth, canRead, protectedPaths) {
+        if (this.root === undefined)
+            return false;
+        if (depth > MAX_DEPTH || this.visited.size >= MAX_FILES || this.bytes >= MAX_TOTAL_BYTES) {
+            this.limited = true;
+            return false;
+        }
+        if (!safeMarkdown(this.root, path) ||
+            credentialReadRefusal(protectedPaths, path) !== undefined ||
+            credentialReadRefusal(this.protectedPaths, path) !== undefined ||
+            !canRead(path) ||
+            matchesDenyPaths(relative(this.root, path).split(sep).join("/"), this.denyPaths))
+            return false;
+        const canonical = await _repositoryInstructionDeps.realpath(path).catch(() => undefined);
+        if (canonical === undefined ||
+            !safeMarkdown(this.root, canonical) ||
+            credentialReadRefusal(protectedPaths, canonical) !== undefined ||
+            credentialReadRefusal(this.protectedPaths, canonical) !== undefined ||
+            !canRead(canonical) ||
+            matchesDenyPaths(relative(this.root, canonical).split(sep).join("/"), this.denyPaths))
+            return false;
+        if (this.visited.has(canonical))
+            return true;
+        this.visited.add(canonical);
+        const text = await _repositoryInstructionDeps
+            .readPrefix(canonical, Math.min(MAX_FILE_BYTES, MAX_TOTAL_BYTES - this.bytes))
+            .catch(() => undefined);
+        if (text === undefined)
+            return false;
+        const bytes = Buffer.byteLength(text, "utf8");
+        if (bytes > MAX_FILE_BYTES || this.bytes + bytes > MAX_TOTAL_BYTES) {
+            this.limited = true;
+            return true;
+        }
+        this.bytes += bytes;
+        if (text.trim() === "")
+            return true;
+        const hash = createHash("sha256").update(text).digest("hex");
+        this.loaded.set(canonical, {
+            path: relative(this.root, canonical),
+            scope,
+            hash,
+            text,
+        });
+        // Claude-style @path imports: local markdown only, never URLs or home paths.
+        for (const match of text.matchAll(/(?:^|\s)@([^\s`<>]+\.md)(?=\s|$)/gm)) {
+            const imported = match[1];
+            if (imported === undefined || isAbsolute(imported) || imported.startsWith("~") || imported.includes(":"))
+                continue;
+            await this.load(resolve(dirname(canonical), imported), scope, depth + 1, canRead, protectedPaths);
+        }
+        return true;
+    }
+}

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

@@ -10,6 +10,7 @@ import { type SpinBreaker } from "#src/infra/spin-breaker/index";
 import type { AgentStreamEvent } from "#src/session/agent-stream-events";
 import type { OpenSessionOpts, SessionHandle } from "#src/session/session-types";
 import type { ResolvedCompaction } from "./compaction.ts";
+import type { RepositoryInstructions } from "./repository-instructions.ts";
 import type { TranscriptStore } from "./transcript-types.ts";
 import type { TurnRetryConfig } from "./turn-retry.ts";
 /** The runtime hooks handed to openSession. */
@@ -96,6 +97,12 @@ export interface NativeSessionState {
      * maps above: set on open, cleared on close.
      */
     readonly transcriptOwners: Map<string, string>;
+    /**
+     * Sessions that keep history written by another model (S5-3), set at open from
+     * `OpenSessionOpts.carryHistoryAcrossModels`. Same lifecycle as the maps above:
+     * set on open, cleared on close.
+     */
+    readonly carryHistoryAcrossModels: Set<string>;
     /** Session name -> resolved compaction settings. Same lifecycle as the maps above. */
     readonly compaction: Map<string, ResolvedCompaction>;
     /**
@@ -130,6 +137,7 @@ export interface NativeSessionState {
      * lifecycle as the maps above: set on open, cleared on close.
      */
     readonly systemPrompts: Map<string, string>;
+    readonly repositoryInstructions: Map<string, RepositoryInstructions>;
 }
 export declare function createNativeSessionState(): NativeSessionState;
 export interface SessionAnchor {