@stackstackstack/dsh-llm 0.1.5

package/lib/invariant.js

@@ -0,0 +1,84 @@
+//#region lib/types/invariant.js
+/** Package-owned LLM stream-protocol invariants. @module @stackstackstack/dsh-llm/invariant */
+const PACKAGE_NAME = "@stackstackstack/dsh-llm";
+/** Cordis companion plugin name. */
+const name = "llm-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Require one chunk index to be a non-negative safe integer. */
+function validateIndex(index, fail) {
+	if (!Number.isSafeInteger(index) || index < 0) fail(`LLM stream block index must be a non-negative safe integer, got ${index}`);
+}
+/** Require a delta to address an open block of its matching type. */
+function validateDelta(open, index, expected, fail) {
+	validateIndex(index, fail);
+	const actual = open.get(index);
+	if (actual !== expected) fail(`${expected} delta at index ${index} requires an open ${expected} block, got ${String(actual)}`);
+}
+/** Wrap one provider stream and enforce its grammar as chunks are consumed. */
+async function* validateStream(source, fail) {
+	const open = /* @__PURE__ */ new Map();
+	let usageSeen = false;
+	let finished = false;
+	for await (const chunk of source) {
+		if (finished) fail(`LLM stream emitted ${chunk.type} after terminal finish`);
+		switch (chunk.type) {
+			case "block-start":
+				validateIndex(chunk.index, fail);
+				if (open.has(chunk.index)) fail(`LLM stream repeated block-start index ${chunk.index}`);
+				open.set(chunk.index, chunk.blockType);
+				break;
+			case "text-delta":
+				validateDelta(open, chunk.index, "text", fail);
+				break;
+			case "reasoning-delta":
+				validateDelta(open, chunk.index, "reasoning", fail);
+				break;
+			case "tool-call-delta":
+				validateDelta(open, chunk.index, "tool-call", fail);
+				break;
+			case "block-end": {
+				validateIndex(chunk.index, fail);
+				const blockType = open.get(chunk.index);
+				if (blockType === void 0) fail(`LLM stream block-end index ${chunk.index} has no open block`);
+				if (chunk.block.type !== blockType) fail(`LLM stream block-end index ${chunk.index} closes ${chunk.block.type}, expected ${blockType}`);
+				open.delete(chunk.index);
+				break;
+			}
+			case "usage":
+				if (usageSeen) fail("LLM stream emitted usage more than once");
+				usageSeen = true;
+				break;
+			case "finish":
+				if (open.size > 0 && chunk.reason.kind !== "error" && chunk.reason.kind !== "aborted") fail(`LLM stream finished with ${open.size} open block(s)`);
+				finished = true;
+				break;
+		}
+		yield chunk;
+	}
+	if (!finished) fail("LLM stream ended without a terminal finish chunk");
+}
+/** Install validation around every provider stream. */
+const install = (ctx, fail) => {
+	ctx.on("llm/stream", (_options, next) => validateStream(next(), fail), {
+		global: true,
+		prepend: true
+	});
+	ctx.on("llm/adapters-updated", () => {
+		const llm = ctx.get("llm");
+		if (llm === void 0) return;
+		for (const provider of llm.listProviders()) try {
+			llm.providerRetryPolicy(provider.id);
+		} catch {
+			fail(`llm/adapters-updated fired while provider "${provider.id}" has no readable registration`);
+		}
+	}, { global: true });
+};
+/**
+* Register the LLM invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/adapter-failure.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalization for values thrown by a final LLM adapter boundary.
+ *
+ * @module @stackstackstack/dsh-llm/adapter-failure
+ */
+import type { LlmFailure } from './types.ts';
+/**
+ * Detach serializable provider facts from a value thrown by an adapter.
+ * @param value - arbitrary value thrown during adapter dispatch or iteration.
+ * @returns immutable provider-neutral facts suitable for a terminal finish chunk.
+ * @internal
+ */
+export declare function normalizeLlmFailure(value: unknown): LlmFailure;
+//# sourceMappingURL=adapter-failure.d.ts.map

