@nathapp/nax-agent 0.1.0 → 0.2.0

package/dist/session/session-interaction.js

@@ -0,0 +1,164 @@
+/**
+ * The facade's InteractionHandler (spec 5.1, 4.3, 6.1). Routes each loop
+ * request:
+ * - question -> the pending-ask table (null on timeout or cancel, which the
+ *   loop answers with its no-operator text);
+ * - an embedder tool -> its own run, after an approval when it is "always";
+ * - a built-in coding tool -> the session's CodingToolRuntime, with the call
+ *   id in the current-call slot so a policy ask can name it.
+ * A failed tool is reported by throwing: the tool batch turns a handler throw
+ * into an isError result whose content is the thrown message.
+ */
+import { NaxError } from "#src/infra/nax-error";
+import { capStrings, redactSecrets } from "#src/internal/redact";
+import { askDenyReason } from "#src/tools/ask-request";
+import { cutToByteCap } from "#src/tools/truncate";
+import { askPerson } from "./session-ask-link.js";
+/** Byte cap on an embedder approval's default summary. */
+export const EMBEDDER_SUMMARY_BYTES = 1024;
+/**
+ * Redaction scans at most this many bytes of an embedder tool input; the
+ * summary keeps far fewer. Same 16x pattern as `turn-event-emitter.ts`'s
+ * `REDACTION_SCAN_BYTES` so the bound is comparable to a tool-call input.
+ */
+const EMBEDDER_SCAN_BYTES = EMBEDDER_SUMMARY_BYTES * 16;
+/** What the model sees of an embedder tool. The facade's handler runs it; this run is never reached. */
+export function embedderToolDescriptor(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        scope: { pathFields: [] },
+        async run() {
+            return { content: `"${tool.name}" runs through the agent session, not the coding-tool runtime.`, isError: true };
+        },
+    };
+}
+export function defaultSummary(input) {
+    let json;
+    try {
+        // Cap before redactSecrets walks: a multi-MB tool input must not run
+        // every SECRET_VALUE_PATTERNS regex (PEM block up to 64KB per match)
+        // over megabytes. The post-serialize cutToByteCap is the display cap;
+        // this is the scan cap.
+        json = JSON.stringify(redactSecrets(capStrings(input, EMBEDDER_SCAN_BYTES))) ?? "null";
+    }
+    catch {
+        return "[input not serializable]";
+    }
+    return cutToByteCap(json, EMBEDDER_SUMMARY_BYTES);
+}
+function toolError(message, tool) {
+    return new NaxError(message, "AGENT_SESSION_TOOL_ERROR", { stage: "agent-session", tool });
+}
+function summaryFor(tool, input) {
+    if (tool.describe === undefined)
+        return defaultSummary(input);
+    try {
+        // Same bound as defaultSummary: cap first, then redact, then display-cut.
+        // capStrings preserves the string's type at runtime; the cast is the
+        // single point where the generic is recovered for cutToByteCap.
+        const described = redactSecrets(capStrings(String(tool.describe(input)), EMBEDDER_SCAN_BYTES));
+        return cutToByteCap(described, EMBEDDER_SUMMARY_BYTES);
+    }
+    catch {
+        return defaultSummary(input);
+    }
+}
+function runSafely(tool, input, ctx) {
+    return Promise.resolve()
+        .then(() => tool.run(input, ctx))
+        .catch((err) => {
+        const cause = err instanceof Error ? err.message : String(err);
+        return { content: `Tool "${tool.name}" failed: ${cause}`, isError: true };
+    });
+}
+/**
+ * Runs the tool, but answers at once when the turn aborts: the batch awaits
+ * this handler with no abort race of its own, so a run that ignores its signal
+ * would otherwise hang the turn. The abandoned run's late settlement is ignored.
+ */
+async function invoke(tool, input, ctx) {
+    const abandoned = {
+        content: `Tool "${tool.name}" was abandoned: the turn ended.`,
+        isError: true,
+    };
+    if (ctx.signal.aborted)
+        return abandoned;
+    let onAbort = () => { };
+    const aborted = new Promise((resolve) => {
+        onAbort = () => resolve(abandoned);
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([runSafely(tool, input, ctx), aborted]);
+    }
+    finally {
+        ctx.signal.removeEventListener("abort", onAbort);
+    }
+}
+async function runEmbedderTool(deps, tool, request) {
+    const toolCallId = request.toolCallId ?? "";
+    const signal = request.signal ?? deps.turnSignal();
+    const input = request.input ?? {};
+    if (tool.approval === "always") {
+        const ask = {
+            tool: tool.name,
+            summary: summaryFor(tool, input),
+            reason: `"${tool.name}" asks before every run`,
+            callId: toolCallId,
+        };
+        const outcome = await askPerson(deps.asks, ask, signal);
+        if (outcome.decision !== "allow") {
+            const reason = askDenyReason(outcome.decidedBy);
+            return { answer: `Denied: ${reason}`, denied: { reason, breach: false } };
+        }
+    }
+    const result = await invoke(tool, input, { sessionId: deps.sessionId, toolCallId, signal });
+    if (result.isError === true)
+        throw toolError(result.content, tool.name);
+    return { answer: result.content };
+}
+function toolCallContext(request) {
+    return {
+        ...(request.turnId !== undefined ? { turnId: request.turnId } : {}),
+        ...(request.roundTrips !== undefined ? { roundTrips: request.roundTrips } : {}),
+        ...(request.toolCallId !== undefined ? { toolCallId: request.toolCallId } : {}),
+        ...(request.deferModelTruncation !== undefined ? { deferModelTruncation: request.deferModelTruncation } : {}),
+        ...(request.signal !== undefined ? { signal: request.signal } : {}),
+        ...(request.onWaiting !== undefined ? { onWaiting: request.onWaiting } : {}),
+    };
+}
+async function runCodingTool(deps, request) {
+    deps.setCurrentCallId(request.toolCallId);
+    try {
+        const outcome = await deps.runtime.callTool(request.name, request.input ?? {}, toolCallContext(request));
+        if (outcome.kind === "denied") {
+            return { answer: `Denied: ${outcome.reason}`, denied: { reason: outcome.reason, breach: outcome.breach } };
+        }
+        if (outcome.kind === "error")
+            throw toolError(outcome.content, request.name);
+        return { answer: outcome.content };
+    }
+    finally {
+        deps.setCurrentCallId(undefined);
+    }
+}
+async function answerQuestion(deps, text) {
+    const { requestId, expiresAt, settled } = deps.asks.table.issue("question", deps.turnSignal());
+    deps.asks.emit({ type: "question", requestId, text, expiresAt });
+    const settlement = await settled;
+    return settlement.by === "human" && "text" in settlement.reply ? { answer: settlement.reply.text } : null;
+}
+export function createSessionInteractionHandler(deps) {
+    return {
+        async onInteraction(request) {
+            if (request.kind === "question")
+                return answerQuestion(deps, request.text);
+            if (request.kind === "context-tool")
+                throw toolError(`Unknown tool "${request.name}"`, request.name);
+            const tool = deps.embedderTools.get(request.name);
+            return tool !== undefined ? runEmbedderTool(deps, tool, request) : runCodingTool(deps, request);
+        },
+    };
+}

package/dist/session/session-tool-support.d.ts

@@ -0,0 +1,48 @@
+import { type CodingToolSupport } from "#src/coding-tools/coding-tool-support";
+import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import type { AskResolver } from "#src/permissions/index";
+import type { CommandLauncher } from "#src/sandbox/index";
+import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
+import type { CodingToolName, ToolGrant } from "#src/tools/types";
+import type { AgentSessionProfile } from "./agent-session-types.ts";
+/** The pipeline stage the facade's tool calls and asks carry. */
+export declare const SESSION_STAGE = "session";
+export declare function declaredToolsFor(profile: AgentSessionProfile, protectedPaths: ProtectedPathsPolicy): readonly CodingToolName[];
+export declare function grantsFor(declared: readonly CodingToolName[]): readonly ToolGrant[];
+/**
+ * Under "gated", every Bash command is put to the person: an unconditional ask
+ * rule on top of the unconditional grant (ask rules are evaluated after
+ * grants). "raw" and "escalate" add none.
+ */
+export declare function askRulesFor(declared: readonly CodingToolName[], bashApproval: BashApprovalMode): readonly ToolGrant[];
+/**
+ * The embedder default (spec 6.2). A session with its own credentials source
+ * (memory or exec) has no credentials directory on disk; one that falls back
+ * to the configureCredentials slot protects that slot's directory.
+ */
+export declare function defaultProtectedPaths(ownCredentials: boolean): ProtectedPathsPolicy;
+export interface SessionLauncherArgs {
+    readonly profile: AgentSessionProfile;
+    readonly root: string;
+    readonly protectedPaths: ProtectedPathsPolicy;
+    readonly bashApproval: BashApprovalMode;
+    readonly allowUnsandboxed: boolean;
+}
+/** The sandbox floor (spec 6.3): "full" needs a usable sandbox unless gated + allowUnsandboxed. */
+export declare function resolveSessionLauncher(args: SessionLauncherArgs): Promise<CommandLauncher | undefined>;
+export interface SessionToolSupportArgs {
+    readonly profile: AgentSessionProfile;
+    readonly root: string;
+    readonly sessionName: string;
+    readonly protectedPaths: ProtectedPathsPolicy;
+    readonly bashApproval: BashApprovalMode;
+    readonly launcher: CommandLauncher | undefined;
+    readonly askResolver: AskResolver;
+    readonly interceptor: CommandInterceptor | undefined;
+}
+export interface SessionToolSupport {
+    readonly support: CodingToolSupport;
+    readonly grants: readonly ToolGrant[];
+}
+export declare function buildSessionToolSupport(args: SessionToolSupportArgs): SessionToolSupport;

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

@@ -0,0 +1,101 @@
+/**
+ * Profile -> coding tools (spec 4.5, 6.2, 6.3). A profile is a capability
+ * statement; this module turns it into the declared tools and grants that
+ * buildCodingToolSupport takes, picks the embedder default protected-paths
+ * policy, and enforces the sandbox floor for "full".
+ */
+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 { AgentSessionError } from "./agent-session-errors.js";
+/** The pipeline stage the facade's tool calls and asks carry. */
+export const SESSION_STAGE = "session";
+const READ_TOOLS = ["Read", "Glob", "Grep", "Git"];
+const WRITE_TOOLS = ["Write", "Edit", "Delete", "Bash"];
+export function declaredToolsFor(profile, protectedPaths) {
+    if (profile === "none")
+        return [...UNIVERSAL_CODING_TOOLS];
+    if (profile === "read")
+        return [...UNIVERSAL_CODING_TOOLS, ...READ_TOOLS];
+    // GitCommit refuses every path without ignore patterns, so it is offered only with them.
+    const commit = protectedPaths.gitIgnorePatterns.length > 0 ? ["GitCommit"] : [];
+    return [...UNIVERSAL_CODING_TOOLS, ...READ_TOOLS, ...WRITE_TOOLS, ...commit];
+}
+export function grantsFor(declared) {
+    return declared.map((tool) => ({ tool, patterns: ["*"] }));
+}
+/**
+ * Under "gated", every Bash command is put to the person: an unconditional ask
+ * rule on top of the unconditional grant (ask rules are evaluated after
+ * grants). "raw" and "escalate" add none.
+ */
+export function askRulesFor(declared, bashApproval) {
+    return bashApproval === "gated" && declared.includes("Bash") ? [{ tool: "Bash", patterns: ["*"] }] : [];
+}
+/** The configured credentials directory; undefined when configureCredentials was never called. */
+function configuredCredentialDir() {
+    try {
+        return credentialsConfig().configDir();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The embedder default (spec 6.2). A session with its own credentials source
+ * (memory or exec) has no credentials directory on disk; one that falls back
+ * to the configureCredentials slot protects that slot's directory.
+ */
+export function defaultProtectedPaths(ownCredentials) {
+    const base = { gitExcludePathspecs: [], gitIgnorePatterns: [] };
+    const credentialDir = ownCredentials ? undefined : configuredCredentialDir();
+    return credentialDir === undefined ? base : { ...base, credentialDir };
+}
+/** The sandbox floor (spec 6.3): "full" needs a usable sandbox unless gated + allowUnsandboxed. */
+export async function resolveSessionLauncher(args) {
+    if (args.profile !== "full")
+        return undefined;
+    const launcher = await resolveSessionSandbox({
+        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;
+    const reason = launcher.state.kind === "unavailable" ? launcher.state.reason : "the sandbox is disabled";
+    throw new AgentSessionError(`Profile "full" needs a usable sandbox (${reason}). Pass bashApproval "gated" with allowUnsandboxed: true to run without one.`, "AGENT_SESSION_SANDBOX_UNAVAILABLE", { reason });
+}
+export function buildSessionToolSupport(args) {
+    const declared = declaredToolsFor(args.profile, args.protectedPaths);
+    const grants = grantsFor(declared);
+    const askRules = askRulesFor(declared, args.bashApproval);
+    const support = buildCodingToolSupport({
+        root: args.root,
+        commandCwd: args.root,
+        pipelineStage: SESSION_STAGE,
+        sessionName: args.sessionName,
+        declared,
+        grants,
+        bashApproval: args.bashApproval,
+        protectedPaths: args.protectedPaths,
+        ownedPaths: EMPTY_OWNED_PATHS_POLICY,
+        askResolver: args.askResolver,
+        ...(askRules.length > 0 ? { askRules } : {}),
+        ...(args.interceptor !== undefined ? { interceptor: args.interceptor } : {}),
+        ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
+    });
+    // Unreachable while the scratchpad trio is always declared and granted; kept for the type.
+    if (support === undefined) {
+        throw new AgentSessionError("No coding tools resolved for the session", "AGENT_SESSION_INVALID_OPTIONS", {
+            profile: args.profile,
+        });
+    }
+    return { support, grants };
+}

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

@@ -26,8 +26,8 @@ import type { ToolDescriptor } from "./tool-descriptor.ts";
 export interface AuthStamp {
     /** Keyed credential digest (see `fingerprint.ts`). Not comparable across machines. */
     fingerprint: string;
-    /** Where the credential was read from. */
-    source: "file" | "exec";
+    /** Where the credential was read from: the `file` store, an `exec` helper, or an in-process `memory` store. */
+    source: "file" | "exec" | "memory";
     /** Account label the source reported, when it reports one. */
     account?: string;
 }
@@ -143,6 +143,28 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * boundary transcript resumption must respect (nax#1877). ACP ignores it.
      */
     transcriptOwner?: string;
+    /**
+     * Native: where the session's history lives (S3 spec 5.5). Mutually exclusive
+     * with `transcriptDir`, which is shorthand for the file store; exactly one of
+     * the two must be set. nax sets `transcriptDir`. ACP ignores it.
+     */
+    transcriptStore?: import("#src/native/session/transcript-types").TranscriptStore;
+    /**
+     * Native: leave the live transcript in place on close (S3 spec 5.5). By
+     * default a clean close deletes it and a failed close moves it aside; the
+     * facade sets this so the session stays resumable. nax leaves it unset.
+     * Limitation: the file store's prune on a failed close (cap 50, oldest first)
+     * counts every transcript in its directory, live ones included, so a
+     * retained session should not share a file-store directory with sessions
+     * that close failed.
+     */
+    retainOnClose?: boolean;
+    /**
+     * Native: the session's system prompt, sent as the request's top-level
+     * `system` on every round trip (not on the compaction summary). The S3
+     * facade sets it from `instructions`; nax leaves it unset. ACP ignores it.
+     */
+    systemPrompt?: string;
     /**
      * Native: resolved compaction settings. A resolved primitive, never NaxConfig —
      * src/agents/native/ must not read config (check:adapter-no-config-import).
@@ -208,6 +230,13 @@ export interface SendTurnOpts {
      * precisely so tool calls made during the turn can carry it.
      */
     turnId?: string;
+    /**
+     * S3-3: per-turn event sink (deltas, stream_reset, tool calls and results,
+     * per-round usage, compaction). Native honours it; ACP ignores it until S4.
+     * Called synchronously; a throw or rejection is contained by the backend.
+     * nax sets none.
+     */
+    onTurnEvent?: import("./turn-event.ts").TurnEventSink;
 }
 /**
  * A single mid-turn interactive Q&A exchange between the agent and a human

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

@@ -0,0 +1,61 @@
+/**
+ * Per-turn events a backend pushes to `SendTurnOpts.onTurnEvent` (S3 spec
+ * 5.3, 5.4). Backend-neutral: the S3 facade adds `sessionId`, `turnId`, `at`
+ * and `metadata` and turns these into its `SessionEvent`s. nax sets no sink.
+ *
+ * - Deltas are provisional. `after_response` handlers may patch the recorded
+ *   text, so the transcript and `TurnResult.output` are authoritative.
+ * - `stream_reset` voids the deltas of `round` so far: the round's request is
+ *   being re-issued (a retry), and `attempt` is the new attempt's 1-based number.
+ * - `usage` is one per round-trip model call and marks the round's end.
+ * - `stream_reset` voids everything since the failed attempt began, including
+ *   any retry backoff; the deltas after it are the new attempt's.
+ * - `usage` excludes the compaction summary call, so a turn's totals come from
+ *   `TurnResult` (`tokenUsage`, `estimatedCostUsd`), not from summing events.
+ * - `tool_call.input` and `tool_result.preview` are redacted BEST-EFFORT (the
+ *   logger's redactor: secret-named keys, known token shapes, KEY=value text)
+ *   and byte-capped. A secret file's text can still appear; treat previews and
+ *   inputs as sensitive. Text and thinking deltas are not redacted.
+ * - Every `tool_call` is followed by exactly one `tool_result`, also when the
+ *   turn throws. A refusal is a non-error result carrying the refusal text.
+ *   Calls the loop answers without running (spin stop, cancel) and `ask_human`
+ *   emit no tool events; they appear only in the transcript.
+ */
+export type TurnEvent = {
+    readonly type: "text_delta";
+    readonly round: number;
+    readonly text: string;
+} | {
+    readonly type: "thinking_delta";
+    readonly round: number;
+    readonly text: string;
+} | {
+    readonly type: "stream_reset";
+    readonly round: number;
+    readonly attempt: number;
+} | {
+    readonly type: "tool_call";
+    readonly callId: string;
+    readonly name: string;
+    readonly input: unknown;
+} | {
+    readonly type: "tool_result";
+    readonly callId: string;
+    readonly isError: boolean;
+    readonly preview: string;
+} | {
+    readonly type: "usage";
+    readonly round: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Absent when the call reported no cache data -- never coerced to 0. */
+    readonly cacheRead?: number;
+    /** Absent when the call reported no cache data -- never coerced to 0. */
+    readonly cacheWrite?: number;
+    readonly costUsd: number;
+} | {
+    readonly type: "compaction";
+    readonly reason: "proactive" | "overflow";
+};
+/** The per-turn sink. Called synchronously; a throw or a rejected promise is contained by the backend. */
+export type TurnEventSink = (event: TurnEvent) => void;

package/dist/session/turn-event.js

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

package/dist/tools/bash-cwd.d.ts

@@ -8,9 +8,9 @@
  * `<root>/child/secret`), so both screens must track it identically to avoid
  * being fooled by it. This module is the ONE definition of "what does a `cd`
  * segment resolve to, and how do separators fold that into the running set
- * of candidate working directories" -- mirroring `isNaxOwnedWritePath` in
- * `nax-owned-writes.ts`, which is the same one-definition-two-callers shape
- * for a different seam.
+ * of candidate working directories" -- mirroring the `OwnedPathsPolicy` port's
+ * `writeRefusal` (`tools/owned-paths.ts`), which is the same
+ * one-definition-two-callers shape for a different seam.
  *
  * What this module does NOT decide: what happens when a `cd` cannot be
  * modelled (an option-shaped target, an opaque one, one that fails to

package/dist/tools/credential-read-deny.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read-deny for the host's credential directory and trust-store file in the
+ * read tools (S3 spec 6.3). Before S3-2 only the sandbox enforced these, and
+ * only for Bash; Read, Glob and Grep enforced root containment alone, so a
+ * workdir containing the credential directory exposed it.
+ *
+ * Paths are compared in canonical form: `realpathSync.native` for a path that
+ * exists returns the on-disk casing on a case-insensitive filesystem, where
+ * `realOrRaw` (JS `realpathSync`) keeps the caller's casing and would let
+ * `.NAX/credentials.json` past a `.nax` prefix check. A path that does not
+ * exist cannot be read, so its lexical form is enough.
+ */
+import type { ProtectedPathsPolicy } from "./protected-paths.ts";
+/**
+ * A predicate over resolved paths, with the credential roots canonicalised
+ * once: Glob tests every hit, and a native realpath per root per hit is waste.
+ */
+export declare function credentialPathTest(protectedPaths: ProtectedPathsPolicy | undefined): (resolved: string) => boolean;
+/** Why `resolved` may not be read, or undefined when it may. */
+export declare function credentialReadRefusal(protectedPaths: ProtectedPathsPolicy | undefined, resolved: string): string | undefined;
+/** True when searching `dir` would reach the credential directory or the trust store. */
+export declare function containsCredentialPath(protectedPaths: ProtectedPathsPolicy | undefined, dir: string): boolean;

package/dist/tools/credential-read-deny.js

@@ -0,0 +1,56 @@
+/**
+ * Read-deny for the host's credential directory and trust-store file in the
+ * read tools (S3 spec 6.3). Before S3-2 only the sandbox enforced these, and
+ * only for Bash; Read, Glob and Grep enforced root containment alone, so a
+ * workdir containing the credential directory exposed it.
+ *
+ * Paths are compared in canonical form: `realpathSync.native` for a path that
+ * exists returns the on-disk casing on a case-insensitive filesystem, where
+ * `realOrRaw` (JS `realpathSync`) keeps the caller's casing and would let
+ * `.NAX/credentials.json` past a `.nax` prefix check. A path that does not
+ * exist cannot be read, so its lexical form is enough.
+ */
+import { realpathSync } from "node:fs";
+import { sep } from "node:path";
+import { realOrRaw } from "#src/internal/realpath";
+function canonical(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return realOrRaw(p);
+    }
+}
+function isWithin(base, target) {
+    return target === base || target.startsWith(`${base}${sep}`);
+}
+function credentialRoots(protectedPaths) {
+    if (protectedPaths === undefined)
+        return [];
+    return [protectedPaths.credentialDir, protectedPaths.trustStoreFile]
+        .filter((p) => p !== undefined)
+        .map(canonical);
+}
+const CREDENTIAL_REFUSAL = "is a host credential or trust-store path, which the read tools are refused regardless of grant";
+/**
+ * A predicate over resolved paths, with the credential roots canonicalised
+ * once: Glob tests every hit, and a native realpath per root per hit is waste.
+ */
+export function credentialPathTest(protectedPaths) {
+    const roots = credentialRoots(protectedPaths);
+    if (roots.length === 0)
+        return () => false;
+    return (resolved) => {
+        const target = canonical(resolved);
+        return roots.some((base) => isWithin(base, target));
+    };
+}
+/** Why `resolved` may not be read, or undefined when it may. */
+export function credentialReadRefusal(protectedPaths, resolved) {
+    return credentialPathTest(protectedPaths)(resolved) ? CREDENTIAL_REFUSAL : undefined;
+}
+/** True when searching `dir` would reach the credential directory or the trust store. */
+export function containsCredentialPath(protectedPaths, dir) {
+    const base = canonical(dir);
+    return credentialRoots(protectedPaths).some((cred) => isWithin(base, cred));
+}

package/dist/tools/glob.js

@@ -14,8 +14,10 @@
  * `<dir>/ <b1> <b2> ...`, unescaping each quoted basename, and joining each
  * basename to its directory reconstructs the matched set exactly.
  */
-import { sep } from "node:path";
+import { join, sep } from "node:path";
 import { getAgentRuntime } from "#src/runtime/index";
+import { credentialPathTest } from "./credential-read-deny.js";
+import { EMPTY_OWNED_PATHS_POLICY } from "./owned-paths.js";
 import { resolveWithin } from "./policy.js";
 const MAX_MATCHES = 500;
 /**
@@ -127,6 +129,9 @@ export const globTool = {
         if (climbsOut(pattern))
             return { content: "no matches" };
         const matches = [];
+        // S3 spec 6.3: credential roots are canonicalised once; a native realpath
+        // per hit would be waste when a listing covers the credential directory.
+        const isCredential = credentialPathTest(ctx.protectedPaths);
         try {
             // `absolute: false` is the repo-wide idiom (test-scanner.ts:318,
             // fragments/store.ts:53, manifest-purge.ts:64) and yields root-relative
@@ -136,7 +141,9 @@ export const globTool = {
             // a throwing iterator and exercise the catch branch without planting a
             // malformed pattern on disk.
             for await (const hit of _globDeps.scan(pattern, { cwd: ctx.root, absolute: false })) {
-                if (resolveWithin(ctx.root, hit) === null)
+                if (resolveWithin(ctx.root, hit, ctx.ownedPaths ?? EMPTY_OWNED_PATHS_POLICY) === null)
+                    continue;
+                if (isCredential(join(ctx.root, hit)))
                     continue;
                 matches.push(hit.split(sep).join("/"));
                 if (matches.length >= MAX_MATCHES)