@stackstackstack/dsh-llm 0.1.5

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

@@ -0,0 +1,62 @@
+/**
+ * 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;
+/**
+ * Deep-freeze a value in place with an iterative traversal, guarding cycles,
+ * so later mutation throws without imposing a JavaScript call-stack depth cap.
+ * {@link AbortSignal} objects are deliberately skipped because they are the
+ * request's live cancellation channel and freezing them breaks abort.
+ * @param value - the value to freeze in place.
+ * @returns the same value, frozen.
+ */
+export declare function deepFreeze<T>(value: T): T;
+//# sourceMappingURL=call-config.d.ts.map

package/lib/types/call-config.js

@@ -0,0 +1,86 @@
+/**
+ * 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);
+}
+/**
+ * Deep-freeze a value in place with an iterative traversal, guarding cycles,
+ * so later mutation throws without imposing a JavaScript call-stack depth cap.
+ * {@link AbortSignal} objects are deliberately skipped because they are the
+ * request's live cancellation channel and freezing them breaks abort.
+ * @param value - the value to freeze in place.
+ * @returns the same value, frozen.
+ */
+export function deepFreeze(value) {
+    const seen = new WeakSet();
+    const pending = [{ kind: 'visit', node: value }];
+    while (pending.length > 0) {
+        const task = pending.pop();
+        /* v8 ignore next -- the loop condition guarantees one pending task. */
+        if (task === undefined)
+            continue;
+        if (task.kind === 'property') {
+            pending.push({ kind: 'visit', node: task.source[task.key] });
+            continue;
+        }
+        const node = task.node;
+        if (node === null || typeof node !== 'object')
+            continue;
+        if (node instanceof AbortSignal)
+            continue;
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        Object.freeze(node);
+        const keys = Object.keys(node);
+        for (let index = keys.length - 1; index >= 0; index--) {
+            const key = keys[index];
+            /* v8 ignore next -- the loop is bounded by the captured key count. */
+            if (key === undefined)
+                continue;
+            pending.push({ kind: 'property', source: node, key });
+        }
+    }
+    return value;
+}
+//# sourceMappingURL=call-config.js.map

package/lib/types/content.d.ts

@@ -0,0 +1,12 @@
+/** Content-block structure helpers. @module @stackstackstack/dsh-llm/content */
+import type { ContentBlock } from './types.ts';
+/**
+ * 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;
+//# sourceMappingURL=content.d.ts.map

package/lib/types/content.js

@@ -0,0 +1,14 @@
+/** Content-block structure helpers. @module @stackstackstack/dsh-llm/content */
+/**
+ * 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)));
+}
+//# 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 @stackstackstack/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

package/lib/types/error.js

@@ -0,0 +1,145 @@
+/**
+ * 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 @stackstackstack/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 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;
+}
+//# sourceMappingURL=error.js.map