package/lib/types/adapter-failure.js

@@ -0,0 +1,105 @@
+/**
+ * Normalization for values thrown by a final LLM adapter boundary.
+ *
+ * @module @stackstackstack/dsh-llm/adapter-failure
+ */
+import { HarnessError } from "./error.js";
+/**
+ * Detach serializable provider facts from a value thrown by an adapter.
+ * @param value - arbitrary value thrown during adapter dispatch or iteration.
+ * @returns immutable provider-neutral facts suitable for a terminal finish chunk.
+ * @internal
+ */
+export function normalizeLlmFailure(value) {
+    const error = value instanceof Error
+        ? value
+        : new HarnessError(thrownMessage(value), 'UNKNOWN', { cause: value });
+    // Cross-package copies preserve own data but not class identity. Trust the
+    // carried facts only when both own properties agree after validation.
+    const carried = ownFailureSnapshot(error);
+    if (carried !== undefined && carried.code === ownErrorCode(error))
+        return carried;
+    return Object.freeze({
+        message: errorMessage(error),
+        code: harnessErrorCode(error),
+    });
+}
+/** Render a non-Error throw without letting hostile coercion escape normalization. */
+function thrownMessage(value) {
+    try {
+        const message = String(value);
+        return message.length > 0 ? message : 'LLM adapter failed';
+    }
+    catch (_hostileThrownValue) {
+        return 'LLM adapter failed';
+    }
+}
+/** Read a foreign error's own data-backed `code` without invoking accessors. */
+function ownErrorCode(error) {
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(error, 'code');
+        return descriptor !== undefined && 'value' in descriptor ? descriptor.value : undefined;
+    }
+    catch (_sdkPropertyTrap) {
+        return undefined;
+    }
+}
+/** Snapshot an own data property without invoking an SDK-defined accessor. */
+function ownFailureSnapshot(error) {
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(error, 'failure');
+        return descriptor !== undefined && 'value' in descriptor
+            ? failureSnapshot(descriptor.value)
+            : undefined;
+    }
+    catch (_sdkPropertyTrap) {
+        return undefined;
+    }
+}
+/** Validate and detach an arbitrary serializable failure payload. */
+function failureSnapshot(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    try {
+        const candidate = value;
+        const message = candidate.message;
+        const code = candidate.code;
+        const status = candidate.status;
+        const providerRetryAfterMs = candidate.providerRetryAfterMs;
+        const requestId = candidate.requestId;
+        if (typeof message !== 'string' || message.length === 0
+            || typeof code !== 'string' || code.length === 0
+            || (status !== undefined && (!Number.isInteger(status) || status < 100 || status > 599))
+            || (providerRetryAfterMs !== undefined
+                && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0))
+            || (requestId !== undefined && (typeof requestId !== 'string' || requestId.length === 0)))
+            return undefined;
+        return Object.freeze({
+            message,
+            code,
+            ...status === undefined ? {} : { status },
+            ...providerRetryAfterMs === undefined ? {} : { providerRetryAfterMs },
+            ...requestId === undefined ? {} : { requestId },
+        });
+    }
+    catch (_sdkFailureGetter) {
+        return undefined;
+    }
+}
+/** Read an SDK error message without letting an accessor replace the primary failure. */
+function errorMessage(error) {
+    try {
+        const message = error.message;
+        if (typeof message === 'string' && message.length > 0)
+            return message;
+    }
+    catch (_sdkMessageGetter) {
+        // The fallback below preserves a serializable failure beside the original Error.
+    }
+    return 'LLM adapter failed';
+}
+/** Trust only Harness-owned codes; third-party SDK codes are not our taxonomy. */
+function harnessErrorCode(error) {
+    return error instanceof HarnessError ? error.code : 'UNKNOWN';
+}
+//# sourceMappingURL=adapter-failure.js.map

