@qilin-agent/llm 0.0.0-stage → 3.1.4

package/lib/types/content.js

@@ -0,0 +1,355 @@
+/** Content-block structure helpers. @module @qilin-agent/llm/content */
+import { assertNever } from '@qilin-agent/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. This is the one image
+ * walk shared by every image policy (capability gating, text-only
+ * serialization, compaction survey), so a consumer cannot silently diverge.
+ * @param content - typed model content blocks.
+ * @returns whether any block is an image.
+ */
+export function contentHasImage(content) {
+    return content.some(block => block.type === 'image');
+}
+/**
+ * True when typed model content contains a file block.
+ * Reads current content on every call without retaining scan results.
+ * @param content - typed model content blocks.
+ * @returns whether any block is a file.
+ */
+export function contentHasFile(content) {
+    for (const block of content) {
+        if (block.type === 'file')
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 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;
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+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;
+}
+/**
+ * Visit every image occurrence of typed content in message order.
+ * @param content - typed model content blocks.
+ * @param visit - called once per occurrence.
+ */
+function visitImageBlocks(content, visit) {
+    for (const block of content) {
+        if (block.type === 'image')
+            visit(block);
+    }
+}
+/** Replace every offloaded occurrence with its placeholder. */
+function replaceOffloadedImages(blocks, placeholder) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'image' && block.offloaded === true) {
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: placeholder(block.attachment) });
+            continue;
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+export function projectOffloadedImages(messages, placeholder) {
+    return messages.map((message) => {
+        const content = replaceOffloadedImages(message.content, placeholder);
+        return content === message.content ? message : { ...message, content };
+    });
+}
+/**
+ * Number of oldest retained image occurrences one route budget removes, in
+ * whole count and byte quanta, once the budget is exceeded. The result depends
+ * only on the represented lengths, so every route names the count the same
+ * way.
+ * @param lengths - represented byte length of every retained occurrence, oldest first.
+ * @param budget - count/byte budgets and removal quanta; unbounded when absent.
+ * @returns how many leading occurrences to offload.
+ */
+function offloadedImagePrefixCount(lengths, budget) {
+    const total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+    const excessCount = budget.maxImages === undefined ? 0 : Math.max(0, lengths.length - budget.maxImages);
+    const excessBytes = budget.maxBytes === undefined ? 0 : Math.max(0, total - budget.maxBytes);
+    if (excessCount === 0 && excessBytes === 0)
+        return 0;
+    const countQuantum = budget.countQuantum ?? 1;
+    const byteQuantum = budget.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;
+}
+/**
+ * Number of oldest retained occurrences a route must still offload before a
+ * derived request fits its budget at the exact byte length the route sends;
+ * zero when the request fits. A route fails with `IMAGE_OFFLOAD_REQUIRED`
+ * carrying this count instead of offloading on its own.
+ * @param messages - derived request history carrying the surface's `offloaded` marks.
+ * @param budget - route representation, budgets, and removal quanta.
+ * @param versionBytes - exact request-version byte length of one retained occurrence.
+ * @returns how many more leading retained occurrences to offload.
+ */
+export function requiredImageOffload(messages, budget, versionBytes) {
+    const lengths = [];
+    for (const message of messages) {
+        visitImageBlocks(message.content, (block) => {
+            if (block.offloaded === true)
+                return;
+            const bytes = versionBytes(block);
+            lengths.push(budget.representation === 'base64' ? base64Length(bytes) : bytes);
+        });
+    }
+    return offloadedImagePrefixCount(lengths, budget);
+}
+/** Replace every image occurrence 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;
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+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 };
+    });
+}
+function withoutDeveloperMessages(messages) {
+    const retained = messages.filter(message => message.role !== 'developer');
+    return retained.length === messages.length ? messages : retained;
+}
+function toolDeclarations(tools, mode, history) {
+    const declarations = new Map(history.tools.map(tool => [tool.name, tool]));
+    for (const update of history.updates) {
+        for (const tool of update.additions) {
+            if (!declarations.has(tool.name)) {
+                // Later additions activate these definitions at their recorded position.
+                declarations.set(tool.name, { ...tool, deferLoading: true });
+            }
+        }
+    }
+    switch (mode) {
+        case 'in-history':
+            // Removal blocks disable tools without discarding their historical definitions.
+            return declarations;
+        case 'addition-only': {
+            // Without removal support, the declaration list must omit inactive tools.
+            const activeNames = new Set(tools?.map(tool => tool.name));
+            for (const name of declarations.keys()) {
+                if (!activeNames.has(name))
+                    declarations.delete(name);
+            }
+            return declarations;
+        }
+        /* v8 ignore next 2 -- closed-union exhaustiveness guard */
+        default:
+            return assertNever(mode);
+    }
+}
+/**
+ * Construct provider declarations from session-folded history without changing logged active tools.
+ * Unsupported routes and incomplete history use current declarations without developer updates.
+ * Explicitly deferred baseline tools become available only after their first retained addition.
+ * @param messages - complete request inputs, or the prefix selected for an auxiliary call.
+ * @param tools - currently active tool schemas.
+ * @param toolUpdate - the resolved route's update mode.
+ * @param history - immutable state folded from committed headers and developer messages.
+ * @returns provider declarations and the corresponding filtered history.
+ */
+export function projectToolUpdates(messages, tools, toolUpdate, history) {
+    if (toolUpdate === undefined) {
+        // Unsupported routes need immediately available tools and no update messages.
+        let immediateTools = tools;
+        if (tools?.some(tool => tool.deferLoading === true)) {
+            immediateTools = tools.map(({ deferLoading: _loading, ...tool }) => tool);
+        }
+        return { messages: withoutDeveloperMessages(messages), tools: immediateTools };
+    }
+    if (history === undefined) {
+        // Current schemas alone cannot resolve definitions referenced by past updates.
+        return { messages: withoutDeveloperMessages(messages), tools };
+    }
+    const messageIds = new Set(messages.flatMap(message => message.role === 'developer' ? [message.id] : []));
+    if (history.updates.some(update => !messageIds.has(update.messageId))) {
+        // An auxiliary prefix may omit updates needed to activate historical declarations.
+        return { messages: withoutDeveloperMessages(messages), tools };
+    }
+    const declarations = toolDeclarations(tools, toolUpdate, history);
+    const updateIds = new Set(history.updates.map(update => update.messageId));
+    // Deferred baseline tools still need their first addition to become available.
+    const offered = new Set(history.tools.filter(tool => !tool.deferLoading).map(tool => tool.name));
+    const projectedMessages = [];
+    for (const message of messages) {
+        if (message.role !== 'developer') {
+            projectedMessages.push(message);
+            continue;
+        }
+        // Earlier declaration series do not govern the current tool set.
+        if (!updateIds.has(message.id))
+            continue;
+        const content = message.content.filter((block) => {
+            switch (block.type) {
+                case 'tool-addition':
+                    // Only declared tools that are not already available need activation.
+                    if (!declarations.has(block.toolName) || offered.has(block.toolName))
+                        return false;
+                    offered.add(block.toolName);
+                    return true;
+                case 'tool-removal':
+                    // Addition-only routes cannot deactivate a tool through history.
+                    if (toolUpdate !== 'in-history')
+                        return false;
+                    return offered.delete(block.toolName);
+                default:
+                    // Other core and plugin-defined blocks retain their content and order.
+                    return true;
+            }
+        });
+        if (content.length === 0)
+            continue;
+        if (content.length === message.content.length) {
+            projectedMessages.push(message);
+        }
+        else {
+            projectedMessages.push({ ...message, content });
+        }
+    }
+    const unchanged = projectedMessages.length === messages.length
+        && projectedMessages.every((message, index) => message === messages[index]);
+    return {
+        messages: unchanged ? messages : projectedMessages,
+        tools: [...declarations.values()],
+    };
+}
+//# sourceMappingURL=content.js.map

