@plumbus/core 0.2.9 → 0.3.1

package/dist/ai/provider.d.ts

@@ -1,9 +1,33 @@
 import type { AIProviderConfig } from '../types/config.js';
+import { type Kind } from './model-pricing.js';
+/**
+ * A single chat-history turn. Used for native multi-turn requests where the
+ * model should see real conversation flow (assistant + user alternation).
+ * Optional — when omitted, providers fall back to single-user-message mode
+ * built from `ProviderRequest.prompt`.
+ */
+export interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
 export interface ProviderRequest {
     /** System prompt / instructions */
     system?: string;
-    /** User prompt content */
+    /**
+     * User prompt content. Used as the SOLE user message when `messages` is
+     * absent. When `messages` is provided, this field is IGNORED — the messages
+     * array is the conversation. Callers passing `messages` may still set
+     * `prompt: ''` for type-compat.
+     */
     prompt: string;
+    /**
+     * Optional native multi-turn conversation history. When present, providers
+     * send `[system?, ...messages]` to the API instead of `[system?, {role:'user', content: prompt}]`.
+     * The LAST entry should be a `user` message (the latest turn). Order is
+     * preserved exactly as supplied. Empty array is treated as "no messages"
+     * (falls back to single-user mode using `prompt`).
+     */
+    messages?: ChatMessage[];
     /** Model name override */
     model?: string;
     /** Temperature (0-2) */
@@ -12,9 +36,30 @@ export interface ProviderRequest {
     maxTokens?: number;
     /** Response format hint */
     responseFormat?: 'text' | 'json';
+    /** Provider-compatible JSON Schema for strict structured outputs. */
+    responseSchema?: Record<string, unknown>;
+    /** Transport used for provider-side structured outputs. Defaults to response_format. */
+    structuredOutputTransport?: 'response_format' | 'tool';
     /** Request timeout in milliseconds (default: 120_000) */
     timeout?: number;
+    /**
+     * External AbortSignal (e.g. `ctx.signal`). When fired, the in-flight
+     * fetch(es) for this request abort immediately. Combined with the internal
+     * timeout signal via `AbortSignal.any([...])`, so whichever triggers first
+     * wins.
+     */
+    signal?: AbortSignal;
+    /**
+     * Deterministic sampling seed. OpenAI-compatible providers (including xAI
+     * Grok) honor this parameter: identical `{seed, temperature, model, prompt}`
+     * tuples produce the same tokens. Combined with `temperature: 0`, lets
+     * callers pin reproducible output for structural-planning prompts. Ignored
+     * by providers that do not support it.
+     */
+    seed?: number;
 }
+/** Compose a request's optional user signal with a timeout, returning a single AbortSignal. */
+export declare function combineRequestSignals(userSignal: AbortSignal | undefined, timeoutMs: number): AbortSignal;
 export interface ProviderResponse {
     content: string;
     model: string;
@@ -52,6 +97,40 @@ export interface EmbeddingResponse {
         totalTokens: number;
     };
 }
+/**
+ * A single model entry returned by `AIProviderAdapter.listModels()`.
+ * The id is whatever the provider's `/v1/models` returns; pricing and `kind`
+ * are joined from the framework's pricing catalog. Models not in the catalog
+ * surface as `kind: 'unknown'` with `null` prices.
+ */
+export interface ProviderModel {
+    /** API identifier (the value to pass as `model` in requests). */
+    id: string;
+    /** Adapter name (e.g. "openai", "anthropic", or a custom adapter's name). */
+    provider: string;
+    /** Capability classification, from the pricing catalog. `'unknown'` if not in the catalog. */
+    kind: Kind | 'unknown';
+    /** USD per 1M input tokens, or `null` if the model is not in the catalog. */
+    inputPerMTok: number | null;
+    /** USD per 1M output tokens, or `null` if the model is not in the catalog. */
+    outputPerMTok: number | null;
+    /** Provider-supplied human-readable label (Anthropic exposes this; OpenAI doesn't). */
+    displayName?: string;
+    /** ISO-8601 creation timestamp when the provider exposes one. */
+    createdAt?: string;
+    /** Owner/team (OpenAI exposes this; Anthropic doesn't). */
+    ownedBy?: string;
+}
+/**
+ * Optional filter passed to `AIProviderAdapter.listModels()`. `kind` accepts a
+ * single Kind or an array. When unset, all models are returned (including
+ * unknown ones). When set against an official endpoint, unknown-kind models
+ * are excluded; against a custom endpoint they are included alongside the
+ * filtered matches (see adapter docs).
+ */
+export interface ListModelsFilter {
+    kind?: Kind | Kind[];
+}
 export interface AIProviderAdapter {
     readonly name: string;
     /** Send a completion request */
@@ -60,7 +139,37 @@ export interface AIProviderAdapter {
     stream(request: ProviderRequest): AsyncIterable<ProviderStreamEvent>;
     /** Generate embeddings for texts */
     embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
+    /**
+     * List models the provider exposes for this account, joined against the
+     * framework's pricing catalog. Optional — custom adapters that don't
+     * implement it still satisfy the interface.
+     *
+     * Filtering rule (see docs for full details):
+     * - No filter → all models, including unknown-kind entries.
+     * - Filter + official endpoint → only matching kinds; unknowns excluded.
+     * - Filter + custom endpoint → matching kinds **plus** all unknowns.
+     *
+     * On network error / 404 / unsupported endpoint, returns `[]` and emits
+     * one `console.warn`; does not throw.
+     */
+    listModels?(filter?: ListModelsFilter): Promise<ProviderModel[]>;
 }
+/**
+ * Shared logic used by adapter `listModels` implementations: join a list of
+ * provider-supplied model entries against the pricing catalog, then apply
+ * the kind filter respecting the official-endpoint rule.
+ */
+export declare function joinAndFilterModels(args: {
+    provider: string;
+    entries: Array<{
+        id: string;
+        displayName?: string;
+        createdAt?: string;
+        ownedBy?: string;
+    }>;
+    filter: ListModelsFilter | undefined;
+    isOfficial: boolean;
+}): ProviderModel[];
 export declare class ProviderAPIError extends Error {
     readonly providerName: string;
     readonly statusCode?: number;

package/dist/ai/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAK/D;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,wFAAwF;IACxF,yBAAyB,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;IACvD,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,WAAW,GAAG,SAAS,EACnC,SAAS,EAAE,MAAM,GAChB,WAAW,CAIb;AAGD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAGD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACnD,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAID;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;IACvB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC;CACtB;AAGD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE9D,+DAA+D;IAC/D,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAErE,oCAAoC;IACpC,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE7D;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAClE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACrC,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,aAAa,EAAE,CAuClB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,IAAI,EAAE;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;CAQF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAW5E;AAsND,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,CAsQlF;AAGD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,iBAAiB,CAsNxF;AAuJD,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,gBAAgB,GAC/B,iBAAiB,CAiBnB"}

package/dist/ai/provider.js

@@ -1,5 +1,56 @@
 // ── AI Provider Adapter Interface ──
 // Abstract interface for AI provider adapters (OpenAI, Anthropic, etc.)
+import { allKnownModels } from './model-pricing.js';
+import { AIIncompleteOutputError, AIRefusalError } from './refusal.js';
+/** Compose a request's optional user signal with a timeout, returning a single AbortSignal. */
+export function combineRequestSignals(userSignal, timeoutMs) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (!userSignal)
+        return timeoutSignal;
+    return AbortSignal.any([userSignal, timeoutSignal]);
+}
+/**
+ * Shared logic used by adapter `listModels` implementations: join a list of
+ * provider-supplied model entries against the pricing catalog, then apply
+ * the kind filter respecting the official-endpoint rule.
+ */
+export function joinAndFilterModels(args) {
+    const catalog = new Map(allKnownModels()
+        .filter(([, rate]) => rate.kind != null)
+        .map(([id, rate]) => [
+        id,
+        {
+            kind: rate.kind,
+            inputPerMTok: rate.inputPerMTok,
+            outputPerMTok: rate.outputPerMTok,
+        },
+    ]));
+    const joined = args.entries.map((e) => {
+        const cat = catalog.get(e.id);
+        const model = {
+            id: e.id,
+            provider: args.provider,
+            kind: cat?.kind ?? 'unknown',
+            inputPerMTok: cat?.inputPerMTok ?? null,
+            outputPerMTok: cat?.outputPerMTok ?? null,
+        };
+        if (e.displayName != null)
+            model.displayName = e.displayName;
+        if (e.createdAt != null)
+            model.createdAt = e.createdAt;
+        if (e.ownedBy != null)
+            model.ownedBy = e.ownedBy;
+        return model;
+    });
+    if (!args.filter?.kind)
+        return joined;
+    const allowedKinds = new Set(Array.isArray(args.filter.kind) ? args.filter.kind : [args.filter.kind]);
+    return joined.filter((m) => {
+        if (m.kind === 'unknown')
+            return !args.isOfficial;
+        return allowedKinds.has(m.kind);
+    });
+}
 export class ProviderAPIError extends Error {
     providerName;
     statusCode;
@@ -52,6 +103,89 @@ function computeRetryDelayMs(attempt, retryAfterHeader) {
     }
     return Math.min(baseRetryDelayMs * 2 ** (attempt - 1), maxRetryDelayMs);
 }
+function buildOpenAIResponseFormat(request) {
+    if (request.responseFormat !== 'json')
+        return undefined;
+    if (!request.responseSchema)
+        return { type: 'json_object' };
+    return {
+        type: 'json_schema',
+        json_schema: {
+            name: 'response',
+            strict: true,
+            schema: request.responseSchema,
+        },
+    };
+}
+const OPENAI_STRUCTURED_OUTPUT_TOOL_NAME = 'return_structured_response';
+function shouldUseOpenAIStructuredTool(args) {
+    return (args.request.structuredOutputTransport === 'tool' &&
+        args.request.responseFormat === 'json' &&
+        !!args.request.responseSchema);
+}
+function buildOpenAIStructuredOutputTool(schema) {
+    return {
+        type: 'function',
+        function: {
+            name: OPENAI_STRUCTURED_OUTPUT_TOOL_NAME,
+            description: 'Return the complete structured response for this request.',
+            strict: true,
+            parameters: schema,
+        },
+    };
+}
+function extractOpenAIMessageContent(message) {
+    const structuredToolCall = message.tool_calls?.find((toolCall) => toolCall.function?.name === OPENAI_STRUCTURED_OUTPUT_TOOL_NAME);
+    const toolArguments = structuredToolCall?.function?.arguments;
+    if (typeof toolArguments === 'string' && toolArguments.length > 0) {
+        return toolArguments;
+    }
+    return message.content ?? '';
+}
+function buildEmptyOpenAIStructuredContentError(args) {
+    const messageKeys = Object.keys(args.choice.message).join(',');
+    const toolCallSummary = args.choice.message.tool_calls
+        ?.map((toolCall) => {
+        const name = toolCall.function?.name ?? 'unknown';
+        const argumentLength = toolCall.function?.arguments?.length ?? 0;
+        return `${name}:argumentsChars=${argumentLength}`;
+    })
+        .join('|') ?? 'none';
+    return new Error(`OpenAI-compatible provider returned empty JSON response content ` +
+        `finish_reason=${args.choice.finish_reason} messageKeys=${messageKeys || 'none'} ` +
+        `hasRefusal=${args.choice.message.refusal ? 'true' : 'false'} ` +
+        `toolCalls=${toolCallSummary}`);
+}
+function openAIUsageToTokenUsage(usage) {
+    return {
+        inputTokens: usage.prompt_tokens,
+        outputTokens: usage.completion_tokens,
+        totalTokens: usage.total_tokens,
+        cachedInputTokens: usage.prompt_tokens_details?.cached_tokens ?? 0,
+    };
+}
+function shouldUseOpenAIMaxCompletionTokens(model) {
+    const normalizedModel = model.trim().toLowerCase();
+    return /^(?:o\d|o\d-|o\d\.)/.test(normalizedModel) || normalizedModel.startsWith('gpt-5');
+}
+function applyOpenAITokenLimit(body, model, maxTokens) {
+    if (!maxTokens)
+        return;
+    if (shouldUseOpenAIMaxCompletionTokens(model)) {
+        body.max_completion_tokens = maxTokens;
+        return;
+    }
+    body.max_tokens = maxTokens;
+}
+function anthropicUsageToTokenUsage(usage) {
+    return {
+        inputTokens: usage.input_tokens,
+        outputTokens: usage.output_tokens,
+        totalTokens: usage.input_tokens + usage.output_tokens,
+        cachedInputTokens: usage.cache_read_input_tokens ?? 0,
+        cacheWriteTokens: usage.cache_creation_input_tokens ?? 0,
+    };
+}
 async function waitForRetry(delayMs) {
     await new Promise((resolve) => setTimeout(resolve, delayMs));
 }
@@ -94,20 +228,46 @@ export function createOpenAIAdapter(config) {
     return {
         name: 'openai',
         async complete(request) {
+            const model = request.model ?? defaultModel;
             const messages = [];
             if (request.system) {
                 messages.push({ role: 'system', content: request.system });
             }
-            messages.push({ role: 'user', content: request.prompt });
+            // Multi-turn path: when `messages` is supplied, append them verbatim
+            // (preserving role + order). Single-turn path (legacy): build a single
+            // user message from `prompt`.
+            if (request.messages && request.messages.length > 0) {
+                for (const msg of request.messages) {
+                    messages.push({ role: msg.role, content: msg.content });
+                }
+            }
+            else {
+                messages.push({ role: 'user', content: request.prompt });
+            }
             const body = {
-                model: request.model ?? defaultModel,
+                model,
                 messages,
                 temperature: request.temperature ?? 0.7,
             };
-            if (request.maxTokens)
-                body.max_tokens = request.maxTokens;
-            if (request.responseFormat === 'json') {
-                body.response_format = { type: 'json_object' };
+            applyOpenAITokenLimit(body, model, request.maxTokens);
+            const structuredToolSchema = shouldUseOpenAIStructuredTool({ request })
+                ? request.responseSchema
+                : undefined;
+            if (structuredToolSchema) {
+                body.tools = [buildOpenAIStructuredOutputTool(structuredToolSchema)];
+                body.tool_choice = {
+                    type: 'function',
+                    function: { name: OPENAI_STRUCTURED_OUTPUT_TOOL_NAME },
+                };
+            }
+            else {
+                const responseFormat = buildOpenAIResponseFormat(request);
+                if (responseFormat) {
+                    body.response_format = responseFormat;
+                }
+            }
+            if (typeof request.seed === 'number') {
+                body.seed = request.seed;
             }
             const resp = await executeRequestWithRetry({
                 providerName: 'openai',
@@ -119,42 +279,77 @@ export function createOpenAIAdapter(config) {
                         Authorization: `Bearer ${config.apiKey}`,
                     },
                     body: JSON.stringify(body),
-                    signal: AbortSignal.timeout(request.timeout ?? defaultTimeout),
+                    signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
                 }),
             });
             const data = (await resp.json());
             const choice = data.choices[0];
             if (!choice)
                 throw new Error('OpenAI returned no choices');
+            const usage = openAIUsageToTokenUsage(data.usage);
+            const content = extractOpenAIMessageContent(choice.message);
+            if (choice.message.refusal) {
+                throw new AIRefusalError({
+                    provider: 'openai',
+                    model: data.model,
+                    refusalText: choice.message.refusal,
+                    usage,
+                });
+            }
+            // Only treat `finish_reason === 'length'` as a hard failure when the
+            // caller asked for structured JSON output. For free-text generation,
+            // a `length` finish is a partial-success: return what we have rather
+            // than discarding tokens the caller already paid for.
+            if (choice.finish_reason === 'length' &&
+                (request.responseFormat === 'json' || !!request.responseSchema)) {
+                throw new AIIncompleteOutputError({
+                    provider: 'openai',
+                    model: data.model,
+                    partialText: content,
+                    usage,
+                    finishReason: choice.finish_reason,
+                });
+            }
+            if (request.responseFormat === 'json' && content.trim().length === 0) {
+                throw buildEmptyOpenAIStructuredContentError({ data, choice });
+            }
             return {
-                content: choice.message.content,
+                content,
                 model: data.model,
-                usage: {
-                    inputTokens: data.usage.prompt_tokens,
-                    outputTokens: data.usage.completion_tokens,
-                    totalTokens: data.usage.total_tokens,
-                    cachedInputTokens: data.usage.prompt_tokens_details?.cached_tokens ?? 0,
-                },
+                usage,
                 finishReason: choice.finish_reason,
             };
         },
         async *stream(request) {
+            const model = request.model ?? defaultModel;
             const messages = [];
             if (request.system) {
                 messages.push({ role: 'system', content: request.system });
             }
-            messages.push({ role: 'user', content: request.prompt });
+            // Multi-turn path: when `messages` is supplied, append them verbatim.
+            // Single-turn path (legacy): single user message from `prompt`.
+            if (request.messages && request.messages.length > 0) {
+                for (const msg of request.messages) {
+                    messages.push({ role: msg.role, content: msg.content });
+                }
+            }
+            else {
+                messages.push({ role: 'user', content: request.prompt });
+            }
             const body = {
-                model: request.model ?? defaultModel,
+                model,
                 messages,
                 temperature: request.temperature ?? 0.7,
                 stream: true,
                 stream_options: { include_usage: true },
             };
-            if (request.maxTokens)
-                body.max_tokens = request.maxTokens;
-            if (request.responseFormat === 'json') {
-                body.response_format = { type: 'json_object' };
+            applyOpenAITokenLimit(body, model, request.maxTokens);
+            const responseFormat = buildOpenAIResponseFormat(request);
+            if (responseFormat) {
+                body.response_format = responseFormat;
+            }
+            if (typeof request.seed === 'number') {
+                body.seed = request.seed;
             }
             let resp;
             try {
@@ -168,7 +363,7 @@ export function createOpenAIAdapter(config) {
                             Authorization: `Bearer ${config.apiKey}`,
                         },
                         body: JSON.stringify(body),
-                        signal: AbortSignal.timeout(request.timeout ?? defaultTimeout),
+                        signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
                     }),
                 });
             }
@@ -206,6 +401,41 @@ export function createOpenAIAdapter(config) {
                 usage: { totalTokens: data.usage.total_tokens },
             };
         },