package/lib/types/api-key.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The one definition of a well-formed provider API key, shared by every
+ * adapter that puts one in an HTTP header.
+ * @module @stackstackstack/dsh-llm/api-key
+ */
+/** Why a supplied API key cannot be used. */
+export type ApiKeyRejection = 'empty' | 'illegalCharacters';
+/** The verdict on one supplied API key. */
+export type ApiKeyCheck = {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly reason: ApiKeyRejection;
+};
+/**
+ * Judge one *supplied* API key, trimming surrounding whitespace first.
+ *
+ * Trimming is silent because a padded key has one unambiguous reading; every
+ * other defect is reported. Absence is a configuration state this function
+ * never sees — a profile naming no credential authenticates through the
+ * provider's own ambient discovery or OAuth — so callers decide whether a
+ * value was supplied before asking.
+ * @param raw - the key exactly as configured, stored, or typed.
+ * @returns the trimmed key, or why it cannot be used.
+ */
+export declare function normalizeApiKey(raw: string): ApiKeyCheck;
+//# sourceMappingURL=api-key.d.ts.map

package/lib/types/api-key.js

@@ -0,0 +1,34 @@
+/**
+ * The one definition of a well-formed provider API key, shared by every
+ * adapter that puts one in an HTTP header.
+ * @module @stackstackstack/dsh-llm/api-key
+ */
+/**
+ * Characters an HTTP header value carries verbatim and every known provider
+ * key uses: printable ASCII, space excluded. A key outside this set cannot
+ * reach any provider — `fetch` refuses to build the header — so this is a
+ * transport invariant rather than one provider's policy. Latin-1 is excluded
+ * deliberately: a header could carry it, but no provider issues it, and
+ * admitting it trades a local explained refusal for an opaque 401.
+ */
+const LEGAL_API_KEY = /^[\x21-\x7E]+$/;
+/**
+ * Judge one *supplied* API key, trimming surrounding whitespace first.
+ *
+ * Trimming is silent because a padded key has one unambiguous reading; every
+ * other defect is reported. Absence is a configuration state this function
+ * never sees — a profile naming no credential authenticates through the
+ * provider's own ambient discovery or OAuth — so callers decide whether a
+ * value was supplied before asking.
+ * @param raw - the key exactly as configured, stored, or typed.
+ * @returns the trimmed key, or why it cannot be used.
+ */
+export function normalizeApiKey(raw) {
+    const value = raw.trim();
+    if (value.length === 0)
+        return { ok: false, reason: 'empty' };
+    if (!LEGAL_API_KEY.test(value))
+        return { ok: false, reason: 'illegalCharacters' };
+    return { ok: true, value };
+}
+//# sourceMappingURL=api-key.js.map

package/lib/types/assembler.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Incremental chunk-to-message assembler. This is the single canonical assembly
+ * algorithm used by the agent loop to build an assistant message from a chunk
+ * stream while logging the raw chunks for replay fidelity.
+ *
+ * @module @stackstackstack/dsh-llm/assembler
+ */
+import type { Message, MessageSource } from './message.ts';
+import type { ContentBlock, FinishReason, StreamChunk, TokenUsage } from './types.ts';
+/**
+ * Incrementally assembles raw {@link StreamChunk}s into complete
+ * {@link ContentBlock}s and a final assistant {@link Message}.
+ *
+ * The agent loop feeds it while logging raw chunks for replay fidelity, then
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ *
+ * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
+ * an index already closed by `block-end` are ignored (malformed stream) so a
+ * misbehaving adapter cannot grow memory or corrupt a completed block.
+ */
+export declare class BlockAssembler {
+    private partials;
+    private order;
+    private _usage;
+    private _finish;
+    private _replayState;
+    /**
+     * Feed one chunk into the assembly state.
+     * @param chunk - the next raw chunk, in stream order.
+     */
+    push(chunk: StreamChunk): void;
+    private ensure;
+    private assemble;
+    /** Invariant accessor: every index in `order` has a partial. */
+    private mustGet;
+    /**
+     * Assemble all blocks seen so far, in stream order.
+     * @returns one block per seen index, except that max-token truncation drops
+     *   tool calls that cannot be executed safely; an open block assembles from
+     *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
+     */
+    blocks(): ContentBlock[];
+    /** Usage from the `usage` chunk; undefined until one arrives. */
+    get usage(): TokenUsage | undefined;
+    /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
+    get finish(): FinishReason;
+    /** Adapter-private replay state from the terminal finish chunk, if any. */
+    get replayState(): unknown;
+    /**
+     * The assembled assistant message.
+     * @param source - producer attribution for the assembled message.
+     * @returns a frozen assistant-role message over `blocks()` (same open-block assembly rules).
+     */
+    message(source?: MessageSource): Message;
+}
+//# sourceMappingURL=assembler.d.ts.map

package/lib/types/assembler.js

@@ -0,0 +1,148 @@
+/**
+ * Incremental chunk-to-message assembler. This is the single canonical assembly
+ * algorithm used by the agent loop to build an assistant message from a chunk
+ * stream while logging the raw chunks for replay fidelity.
+ *
+ * @module @stackstackstack/dsh-llm/assembler
+ */
+import { CallId } from "./brand.js";
+import { assertNever } from "./never.js";
+import { createMessage } from "./message.js";
+/**
+ * Incrementally assembles raw {@link StreamChunk}s into complete
+ * {@link ContentBlock}s and a final assistant {@link Message}.
+ *
+ * The agent loop feeds it while logging raw chunks for replay fidelity, then
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ *
+ * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
+ * an index already closed by `block-end` are ignored (malformed stream) so a
+ * misbehaving adapter cannot grow memory or corrupt a completed block.
+ */
+export class BlockAssembler {
+    partials = new Map();
+    order = [];
+    _usage;
+    _finish;
+    _replayState = undefined;
+    /**
+     * Feed one chunk into the assembly state.
+     * @param chunk - the next raw chunk, in stream order.
+     */
+    push(chunk) {
+        switch (chunk.type) {
+            case 'block-start': {
+                if (!this.partials.has(chunk.index)) {
+                    this.order.push(chunk.index);
+                    this.partials.set(chunk.index, {
+                        blockType: chunk.blockType,
+                        text: '',
+                        toolCallArguments: '',
+                    });
+                }
+                return;
+            }
+            case 'text-delta':
+            case 'reasoning-delta': {
+                const partial = this.ensure(chunk.index, chunk.type === 'text-delta' ? 'text' : 'reasoning');
+                if (partial.block)
+                    return; // closed by block-end; ignore stragglers
+                partial.text += chunk.text;
+                return;
+            }
+            case 'tool-call-delta': {
+                const partial = this.ensure(chunk.index, 'tool-call');
+                if (partial.block)
+                    return; // closed by block-end; ignore stragglers
+                partial.toolCallId = chunk.id;
+                if (chunk.name)
+                    partial.toolCallName = chunk.name;
+                partial.toolCallArguments += chunk.argumentsDelta;
+                return;
+            }
+            case 'block-end': {
+                const partial = this.ensure(chunk.index, chunk.block.type);
+                // First close wins; ignoring re-close stragglers keeps streamed output
+                // and the final assembled block in agreement.
+                if (partial.block)
+                    return;
+                partial.block = chunk.block;
+                return;
+            }
+            case 'usage': {
+                this._usage = chunk.usage;
+                return;
+            }
+            case 'finish': {
+                this._finish = chunk.reason;
+                this._replayState = chunk.replayState;
+                return;
+            }
+            default: return assertNever(chunk, 'BlockAssembler.push');
+        }
+    }
+    ensure(index, blockType) {
+        let partial = this.partials.get(index);
+        if (!partial) {
+            partial = { blockType, text: '', toolCallArguments: '' };
+            this.partials.set(index, partial);
+            this.order.push(index);
+        }
+        return partial;
+    }
+    assemble(partial, index) {
+        if (partial.block)
+            return partial.block;
+        switch (partial.blockType) {
+            case 'text': return { type: 'text', text: partial.text };
+            case 'reasoning': return { type: 'reasoning', text: partial.text };
+            case 'tool-call': return {
+                type: 'tool-call',
+                id: partial.toolCallId ?? CallId(`call-${index}`),
+                name: partial.toolCallName ?? '',
+                arguments: partial.toolCallArguments,
+            };
+            default: throw new Error(`cannot assemble incomplete block of type "${partial.blockType}"`);
+        }
+    }
+    /** Invariant accessor: every index in `order` has a partial. */
+    mustGet(index) {
+        const partial = this.partials.get(index);
+        if (!partial)
+            throw new Error(`BlockAssembler invariant violated: no partial for index ${index}`);
+        return partial;
+    }
+    /**
+     * Assemble all blocks seen so far, in stream order.
+     * @returns one block per seen index, except that max-token truncation drops
+     *   tool calls that cannot be executed safely; an open block assembles from
+     *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
+     */
+    blocks() {
+        const blocks = this.order.map(index => this.assemble(this.mustGet(index), index));
+        return this.finish.kind === 'max-tokens'
+            ? blocks.filter(block => block.type !== 'tool-call')
+            : blocks;
+    }
+    /** Usage from the `usage` chunk; undefined until one arrives. */
+    get usage() {
+        return this._usage;
+    }
+    /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
+    get finish() {
+        return this._finish ?? { kind: 'stop' };
+    }
+    /** Adapter-private replay state from the terminal finish chunk, if any. */
+    get replayState() {
+        return this._replayState;
+    }
+    /**
+     * The assembled assistant message.
+     * @param source - producer attribution for the assembled message.
+     * @returns a frozen assistant-role message over `blocks()` (same open-block assembly rules).
+     */
+    message(source = { kind: 'plugin', plugin: 'dsh-llm/assembler' }) {
+        return createMessage({ role: 'assistant', content: this.blocks(), source });
+    }
+}
+//# sourceMappingURL=assembler.js.map

package/lib/types/attribution.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 @stackstackstack/dsh-llm/attribution
+ */
+/**
+ * Static public application identity sent to LLM providers.
+ *
+ * Every field is a public product fact, safe on every request: no secrets,
+ * local paths, session ids, prompt text, or per-user identifiers belong here,
+ * and nothing per-request may influence the values.
+ */
+export interface AppIdentity {
+    /** `User-Agent` product token (lowercase, hyphenated). */
+    product: string;
+    /** Product version; sourced from package metadata, never hand-copied. */
+    version: string;
+    /** Repository home URL of the app, used as the `User-Agent` comment. */
+    url: string;
+}
+/**
+ * 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 declare const APP_IDENTITY: AppIdentity;
+/**
+ * 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 declare function userAgent(identity?: AppIdentity): string;
+/**
+ * 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 declare function attributionHeaders(identity?: AppIdentity): Record<string, string>;
+//# sourceMappingURL=attribution.d.ts.map

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 @stackstackstack/dsh-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: 'deepseek-harness',
+    version,
+    url: 'https://github.com/deepseek-ai/deepseek-harness',
+};
+/**
+ * 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,48 @@
+/**
+ * dsh-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive itself lives in `@stackstackstack/dsh-brand` (a
+ * zero-dependency type-only package) 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 @stackstackstack/dsh-llm/brand
+ */
+import type { Branded } from '@stackstackstack/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, branded; no validation is performed.
+ */
+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 CallId = Branded<'CallId'>;
+/**
+ * Brand a string as a {@link CallId}.
+ * @param id - the provider-issued (or synthesized) call id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function CallId(id: string): CallId;
+/** 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,44 @@
+/**
+ * dsh-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive itself lives in `@stackstackstack/dsh-brand` (a
+ * zero-dependency type-only package) 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 @stackstackstack/dsh-llm/brand
+ */
+/**
+ * Brand a message identifier.
+ * @param id - the opaque message identifier.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function MessageId(id) {
+    return id;
+}
+/**
+ * Brand a string as a {@link CallId}.
+ * @param id - the provider-issued (or synthesized) call id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CallId(id) {
+    return 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 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 id;
+}
+//# sourceMappingURL=brand.js.map