@xlaunch/llm 0.2.0-beta.1

package/lib/types/attribution.js

@@ -0,0 +1,46 @@
+/**
+ * Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
+ * adapters from drifting. See
+ * `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+ *
+ * App-attribution vocabulary for provider requests.
+ * @module @xlaunch/llm/attribution
+ */
+import { createRequire } from 'node:module';
+// The package's own manifest is the single source of the version so the
+// User-Agent cannot drift from what is published (`./package.json` is an
+// export of this package; the relative path resolves from both `src/` and
+// the bundled `lib/`).
+const { version } = createRequire(import.meta.url)('../package.json');
+/**
+ * The harness's own identity: the default every adapter sends. Deployments
+ * that need a white-label identity pass their own {@link AppIdentity} to
+ * {@link attributionHeaders} — omission falls back to this default; nothing
+ * can suppress attribution entirely.
+ */
+export const APP_IDENTITY = {
+    product: 'xlaunch',
+    version,
+    url: 'https://github.com/Northlatch-Labs-LLC/xlaunch-agent',
+};
+/**
+ * The standard `User-Agent` value: `product/version (+url)`. The
+ * parenthesized `+url` comment is the conventional self-identification form
+ * (RFC 9110 §10.1.5 product + comment syntax).
+ * @param identity - the identity to render; defaults to {@link APP_IDENTITY}.
+ * @returns the ready-to-send header value.
+ */
+export function userAgent(identity = APP_IDENTITY) {
+    return `${identity.product}/${identity.version} (+${identity.url})`;
+}
+/**
+ * Build the attribution headers an adapter must send on every provider
+ * request. Header names are lowercase (HTTP field names are case-insensitive
+ * on the wire).
+ * @param identity - the identity to send; defaults to {@link APP_IDENTITY} — omission cannot suppress attribution.
+ * @returns headers to merge into the provider request (currently just `user-agent`).
+ */
+export function attributionHeaders(identity = APP_IDENTITY) {
+    return { 'user-agent': userAgent(identity) };
+}
+//# sourceMappingURL=attribution.js.map

package/lib/types/brand.d.ts