+        async listModels(filter) {
+            const isOfficial = baseUrl === 'https://api.openai.com/v1';
+            try {
+                const resp = await fetch(`${baseUrl}/models`, {
+                    method: 'GET',
+                    headers: { Authorization: `Bearer ${config.apiKey}` },
+                    signal: AbortSignal.timeout(defaultTimeout),
+                });
+                if (!resp.ok) {
+                    console.warn(`[plumbus] OpenAI listModels: ${baseUrl}/models returned ${resp.status} ${resp.statusText}; returning empty list`);
+                    return [];
+                }
+                const data = (await resp.json());
+                if (!Array.isArray(data.data)) {
+                    console.warn(`[plumbus] OpenAI listModels: ${baseUrl}/models returned unexpected response shape; returning empty list`);
+                    return [];
+                }
+                const entries = data.data.map((m) => {
+                    const e = { id: m.id };
+                    if (typeof m.created === 'number') {
+                        e.createdAt = new Date(m.created * 1000).toISOString();
+                    }
+                    if (typeof m.owned_by === 'string') {
+                        e.ownedBy = m.owned_by;
+                    }
+                    return e;
+                });
+                return joinAndFilterModels({ provider: 'openai', entries, filter, isOfficial });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[plumbus] OpenAI listModels: ${baseUrl}/models failed (${msg}); returning empty list`);
+                return [];
+            }
+        },
     };
 }
 export function createAnthropicAdapter(config) {
@@ -215,14 +445,27 @@ export function createAnthropicAdapter(config) {
     return {
         name: 'anthropic',
         async complete(request) {
+            // Multi-turn path: when `messages` is supplied, send them verbatim.
+            // Single-turn path: synthesize a single user message from `prompt`.
+            const messages = request.messages && request.messages.length > 0
+                ? request.messages.map((m) => ({ role: m.role, content: m.content }))
+                : [{ role: 'user', content: request.prompt }];
             const body = {
                 model: request.model ?? defaultModel,
-                messages: [{ role: 'user', content: request.prompt }],
+                messages,
                 max_tokens: request.maxTokens ?? 4096,
                 temperature: request.temperature ?? 0.7,
             };
             if (request.system)
                 body.system = request.system;
+            if (request.responseFormat === 'json' && request.responseSchema) {
+                body.output_config = {
+                    format: {
+                        type: 'json_schema',
+                        schema: request.responseSchema,
+                    },
+                };
+            }
             const resp = await executeRequestWithRetry({
                 providerName: 'anthropic',
                 errorLabel: 'Anthropic API',
@@ -234,37 +477,66 @@ export function createAnthropicAdapter(config) {
                         'anthropic-version': '2023-06-01',
                     },
                     body: JSON.stringify(body),
-                    signal: AbortSignal.timeout(request.timeout ?? defaultTimeout),
+                    signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
                 }),
             });
             const data = (await resp.json());
+            const usage = anthropicUsageToTokenUsage(data.usage);
             const text = data.content
                 .filter((c) => c.type === 'text')
                 .map((c) => c.text)
                 .join('');
+            if (data.stop_reason === 'refusal') {
+                throw new AIRefusalError({
+                    provider: 'anthropic',
+                    model: data.model,
+                    refusalText: text || 'Request refused by Anthropic',
+                    usage,
+                });
+            }
+            // Mirror the OpenAI adapter: only throw on max_tokens when the caller
+            // requested structured JSON output. Free-text completions should return
+            // the partial content.
+            if (data.stop_reason === 'max_tokens' &&
+                (request.responseFormat === 'json' || !!request.responseSchema)) {
+                throw new AIIncompleteOutputError({
+                    provider: 'anthropic',
+                    model: data.model,
+                    partialText: text,
+                    usage,
+                    finishReason: data.stop_reason,
+                });
+            }
             return {
                 content: text,
                 model: data.model,
-                usage: {
-                    inputTokens: data.usage.input_tokens,
-                    outputTokens: data.usage.output_tokens,
-                    totalTokens: data.usage.input_tokens + data.usage.output_tokens,
-                    cachedInputTokens: data.usage.cache_read_input_tokens ?? 0,
-                    cacheWriteTokens: data.usage.cache_creation_input_tokens ?? 0,
-                },
+                usage,
                 finishReason: data.stop_reason,
             };
         },
         async *stream(request) {
+            // Multi-turn path: when `messages` is supplied, send them verbatim.
+            // Single-turn path: synthesize a single user message from `prompt`.
+            const messages = request.messages && request.messages.length > 0
+                ? request.messages.map((m) => ({ role: m.role, content: m.content }))
+                : [{ role: 'user', content: request.prompt }];
             const body = {
                 model: request.model ?? defaultModel,
-                messages: [{ role: 'user', content: request.prompt }],
+                messages,
                 max_tokens: request.maxTokens ?? 4096,
                 temperature: request.temperature ?? 0.7,
                 stream: true,
             };
             if (request.system)
                 body.system = request.system;
+            if (request.responseFormat === 'json' && request.responseSchema) {
+                body.output_config = {
+                    format: {
+                        type: 'json_schema',
+                        schema: request.responseSchema,
+                    },
+                };
+            }
             let resp;
             try {
                 resp = await executeRequestWithRetry({
@@ -278,7 +550,7 @@ export function createAnthropicAdapter(config) {
                             'anthropic-version': '2023-06-01',
                         },
                         body: JSON.stringify(body),
-                        signal: AbortSignal.timeout(request.timeout ?? defaultTimeout),
+                        signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
                     }),
                 });
             }
@@ -296,6 +568,60 @@ export function createAnthropicAdapter(config) {
             // Users should pair with an embedding-capable provider for RAG
             throw new Error('Anthropic does not provide an embedding API. Use an OpenAI-compatible provider for embeddings.');
         },
+        async listModels(filter) {
+            const isOfficial = baseUrl === 'https://api.anthropic.com/v1';
+            const entries = [];
+            let afterId;
+            try {
+                // Anthropic /models is paginated via `has_more` / `last_id` + `after_id` query param.
+                // Cap iterations defensively so a misbehaving API doesn't loop forever.
+                for (let page = 0; page < 20; page++) {
+                    const url = new URL(`${baseUrl}/models`);
+                    url.searchParams.set('limit', '100');
+                    if (afterId)
+                        url.searchParams.set('after_id', afterId);
+                    const resp = await fetch(url, {
+                        method: 'GET',
+                        headers: {
+                            'x-api-key': config.apiKey,
+                            'anthropic-version': '2023-06-01',
+                        },
+                        signal: AbortSignal.timeout(defaultTimeout),
+                    });
+                    if (!resp.ok) {
+                        console.warn(`[plumbus] Anthropic listModels: ${url} returned ${resp.status} ${resp.statusText}; returning ${entries.length === 0 ? 'empty' : 'partial'} list`);
+                        if (entries.length === 0)
+                            return [];
+                        break;
+                    }
+                    const data = (await resp.json());
+                    if (!Array.isArray(data.data)) {
+                        console.warn(`[plumbus] Anthropic listModels: ${url} returned unexpected response shape; returning ${entries.length === 0 ? 'empty' : 'partial'} list`);
+                        if (entries.length === 0)
+                            return [];
+                        break;
+                    }
+                    for (const m of data.data) {
+                        const e = { id: m.id };
+                        if (typeof m.display_name === 'string')
+                            e.displayName = m.display_name;
+                        if (typeof m.created_at === 'string')
+                            e.createdAt = m.created_at;
+                        entries.push(e);
+                    }
+                    if (!data.has_more || !data.last_id)
+                        break;
+                    afterId = data.last_id;
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[plumbus] Anthropic listModels: ${baseUrl}/models failed (${msg}); returning ${entries.length === 0 ? 'empty' : 'partial'} list`);
+                if (entries.length === 0)
+                    return [];
+            }
+            return joinAndFilterModels({ provider: 'anthropic', entries, filter, isOfficial });
+        },
     };
 }
 async function* parseSSEStream(resp, parseChunk) {