@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/llm/lib/types/content.js

@@ -1,4 +1,23 @@
 /** Content-block structure helpers. @module @nomix-ai/nomix-llm/content */
+/** Model-facing stand-in for an image removed to fit a provider request bound. */
+export const OFFLOADED_IMAGE_TEXT = '[image omitted to keep the request within its image limit; older images are omitted first. If this image is still needed, read its file again when a path is available; otherwise ask the user to attach it again.]';
+/**
+ * Stable text shown to a model that cannot accept one durable image reference.
+ * @param ref - durable master reference omitted from the request.
+ * @returns deterministic text-only placeholder.
+ */
+export function textOnlyImageText(ref) {
+    const digest = String(ref.attachmentId).slice('sha256:'.length, 'sha256:'.length + 8);
+    return `[image omitted because this model accepts text only; attachment sha256:${digest}]`;
+}
+/**
+ * Stable model-facing handle for one exact request image.
+ * @param version - exact request image shown beside the text.
+ * @returns attachment handle and request-image dimensions.
+ */
+export function requestImageHandleText(version) {
+    return `Image ${version.attachment.attachmentId}; request image ${version.width}x${version.height}px.`;
+}
 /**
  * True when typed model content contains an image block, walking nested
  * tool-result content. This is the one recursive image walk shared by every
@@ -11,4 +30,134 @@ export function contentHasImage(content) {
     return content.some(block => block.type === 'image'
         || (block.type === 'tool-result' && contentHasImage(block.content)));
 }
+/** Base64 length of raw image bytes, including padding. */
+function base64Length(bytes) {
+    return Math.ceil(bytes / 3) * 4;
+}
+/** Collect represented image lengths in request and nested-block order. */
+function collectImageLengths(blocks, lengths, policy) {
+    for (const block of blocks) {
+        if (block.type === 'image') {
+            const bytes = policy.byteLength === undefined
+                ? block.attachment.bytes
+                : policy.byteLength(block.attachment);
+            lengths.push(policy.representation === 'base64' ? base64Length(bytes) : bytes);
+        }
+        else if (block.type === 'tool-result') {
+            collectImageLengths(block.content, lengths, policy);
+        }
+    }
+}
+/** Replace the first `remaining.count` image occurrences without mutating durable messages. */
+function replaceOldestImages(blocks, remaining) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'image' && remaining.count > 0) {
+            remaining.count -= 1;
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: OFFLOADED_IMAGE_TEXT });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceOldestImages(block.content, remaining);
+            if (content !== block.content) {
+                next ??= blocks.slice(0, index);
+                next.push({ ...block, content });
+                continue;
+            }
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+/** Replace every image occurrence, including nested tool results, for a text-only model. */
+function replaceImagesForTextModel(blocks) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'image') {
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: textOnlyImageText(block.attachment) });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceImagesForTextModel(block.content);
+            if (content !== block.content) {
+                next ??= blocks.slice(0, index);
+                next.push({ ...block, content });
+                continue;
+            }
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+/**
+ * Project durable image history into deterministic text for an exact text-only model.
+ * @param messages - complete request history.
+ * @returns the original list without images, otherwise shallow message copies with stable placeholders.
+ */
+export function projectImagesForTextModel(messages) {
+    if (!messages.some(message => contentHasImage(message.content)))
+        return messages;
+    return messages.map((message) => {
+        const content = replaceImagesForTextModel(message.content);
+        return content === message.content ? message : { ...message, content };
+    });
+}
+/**
+ * Return transient request messages whose oldest images are replaced until
+ * their accumulated base64 payload fits the configured bound. The selection
+ * is deterministic from durable message order and attachment metadata; a
+ * provider can serialize the returned messages without reading omitted bytes.
+ * @param messages - complete request history, oldest first.
+ * @param maxRequestImageBytes - positive bound on total base64 image payload; undefined preserves every image.
+ * @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
+ */
+export function offloadRequestImages(messages, maxRequestImageBytes) {
+    return offloadRequestImagesWithPolicy(messages, {
+        representation: 'base64',
+        ...maxRequestImageBytes === undefined ? {} : { maxBytes: maxRequestImageBytes },
+        byteQuantum: 1,
+    });
+}
+/**
+ * Return a deterministic transient projection whose oldest images are replaced
+ * in whole count and byte quanta after a route budget is exceeded. The target
+ * depends only on complete durable history: at 129 one-megabyte images under
+ * a 128 MiB bound with a 64 MiB quantum, the oldest 65 images are removed so
+ * 64 MiB remain; that removed prefix stays fixed until total history exceeds
+ * 192 MiB.
+ * @param messages - complete request history, oldest first.
+ * @param policy - route representation, budgets, and removal quanta.
+ * @returns original messages below both bounds, otherwise shallow copies with deterministic placeholders.
+ */
+export function offloadRequestImagesWithPolicy(messages, policy) {
+    const lengths = [];
+    for (const message of messages)
+        collectImageLengths(message.content, lengths, policy);
+    const total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+    const excessCount = policy.maxImages === undefined ? 0 : Math.max(0, lengths.length - policy.maxImages);
+    const excessBytes = policy.maxBytes === undefined ? 0 : Math.max(0, total - policy.maxBytes);
+    if (excessCount === 0 && excessBytes === 0)
+        return messages;
+    const countQuantum = policy.countQuantum ?? 1;
+    const byteQuantum = policy.byteQuantum ?? 1;
+    const removeCount = excessCount === 0 ? 0 : Math.ceil(excessCount / countQuantum) * countQuantum;
+    const removeBytes = excessBytes === 0 ? 0 : Math.ceil(excessBytes / byteQuantum) * byteQuantum;
+    let count = 0;
+    let removedBytes = 0;
+    for (const imageBytes of lengths) {
+        const byteTargetMet = removeBytes === 0
+            || (byteQuantum === 1 ? removedBytes >= removeBytes : removedBytes > removeBytes);
+        if (count >= removeCount && byteTargetMet)
+            break;
+        removedBytes += imageBytes;
+        count += 1;
+    }
+    const remaining = { count };
+    return messages.map((message) => {
+        const content = replaceOldestImages(message.content, remaining);
+        return content === message.content ? message : { ...message, content };
+    });
+}
 //# sourceMappingURL=content.js.map

