@xlaunch/llm 0.2.0-beta.1

package/lib/typert.remote-client.d.ts

@@ -0,0 +1,26 @@
+/* Generated by @xlaunch/typert-generator from the Host FaceModel — do not edit. */
+import type {
+  RemoteResult,
+  TypertRemoteContribution,
+} from '@xlaunch/typert-protocol'
+import type { LlmConfigurableProvider, LlmDiscoveredModel, LlmModelDiscoveryRequest, LlmProviderInfo } from '@xlaunch/llm/types'
+
+declare module '@xlaunch/typert-protocol' {
+  interface TypertRemoteNamespace$6c6c6d {
+    discoverModels: (settingsNs: string, request: LlmModelDiscoveryRequest, signal?: AbortSignal) => Promise<RemoteResult<LlmDiscoveredModel[]>>
+    listConfigurableProviders: () => Promise<RemoteResult<LlmConfigurableProvider[]>>
+    listProviders: () => Promise<RemoteResult<LlmProviderInfo[]>>
+  }
+  interface TypertRemoteMap {
+    'llm/discoverModels': (settingsNs: string, request: LlmModelDiscoveryRequest, signal?: AbortSignal) => Promise<RemoteResult<LlmDiscoveredModel[]>>
+    'llm/listConfigurableProviders': () => Promise<RemoteResult<LlmConfigurableProvider[]>>
+    'llm/listProviders': () => Promise<RemoteResult<LlmProviderInfo[]>>
+  }
+  interface TypertRemoteNamespaceMap {
+    'llm': TypertRemoteNamespace$6c6c6d
+  }
+}
+
+export declare const TYPERT_REMOTE: TypertRemoteContribution
+export default TYPERT_REMOTE
+//# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -0,0 +1,102 @@
+/* Generated by @xlaunch/typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+const _xlaunch_llm_llm_discoverModels_parameter_0$schema = z.string()
+const _xlaunch_llm_llm_discoverModels_parameter_1$schema = z.object({
+  'provider': z.string().optional(),
+  'baseURL': z.string().optional(),
+  'api': z.string().optional(),
+  'apiKey': z.string().optional(),
+})
+const _xlaunch_llm_llm_discoverModels_result$schema = z.array(z.object({
+  'id': z.string(),
+  'name': z.string().optional(),
+  'contextWindow': z.number().optional(),
+  'maxTokens': z.number().optional(),
+}))
+const _xlaunch_llm_llm_listConfigurableProviders_result$schema = z.array(z.object({
+  'provider': z.string(),
+  'displayName': z.string(),
+  'settingsNs': z.string(),
+  'settingsPath': z.array(z.string()),
+  'declared': z.boolean().optional(),
+}))
+const _xlaunch_llm_llm_listProviders_result$schema = z.array(z.object({
+  'id': z.string(),
+  'name': z.string(),
+}))
+
+export const TYPERT_REMOTE = {
+  package: '@xlaunch/llm',
+  descriptors: [
+    {
+      id: '@xlaunch/llm#llm/discoverModels',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'discoverModels',
+      implementation: 'remoteDiscoverModels',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'settingsNs',
+          wire: 'settingsNs',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@xlaunch/llm#llm/discoverModels:settingsNs',
+            schema: _xlaunch_llm_llm_discoverModels_parameter_0$schema,
+          },
+        },
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@xlaunch/llm/types#LlmModelDiscoveryRequest',
+            schema: _xlaunch_llm_llm_discoverModels_parameter_1$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@xlaunch/llm#llm/discoverModels:result',
+        schema: _xlaunch_llm_llm_discoverModels_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":625,"column":9},
+    },
+    {
+      id: '@xlaunch/llm#llm/listConfigurableProviders',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'listConfigurableProviders',
+      invocation: { kind: 'direct' },
+      parameters: [
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@xlaunch/llm#llm/listConfigurableProviders:result',
+        schema: _xlaunch_llm_llm_listConfigurableProviders_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":538,"column":3},
+    },
+    {
+      id: '@xlaunch/llm#llm/listProviders',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'listProviders',
+      invocation: { kind: 'direct' },
+      parameters: [
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@xlaunch/llm#llm/listProviders:result',
+        schema: _xlaunch_llm_llm_listProviders_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":466,"column":3},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

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

@@ -0,0 +1,14 @@
+/**
+ * Normalization for values thrown by a final LLM adapter boundary.
+ *
+ * @module @xlaunch/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 @xlaunch/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 @xlaunch/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 @xlaunch/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,75 @@
+/**
+ * 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 @xlaunch/llm/assembler
+ */
+import type { Message, MessageSource } from './message.ts';
+import type { ContentBlock, FinishReason, ReplayEnvelope, 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,
+ * or `interruptedBlocks()` when cancellation cut the stream short.
+ *
+ * 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;
+    /**
+     * The one shared keep/drop decision over all seen blocks: max-token
+     * truncation drops tool calls that cannot be executed safely. Emitted blocks
+     * and replay metadata both derive from this result, so they cannot disagree.
+     */
+    private assembled;
+    /**
+     * 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[];
+    /**
+     * Assemble the prefix an interrupted stream can safely finalize: closed and
+     * open text/reasoning blocks with non-whitespace content, in stream order.
+     * Tool calls are omitted because interruption precedes dispatch; retaining
+     * one would require a fabricated result. Open unknown blocks are also omitted.
+     * @returns the kept blocks; empty when nothing streamed before the interruption.
+     */
+    interruptedBlocks(): 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;
+    /**
+     * Replay metadata from the terminal finish chunk, if any, with per-block
+     * entries pruned in step with {@link blocks}. Undefined when the envelope's
+     * entries do not align with the emitted blocks.
+     */
+    get replayState(): ReplayEnvelope | undefined;
+    /**
+     * 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,191 @@
+/**
+ * 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 @xlaunch/llm/assembler
+ */
+import { brandString } from '@xlaunch/brand';
+import { assertNever } from '@xlaunch/util-values';
+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,
+ * or `interruptedBlocks()` when cancellation cut the stream short.
+ *
+ * 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;
+    /**
+     * 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 ?? brandString(`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;
+    }
+    /**
+     * The one shared keep/drop decision over all seen blocks: max-token
+     * truncation drops tool calls that cannot be executed safely. Emitted blocks
+     * and replay metadata both derive from this result, so they cannot disagree.
+     */
+    assembled() {
+        const all = this.order.map(index => this.assemble(this.mustGet(index), index));
+        const kept = this.finish.kind === 'max-tokens'
+            ? all.map(block => block.type !== 'tool-call')
+            : undefined;
+        const blocks = kept === undefined ? all : all.filter((_, position) => kept[position]);
+        const envelope = this._replayState;
+        if (envelope?.blocks === undefined)
+            return { blocks, replay: envelope };
+        if (envelope.blocks.length !== all.length)
+            return { blocks, replay: undefined };
+        return {
+            blocks,
+            replay: kept === undefined || blocks.length === all.length
+                ? envelope
+                : { response: envelope.response, blocks: envelope.blocks.filter((_, position) => kept[position]) },
+        };
+    }
+    /**
+     * 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() {
+        return this.assembled().blocks;
+    }
+    /**
+     * Assemble the prefix an interrupted stream can safely finalize: closed and
+     * open text/reasoning blocks with non-whitespace content, in stream order.
+     * Tool calls are omitted because interruption precedes dispatch; retaining
+     * one would require a fabricated result. Open unknown blocks are also omitted.
+     * @returns the kept blocks; empty when nothing streamed before the interruption.
+     */
+    interruptedBlocks() {
+        return this.order
+            .map((index) => {
+            const partial = this.mustGet(index);
+            const type = partial.block?.type ?? partial.blockType;
+            if (type !== 'text' && type !== 'reasoning')
+                return undefined;
+            return this.assemble(partial, index);
+        })
+            .filter((block) => (block?.type === 'text' || block?.type === 'reasoning') && block.text.trim() !== '');
+    }
+    /** 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' };
+    }
+    /**
+     * Replay metadata from the terminal finish chunk, if any, with per-block
+     * entries pruned in step with {@link blocks}. Undefined when the envelope's
+     * entries do not align with the emitted blocks.
+     */
+    get replayState() {
+        return this.assembled().replay;
+    }
+    /**
+     * 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: 'xlaunch-llm/assembler' }) {
+        return createMessage({ role: 'assistant', content: this.blocks(), source });
+    }
+}
+//# sourceMappingURL=assembler.js.map