@@ -0,0 +1,56 @@
+/**
+ * xlaunch-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@xlaunch/brand` so every owner of a cross-boundary id can brand it
+ * without depending on xlaunch-llm; see that package's README for the
+ * nominal-typing policy.
+ *
+ * @module @xlaunch/llm/brand
+ */
+import { type Branded } from '@xlaunch/brand';
+/** Stable identity carried by one message across inbox, log, and model-request boundaries. */
+export type MessageId = Branded<'MessageId'>;
+/**
+ * Brand a message identifier.
+ * @param id - the opaque message identifier.
+ * @returns the same string with the message-id brand.
+ */
+export declare function MessageId(id: string): MessageId;
+/**
+ * Correlates a model-issued tool call with its result. Provider-issued for
+ * real adapters; synthesized by mocks/assembler fallbacks.
+ */
+export type ToolCallId = Branded<'ToolCallId'>;
+/**
+ * Brand a string as a {@link ToolCallId}.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string with the tool-call-id brand.
+ */
+export declare function ToolCallId(id: string): ToolCallId;
+/** Provider-issued request identifier retained for diagnostics across package boundaries. */
+export type ProviderRequestId = Branded<'ProviderRequestId'>;
+/**
+ * Brand a provider-issued request identifier.
+ * @param id - the opaque provider-issued string.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function ProviderRequestId(id: string): ProviderRequestId;
+/** Identity of one model streaming attempt, unique within one Agent lifecycle. */
+export type LlmAttemptId = Branded<'LlmAttemptId'>;
+/**
+ * Brand one loop-owned streaming attempt identifier.
+ * @param id - the opaque Agent-lifecycle-local identifier.
+ * @returns the same string with the attempt-id brand.
+ */
+export declare function LlmAttemptId(id: string): LlmAttemptId;
+/** Adapter-owned identifier for one model's selectable reasoning effort. */
+export type ReasoningEffortId = Branded<'ReasoningEffortId'>;
+/**
+ * Brand an adapter-owned reasoning-effort identifier.
+ * @param id - the opaque identifier exposed by one model capability.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function ReasoningEffortId(id: string): ReasoningEffortId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,53 @@
+/**
+ * xlaunch-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@xlaunch/brand` so every owner of a cross-boundary id can brand it
+ * without depending on xlaunch-llm; see that package's README for the
+ * nominal-typing policy.
+ *
+ * @module @xlaunch/llm/brand
+ */
+import { brandString } from '@xlaunch/brand';
+/**
+ * Brand a message identifier.
+ * @param id - the opaque message identifier.
+ * @returns the same string with the message-id brand.
+ */
+export function MessageId(id) {
+    return brandString(id);
+}
+/**
+ * Brand a string as a {@link ToolCallId}.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string with the tool-call-id brand.
+ */
+export function ToolCallId(id) {
+    return brandString(id);
+}
+/**
+ * Brand a provider-issued request identifier.
+ * @param id - the opaque provider-issued string.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function ProviderRequestId(id) {
+    return brandString(id);
+}
+/**
+ * Brand one loop-owned streaming attempt identifier.
+ * @param id - the opaque Agent-lifecycle-local identifier.
+ * @returns the same string with the attempt-id brand.
+ */
+export function LlmAttemptId(id) {
+    return brandString(id);
+}
+/**
+ * Brand an adapter-owned reasoning-effort identifier.
+ * @param id - the opaque identifier exposed by one model capability.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function ReasoningEffortId(id) {
+    return brandString(id);
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/call-config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Conversation call configuration and freeze utilities. Provider routing,
+ * model, reasoning effort, and sampling values are request-header state that
+ * can affect cache reuse; request waterfalls replace them and the loop logs
+ * changed snapshots instead of allowing silent per-call drift.
+ * @module xlaunch-llm/call-config
+ */
+import type { GenerateOptions } from './types.ts';
+import type { ReasoningEffortId } from './brand.ts';
+/**
+ * Provider, model, reasoning effort, and sampling scalars of one conversation's
+ * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
+ * the loop builds requests from the logged header rather than accepting these
+ * per call.
+ */
+export interface LlmCallConfig {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+}
+/**
+ * Effective config fields supplied by exact-model adapter resolution rather
+ * than by the caller's request proposal.
+ */
+export interface LlmCallConfigAdapterDefaults {
+    reasoningEffort?: true;
+    maxTokens?: true;
+}
+/**
+ * Field-wise equality over {@link LlmCallConfig} — the comparison a caller
+ * runs to decide whether a proposed configuration is a real change (worth a
+ * logged header snapshot) or the held one restated.
+ * @param a - one configuration.
+ * @param b - the other.
+ * @returns whether every field (including the `stop` list, element-wise) matches.
+ */
+export declare function callConfigEquals(a: LlmCallConfig, b: LlmCallConfig): boolean;
+/**
+ * Mark one exact request object as assembled by xlaunch-agent-loop.
+ * @param request - loop-owned request envelope before LLM dispatch.
+ * @returns the same request object marked as created by the process-local agent loop.
+ */
+export declare function markAgentLoopRequest<T extends GenerateOptions>(request: T): T;
+/**
+ * Test whether the exact request object was assembled by xlaunch-agent-loop.
+ * @param request - request envelope observed at the LLM waterfall.
+ * @returns whether {@link markAgentLoopRequest} recorded this object.
+ */
+export declare function isAgentLoopRequest(request: GenerateOptions): boolean;
+//# sourceMappingURL=call-config.d.ts.map

package/lib/types/call-config.js