package/dist/kernel/llm/lib/types/index.d.ts

@@ -5,8 +5,8 @@
  *
  * @module @nomix-ai/nomix-llm
  */
-import { Context, Service } from '@nomix-ai/cordis';
-import type { GenerateOptions, LlmConfigurableProvider, LlmDiscoveredModel, LlmFailure, LlmModelContext, LlmModelDiscoveryRequest, LlmModelInfo, LlmResolvedModelInfo, LlmProviderInfo, StreamChunk } from './types.ts';
+import { Context, Service } from '../../../cordis/lib/index.js';
+import type { GenerateOptions, LlmConfigurableProvider, LlmDiscoveredModel, LlmFailure, LlmModelContext, LlmModelDiscoveryRequest, LlmModelInfo, LlmResolvedModelInfo, LlmProviderInfo, ModelModality, StreamChunk } from './types.ts';
 import type { ResolvedRetryPolicy } from './retry-policy.ts';
 import type { ProviderRequestId } from './brand.ts';
 import type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
@@ -93,6 +93,8 @@ export interface PreparedLlmCall {
     readonly retryPolicy: ResolvedRetryPolicy;
     /** Detached context metadata resolved with the registration-bound call. */
     readonly context?: LlmModelContext;
+    /** Exact model modalities captured with the adapter dispatch generation. */
+    readonly inputModalities?: readonly ModelModality[];
     /** Config fields materialized by the captured adapter rather than proposed by the caller. */
     readonly adapterDefaults: LlmCallConfigAdapterDefaults;
     /**
@@ -104,6 +106,13 @@ export interface PreparedLlmCall {
      */
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }
+/** One adapter-owned model-resolution generation bound to its eventual stream call. */
+export interface PreparedAdapterCall {
+    /** Exact model metadata from the same adapter generation as {@link stream}. */
+    readonly model: LlmResolvedModelInfo;
+    /** Dispatch through that generation without re-reading dynamic connection facts. */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
 /**
  * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
  * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
@@ -141,6 +150,16 @@ export declare abstract class LlmAdapter {
      * @returns provider/model identity plus any context, call-default, and reasoning metadata.
      */
     resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /**
+     * Bind exact model metadata and the eventual request dispatch to one adapter generation.
+     * Dynamic adapters override this so settings changes between preparation and
+     * dispatch cannot combine one generation's capabilities with another's endpoint.
+     * @param provider - registered provider route.
+     * @param model - exact model id.
+     * @param signal - cancellation for model resolution.
+     * @returns model metadata and a one-generation stream entry point.
+     */
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
     /**
      * Stream one model call as raw chunks. The only required method.
      * @param options - the fully-assembled request; implementations must honor `options.signal`.
@@ -293,6 +312,8 @@ export declare class LlmRuntime extends Service {
      */
     resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
     private resolveModelInfoFor;
+    /** Validate and detach one adapter-returned exact model result. */
+    private normalizeModelInfo;
     /**
      * Validate a conversation call config against its exact model capability and
      * materialize adapter-configured defaults. Unsupported explicit efforts
@@ -305,6 +326,8 @@ export declare class LlmRuntime extends Service {
      */
     resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>;
     private resolveCallFor;
+    /** Validate request controls against one already-bound exact model result. */
+    private resolveCallWithInfo;
     /**
      * Resolve one call under its current adapter registration. The returned
      * one-shot handle keeps that registration across header logging and dispatch,

package/dist/kernel/llm/lib/types/index.js

@@ -5,13 +5,14 @@
  *
  * @module @nomix-ai/nomix-llm
  */
-import { Service } from '@nomix-ai/cordis';
+import { Service } from '../../../cordis/lib/index.js';
 import { freezeMessage } from "./message.js";
 import { resolveRetryPolicy } from "./retry-policy.js";
 import { callConfigEquals, deepFreeze } from "./call-config.js";
 import { HarnessError, INVALID_CREDENTIAL_CODE } from "./error.js";
 import { normalizeLlmFailure } from "./adapter-failure.js";
 import { normalizeApiKey } from "./api-key.js";
+import { contentHasImage, projectImagesForTextModel } from "./content.js";
 export * from "./attribution.js";
 export * from "./brand.js";
 export * from "./never.js";
@@ -140,6 +141,21 @@ export class LlmAdapter {
     resolveModel(provider, model, _signal) {
         return Promise.resolve({ provider, id: model, name: model });
     }
+    /**
+     * Bind exact model metadata and the eventual request dispatch to one adapter generation.
+     * Dynamic adapters override this so settings changes between preparation and
+     * dispatch cannot combine one generation's capabilities with another's endpoint.
+     * @param provider - registered provider route.
+     * @param model - exact model id.
+     * @param signal - cancellation for model resolution.
+     * @returns model metadata and a one-generation stream entry point.
+     */
+    async prepareCall(provider, model, signal) {
+        return {
+            model: await this.resolveModel(provider, model, signal),
+            stream: options => this.stream(options),
+        };
+    }
 }
 /**
  * The abstract `llm` service: an adapter registry plus a streaming model-call
@@ -466,8 +482,12 @@ export class LlmRuntime extends Service {
         return this.resolveModelInfoFor(this.registration(provider), model, signal);
     }
     async resolveModelInfoFor(registration, model, signal) {
+        const resolved = await registration.adapter.resolveModel(registration.provider.id, model, signal);
+        return this.normalizeModelInfo(registration, model, resolved);
+    }
+    /** Validate and detach one adapter-returned exact model result. */
+    normalizeModelInfo(registration, model, resolved) {
         const provider = registration.provider.id;
-        const resolved = await registration.adapter.resolveModel(provider, model, signal);
         if (typeof resolved.provider !== 'string'
             || resolved.provider !== provider
             || typeof resolved.id !== 'string'
@@ -547,6 +567,10 @@ export class LlmRuntime extends Service {
     }
     async resolveCallFor(registration, config, signal) {
         const info = await this.resolveModelInfoFor(registration, config.model, signal);
+        return this.resolveCallWithInfo(config, info);
+    }
+    /** Validate request controls against one already-bound exact model result. */
+    resolveCallWithInfo(config, info) {
         const defaulted = config.maxTokens === undefined && info.defaultMaxTokens !== undefined
             ? { ...config, maxTokens: info.defaultMaxTokens }
             : config;
@@ -571,6 +595,7 @@ export class LlmRuntime extends Service {
         return {
             config: resolvedConfig,
             ...info.context === undefined ? {} : { context: info.context },
+            modelInfo: info,
         };
     }
     /**
@@ -583,7 +608,9 @@ export class LlmRuntime extends Service {
      */
     async prepareCall(config, signal) {
         const registration = this.registration(config.provider);
-        const resolved = await this.resolveCallFor(registration, config, signal);
+        const adapterCall = await registration.adapter.prepareCall(config.provider, config.model, signal);
+        const modelInfo = this.normalizeModelInfo(registration, config.model, adapterCall.model);
+        const resolved = this.resolveCallWithInfo(config, modelInfo);
         const resolvedConfig = deepFreeze(structuredClone(resolved.config));
         const context = resolved.context === undefined
             ? undefined
@@ -602,6 +629,9 @@ export class LlmRuntime extends Service {
             retryPolicy: registration.retryPolicy,
             adapterDefaults,
             ...context === undefined ? {} : { context },
+            ...modelInfo.inputModalities === undefined
+                ? {}
+                : { inputModalities: Object.freeze([...modelInfo.inputModalities]) },
             stream: (options) => {
                 if (dispatched) {
                     throw new LlmError('a prepared LLM call can only be dispatched once', 'INVALID_PREPARED_CALL');
@@ -610,7 +640,12 @@ export class LlmRuntime extends Service {
                     throw new LlmError('prepared LLM call config changed before adapter dispatch', 'INVALID_PREPARED_CALL');
                 }
                 dispatched = true;
-                return this.streamWithRegistration(options, { registration, config: resolvedConfig });
+                return this.streamWithRegistration(options, {
+                    registration,
+                    config: resolvedConfig,
+                    modelInfo,
+                    dispatch: options => adapterCall.stream(options),
+                });
             },
         });
     }
@@ -647,9 +682,21 @@ export class LlmRuntime extends Service {
         let iterator;
         try {
             const registration = prepared?.registration ?? this.registration(options.provider);
-            const resolvedConfig = prepared === undefined
-                ? (await this.resolveCallFor(registration, options, options.signal)).config
-                : prepared.config;
+            const adapter = registration.adapter;
+            let modelInfo;
+            let resolvedConfig;
+            let dispatch;
+            if (prepared === undefined) {
+                const adapterCall = await adapter.prepareCall(options.provider, options.model, options.signal);
+                modelInfo = this.normalizeModelInfo(registration, options.model, adapterCall.model);
+                resolvedConfig = this.resolveCallWithInfo(options, modelInfo).config;
+                dispatch = options => adapterCall.stream(options);
+            }
+            else {
+                modelInfo = prepared.modelInfo;
+                resolvedConfig = prepared.config;
+                dispatch = prepared.dispatch;
+            }
             if (prepared !== undefined && !callConfigEquals(options, resolvedConfig)) {
                 throw new LlmError('prepared LLM call config changed before adapter dispatch', 'INVALID_PREPARED_CALL');
             }
@@ -658,8 +705,14 @@ export class LlmRuntime extends Service {
                 : Object.isFrozen(options)
                     ? deepFreeze({ ...options, ...resolvedConfig })
                     : { ...options, ...resolvedConfig };
-            const adapter = registration.adapter;
-            const stream = adapter.stream(this.forAdapter(resolvedOptions, adapter));
+            const projectedOptions = modelInfo.inputModalities !== undefined
+                && !modelInfo.inputModalities.includes('image')
+                && resolvedOptions.messages.some(message => contentHasImage(message.content))
+                ? Object.isFrozen(resolvedOptions)
+                    ? deepFreeze({ ...resolvedOptions, messages: projectImagesForTextModel(resolvedOptions.messages) })
+                    : { ...resolvedOptions, messages: projectImagesForTextModel(resolvedOptions.messages) }
+                : resolvedOptions;
+            const stream = dispatch(this.forAdapter(projectedOptions, adapter));
             iterator = stream[Symbol.asyncIterator]();
         }
         catch (error) {

package/dist/kernel/llm/lib/types/invariant.d.ts

@@ -1,5 +1,5 @@
 /** Package-owned LLM stream-protocol invariants. @module @nomix-ai/nomix-llm/invariant */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "llm-invariant";
 /** Service required before the companion can reserve package ownership. */

package/dist/kernel/llm/lib/types/retry-policy.d.ts

@@ -6,7 +6,7 @@
  *
  * @module @nomix-ai/nomix-llm/retry-policy
  */
-import z from '@nomix-ai/schemastery';
+import z from '../../../schemastery/lib/index.mjs';
 /** Bounded exponential backoff with symmetric jitter around each local delay. */
 export interface BackoffConfig {
     /** Initial local exponential-backoff delay in milliseconds (default 500). */
@@ -20,7 +20,7 @@ export interface BackoffConfig {
 export interface NormalRetryPolicyConfig {
     /** Retry only configured transient failure codes. */
     mode: 'normal';
-    /** Maximum eligible retries after the first request (default 2). */
+    /** Maximum eligible retries after the first request (default 5). */
     maxRetries?: number;
     /** Stable failure codes eligible for this policy. */
     retryableCodes?: string[];

package/dist/kernel/llm/lib/types/retry-policy.js

@@ -6,10 +6,10 @@
  *
  * @module @nomix-ai/nomix-llm/retry-policy
  */
-import z from '@nomix-ai/schemastery';
+import z from '../../../schemastery/lib/index.mjs';
 import { MAX_TIMER_DELAY_MS } from '../../../timeout/lib/index.js';
 import { EMPTY_RESPONSE_CODE } from "./error.js";
-const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_RETRIES = 5;
 const DEFAULT_INITIAL_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 10_000;
 const DEFAULT_JITTER_RATIO = 0.1;
@@ -43,7 +43,11 @@ export const RetryPolicySchema = z.union([
 const NORMAL_POLICY_KEYS = new Set([
     'mode', 'maxRetries', 'retryableCodes', 'backoff',
 ]);
-const ALWAYS_POLICY_KEYS = new Set(['mode', 'backoff']);
+// Layered configuration can retain normal-only fields after switching modes;
+// always mode ignores those inactive values while still rejecting unknown keys.
+const ALWAYS_POLICY_KEYS = new Set([
+    'mode', 'maxRetries', 'retryableCodes', 'backoff',
+]);
 const BACKOFF_KEYS = new Set(['initialDelayMs', 'maxDelayMs', 'jitterRatio']);
 function validateKeys(value, allowed, path) {
     for (const key of Object.keys(value)) {

package/dist/kernel/llm/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomix-ai/nomix-llm",
   "description": "Provider-neutral LLM service interface for the Nomix Harness",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },