@x1a0f3n9/dsh-llm 0.1.2-alpha.6

package/lib/types/brand.d.ts

@@ -0,0 +1,48 @@
+/**
+ * dsh-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@x1a0f3n9/dsh-brand` so every owner of a cross-boundary id can brand it
+ * without depending on dsh-llm; see that package's README for the
+ * nominal-typing policy.
+ *
+ * @module @x1a0f3n9/dsh-llm/brand
+ */
+import { type Branded } from '@x1a0f3n9/dsh-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;
+/** 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,45 @@
+/**
+ * dsh-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@x1a0f3n9/dsh-brand` so every owner of a cross-boundary id can brand it
+ * without depending on dsh-llm; see that package's README for the
+ * nominal-typing policy.
+ *
+ * @module @x1a0f3n9/dsh-llm/brand
+ */
+import { brandString } from '@x1a0f3n9/dsh-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 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 dsh-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 dsh-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 dsh-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 dsh-llm/call-config
+ */
+/** Process-local identities of request objects assembled by dsh-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 dsh-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 dsh-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,105 @@
+/** Content-block structure helpers. @module @x1a0f3n9/dsh-llm/content */
+import type { ContentBlock } from './types.ts';
+import type { Message } from './message.ts';
+import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@x1a0f3n9/dsh-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;
+/** 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,221 @@
+/** Content-block structure helpers. @module @x1a0f3n9/dsh-llm/content */
+import { assertNever } from '@x1a0f3n9/dsh-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)));
+}
+/** 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

package/lib/types/error.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Harness error base with a stable machine-routable code and chained cause.
+ * Package errors extend it so tool results and replay can retain failure class.
+ * @module @x1a0f3n9/dsh-llm/error
+ */
+/**
+ * Base class for all harness errors. Carries a `code` (stable, programmatic —
+ * e.g. `NO_ADAPTER`, `INVALID_ARGS`, `INVARIANT`) distinct from the
+ * human-readable `message`, and supports `cause` chaining via the standard
+ * `ErrorOptions`. `name` defaults to the subclass constructor name.
+ */
+export declare class HarnessError extends Error {
+    /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/** Canonical provider-neutral code for a model request rejected because its context window was exceeded. */
+export declare const CONTEXT_WINDOW_EXCEEDED_CODE = "CONTEXT_WINDOW_EXCEEDED";
+/** Canonical provider-neutral code for an exhausted account quota or balance. */
+export declare const QUOTA_EXCEEDED_CODE = "QUOTA";
+/**
+ * Canonical provider-neutral code for a response that completed normally but
+ * carried no content blocks at all. Providers occasionally emit a degenerate
+ * completion (a terminal stop with zero output); adapters classify it as this
+ * failure instead of yielding an empty assistant message, because an empty
+ * message silently ends the turn with nothing for the user or the loop to act
+ * on. The attempt produced nothing durable, so retry policy treats it as safe
+ * to repeat.
+ */
+export declare const EMPTY_RESPONSE_CODE = "EMPTY_RESPONSE";
+/**
+ * Canonical provider-neutral code for a credential that was supplied but
+ * cannot be used — malformed rather than absent. Distinct from
+ * `MISSING_CREDENTIAL` because the fix differs: correct the stored value
+ * rather than supply one. Deliberately outside the default retryable set —
+ * a malformed credential fails identically on every attempt.
+ */
+export declare const INVALID_CREDENTIAL_CODE = "INVALID_CREDENTIAL";
+/**
+ * Recognize the context-overflow wording used by OpenAI-compatible providers
+ * and library adapters. Adapters pass all available provider code, type, and
+ * message text so both thrown and in-band delivery styles share one classifier.
+ * @param detail - provider error code/type/message text joined into one string.
+ * @returns true when the detail identifies a request exceeding the model context window.
+ */
+export declare function isContextWindowExceededError(detail: string): boolean;
+/**
+ * Recognize provider wording that identifies an exhausted account quota rather
+ * than a transient request-rate limit.
+ * @param detail - provider error code/type/message text joined into one string.
+ * @returns true only for terminal quota, balance, credit, budget, or usage-limit wording.
+ */
+export declare function isQuotaExceededError(detail: string): boolean;
+/**
+ * Render a thrown value with its full `cause` chain and AggregateError
+ * members, so transport wrappers like undici's `TypeError: fetch failed`
+ * surface the underlying failure instead of masking it. Plain structured
+ * failures render their own data-backed `message`. Diagnostic-surface
+ * rendering only (messages, notices, logs) — never parse the result; route on
+ * {@link HarnessError.code}.
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns the outermost message first, each cause appended with `: ` (skipped
+ * when it repeats the wrapper message verbatim), and AggregateError members
+ * bracketed and `; `-joined.
+ */
+export declare function errorChain(value: unknown): string;
+/**
+ * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at runtime boundaries).
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
+ */
+export declare function isHarnessError(value: unknown): value is HarnessError;
+//# sourceMappingURL=error.d.ts.map