@@ -0,0 +1,46 @@
+/**
+ * Conversation call configuration and freeze utilities. Provider routing,
+ * model, reasoning effort, and sampling values are request-header state that
+ * can affect cache reuse; request waterfalls replace them and the loop logs
+ * changed snapshots instead of allowing silent per-call drift.
+ * @module xlaunch-llm/call-config
+ */
+/** Process-local identities of request objects assembled by xlaunch-agent-loop. */
+const AGENT_LOOP_REQUESTS = new WeakSet();
+/**
+ * Field-wise equality over {@link LlmCallConfig} — the comparison a caller
+ * runs to decide whether a proposed configuration is a real change (worth a
+ * logged header snapshot) or the held one restated.
+ * @param a - one configuration.
+ * @param b - the other.
+ * @returns whether every field (including the `stop` list, element-wise) matches.
+ */
+export function callConfigEquals(a, b) {
+    if (a.provider !== b.provider
+        || a.model !== b.model
+        || a.reasoningEffort !== b.reasoningEffort
+        || a.temperature !== b.temperature
+        || a.maxTokens !== b.maxTokens)
+        return false;
+    if (a.stop === undefined || b.stop === undefined)
+        return a.stop === b.stop;
+    return a.stop.length === b.stop.length && a.stop.every((s, i) => s === b.stop?.[i]);
+}
+/**
+ * Mark one exact request object as assembled by xlaunch-agent-loop.
+ * @param request - loop-owned request envelope before LLM dispatch.
+ * @returns the same request object marked as created by the process-local agent loop.
+ */
+export function markAgentLoopRequest(request) {
+    AGENT_LOOP_REQUESTS.add(request);
+    return request;
+}
+/**
+ * Test whether the exact request object was assembled by xlaunch-agent-loop.
+ * @param request - request envelope observed at the LLM waterfall.
+ * @returns whether {@link markAgentLoopRequest} recorded this object.
+ */
+export function isAgentLoopRequest(request) {
+    return AGENT_LOOP_REQUESTS.has(request);
+}
+//# sourceMappingURL=call-config.js.map

package/lib/types/content.d.ts

