@plumbus/core 0.6.10 → 0.6.14

package/dist/ai/provider.d.ts

@@ -1,15 +1,63 @@
 import type { AIProviderConfig } from '../types/config.js';
 import { type Kind } from './model-pricing.js';
+export interface AITool {
+    name: string;
+    description: string;
+    /** JSON Schema object root (from zodToProviderJsonSchema(...).schema). */
+    parameters: Record<string, unknown>;
+}
+export type AIToolChoice = 'auto' | 'none' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+/** Discriminated on argumentsStatus. Adapters parse at the boundary (§6.4). */
+export type AIToolCall = {
+    id: string;
+    name: string;
+    argumentsStatus: 'parsed';
+    arguments: unknown;
+} | {
+    id: string;
+    name: string;
+    argumentsStatus: 'invalid';
+    /** Internal transcript data — MUST NOT reach browser events, audit, or user errors. Bounded. */
+    rawArguments: string;
+    /** Internal transcript data — MUST NOT reach browser events, audit, or user errors. Bounded. */
+    parseError: string;
+};
+export interface AIToolExecutionOptions {
+    /** Chat tool rounds MUST set this false (§6.2). */
+    parallelToolCalls?: boolean;
+}
+export interface AIProviderCapabilities {
+    tools: boolean;
+    streamingTools: boolean;
+    parallelToolCalls: boolean;
+    parallelToolCallControl: boolean;
+    namedToolChoice: boolean;
+}
 /**
  * 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`.
+ * model should see real conversation flow. Optional — when omitted, providers
+ * fall back to single-user-message mode built from `ProviderRequest.prompt`.
+ * The user/assistant variants remain construction-compatible with existing
+ * callers; the `tool` variant carries a tool observation back to the model.
  */
