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

package/dist/session/agent-session.js

@@ -4,6 +4,7 @@ import { AgentSessionError } from "./agent-session-errors.js";
 import { resolveAgentSessionOptions } from "./agent-session-options.js";
 import { checkBackendKind, interruptedTurnOf, loadResumable, resumeInput } from "./agent-session-resume.js";
 import { claimTurn } from "./agent-session-turn.js";
+import { validateImageAttachments } from "./image-input.js";
 import { createPendingAskTable } from "./pending-asks.js";
 import { createSessionAskPort } from "./session-ask-port.js";
 /** The handler's turn signal between turns: never aborts. */
@@ -24,6 +25,8 @@ class FacadeAgentSession {
     active;
     last;
     closing;
+    /** True while the backend's configure is pending: send, runCommand and configure refuse BUSY. */
+    configuring = false;
     constructor(parts, last) {
         this.parts = parts;
         this.last = last;
@@ -44,7 +47,13 @@ class FacadeAgentSession {
     get lastTurn() {
         return this.last;
     }
-    send(message) {
+    async acceptsImages() {
+        if (this.closing !== undefined) {
+            throw new AgentSessionError(`Session "${this.id}" is closed`, "AGENT_SESSION_CLOSED", { sessionId: this.id });
+        }
+        return this.parts.opened.acceptsImages?.() ?? false;
+    }
+    send(message, input) {
         if (this.closing !== undefined) {
             throw new AgentSessionError(`Session "${this.id}" is closed`, "AGENT_SESSION_CLOSED", { sessionId: this.id });
         }
@@ -53,7 +62,24 @@ class FacadeAgentSession {
                 sessionId: this.id,
             });
         }
+        if (this.configuring) {
+            throw new AgentSessionError(`Session "${this.id}" is being configured`, "AGENT_SESSION_BUSY", {
+                sessionId: this.id,
+            });
+        }
+        const images = input?.images;
+        const reason = images === undefined ? undefined : validateImageAttachments(images);
+        if (reason !== undefined) {
+            throw new AgentSessionError(reason, "AGENT_SESSION_INVALID_INPUT", { sessionId: this.id });
+        }
+        if (images?.length && this.parts.opened.acceptsImages === undefined) {
+            throw new AgentSessionError(`Session "${this.id}" cannot receive images`, "AGENT_SESSION_CAPABILITY_UNSUPPORTED", {
+                sessionId: this.id,
+                capability: "images",
+            });
+        }
         const turn = claimTurn(this.parts.ctx, message, {
+            images,
             onStart: (live) => {
                 this.parts.slot.turn = live;
             },
@@ -67,10 +93,40 @@ class FacadeAgentSession {
         this.active = turn;
         return turn.iterable;
     }
+    async configure(input) {
+        const refusal = this.configureRefusal(input);
+        if (refusal !== undefined)
+            throw refusal;
+        const configure = this.parts.opened.configure;
+        if (configure === undefined)
+            throw this.refusal("AGENT_SESSION_CAPABILITY_UNSUPPORTED", { capability: "configure" });
+        this.configuring = true;
+        try {
+            await configure.call(this.parts.opened, input);
+        }
+        finally {
+            this.configuring = false;
+        }
+    }
+    /** The refusals that precede the backend call, in the documented order; the backend check is last and separate. */
+    configureRefusal(input) {
+        if (this.closing !== undefined)
+            return this.refusal("AGENT_SESSION_CLOSED");
+        if (this.active !== undefined || this.configuring)
+            return this.refusal("AGENT_SESSION_BUSY");
+        const { model, effort } = input;
+        if ((model === undefined && effort === undefined) || model === "" || effort === "") {
+            return this.refusal("AGENT_SESSION_INVALID_OPTIONS", { path: "configure" });
+        }
+        return undefined;
+    }
+    refusal(code, context = {}) {
+        return new AgentSessionError(`Session "${this.id}" cannot be configured`, code, { sessionId: this.id, ...context });
+    }
     async runCommand(command, onEvent) {
         const code = this.closing !== undefined
             ? "AGENT_SESSION_CLOSED"
-            : this.active !== undefined
+            : this.active !== undefined || this.configuring
                 ? "AGENT_SESSION_BUSY"
                 : this.parts.opened.runCommand === undefined
                     ? "AGENT_SESSION_CAPABILITY_UNSUPPORTED"

package/dist/session/image-input.d.ts

@@ -0,0 +1,15 @@
+import type { ImageAttachment } from "#src/cost/standard-types";
+/** Supported encodings; dimensions are supplied by callers, not decoded here. */
+export declare const IMAGE_MIME_TYPES: readonly string[];
+export declare const MAX_IMAGES_PER_MESSAGE = 10;
+/** Base64 characters per image (5 MiB encoded, 3.75 MiB raw). */
+export declare const MAX_IMAGE_BASE64_CHARS = 5242880;
+export declare const MAX_REQUEST_IMAGES = 20;
+/** Base64 characters per model request and per send. */
+export declare const MAX_REQUEST_IMAGE_BASE64_CHARS = 20971520;
+export declare const IMAGE_TOKEN_ESTIMATE = 1600;
+export type SendInput = {
+    readonly images?: readonly ImageAttachment[];
+};
+/** Return the first failure, in count, image order, then total-size order. */
+export declare function validateImageAttachments(images: readonly ImageAttachment[]): string | undefined;

package/dist/session/image-input.js

@@ -0,0 +1,46 @@
+/** Supported encodings; dimensions are supplied by callers, not decoded here. */
+export const IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+export const MAX_IMAGES_PER_MESSAGE = 10;
+/** Base64 characters per image (5 MiB encoded, 3.75 MiB raw). */
+export const MAX_IMAGE_BASE64_CHARS = 5_242_880;
+export const MAX_REQUEST_IMAGES = 20;
+/** Base64 characters per model request and per send. */
+export const MAX_REQUEST_IMAGE_BASE64_CHARS = 20_971_520;
+export const IMAGE_TOKEN_ESTIMATE = 1_600;
+function validateImage(image) {
+    if (!IMAGE_MIME_TYPES.includes(image.mimeType)) {
+        return `Unsupported image MIME type: ${JSON.stringify(image.mimeType)}`;
+    }
+    if (image.data.length === 0)
+        return "Image data is empty";
+    if (image.data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(image.data)) {
+        return "Image data is not base64";
+    }
+    if (image.data.length > MAX_IMAGE_BASE64_CHARS) {
+        return `Image data exceeds the per-image limit of ${MAX_IMAGE_BASE64_CHARS} base64 characters`;
+    }
+    for (const dimension of ["width", "height"]) {
+        const value = image[dimension];
+        if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+            return `Image ${dimension} must be a positive integer`;
+        }
+    }
+    return undefined;
+}
+/** Return the first failure, in count, image order, then total-size order. */
+export function validateImageAttachments(images) {
+    if (images.length > MAX_IMAGES_PER_MESSAGE) {
+        return `Image count exceeds the limit of ${MAX_IMAGES_PER_MESSAGE} images per message`;
+    }
+    let total = 0;
+    for (const image of images) {
+        const reason = validateImage(image);
+        if (reason !== undefined)
+            return reason;
+        total += image.data.length;
+    }
+    if (total > MAX_REQUEST_IMAGE_BASE64_CHARS) {
+        return `Image data exceeds the total limit of ${MAX_REQUEST_IMAGE_BASE64_CHARS} base64 characters`;
+    }
+    return undefined;
+}

package/dist/session/native-backend.js

@@ -132,6 +132,7 @@ async function openNative(resolved, ctx) {
     return {
         adapter,
         handle,
+        acceptsImages: () => adapter.imageInput(handle),
         runCommand: async ({ command, callId, signal }) => {
             try {
                 const response = await interactionHandler.onInteraction({

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

@@ -7,7 +7,7 @@
  */
 import type { TranscriptDoc, TranscriptStore } from "#src/native/session/transcript-types";
 import type { SandboxState } from "#src/sandbox/types";
-import type { AgentSessionProfile, ApprovalDecidedBy, CommandRunResult, EmbedderTool } from "./agent-session-types.ts";
+import type { AgentSessionProfile, ApprovalDecidedBy, CommandRunResult, EmbedderTool, SessionConfigureInput } from "./agent-session-types.ts";
 import type { AgentSessionAdapter, SendTurnOpts, SessionHandle } from "./session-types.ts";
 export interface BackendInfo {
     /** "native" or "acp:<agent>"; recorded in the transcript document. */
@@ -89,6 +89,10 @@ export interface BackendOpenContext {
     readonly providerInstructions?: string;
 }
 export interface OpenedBackend {
+    /** Absent on a backend that cannot receive image input. Re-read the current model/agent on each query. */
+    acceptsImages?(): Promise<boolean>;
+    /** Absent on a backend that cannot change model or effort on a live session. The facade validates `input` first. */
+    configure?(input: SessionConfigureInput): Promise<void>;
     /** Absent on a backend that cannot run a host-side command (ACP). */
     runCommand?(request: {
         command: string;

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

@@ -10,7 +10,7 @@
  * working; a consumer of anything outside that subset (`AuthStamp`,
  * `InvalidToolCallDetail`) imports it from `@nathapp/nax-agent` directly.
  */
-import type { Pricing, PricingRates, TokenUsage } from "#src/cost/standard-types";
+import type { ImageAttachment, Pricing, PricingRates, TokenUsage } from "#src/cost/standard-types";
 import type { ResolvedPermissions } from "#src/permissions/index";
 import type { ProtocolIds } from "#src/session/protocol-types";
 import type { AdapterFailure } from "./adapter-failure.ts";
@@ -234,6 +234,8 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
 }
 /** Options for sendTurn(). */
 export interface SendTurnOpts {
+    /** Images accompanying this turn's prompt; omitted for text-only turns. */
+    images?: readonly ImageAttachment[];
     /** Unified callback for context-tool calls and agent questions. */
     interactionHandler: import("./interaction-handler.ts").InteractionHandler;
     /** Native-only in-process loop-event registrations for this turn. ACP ignores this. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.91.7-canary.8",
+  "version": "0.91.7",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -47,13 +47,13 @@
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@nathapp/nax-ai": "0.91.7-canary.8",
+    "@nathapp/nax-ai": "0.91.7",
     "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
     "provenance": true,
-    "tag": "canary"
+    "tag": "latest"
   }
 }