package/lib/types/error.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 @qilin-agent/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;
+/**
+ * Canonical code for a request an image-capable route cannot send until more
+ * of its images are offloaded. The failure's `offloadImages` names how many
+ * more of the oldest retained occurrences must be offloaded;
+ * `dsh-compaction-image-offload` records an `image/offload` selection before
+ * the agent or summarizer retries with freshly derived input.
+ */
+export declare const IMAGE_OFFLOAD_REQUIRED_CODE = "IMAGE_OFFLOAD_REQUIRED";
+//# sourceMappingURL=error.d.ts.map

package/lib/types/error.js

@@ -0,0 +1,153 @@
+/**
+ * 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 @qilin-agent/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 class HarnessError extends Error {
+    /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+/** Canonical provider-neutral code for a model request rejected because its context window was exceeded. */
+export const CONTEXT_WINDOW_EXCEEDED_CODE = 'CONTEXT_WINDOW_EXCEEDED';
+/** Canonical provider-neutral code for an exhausted account quota or balance. */
+export 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 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 const INVALID_CREDENTIAL_CODE = 'INVALID_CREDENTIAL';
+/** Structured codes and plain phrases that explicitly name a context bound being exceeded. */
+const STRUCTURED_CONTEXT_OVERFLOW = new RegExp(String.raw `(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]`
+    + String.raw `(?:exceed(?:ed|s)?|overflow(?:ed)?|limit[\s_-]exceeded)(?:$|[^a-z0-9])`, 'i');
+/** Request-size wording that ties "too large" directly to model context capacity. */
+const TOO_LARGE_FOR_CONTEXT = new RegExp(String.raw `\b(?:request|prompt|input|messages?)\s+(?:is\s+|are\s+)?`
+    + String.raw `too\s+(?:large|long)\s+for\s+(?:(?:this|the)\s+)?`
+    + String.raw `(?:model(?:'s)?\s+)?context(?:\s+window)?\b`, 'i');
+/** "Exceeds" wording is safe only when its object is explicitly the model context. */
+const EXCEEDS_MODEL_CONTEXT = new RegExp(String.raw `\b(?:input|prompt|request|messages?)\b.{0,40}`
+    + String.raw `\b(?:exceed(?:s|ed)?|overflows?|is\s+larger\s+than)\b.{0,40}`
+    + String.raw `\b(?:the\s+)?(?:model(?:'s)?\s+)?context(?:\s+(?:length|window))?\b`, 'i');
+/**
+ * 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 function isContextWindowExceededError(detail) {
+    return STRUCTURED_CONTEXT_OVERFLOW.test(detail)
+        || /\b(?:maximum|max)(?:\s+(?:allowed|supported))?\s+context\s+(?:length|window)\b/i.test(detail)
+        || TOO_LARGE_FOR_CONTEXT.test(detail)
+        || /\b(?:input|prompt|request)\s+(?:is\s+)?too\s+(?:long|large)\s+for\s+(?:this|the)\s+model\b/i.test(detail)
+        || EXCEEDS_MODEL_CONTEXT.test(detail);
+}
+/**
+ * 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 function isQuotaExceededError(detail) {
+    return /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i.test(detail)
+        || /\b(?:quota|usage[\s_-]+limit)[\s_-]+(?:exceeded|exhausted|reached)\b/i.test(detail)
+        || /\bexceed(?:ed|s)?[\s_-]+(?:(?:your|the)[\s_-]+)?(?:current[\s_-]+)?quota\b/i.test(detail)
+        || /\b(?:balance|credits?)[\s_-]+(?:exhausted|depleted)\b/i.test(detail)
+        || /\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i.test(detail);
+}
+/**
+ * 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 function errorChain(value) {
+    // Tracks the active recursion path (entries removed on exit), so only true
+    // cycles are flagged and a diamond-shared cause still renders in full.
+    const path = new Set();
+    const render = (current) => {
+        if (path.has(current))
+            return '<circular cause>';
+        path.add(current);
+        try {
+            if (!(current instanceof Error)) {
+                if (typeof current === 'object' && current !== null) {
+                    const descriptor = Object.getOwnPropertyDescriptor(current, 'message');
+                    if (descriptor !== undefined && 'value' in descriptor && typeof descriptor.value === 'string') {
+                        return descriptor.value;
+                    }
+                }
+                return String(current);
+            }
+            const message = current.message === '' ? current.name : current.message;
+            const members = current instanceof AggregateError && current.errors.length > 0
+                ? ` [${current.errors.map(render).join('; ')}]`
+                : '';
+            const causeText = current.cause === undefined || current.cause === null
+                ? ''
+                : render(current.cause);
+            // Wrappers like `new HarnessError(String(value), code, { cause: value })`
+            // repeat their cause verbatim; rendering it again would only add noise.
+            const cause = causeText === '' || causeText === message ? '' : `: ${causeText}`;
+            return `${message}${members}${cause}`;
+        }
+        catch {
+            // Only hostile coercion or hostile accessors (a throwing toString /
+            // Symbol.toPrimitive on a non-Error, or a throwing message/name/cause/
+            // errors getter on an Error subclass): this renderer feeds UI notices
+            // and logs, so nothing may escape. Inner frames catch their own throws,
+            // so only the hostile node collapses, not the whole chain.
+            return '<unrenderable value>';
+        }
+        finally {
+            path.delete(current);
+        }
+    };
+    return render(value);
+}
+/**
+ * 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 function isHarnessError(value) {
+    return value instanceof HarnessError;
+}
+/**
+ * Canonical code for a request an image-capable route cannot send until more
+ * of its images are offloaded. The failure's `offloadImages` names how many
+ * more of the oldest retained occurrences must be offloaded;
+ * `dsh-compaction-image-offload` records an `image/offload` selection before
+ * the agent or summarizer retries with freshly derived input.
+ */
+export const IMAGE_OFFLOAD_REQUIRED_CODE = 'IMAGE_OFFLOAD_REQUIRED';
+//# sourceMappingURL=error.js.map