-export interface ChatMessage {
-    role: 'user' | 'assistant';
+export type ChatMessage = {
+    role: 'user';
     content: string;
-}
+} | {
+    role: 'assistant';
+    content: string;
+    toolCalls?: AIToolCall[];
+} | {
+    role: 'tool';
+    content: string;
+    toolCallId: string;
+    name: string;
+};
 export interface ProviderRequest {
     /** System prompt / instructions */
     system?: string;
@@ -34,6 +82,12 @@ export interface ProviderRequest {
     temperature?: number;
     /** Max tokens for response */
     maxTokens?: number;
+    /**
+     * Reasoning effort for models that support it. Sent ONLY when set (OpenAI
+     * `reasoning_effort` on o-series / gpt-5 family); adapters for providers
+     * without an equivalent parameter ignore it.
+     */
+    reasoningEffort?: 'low' | 'medium' | 'high';
     /** Response format hint */
     responseFormat?: 'text' | 'json';
     /** Provider-compatible JSON Schema for strict structured outputs. */
@@ -57,6 +111,12 @@ export interface ProviderRequest {
      * by providers that do not support it.
      */
     seed?: number;
+    /** Provider-native caller tools. When present the adapter forwards them and returns tool calls. */
+    tools?: AITool[];
+    /** Tool-choice directive forwarded to the provider. */
+    toolChoice?: AIToolChoice;
+    /** Tool-execution options (e.g. disable parallel tool calls). */
+    toolExecution?: AIToolExecutionOptions;
 }
 /** Compose a request's optional user signal with a timeout, returning a single AbortSignal. */
 export declare function combineRequestSignals(userSignal: AbortSignal | undefined, timeoutMs: number): AbortSignal;
@@ -65,6 +125,8 @@ export interface ProviderResponse {
     model: string;
     usage: TokenUsage;
     finishReason: string;
+    /** Parsed provider tool calls (present when finishReason is 'tool_calls'/'tool_use'). */
+    toolCalls?: AIToolCall[];
 }
 export interface TokenUsage {
     inputTokens: number;
@@ -83,6 +145,8 @@ export interface ProviderStreamEvent {
     usage?: TokenUsage;
     /** Finish reason (for done events) */
     finishReason?: string;
+    /** Provider tool calls on a done event (streaming tools; unused by built-in adapters this release). */
+    toolCalls?: AIToolCall[];
     /** Error message (for error events) */
     error?: string;
 }
@@ -142,6 +206,13 @@ export interface ListModelsFilter {
 }
 export interface AIProviderAdapter {
     readonly name: string;
+    /**
+     * Declared provider capabilities. Optional for backward compat with external
+     * adapters: an adapter that omits this MUST be treated by callers as
+     * declaring every value `false` (§6.2). Both built-in adapters declare it and
+     * implement caller tools natively (C11).
+     */
+    readonly capabilities?: AIProviderCapabilities;
     /** Send a completion request */
     complete(request: ProviderRequest): Promise<ProviderResponse>;
     /** Stream a completion request, yielding incremental events */
@@ -193,6 +264,8 @@ export declare class ProviderAPIError extends Error {
     });
 }
 export declare function isProviderAPIError(value: unknown): value is ProviderAPIError;
+/** Normalize a provider-specific finish/stop reason into the framework's vocabulary. */
+export declare function normalizeFinishReason(raw: string | undefined): 'stop' | 'length' | 'refusal' | 'tool_calls' | 'other';
 export interface OpenAIAdapterConfig {
     apiKey: string;
     model?: string;

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":"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"}

package/dist/ai/provider.js

@@ -1,7 +1,7 @@
 // ── AI Provider Adapter Interface ──
 // Abstract interface for AI provider adapters (OpenAI, Anthropic, etc.)
 import { allKnownModels, calculateModelCost } from './model-pricing.js';
-import { AIIncompleteOutputError, AIRefusalError } from './refusal.js';
+import { AIIncompleteOutputError, AIInvalidRequestError, 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);
@@ -194,6 +194,17 @@ function applyOpenAITemperature(body, model, temperature) {
         return;
     body.temperature = temperature ?? 0.7;
 }
+/**
+ * `reasoning_effort` is sent ONLY when explicitly configured — no model
+ * detection. A model that rejects the parameter fails loudly (HTTP 400)
+ * instead of silently running without reasoning, so a misconfigured prompt
+ * is visible immediately.
+ */
+function applyOpenAIReasoningEffort(body, reasoningEffort) {
+    if (reasoningEffort) {
+        body.reasoning_effort = reasoningEffort;
+    }
+}
 function anthropicUsageToTokenUsage(usage) {
     return {
         inputTokens: usage.input_tokens,
@@ -237,6 +248,197 @@ async function executeRequestWithRetry(args) {
         message: `${args.errorLabel} request failed`,
     });
 }
+// ── Provider tool-calling helpers ──
+/** Portable tool-name grammar (C9). The reserved `flow__` prefix is enforced at chat bind time, not here. */
+const CALLER_TOOL_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+/** Validate caller-supplied tool definitions: portable name grammar + uniqueness. */
+function validateCallerTools(tools) {
+    const seen = new Set();
+    for (const tool of tools) {
+        if (!CALLER_TOOL_NAME_PATTERN.test(tool.name)) {
+            throw new AIInvalidRequestError({
+                reason: 'tool_name_invalid',
+                message: `Tool name "${tool.name}" does not match ^[A-Za-z][A-Za-z0-9_-]{0,63}$`,
+            });
+        }
+        if (seen.has(tool.name)) {
+            throw new AIInvalidRequestError({
+                reason: 'duplicate_tool_name',
+                message: `Duplicate tool name "${tool.name}"`,
+            });
+        }
+        seen.add(tool.name);
+    }
+}
+/** Normalize a provider-specific finish/stop reason into the framework's vocabulary. */
+export function normalizeFinishReason(raw) {
+    switch (raw) {
+        case 'stop':
+        case 'end_turn':
+        case 'stop_sequence':
+            return 'stop';
+        case 'length':
+        case 'max_tokens':
+            return 'length';
+        case 'tool_calls':
+        case 'tool_use':
+            return 'tool_calls';
+        case 'refusal':
+        case 'content_filter':
+            return 'refusal';
+        default:
+            return 'other';
+    }
+}
+/** Guard used by both adapters: caller tools cannot coexist with the tool-transport structured output (§6.6). */
+function assertNoStructuredOutputToolConflict(request) {
+    if (request.structuredOutputTransport === 'tool') {
+        throw new AIInvalidRequestError({
+            reason: 'caller_tools_conflict_with_structured_output_tool',
+            message: "Caller tools cannot be combined with structuredOutputTransport: 'tool'.",
+        });
+    }
+}
+/** Map framework ChatMessage[] to OpenAI chat-completions messages. */
+function toOpenAIMessages(request) {
+    const messages = [];
+    if (request.system)
+        messages.push({ role: 'system', content: request.system });
+    if (request.messages && request.messages.length > 0) {
+        for (const msg of request.messages) {
+            if (msg.role === 'tool') {
+                messages.push({ role: 'tool', tool_call_id: msg.toolCallId, content: msg.content });
+            }
+            else if (msg.role === 'assistant') {
+                const entry = {
+                    role: 'assistant',
+                    content: msg.content.length > 0 ? msg.content : null,
+                };
+                if (msg.toolCalls && msg.toolCalls.length > 0) {
+                    entry.tool_calls = msg.toolCalls.map((tc) => ({
+                        id: tc.id,
+                        type: 'function',
+                        function: {
+                            name: tc.name,
+                            arguments: tc.argumentsStatus === 'parsed'
+                                ? JSON.stringify(tc.arguments ?? {})
+                                : tc.rawArguments,
+                        },
+                    }));
+                }
+                messages.push(entry);
+            }
+            else {
+                messages.push({ role: 'user', content: msg.content });
+            }
+        }
+    }
+    else {
+        messages.push({ role: 'user', content: request.prompt });
+    }
+    return messages;
+}
+/** Map AIToolChoice to the OpenAI `tool_choice` wire value. */
+function buildOpenAIToolChoice(toolChoice) {
+    if (toolChoice === undefined)
+        return undefined;
+    if (toolChoice === 'auto' || toolChoice === 'none')
+        return toolChoice;
+    return { type: 'function', function: { name: toolChoice.function.name } };
+}
+/** Parse OpenAI tool_calls into framework AIToolCall records (§6.4). */
+function parseOpenAIToolCalls(toolCalls) {
+    if (!toolCalls)
+        return [];
+    const result = [];
+    for (const tc of toolCalls) {
+        const name = tc.function?.name;
+        if (!name)
+            continue;
+        const id = tc.id ?? crypto.randomUUID();
+        const rawArguments = tc.function?.arguments ?? '';
+        try {
+            const parsed = rawArguments.trim().length === 0 ? {} : JSON.parse(rawArguments);
+            result.push({ id, name, argumentsStatus: 'parsed', arguments: parsed });
+        }
+        catch (err) {
+            result.push({
+                id,
+                name,
+                argumentsStatus: 'invalid',
+                rawArguments: rawArguments.slice(0, 4096),
+                parseError: (err instanceof Error ? err.message : String(err)).slice(0, 512),
+            });
+        }
+    }
+    return result;
+}
+/** Map framework ChatMessage[] to Anthropic messages (tool_use / tool_result blocks). */
+function toAnthropicMessages(request) {
+    if (!request.messages || request.messages.length === 0) {
+        return [{ role: 'user', content: request.prompt }];
+    }
+    const out = [];
+    for (const msg of request.messages) {
+        if (msg.role === 'tool') {
+            const block = { type: 'tool_result', tool_use_id: msg.toolCallId, content: msg.content };
+            const last = out[out.length - 1];
+            if (last && last.role === 'user' && Array.isArray(last.content)) {
+                last.content.push(block);
+            }
+            else {
+                out.push({ role: 'user', content: [block] });
+            }
+        }
+        else if (msg.role === 'assistant') {
+            const blocks = [];
+            if (msg.content.length > 0)
+                blocks.push({ type: 'text', text: msg.content });
+            if (msg.toolCalls) {
+                for (const tc of msg.toolCalls) {
+                    blocks.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.name,
+                        input: tc.argumentsStatus === 'parsed' ? (tc.arguments ?? {}) : {},
+                    });
+                }
+            }
+            out.push({ role: 'assistant', content: blocks.length > 0 ? blocks : msg.content });
+        }
+        else {
+            out.push({ role: 'user', content: msg.content });
+        }
+    }
+    return out;
+}
+/** Map AIToolChoice + execution options to the Anthropic `tool_choice` wire value. */
+function buildAnthropicToolChoice(toolChoice, toolExecution) {
+    const disableParallel = toolExecution?.parallelToolCalls === false;
+    if (toolChoice === undefined && !disableParallel)
+        return undefined;
+    let base;
+    if (toolChoice === undefined || toolChoice === 'auto')
+        base = { type: 'auto' };
+    else if (toolChoice === 'none')
+        base = { type: 'none' };
+    else
+        base = { type: 'tool', name: toolChoice.function.name };
+    if (disableParallel && base.type !== 'none')
+        base.disable_parallel_tool_use = true;
+    return base;
+}
+/** Parse Anthropic tool_use content blocks into framework AIToolCall records. */
+function parseAnthropicToolUse(content) {
+    return content
+        .filter((c) => c.type === 'tool_use')
+        .map((c) => ({
+        id: c.id ?? crypto.randomUUID(),
+        name: c.name ?? '',
+        argumentsStatus: 'parsed',
+        arguments: c.input ?? {},
+    }));
+}
 export function createOpenAIAdapter(config) {
     const defaultModel = config.model ?? 'gpt-4o';
     const defaultEmbeddingModel = config.embeddingModel ?? 'text-embedding-3-small';
@@ -244,43 +446,53 @@ export function createOpenAIAdapter(config) {
     const defaultTimeout = config.requestTimeout ?? 120_000;
     return {
         name: 'openai',
+        capabilities: {
+            tools: true,
+            streamingTools: false,
+            parallelToolCalls: true,
+            parallelToolCallControl: true,
+            namedToolChoice: true,
+        },
         async complete(request) {
             const model = request.model ?? defaultModel;
-            const messages = [];
-            if (request.system) {
-                messages.push({ role: 'system', content: request.system });
-            }
-            // 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 messages = toOpenAIMessages(request);
             const body = {
                 model,
                 messages,
             };
             applyOpenAITemperature(body, model, request.temperature);
+            applyOpenAIReasoningEffort(body, request.reasoningEffort);
             applyOpenAITokenLimit(body, model, request.maxTokens);
-            const structuredToolSchema = shouldUseOpenAIStructuredTool({ request })
-                ? request.responseSchema
-                : undefined;
-            if (structuredToolSchema) {
-                body.tools = [buildOpenAIStructuredOutputTool(structuredToolSchema)];
-                body.tool_choice = {
+            if (request.tools && request.tools.length > 0) {
+                assertNoStructuredOutputToolConflict(request);
+                validateCallerTools(request.tools);
+                body.tools = request.tools.map((t) => ({
                     type: 'function',
-                    function: { name: OPENAI_STRUCTURED_OUTPUT_TOOL_NAME },
-                };
+                    function: { name: t.name, description: t.description, parameters: t.parameters },
+                }));
+                const callerToolChoice = buildOpenAIToolChoice(request.toolChoice);
+                if (callerToolChoice !== undefined)
+                    body.tool_choice = callerToolChoice;
+                if (request.toolExecution?.parallelToolCalls === false) {
+                    body.parallel_tool_calls = false;
+                }
             }
             else {
-                const responseFormat = buildOpenAIResponseFormat(request);
-                if (responseFormat) {
-                    body.response_format = responseFormat;
+                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') {
@@ -313,6 +525,15 @@ export function createOpenAIAdapter(config) {
                     usage,
                 });
             }
+            if (request.tools && request.tools.length > 0 && choice.finish_reason === 'tool_calls') {
+                return {
+                    content,
+                    model: data.model,
+                    usage,
+                    finishReason: 'tool_calls',
+                    toolCalls: parseOpenAIToolCalls(choice.message.tool_calls),
+                };
+            }
             // 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
@@ -360,6 +581,7 @@ export function createOpenAIAdapter(config) {
                 stream_options: { include_usage: true },
             };
             applyOpenAITemperature(body, model, request.temperature);
+            applyOpenAIReasoningEffort(body, request.reasoningEffort);
             applyOpenAITokenLimit(body, model, request.maxTokens);
             const responseFormat = buildOpenAIResponseFormat(request);
             if (responseFormat) {
@@ -463,12 +685,15 @@ export function createAnthropicAdapter(config) {
     const defaultTimeout = config.requestTimeout ?? 120_000;
     return {
         name: 'anthropic',
+        capabilities: {
+            tools: true,
+            streamingTools: false,
+            parallelToolCalls: true,
+            parallelToolCallControl: true,
+            namedToolChoice: true,
+        },
         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 messages = toAnthropicMessages(request);
             const body = {
                 model: request.model ?? defaultModel,
                 messages,
@@ -485,6 +710,18 @@ export function createAnthropicAdapter(config) {
                     },
                 };
             }
+            if (request.tools && request.tools.length > 0) {
+                assertNoStructuredOutputToolConflict(request);
+                validateCallerTools(request.tools);
+                body.tools = request.tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    input_schema: t.parameters,
+                }));
+                const callerToolChoice = buildAnthropicToolChoice(request.toolChoice, request.toolExecution);
+                if (callerToolChoice !== undefined)
+                    body.tool_choice = callerToolChoice;
+            }
             const resp = await executeRequestWithRetry({
                 providerName: 'anthropic',
                 errorLabel: 'Anthropic API',
@@ -503,7 +740,7 @@ export function createAnthropicAdapter(config) {
             const usage = anthropicUsageToTokenUsage(data.usage);
             const text = data.content
                 .filter((c) => c.type === 'text')
-                .map((c) => c.text)
+                .map((c) => c.text ?? '')
                 .join('');
             if (data.stop_reason === 'refusal') {
                 throw new AIRefusalError({
@@ -513,6 +750,15 @@ export function createAnthropicAdapter(config) {
                     usage,
                 });
             }
+            if (request.tools && request.tools.length > 0 && data.stop_reason === 'tool_use') {
+                return {
+                    content: text,
+                    model: data.model,
+                    usage,
+                    finishReason: 'tool_use',
+                    toolCalls: parseAnthropicToolUse(data.content),
+                };
+            }
             // Mirror the OpenAI adapter: only throw on max_tokens when the caller
             // requested structured JSON output. Free-text completions should return
             // the partial content.