@@ -0,0 +1,130 @@
+/** Content-block structure helpers. @module @xlaunch/llm/content */
+import type { ContentBlock } from './types.ts';
+import type { Message } from './message.ts';
+import type { AttachmentStore, FileAttachmentRef, ImageAttachmentRef, RequestImageAttachment } from '@xlaunch/attachment';
+/** Execution-world path that model tools can use to read one normalized attachment. */
+export interface ImageAttachmentAccess {
+    /** Absolute path to immutable normalized bytes; callers must treat it as read-only. */
+    readonlyPath: string;
+}
+/**
+ * Resolve current execution-world access for one durable image reference.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when unavailable.
+ */
+export type ImageAttachmentAccessResolver = (ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
+/**
+ * Bridge one attachment provider's host object location into the mounted
+ * tool execution world. The consumer supplies the current filesystem
+ * provider's mapping without making attachment or LLM definitions depend on it.
+ * @param attachments - provider that owns the normalized attachment object.
+ * @param mapHostPath - map one absolute host path into the current tool execution world.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when either provider exposes no mapping.
+ * @throws an attachment error when the durable reference is invalid.
+ */
+export declare function resolveImageAttachmentAccess(attachments: AttachmentStore, mapHostPath: (hostPath: string) => string | undefined, ref: ImageAttachmentRef): ImageAttachmentAccess | undefined;
+/**
+ * Stable text shown to a model that cannot accept one durable image reference.
+ * @param ref - durable normalized attachment omitted from the request.
+ * @returns deterministic text-only placeholder.
+ */
+export declare function textOnlyImageText(ref: ImageAttachmentRef): string;
+/**
+ * Stable model-facing handle for one exact request image. Identity comes from
+ * the occurrence's own durable reference: request versions are prepared per
+ * attachment id, so one shared version may serve occurrences whose display
+ * names differ.
+ * @param ref - the occurrence's durable normalized attachment.
+ * @param version - exact request-image dimensions shown beside the text.
+ * @param access - optional path resolved for the current tool execution world.
+ * @returns attachment handle and request-image dimensions.
+ */
+export declare function requestImageHandleText(ref: ImageAttachmentRef, version: Pick<RequestImageAttachment, 'width' | 'height'>, access?: ImageAttachmentAccess): string;
+/**
+ * Stable per-image placeholder for a request-limit omission.
+ * @param ref - durable normalized attachment omitted from this request.
+ * @param access - optional provider-resolved path for model tools.
+ * @returns identity, normalized metadata, and the available recovery path.
+ */
+export declare function offloadedImageText(ref: ImageAttachmentRef, access?: ImageAttachmentAccess): string;
+/**
+ * True when typed model content contains an image block, walking nested
+ * tool-result content. This is the one recursive image walk shared by every
+ * image policy (capability gating, text-only serialization, compaction
+ * survey), so a consumer cannot silently diverge on nesting depth.
+ * @param content - typed model content blocks.
+ * @returns whether any nested block is an image.
+ */
+export declare function contentHasImage(content: readonly ContentBlock[]): boolean;
+/**
+ * True when typed model content contains a file block, walking nested
+ * tool-result content on the same recursion every file policy shares.
+ * @param content - typed model content blocks.
+ * @returns whether any nested block is a file.
+ */
+export declare function contentHasFile(content: readonly ContentBlock[]): boolean;
+/**
+ * Stable model-facing handle for one durable file reference: the address of
+ * the verbatim stored copy and the instruction to read it on demand. This is
+ * the only representation a provider ever receives for a file.
+ * @param ref - durable verbatim file reference.
+ * @param readonlyPath - execution-world path of the stored copy, when resolvable.
+ * @returns deterministic handle text naming the file, its size, and its address.
+ */
+export declare function fileHandleText(ref: FileAttachmentRef, readonlyPath: string | undefined): string;
+/**
+ * Project durable file history into deterministic handle text for every model
+ * route. Unlike images, no provider receives file blocks natively, so this
+ * projection is unconditional in request assembly.
+ * @param messages - complete request history.
+ * @param resolvePath - resolve one reference's current execution-world read path.
+ * @returns the original list without files, otherwise shallow message copies with handle text.
+ */
+export declare function projectFilesToText(messages: readonly Message[], resolvePath: (ref: FileAttachmentRef) => string | undefined): readonly Message[];
+/** Byte accounting and quantized removal policy for one request representation. */
+export interface RequestImageOffloadPolicy {
+    /** Image count accepted by the route; omission leaves count unbounded. */
+    maxImages?: number;
+    /** Accumulated image bytes accepted by the route; omission leaves bytes unbounded. */
+    maxBytes?: number;
+    /** Number of excess images removed as one deterministic step. */
+    countQuantum?: number;
+    /** Number of excess bytes removed as one deterministic step. */
+    byteQuantum?: number;
+    /** Whether byte accounting uses raw file bytes or inline base64 length. */
+    representation: 'raw' | 'base64';
+    /** Resolve the encoded request-version length; omission uses normalized attachment bytes. */
+    byteLength?: (ref: ImageAttachmentRef) => number;
+    /** Build the model-visible replacement for each omitted attachment. */
+    placeholder: (ref: ImageAttachmentRef) => string;
+}
+/**
+ * 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 declare function projectImagesForTextModel(messages: readonly Message[]): readonly Message[];
+/**
+ * Number of oldest image occurrences one request projection removes, in whole
+ * count and byte quanta, once a route budget is exceeded. The result depends
+ * only on the represented lengths, so provider request pricing reproduces the
+ * exact serialization decision without building the projected messages.
+ * @param lengths - represented byte length of every occurrence, in request order.
+ * @param policy - count/byte budgets and removal quanta; unbounded when absent.
+ * @returns how many leading occurrences the projection replaces with placeholders.
+ */
+export declare function offloadedImagePrefixCount(lengths: readonly number[], policy: Pick<RequestImageOffloadPolicy, 'maxImages' | 'maxBytes' | 'countQuantum' | 'byteQuantum'>): number;
+/**
+ * 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 declare function offloadRequestImagesWithPolicy(messages: readonly Message[], policy: RequestImageOffloadPolicy): readonly Message[];
+//# sourceMappingURL=content.d.ts.map

package/lib/types/content.js

@@ -0,0 +1,284 @@
+/** Content-block structure helpers. @module @xlaunch/llm/content */
+import { assertNever } from '@xlaunch/util-values';
+/**
+ * Bridge one attachment provider's host object location into the mounted
+ * tool execution world. The consumer supplies the current filesystem
+ * provider's mapping without making attachment or LLM definitions depend on it.
+ * @param attachments - provider that owns the normalized attachment object.
+ * @param mapHostPath - map one absolute host path into the current tool execution world.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when either provider exposes no mapping.
+ * @throws an attachment error when the durable reference is invalid.
+ */
+export function resolveImageAttachmentAccess(attachments, mapHostPath, ref) {
+    const hostPath = attachments.imageHostPath(ref);
+    if (hostPath === undefined)
+        return undefined;
+    const readonlyPath = mapHostPath(hostPath);
+    return readonlyPath === undefined ? undefined : { readonlyPath };
+}
+function quoted(value) {
+    return JSON.stringify(value);
+}
+function imageIdentity(ref) {
+    return ref.name === undefined
+        ? String(ref.attachmentId)
+        : `${quoted(ref.name)} (${ref.attachmentId})`;
+}
+function extension(mediaType) {
+    switch (mediaType) {
+        case 'image/png': return '.png';
+        case 'image/jpeg': return '.jpg';
+        case 'image/webp': return '.webp';
+        case 'image/gif': return '.gif';
+        default: return assertNever(mediaType, 'image extension');
+    }
+}
+function normalizedAccessText(ref, access) {
+    return ` Normalized copy (read-only; may be resized or re-encoded): ${quoted(access.readonlyPath)} (${ref.width}x${ref.height}px, ${ref.mediaType}).`
+        + ' Source dimensions, format, and byte size may differ.'
+        + ` Copy to a writable path ending in ${extension(ref.mediaType)} before editing.`;
+}
+/**
+ * Stable text shown to a model that cannot accept one durable image reference.
+ * @param ref - durable normalized attachment 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. Identity comes from
+ * the occurrence's own durable reference: request versions are prepared per
+ * attachment id, so one shared version may serve occurrences whose display
+ * names differ.
+ * @param ref - the occurrence's durable normalized attachment.
+ * @param version - exact request-image dimensions shown beside the text.
+ * @param access - optional path resolved for the current tool execution world.
+ * @returns attachment handle and request-image dimensions.
+ */
+export function requestImageHandleText(ref, version, access) {
+    const preview = `Image ${imageIdentity(ref)}; request preview ${version.width}x${version.height}px.`;
+    return access === undefined
+        ? `${preview} It may be resized or re-encoded; source dimensions, format, and byte size may differ.`
+        : preview + normalizedAccessText(ref, access);
+}
+/**
+ * Stable per-image placeholder for a request-limit omission.
+ * @param ref - durable normalized attachment omitted from this request.
+ * @param access - optional provider-resolved path for model tools.
+ * @returns identity, normalized metadata, and the available recovery path.
+ */
+export function offloadedImageText(ref, access) {
+    const identity = `image omitted to fit request image limits; ${imageIdentity(ref)}.`;
+    if (access === undefined) {
+        return `[${identity} No local normalized image path is available; ask the user to attach it again if needed.]`;
+    }
+    return `[${identity}${normalizedAccessText(ref, access)}]`;
+}
+/**
+ * True when typed model content contains an image block, walking nested
+ * tool-result content. This is the one recursive image walk shared by every
+ * image policy (capability gating, text-only serialization, compaction
+ * survey), so a consumer cannot silently diverge on nesting depth.
+ * @param content - typed model content blocks.
+ * @returns whether any nested block is an image.
+ */
+export function contentHasImage(content) {
+    return content.some(block => block.type === 'image'
+        || (block.type === 'tool-result' && contentHasImage(block.content)));
+}
+/**
+ * True when typed model content contains a file block, walking nested
+ * tool-result content on the same recursion every file policy shares.
+ * @param content - typed model content blocks.
+ * @returns whether any nested block is a file.
+ */
+export function contentHasFile(content) {
+    return content.some(block => block.type === 'file'
+        || (block.type === 'tool-result' && contentHasFile(block.content)));
+}
+/**
+ * Stable model-facing handle for one durable file reference: the address of
+ * the verbatim stored copy and the instruction to read it on demand. This is
+ * the only representation a provider ever receives for a file.
+ * @param ref - durable verbatim file reference.
+ * @param readonlyPath - execution-world path of the stored copy, when resolvable.
+ * @returns deterministic handle text naming the file, its size, and its address.
+ */
+export function fileHandleText(ref, readonlyPath) {
+    const digest = String(ref.attachmentId).slice('sha256:'.length, 'sha256:'.length + 8);
+    const identity = `File ${quoted(ref.name)} (${ref.bytes} bytes, sha256:${digest})`;
+    if (readonlyPath === undefined) {
+        return `[${identity} was uploaded, but the current execution environment cannot access a readable path. Report that limitation if its contents are needed; do not claim to have read it.]`;
+    }
+    return `[${identity}: verbatim read-only copy saved at ${quoted(readonlyPath)}. Read that path with your file tools when its contents are needed; copy it to a writable location before modifying it. When delegating file work, include this saved path in the delegation prompt; only subagents sharing this execution environment can read it.]`;
+}
+/** Replace every file occurrence, including nested tool results, with handle text. */
+function replaceFilesWithHandles(blocks, resolvePath) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'file') {
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: fileHandleText(block.attachment, resolvePath(block.attachment)) });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceFilesWithHandles(block.content, resolvePath);
+            if (content !== block.content) {
+                next ??= blocks.slice(0, index);
+                next.push({ ...block, content });
+                continue;
+            }
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+/**
+ * Project durable file history into deterministic handle text for every model
+ * route. Unlike images, no provider receives file blocks natively, so this
+ * projection is unconditional in request assembly.
+ * @param messages - complete request history.
+ * @param resolvePath - resolve one reference's current execution-world read path.
+ * @returns the original list without files, otherwise shallow message copies with handle text.
+ */
+export function projectFilesToText(messages, resolvePath) {
+    if (!messages.some(message => contentHasFile(message.content)))
+        return messages;
+    return messages.map((message) => {
+        const content = replaceFilesWithHandles(message.content, resolvePath);
+        return content === message.content ? message : { ...message, 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, placeholder) {
+    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: placeholder(block.attachment) });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceOldestImages(block.content, remaining, placeholder);
+            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 };
+    });
+}
+/**
+ * Number of oldest image occurrences one request projection removes, in whole
+ * count and byte quanta, once a route budget is exceeded. The result depends
+ * only on the represented lengths, so provider request pricing reproduces the
+ * exact serialization decision without building the projected messages.
+ * @param lengths - represented byte length of every occurrence, in request order.
+ * @param policy - count/byte budgets and removal quanta; unbounded when absent.
+ * @returns how many leading occurrences the projection replaces with placeholders.
+ */
+export function offloadedImagePrefixCount(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 0;
+    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;
+    }
+    return count;
+}
+/**
+ * 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 count = offloadedImagePrefixCount(lengths, policy);
+    if (count === 0)
+        return messages;
+    const remaining = { count };
+    return messages.map((message) => {
+        const content = replaceOldestImages(message.content, remaining, policy.placeholder);
+        return content === message.content ? message : { ...message, content };
+    });
+}
+//# sourceMappingURL=content.js.map