@nathapp/nax-agent 0.91.7-canary.8 → 0.91.7

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.91.7] - 2026-11-01
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.91.7-canary.12] - 2026-11-01
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.91.7-canary.11] - 2026-10-31
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.91.7-canary.10] - 2026-10-30
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.91.7-canary.9] - 2026-10-30
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
 ## [0.91.7-canary.8] - 2026-10-29
 
 - No changes in this package. Released in lockstep with the other nax packages.

package/dist/config/catalog-overrides.d.ts

@@ -82,6 +82,8 @@ export interface CatalogModelOverride {
      * than the newer model's real one (nax-ai 0.1.11, nax#1982).
      */
     maxTokens?: number;
+    /** Accepted input modalities; omit to inherit known catalog metadata. */
+    input?: ("text" | "image")[];
     supportsTools: boolean;
     thinkingLevels: ThinkingLevel[];
     pricing: CatalogPricing;

package/dist/cost/standard-types.d.ts

@@ -6,4 +6,4 @@
  * keeps a single allow-listed file. In S1-5 this becomes a re-export in
  * packages/nax-agent and the allow-list entry is removed.
  */
-export type { Pricing, PricingRates, PricingTier, TokenUsage } from "@nathapp/nax-ai";
+export type { ImageAttachment, Pricing, PricingRates, PricingTier, TokenUsage } from "@nathapp/nax-ai";

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export type { CommandInterceptor, InterceptRequest, InterceptResult, ShellInterc
 export { appendCommandSafetyRow, type BuildCommandShadowOptions, buildCommandShadow, buildRequest, type Classify, COMMAND_SAFETY_DIR, type CommandGuard, type CommandSafetyRow, type CommandShadow, type CommandShadowOptions, createCommandGuard, createCommandShadow, createSystemOneClient, detectTmpWrite, type ExecRun, type FinalOutcome, type GuardDecision, type GuardInput, HARM_OPTIONS, HARM_QUESTION_ID, type HarmOption, isTempOnly, type LedgerOutcome, type MechanicalVerdict, type ModelAnswers, type ModelResult, type Observation, openShadowTap, parseAnswer, QUESTION_IDS, QUESTION_SET_VERSION, type QuestionId, RULE_SET_VERSION, type RuleContext, type RuleResult, type ShadowCall, type ShadowTap, SYSTEMONE_MODEL_LABEL, type SystemOneClientOptions, type SystemOneQuestion, type SystemOneRequest, scoreGuard, scoreRules, shadowCacheKey, toMechanical, } from "#src/command-safety/index";
 export { addTokenUsage, estimateCostUsd, inputClassTokens, type Pricing, type PricingRates, type PricingTier, priceCall, type TokenUsage, } from "#src/cost/core/index";
 export { type ModelSpec, parseModelSpec, } from "#src/cost/model-spec";
+export type { ImageAttachment } from "#src/cost/standard-types";
 export type { AgentLogger, CredentialAuthConfig, CredentialsConfig } from "#src/infra/index";
 export { configureCredentials, getLogger, setAgentLogger } from "#src/infra/index";
 export { createStderrTail, type StderrTail } from "#src/infra/stderr-tail";
@@ -31,8 +32,9 @@ export { createSessionStorage, defaultSessionsDir, processAlive, LIST_PAGE_SIZE,
 export type { AdapterFailure } from "#src/session/adapter-failure";
 export { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError, type AgentSessionErrorCode } from "#src/session/agent-session-errors";
-export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CostSource, CommandRunResult, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
+export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CostSource, CommandRunResult, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionConfigureInput, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
 export type { AgentAwaitingHumanEvent, AgentCallEndedEvent, AgentCallStartedEvent, AgentMessageUpdateEvent, AgentProcessUpdateEvent, AgentStreamEvent, AgentStreamEventBase, AgentThinkingUpdateEvent, AgentToolCallUpdateEvent, AgentUsageUpdateEvent, } from "#src/session/agent-stream-events";
+export { IMAGE_MIME_TYPES, IMAGE_TOKEN_ESTIMATE, MAX_IMAGE_BASE64_CHARS, MAX_IMAGES_PER_MESSAGE, MAX_REQUEST_IMAGE_BASE64_CHARS, MAX_REQUEST_IMAGES, type SendInput, validateImageAttachments, } from "#src/session/image-input";
 export { type AdapterInteraction, type AdapterInteractionResponse, type InteractionHandler, NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
 export { nativeBackend } from "#src/session/native-backend";
 export type { NativeBackendOptions } from "#src/session/native-backend-options";

package/dist/index.js

@@ -25,6 +25,7 @@ export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_S
 export { createSessionStorage, defaultSessionsDir, processAlive, LIST_PAGE_SIZE, LOCK_HEARTBEAT_MS, LOCK_STALE_MS, SESSION_ID_PATTERN, SESSION_META_MODES, } from "#src/session-store/index";
 export { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError } from "#src/session/agent-session-errors";
+export { IMAGE_MIME_TYPES, IMAGE_TOKEN_ESTIMATE, MAX_IMAGE_BASE64_CHARS, MAX_IMAGES_PER_MESSAGE, MAX_REQUEST_IMAGE_BASE64_CHARS, MAX_REQUEST_IMAGES, validateImageAttachments, } from "#src/session/image-input";
 export { NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
 export { nativeBackend } from "#src/session/native-backend";
 export { SessionTurnError, } from "#src/session/session-types";

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

@@ -1,6 +1,6 @@
 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: {
+type WriteText = (path: string, content: string | Uint8Array, options: {
     encoding: "utf8";
     mode?: number;
 }) => Promise<void>;
@@ -10,7 +10,7 @@ export declare const _atomicWriteDeps: {
     rename: typeof rename;
     rm: typeof rm;
 };
-export declare function writeFileAtomic(path: string, content: string, options?: {
+export declare function writeFileAtomic(path: string, content: string | Uint8Array, options?: {
     mode?: number;
 }): Promise<void>;
 export {};

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

@@ -50,7 +50,7 @@ export declare function getGitRoot(workdir: string): Promise<string | null>;
 export declare function gitWithTimeout(args: string[], workdir: string, timeoutMs?: number, maxBytes?: number, 
 /** Full argv INCLUDING argv[0]. Callers that must control argv[0] pass this;
  *  everyone else gets ["git", ...args] as before. */
-argvOverride?: readonly string[]): Promise<{
+argvOverride?: readonly string[], envOverlay?: Readonly<Record<string, string>>): Promise<{
     stdout: string;
     stderr: string;
     exitCode: number;

package/dist/internal/git-exec.js

@@ -71,10 +71,10 @@ export async function getGitRoot(workdir) {
 export async function gitWithTimeout(args, workdir, timeoutMs = _gitDeps.gitTimeoutMs, maxBytes, 
 /** Full argv INCLUDING argv[0]. Callers that must control argv[0] pass this;
  *  everyone else gets ["git", ...args] as before. */
-argvOverride) {
+argvOverride, envOverlay) {
     const proc = _gitDeps.spawn(hardenedGitArgv(argvOverride ?? ["git", ...args]), {
         cwd: workdir,
-        env: hardenedGitEnv(process.env),
+        env: hardenedGitEnv(envOverlay === undefined ? process.env : { ...process.env, ...envOverlay }),
         stdout: "pipe",
         stderr: "pipe",
     });

package/dist/internal.d.ts

@@ -105,3 +105,4 @@ export * from "#src/tools/run-command-exec";
 export * from "#src/tools/runtime";
 export * from "#src/tools/tool-audit";
 export * as truncateModule from "#src/tools/truncate";
+export { _transcriptImagesDeps } from "./native/session/transcript-images.ts";

package/dist/internal.js

@@ -106,3 +106,4 @@ export * from "#src/tools/run-command-exec";
 export * from "#src/tools/runtime";
 export * from "#src/tools/tool-audit";
 export * as truncateModule from "#src/tools/truncate";
+export { _transcriptImagesDeps } from "./native/session/transcript-images.js";

package/dist/native/models.js

@@ -118,6 +118,7 @@ export function toProviderOverrides(overrides) {
             // Omitted when the override declares none: nax-ai then falls back to the
             // template sibling's ceiling, which is the only honest value available.
             ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+            ...(model.input !== undefined ? { input: model.input } : {}),
             ...(model.thinkingFormat !== undefined ? { thinkingFormat: model.thinkingFormat } : {}),
             supportsTools: model.supportsTools,
             thinkingLevels: model.thinkingLevels,

package/dist/native/session/compaction.js

@@ -7,6 +7,7 @@
  *
  * See docs/superpowers/specs/2026-09-04-native-context-compaction-design.md.
  */
+import { IMAGE_TOKEN_ESTIMATE } from "#src/session/image-input";
 /** A reply needs room whatever the window is. */
 const MIN_HEADROOM_TOKENS = 4096;
 /** ...but never take a quarter of a small window for headroom. */
@@ -18,9 +19,16 @@ const CHARS_PER_TOKEN = 4;
  */
 export function estimateTokens(message) {
     let chars = 0;
+    let imageTokens = 0;
     switch (message.role) {
         case "user":
             chars = message.content.length;
+            for (const image of message.images ?? []) {
+                imageTokens +=
+                    image.width !== undefined && image.height !== undefined
+                        ? Math.min(IMAGE_TOKEN_ESTIMATE, Math.ceil((image.width * image.height) / 750))
+                        : IMAGE_TOKEN_ESTIMATE;
+            }
             break;
         case "assistant":
             chars = message.content.length;
@@ -33,7 +41,7 @@ export function estimateTokens(message) {
             chars = message.content.length;
             break;
     }
-    return Math.ceil(chars / CHARS_PER_TOKEN);
+    return Math.ceil(chars / CHARS_PER_TOKEN) + imageTokens;
 }
 /**
  * Anchor on truth, guess only the tail.

package/dist/native/session/image-context.d.ts

@@ -0,0 +1,5 @@
+import type { TranscriptMessage } from "./compaction.ts";
+/** Text-only summary input view; never rewrite the image-bearing transcript. */
+export declare function imagesAsNotes(messages: readonly TranscriptMessage[]): readonly TranscriptMessage[];
+/** Bound only the wire copy, preserving transcript data and dormant array identity. */
+export declare function capRequestImages(messages: readonly TranscriptMessage[]): readonly TranscriptMessage[];

package/dist/native/session/image-context.js

@@ -0,0 +1,46 @@
+import { MAX_REQUEST_IMAGE_BASE64_CHARS, MAX_REQUEST_IMAGES } from "#src/session/image-input";
+/** Text-only summary input view; never rewrite the image-bearing transcript. */
+export function imagesAsNotes(messages) {
+    return messages.map((message) => {
+        if (message.role !== "user" || message.images === undefined)
+            return message;
+        const { images, ...textMessage } = message;
+        const notes = images.map((image) => {
+            const dimensions = image.width !== undefined && image.height !== undefined ? ` ${image.width}x${image.height}` : "";
+            return `[image: ${image.mimeType}${dimensions}]`;
+        });
+        const content = [...(message.content === "" ? [] : [message.content]), ...notes].join("\n");
+        return { ...textMessage, content };
+    });
+}
+/** Bound only the wire copy, preserving transcript data and dormant array identity. */
+export function capRequestImages(messages) {
+    let count = 0;
+    let chars = 0;
+    let bounded;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role !== "user" || !message.images?.length)
+            continue;
+        const kept = new Set();
+        for (let i = message.images.length - 1; i >= 0; i -= 1) {
+            const image = message.images[i];
+            if (image && count < MAX_REQUEST_IMAGES && chars + image.data.length <= MAX_REQUEST_IMAGE_BASE64_CHARS) {
+                kept.add(i);
+                count += 1;
+                chars += image.data.length;
+            }
+        }
+        if (kept.size === message.images.length)
+            continue;
+        bounded ??= [...messages];
+        const images = message.images.filter((_, i) => kept.has(i));
+        const notes = message.images
+            .filter((_, i) => !kept.has(i))
+            .map((image) => `[image from an earlier turn dropped from context: ${image.mimeType}]`);
+        const { images: _images, ...textMessage } = message;
+        const content = [...(message.content === "" ? [] : [message.content]), ...notes].join("\n");
+        bounded[index] = { ...textMessage, content, ...(images.length ? { images } : {}) };
+    }
+    return bounded ?? messages;
+}

package/dist/native/session/loop-events/external-handler.d.ts

@@ -19,20 +19,41 @@ import type { HandlerOf, LoopEvent, LoopHandlerContext, LoopHandlerEntry } from
 /**
  * How long a plugin handler may run before the wrapper answers for it. A
  * constant by ruling, not a `NaxConfig` key: it bounds the turn's liveness, it
- * is not a policy a project tunes per package.
+ * is not a policy a project tunes per package. An entry with its own
+ * `timeoutMs` replaces it for that handler alone (US-001 — see `deadlineFor`).
  */
 export declare const LOOP_HANDLER_TIMEOUT_MS = 10000;
 /**
- * Test seam for the deadline only. Read at DISPATCH time, never captured when
- * the handler is wrapped — a wrapped handler is installed once and dispatched
- * many times.
+ * The handle the deadline timer is armed with. Bun's `Timer` and a virtual
+ * clock's numeric id are the same thing at runtime, and the test seam below
+ * carries either.
  */
-export declare const _externalHandlerDeps: {
+type TimerHandle = number | ReturnType<typeof setTimeout>;
+interface ExternalHandlerDeps {
+    /**
+     * Test seam for the deadline only. Read at DISPATCH time, never captured
+     * when the handler is wrapped — a wrapped handler is installed once and
+     * dispatched many times.
+     */
     timeoutMs: number;
-};
+    /**
+     * The timer pair the deadline is armed on. Injected rather than called on the
+     * globals so a test can drive the deadline on `makeFakeClock()` instead of
+     * sleeping for it (`docs/guides/testing-rules.md` §3 forbids a fixed sleep,
+     * and "wait a real 100 ms and hope the 10 ms default lost the race" is the
+     * flake it forbids).
+     *
+     * The defaults READ the globals at call time instead of capturing them, so a
+     * `withTimerSpy` substitution still observes the timer the wrapper arms.
+     */
+    setTimeout(handler: () => void, delayMs: number): TimerHandle;
+    clearTimeout(handle: TimerHandle | undefined): void;
+}
+export declare const _externalHandlerDeps: ExternalHandlerDeps;
 /**
  * Wrap one staged plugin registration into a built-in-shaped `HandlerOf<E>`:
  * same payload, same patch, but with a bounded lifetime, the turn's context,
  * and a failure that is attributed and never rethrown.
  */
 export declare function wrapExternalHandler<E extends LoopEvent>(entry: LoopHandlerEntry, getCtx: () => LoopHandlerContext, signal: AbortSignal): HandlerOf<E>;
+export {};

package/dist/native/session/loop-events/external-handler.js

@@ -21,17 +21,33 @@ import { isCompleteBeforeToolOutcome } from "./registry.js";
 /**
  * How long a plugin handler may run before the wrapper answers for it. A
  * constant by ruling, not a `NaxConfig` key: it bounds the turn's liveness, it
- * is not a policy a project tunes per package.
+ * is not a policy a project tunes per package. An entry with its own
+ * `timeoutMs` replaces it for that handler alone (US-001 — see `deadlineFor`).
  */
 export const LOOP_HANDLER_TIMEOUT_MS = 10_000;
-/**
- * Test seam for the deadline only. Read at DISPATCH time, never captured when
- * the handler is wrapped — a wrapped handler is installed once and dispatched
- * many times.
- */
 export const _externalHandlerDeps = {
     timeoutMs: LOOP_HANDLER_TIMEOUT_MS,
+    setTimeout: (handler, delayMs) => globalThis.setTimeout(handler, delayMs),
+    clearTimeout: (handle) => {
+        if (handle !== undefined)
+            globalThis.clearTimeout(handle);
+    },
 };
+/**
+ * The deadline THIS dispatch is bounded by (US-001): the entry's own when it is
+ * a finite positive number, the module default otherwise.
+ *
+ * `0` and `Infinity` are not deadlines — one would answer before the handler
+ * was ever called, the other would disable the bound — so they fall back to the
+ * default rather than being trusted as an override. `NaN` is not finite and
+ * falls back the same way.
+ */
+function deadlineFor(entry) {
+    const override = entry.timeoutMs;
+    if (override === undefined || !Number.isFinite(override) || override <= 0)
+        return _externalHandlerDeps.timeoutMs;
+    return override;
+}
 /**
  * The patch fields whose presence is worth tracing: the ones a later
  * `applyHistoryPatch` can reject, so a rejection is attributable to a plugin.
@@ -53,10 +69,14 @@ const TRACED_PATCH_FIELDS = ["seed", "history", "messages", "summary"];
  *
  * `setTimeout` and not `Bun.sleep()`: the handle has to be cancelled mid-flight
  * (`clearTimeout`), which is the sanctioned exception to the Bun-native delay
- * rule.
+ * rule. Both go through `_externalHandlerDeps`, whose defaults forward to the
+ * globals at call time (see its doc).
+ *
+ * `timeoutMs` is the entry's own deadline when it has one — `deadlineFor` — so
+ * a long-running hook widens only its own bound.
  */
 function raceSettlement(entry, payload, deps) {
-    const timeoutMs = _externalHandlerDeps.timeoutMs;
+    const timeoutMs = deadlineFor(entry);
     return new Promise((resolve) => {
         let settled = false;
         let timer;
@@ -65,12 +85,12 @@ function raceSettlement(entry, payload, deps) {
                 return;
             settled = true;
             if (timer !== undefined)
-                clearTimeout(timer);
+                _externalHandlerDeps.clearTimeout(timer);
             deps.signal.removeEventListener("abort", onAbort);
             resolve(result);
         };
         const onAbort = () => finish({ ok: false, reason: "aborted before it settled" });
-        timer = setTimeout(() => finish({ ok: false, reason: `did not settle within ${timeoutMs}ms` }), timeoutMs);
+        timer = _externalHandlerDeps.setTimeout(() => finish({ ok: false, reason: `did not settle within ${timeoutMs}ms` }), timeoutMs);
         deps.signal.addEventListener("abort", onAbort, { once: true });
         // The context is read here, at dispatch, so a handler always sees the facts
         // of the turn it is running in. Read in its OWN try: a `getCtx` throw is

package/dist/native/session/loop-events/registry.js

@@ -58,7 +58,7 @@ const PATCHABLE_FIELDS = {
     // A decision, not a field patch — chained in dispatchBeforeTool below.
     before_tool: [],
     after_tool: ["content", "isError"],
-    before_turn: ["seed", "history"],
+    before_turn: ["seed", "history", "block", "promptContext"],
     transform_context: ["messages"],
     before_request: ["options"],
     after_response: ["text", "toolCalls", "thinking"],

package/dist/native/session/loop-events/types.d.ts

@@ -99,6 +99,30 @@ export interface BeforeTurnPatch {
     readonly seed?: readonly NativeTranscriptMessage[];
     /** Honoured ONLY when payload.boundary is true (spec 3.2, 6.1). */
     readonly history?: readonly NativeTranscriptMessage[];
+    /**
+     * Refuse the turn (US-001). `runNativeTurn` throws `NATIVE_TURN_BLOCKED`
+     * carrying `reason` as its message BEFORE it appends anything to the
+     * transcript or makes a provider request, so a hook can stop a prompt
+     * reaching the model without seeing it first. `block` wins over every other
+     * field in the same patch.
+     *
+     * `reason` is typed, but a plugin's `loop-handlers` are raw JavaScript: when
+     * `reason` is missing, not a string, or blank, the turn is STILL refused and
+     * the message falls back to a text naming the reason as absent, so the
+     * refusal is never a bare `NATIVE_TURN_BLOCKED:` line.
+     */
+    readonly block?: {
+        readonly reason: string;
+    };
+    /**
+     * Context to PREFIX to the first message the turn seeds (US-001).
+     *
+     * `seed` cannot carry it: that patch REPLACES the prompt message, and the
+     * prompt's images go with it. A prefix leaves the caller's message — text,
+     * images and all — exactly as it was, with the context above it. An empty
+     * string is no context, so the message is untouched.
+     */
+    readonly promptContext?: string;
 }
 /** `transform_context` — fires before every provider request attempt. */
 export interface TransformContextPayload {
@@ -248,6 +272,15 @@ export interface LoopHandlerEntry {
     readonly plugin: string;
     readonly event: LoopEvent;
     readonly handler: ExternalHandlerOf<LoopEvent>;
+    /**
+     * How long THIS handler may run before `wrapExternalHandler` answers for it,
+     * replacing `LOOP_HANDLER_TIMEOUT_MS` (US-001). A formatter or type check
+     * after an edit routinely needs longer than the 10 s default; a handler that
+     * does not set it keeps that default, so widening one hook never widens the
+     * rest. Only a FINITE POSITIVE number is a deadline — `0` and `Infinity` are
+     * not, and fall back to the default rather than disabling the bound.
+     */
+    readonly timeoutMs?: number;
 }
 /**
  * Every plugin-contributed handler for a run, in install order. The registry

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

@@ -0,0 +1,20 @@
+import { type FileHandle, link, lstat, mkdir, open, realpath, rm } from "node:fs/promises";
+import { writeFileAtomic } from "#src/internal/atomic-write";
+import type { TranscriptDoc } from "./transcript-types.ts";
+/** Filesystem operations separate from the atomic writer's write/rename seam. */
+export declare const _transcriptImagesDeps: {
+    link: typeof link;
+    mkdir: typeof mkdir;
+    open: typeof open;
+    realpath: typeof realpath;
+    lstat: typeof lstat;
+    readFile: (path: string | FileHandle) => Promise<NonSharedBuffer>;
+    rm: typeof rm;
+    stat: (path: string) => Promise<import("node:fs").Stats>;
+    writeFileAtomic: typeof writeFileAtomic;
+};
+export declare function transcriptImagesPath(path: string): string;
+/** Preflight the WHOLE document before even creating the image directory. */
+export declare function splitTranscriptImages(path: string, doc: TranscriptDoc): Promise<unknown>;
+/** Decode the private disk format; callers only ever see inline attachments. */
+export declare function rehydrateTranscriptImages(path: string, value: object): Promise<TranscriptDoc>;