@openshain/agent 0.1.1 → 0.2.0

package/dist/providers/anthropic.js

@@ -0,0 +1,214 @@
+import Anthropic, {} from "@anthropic-ai/sdk";
+import { OpenshainError, } from "@openshain/core";
+export const ANTHROPIC_PROVIDER_ID = "anthropic";
+/** Used when the request names no output limit. The config's limit normally does. */
+const DEFAULT_MAX_TOKENS = 16_000;
+/** Builds the provider from the model section of openshain.yaml. The key comes from the environment variable the config names. */
+export function anthropicProvider(model, env = process.env) {
+    const apiKey = env[model.apiKeyEnv];
+    if (!apiKey) {
+        throw new OpenshainError("config", `environment variable ${model.apiKeyEnv} is not set; it should hold the Anthropic API key`);
+    }
+    return new AnthropicProvider({
+        model: model.model,
+        apiKey,
+        ...(model.baseUrl && { baseUrl: model.baseUrl }),
+    });
+}
+/** Claude through the Messages API. Thinking blocks travel as opaque parts and go back unchanged. */
+export class AnthropicProvider {
+    id = ANTHROPIC_PROVIDER_ID;
+    client;
+    model;
+    constructor(options) {
+        this.model = options.model;
+        this.client = new Anthropic({
+            apiKey: options.apiKey.trim(),
+            ...(options.baseUrl && { baseURL: baseUrlRoot(options.baseUrl) }),
+            ...(options.fetch && { fetch: options.fetch }),
+        });
+    }
+    describe() {
+        return { provider: ANTHROPIC_PROVIDER_ID, model: this.model, capabilities: { tools: true } };
+    }
+    async generate(request, signal) {
+        const params = toParams(request, this.model);
+        try {
+            const message = await this.client.messages.create(params, { ...(signal && { signal }) });
+            return fromMessage(message);
+        }
+        catch (err) {
+            throw toError(err);
+        }
+    }
+}
+/**
+ * The request as the Messages API takes it. providerOptions land on the body as they are, so
+ * thinking, output_config and cache_control can be set or overridden from the config; `effort`
+ * alone is a shorthand for output_config.effort. The model, the limit, the system prompt, the
+ * tools, the messages and the choice not to stream come from the runtime and cannot be
+ * overridden. A cache breakpoint goes on the last block of the last message that will be sent
+ * unchanged next turn (`stableMessages`), so the next turn reads that prefix from the cache.
+ */
+export function toParams(request, model) {
+    const { effort, output_config, model: _model, max_tokens: _maxTokens, system: _system, tools: _tools, messages: _messages, stream: _stream, ...extra } = request.providerOptions ?? {};
+    const outputConfig = {
+        ...output_config,
+        ...(effort !== undefined && { effort }),
+    };
+    const messages = request.messages.map(toMessage);
+    anchorCache(messages, request.stableMessages ?? 0);
+    return {
+        ...extra,
+        ...(Object.keys(outputConfig).length > 0 && { output_config: outputConfig }),
+        model,
+        stream: false,
+        max_tokens: request.maxOutputTokens ?? DEFAULT_MAX_TOKENS,
+        ...(request.system && { system: request.system }),
+        ...(request.tools && request.tools.length > 0 && { tools: request.tools.map(toTool) }),
+        messages,
+    };
+}
+/** Marks the last block of the last stable message, the point up to which the next turn is identical. */
+function anchorCache(messages, stable) {
+    const anchor = messages[stable - 1];
+    if (!anchor || !Array.isArray(anchor.content))
+        return;
+    const last = anchor.content.at(-1);
+    if (last && (last.type === "text" || last.type === "tool_result" || last.type === "tool_use")) {
+        last.cache_control = { type: "ephemeral" };
+    }
+}
+/** The SDK appends /v1/messages itself, so a base URL that ends in /v1 loses that part. */
+export function baseUrlRoot(baseUrl) {
+    return baseUrl.replace(/\/v1\/?$/, "");
+}
+function toTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.inputSchema,
+    };
+}
+function toMessage(message) {
+    const content = [];
+    if (message.role === "user") {
+        for (const part of message.content) {
+            if (part.type === "text") {
+                if (part.text !== "")
+                    content.push({ type: "text", text: part.text });
+            }
+            else {
+                content.push({
+                    type: "tool_result",
+                    tool_use_id: part.callId,
+                    content: part.content,
+                    ...(part.isError && { is_error: true }),
+                });
+            }
+        }
+        return { role: "user", content };
+    }
+    for (const part of message.content) {
+        if (part.type === "text") {
+            if (part.text !== "")
+                content.push({ type: "text", text: part.text });
+        }
+        else if (part.type === "tool_call") {
+            content.push({ type: "tool_use", id: part.id, name: part.name, input: part.input });
+        }
+        else if (part.provider === ANTHROPIC_PROVIDER_ID) {
+            content.push(part.data);
+        }
+    }
+    if (content.length === 0) {
+        throw new OpenshainError("invalid_response", "an assistant message has nothing this provider can send; it may belong to another provider");
+    }
+    return { role: "assistant", content };
+}
+/**
+ * The response in the contract's terms. Every block that is not text or a tool call is kept
+ * opaque. A refusal's explanation becomes text, so the log says why. A response whose shape is
+ * not a message is an invalid response.
+ */
+export function fromMessage(message) {
+    if (!message || !Array.isArray(message.content)) {
+        throw new OpenshainError("invalid_response", "the response is not a message");
+    }
+    const content = [];
+    for (const block of message.content) {
+        if (block.type === "text")
+            content.push({ type: "text", text: block.text });
+        else if (block.type === "tool_use") {
+            content.push({ type: "tool_call", id: block.id, name: block.name, input: block.input });
+        }
+        else
+            content.push({ type: "opaque", provider: ANTHROPIC_PROVIDER_ID, data: block });
+    }
+    const explanation = message.stop_details?.explanation;
+    if (message.stop_reason === "refusal" && explanation) {
+        content.push({ type: "text", text: explanation });
+    }
+    return {
+        message: { role: "assistant", content },
+        stopReason: toStopReason(message.stop_reason, content.some((part) => part.type === "tool_call")),
+        usage: toUsage(message.usage),
+        raw: message,
+    };
+}
+const STOP_REASONS = {
+    end_turn: "end_turn",
+    stop_sequence: "end_turn",
+    tool_use: "tool_call",
+    max_tokens: "max_tokens",
+    refusal: "refusal",
+};
+/** Some gateways say end_turn with tool_use blocks present; the blocks decide. */
+function toStopReason(reason, hasToolUse) {
+    if (hasToolUse && reason !== "max_tokens")
+        return "tool_call";
+    return (reason && STOP_REASONS[reason]) || "other";
+}
+function toUsage(usage) {
+    const thinking = usage?.output_tokens_details?.thinking_tokens;
+    const read = usage?.cache_read_input_tokens ?? 0;
+    const written = usage?.cache_creation_input_tokens ?? 0;
+    return {
+        inputTokens: (usage?.input_tokens ?? 0) + read + written,
+        outputTokens: usage?.output_tokens ?? 0,
+        ...(usage?.cache_read_input_tokens != null && {
+            cachedInputTokens: usage.cache_read_input_tokens,
+        }),
+        ...(usage?.cache_creation_input_tokens != null && {
+            cacheWriteTokens: usage.cache_creation_input_tokens,
+        }),
+        ...(thinking != null && { reasoningTokens: thinking }),
+    };
+}
+/** The SDK's typed errors as the codes the runtime records. Anything else means the response could not be read. */
+function toError(err) {
+    if (err instanceof OpenshainError)
+        return err;
+    if (err instanceof Anthropic.APIUserAbortError)
+        return wrap("network", err);
+    if (err instanceof Anthropic.AuthenticationError)
+        return wrap("auth", err);
+    if (err instanceof Anthropic.PermissionDeniedError)
+        return wrap("auth", err);
+    if (err instanceof Anthropic.RateLimitError)
+        return wrap("rate_limit", err);
+    if (err instanceof Anthropic.BadRequestError)
+        return wrap("config", err);
+    if (err instanceof Anthropic.NotFoundError)
+        return wrap("config", err);
+    if (err instanceof Anthropic.APIConnectionError)
+        return wrap("network", err);
+    if (err instanceof Anthropic.InternalServerError)
+        return wrap("network", err);
+    if (err instanceof Anthropic.APIError)
+        return wrap("invalid_response", err);
+    return wrap("invalid_response", err instanceof Error ? err : new Error(String(err)));
+}
+function wrap(code, err) {
+    return new OpenshainError(code, `Anthropic: ${err.message}`, { cause: err });
+}

package/dist/providers/openai-compatible.d.ts

@@ -0,0 +1,47 @@
+import { type ModelDescription, type ModelProvider, type ModelRequest, type ModelResponse, type RuntimeProviders } from "@openshain/core";
+import { type ClientOptions } from "openai";
+import type { ChatCompletion, ChatCompletionCreateParamsNonStreaming } from "openai/resources/chat/completions";
+export declare const OPENAI_COMPATIBLE_PROVIDER_ID = "openai-compatible";
+type ModelSection = Parameters<RuntimeProviders["models"][string]>[0];
+export interface OpenAICompatibleProviderOptions {
+    model: string;
+    apiKey: string;
+    /** The API root including its version segment, for example http://localhost:11434/v1. */
+    baseUrl?: string;
+    /** False for an endpoint that cannot call tools. The runtime then refuses to start. */
+    tools?: boolean;
+    /** Replaces the global fetch. Tests answer through it with recorded responses. */
+    fetch?: NonNullable<ClientOptions["fetch"]>;
+}
+/**
+ * Builds the provider from the model section of openshain.yaml. The key comes from the environment
+ * variable the config names; `options: { tools: false }` declares an endpoint without tool support.
+ */
+export declare function openaiCompatibleProvider(model: ModelSection, env?: Record<string, string | undefined>): OpenAICompatibleProvider;
+/** Any chat completions endpoint with function calling: OpenAI, a local server, or another vendor's compatible API. */
+export declare class OpenAICompatibleProvider implements ModelProvider {
+    readonly id = "openai-compatible";
+    private readonly client;
+    private readonly model;
+    private readonly tools;
+    constructor(options: OpenAICompatibleProviderOptions);
+    describe(): ModelDescription;
+    generate(request: ModelRequest, signal?: AbortSignal): Promise<ModelResponse>;
+}
+/**
+ * The request as chat completions take it. providerOptions land on the body as they are
+ * (reasoning_effort, temperature, and so on); the model, the limit, the messages, the tools and
+ * the choice not to stream come from the runtime. The limit is sent as max_completion_tokens; a
+ * max_tokens in the options only asks for that older name, which some servers still expect,
+ * and its value is ignored. A `tools` flag in the options is the provider's, not the request's.
+ */
+export declare function toParams(request: ModelRequest, model: string): ChatCompletionCreateParamsNonStreaming;
+/**
+ * The completion in the contract's terms. Fields of the assistant message beyond content and
+ * tool calls, such as a server's reasoning, are kept opaque and go back with the message. Tool
+ * calls that are not function calls are kept opaque too, but never sent back. A refusal's text
+ * becomes text, so the log says why. A response whose shape is not a completion is an invalid
+ * response.
+ */
+export declare function fromCompletion(completion: ChatCompletion): ModelResponse;
+export {};

package/dist/providers/openai-compatible.js

@@ -0,0 +1,251 @@
+import { OpenshainError, } from "@openshain/core";
+import OpenAI, {} from "openai";
+export const OPENAI_COMPATIBLE_PROVIDER_ID = "openai-compatible";
+/** Used when the request names no output limit. The config's limit normally does. */
+const DEFAULT_MAX_TOKENS = 16_000;
+/**
+ * Builds the provider from the model section of openshain.yaml. The key comes from the environment
+ * variable the config names; `options: { tools: false }` declares an endpoint without tool support.
+ */
+export function openaiCompatibleProvider(model, env = process.env) {
+    const apiKey = env[model.apiKeyEnv];
+    if (!apiKey) {
+        throw new OpenshainError("config", `environment variable ${model.apiKeyEnv} is not set; it should hold the API key`);
+    }
+    return new OpenAICompatibleProvider({
+        model: model.model,
+        apiKey,
+        ...(model.baseUrl && { baseUrl: model.baseUrl }),
+        ...(model.options?.tools === false && { tools: false }),
+    });
+}
+/** Any chat completions endpoint with function calling: OpenAI, a local server, or another vendor's compatible API. */
+export class OpenAICompatibleProvider {
+    id = OPENAI_COMPATIBLE_PROVIDER_ID;
+    client;
+    model;
+    tools;
+    constructor(options) {
+        this.model = options.model;
+        this.tools = options.tools ?? true;
+        this.client = new OpenAI({
+            apiKey: options.apiKey.trim(),
+            ...(options.baseUrl && { baseURL: options.baseUrl }),
+            ...(options.fetch && { fetch: options.fetch }),
+        });
+    }
+    describe() {
+        return {
+            provider: OPENAI_COMPATIBLE_PROVIDER_ID,
+            model: this.model,
+            capabilities: { tools: this.tools },
+        };
+    }
+    async generate(request, signal) {
+        const params = toParams(request, this.model);
+        try {
+            const completion = await this.client.chat.completions.create(params, {
+                ...(signal && { signal }),
+            });
+            return fromCompletion(completion);
+        }
+        catch (err) {
+            throw toError(err);
+        }
+    }
+}
+/**
+ * The request as chat completions take it. providerOptions land on the body as they are
+ * (reasoning_effort, temperature, and so on); the model, the limit, the messages, the tools and
+ * the choice not to stream come from the runtime. The limit is sent as max_completion_tokens; a
+ * max_tokens in the options only asks for that older name, which some servers still expect,
+ * and its value is ignored. A `tools` flag in the options is the provider's, not the request's.
+ */
+export function toParams(request, model) {
+    const { tools: _flag, model: _model, messages: _messages, stream: _stream, max_completion_tokens: _limit, max_tokens: legacy, ...extra } = request.providerOptions ?? {};
+    const limit = request.maxOutputTokens ?? DEFAULT_MAX_TOKENS;
+    const messages = [];
+    if (request.system)
+        messages.push({ role: "system", content: request.system });
+    for (const message of request.messages)
+        messages.push(...toMessages(message));
+    return {
+        ...extra,
+        model,
+        stream: false,
+        ...(legacy !== undefined ? { max_tokens: limit } : { max_completion_tokens: limit }),
+        messages,
+        ...(request.tools && request.tools.length > 0 && { tools: request.tools.map(toTool) }),
+    };
+}
+function toTool(tool) {
+    return {
+        type: "function",
+        function: { name: tool.name, description: tool.description, parameters: tool.inputSchema },
+    };
+}
+/** One contract message becomes one or more chat messages: every tool result is a message of its own. */
+function toMessages(message) {
+    if (message.role === "user") {
+        const out = [];
+        const texts = [];
+        for (const part of message.content) {
+            if (part.type === "text") {
+                if (part.text !== "")
+                    texts.push(part.text);
+            }
+            else {
+                out.push({ role: "tool", tool_call_id: part.callId, content: part.content });
+            }
+        }
+        if (texts.length > 0)
+            out.push({ role: "user", content: texts.join("\n") });
+        return out;
+    }
+    const texts = [];
+    const toolCalls = [];
+    let opaque = {};
+    for (const part of message.content) {
+        if (part.type === "text") {
+            if (part.text !== "")
+                texts.push(part.text);
+        }
+        else if (part.type === "tool_call") {
+            toolCalls.push({
+                id: part.id,
+                type: "function",
+                function: { name: part.name, arguments: JSON.stringify(part.input ?? {}) },
+            });
+        }
+        else if (part.provider === OPENAI_COMPATIBLE_PROVIDER_ID) {
+            opaque = { ...opaque, ...part.data };
+        }
+    }
+    const { unsupported_tool_calls: _unsupported, ...sent } = opaque;
+    if (texts.length === 0 && toolCalls.length === 0 && Object.keys(sent).length === 0) {
+        throw new OpenshainError("invalid_response", "an assistant message has nothing this provider can send; it may belong to another provider");
+    }
+    return [
+        {
+            ...sent,
+            role: "assistant",
+            content: texts.length > 0 ? texts.join("\n") : null,
+            ...(toolCalls.length > 0 && { tool_calls: toolCalls }),
+        },
+    ];
+}
+/**
+ * The completion in the contract's terms. Fields of the assistant message beyond content and
+ * tool calls, such as a server's reasoning, are kept opaque and go back with the message. Tool
+ * calls that are not function calls are kept opaque too, but never sent back. A refusal's text
+ * becomes text, so the log says why. A response whose shape is not a completion is an invalid
+ * response.
+ */
+export function fromCompletion(completion) {
+    const choice = completion?.choices?.[0];
+    if (!choice?.message) {
+        throw new OpenshainError("invalid_response", "the completion has no message");
+    }
+    const { role: _role, content: rawContent, tool_calls, refusal, ...rest } = choice.message;
+    const content = [];
+    const text = joinContent(rawContent);
+    if (text)
+        content.push({ type: "text", text });
+    if (refusal)
+        content.push({ type: "text", text: refusal });
+    const calls = (tool_calls ?? []).filter((call) => call.type === "function");
+    for (const call of calls) {
+        content.push({
+            type: "tool_call",
+            id: call.id,
+            name: call.function.name,
+            input: parseArguments(call.function.arguments),
+        });
+    }
+    const unsupported = (tool_calls ?? []).filter((call) => call.type !== "function");
+    const opaque = Object.fromEntries(Object.entries(rest).filter(([key, value]) => key !== "annotations" && value != null));
+    if (unsupported.length > 0)
+        opaque.unsupported_tool_calls = unsupported;
+    if (Object.keys(opaque).length > 0) {
+        content.push({ type: "opaque", provider: OPENAI_COMPATIBLE_PROVIDER_ID, data: opaque });
+    }
+    return {
+        message: { role: "assistant", content },
+        stopReason: toStopReason(choice.finish_reason, calls.length > 0),
+        usage: toUsage(completion.usage),
+        raw: completion,
+    };
+}
+/** Content is a string, but some servers return text parts; those are joined. */
+function joinContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => part && typeof part === "object" ? part.text : undefined)
+        .filter((text) => typeof text === "string")
+        .join("");
+}
+/** Tool arguments arrive as a JSON string. One that does not parse is passed on as it is, so the schema check reports it. */
+function parseArguments(args) {
+    if (args.trim() === "")
+        return {};
+    try {
+        return JSON.parse(args);
+    }
+    catch {
+        return args;
+    }
+}
+const STOP_REASONS = {
+    stop: "end_turn",
+    tool_calls: "tool_call",
+    length: "max_tokens",
+    content_filter: "refusal",
+};
+/** Some servers say `stop` even when they made tool calls; the function calls decide either way. */
+function toStopReason(reason, hasToolCalls) {
+    if (hasToolCalls && reason !== "length")
+        return "tool_call";
+    if (reason === "tool_calls" && !hasToolCalls)
+        return "other";
+    return (reason && STOP_REASONS[reason]) || "other";
+}
+function toUsage(usage) {
+    const cached = usage?.prompt_tokens_details?.cached_tokens;
+    const reasoning = usage?.completion_tokens_details?.reasoning_tokens;
+    return {
+        inputTokens: usage?.prompt_tokens ?? 0,
+        outputTokens: usage?.completion_tokens ?? 0,
+        ...(cached != null && { cachedInputTokens: cached }),
+        ...(reasoning != null && { reasoningTokens: reasoning }),
+    };
+}
+/** The SDK's typed errors as the codes the runtime records. Anything else means the response could not be read. */
+function toError(err) {
+    if (err instanceof OpenshainError)
+        return err;
+    if (err instanceof OpenAI.APIUserAbortError)
+        return wrap("network", err);
+    if (err instanceof OpenAI.AuthenticationError)
+        return wrap("auth", err);
+    if (err instanceof OpenAI.PermissionDeniedError)
+        return wrap("auth", err);
+    if (err instanceof OpenAI.RateLimitError)
+        return wrap("rate_limit", err);
+    if (err instanceof OpenAI.BadRequestError)
+        return wrap("config", err);
+    if (err instanceof OpenAI.NotFoundError)
+        return wrap("config", err);
+    if (err instanceof OpenAI.APIConnectionError)
+        return wrap("network", err);
+    if (err instanceof OpenAI.InternalServerError)
+        return wrap("network", err);
+    if (err instanceof OpenAI.APIError)
+        return wrap("invalid_response", err);
+    return wrap("invalid_response", err instanceof Error ? err : new Error(String(err)));
+}
+function wrap(code, err) {
+    return new OpenshainError(code, `chat completions: ${err.message}`, { cause: err });
+}

package/dist/session.d.ts

@@ -0,0 +1,41 @@
+import { type AnyEvent, type ModelProvider, type Runtime, type ToolDefinition, type Work, type WorkId } from "@openshain/core";
+/** How much one turn of a session may do before the person hears back. */
+export declare const TURN_LIMITS: {
+    readonly modelCalls: 5;
+    readonly toolCalls: 10;
+};
+/** What the session's model may do: hand work out and look work up. It never touches files itself. */
+export declare const SESSION_TOOLS: readonly ToolDefinition[];
+export interface SessionOptions {
+    /** Defaults to the runtime's model, for the session and for the works it starts. */
+    model?: ModelProvider;
+    /** The name the agent goes by. Picked from the list, avoiding open sessions' names, when omitted. */
+    agentName?: string;
+    /** Called after every event the session records. A returned promise is awaited before the next step. */
+    onEvent?: (event: AnyEvent) => void | Promise<void>;
+    /** Called after every event a work started from this session records. A returned promise is awaited. */
+    onWorkEvent?: (workId: WorkId, event: AnyEvent) => void | Promise<void>;
+    /** Answers a question a work asks the person. Without it, the work waits for input. */
+    onInput?: (workId: WorkId, question: string) => Promise<string>;
+}
+export type TurnStop = "turn_limit" | "aborted" | "max_tokens" | "refusal" | "model_error";
+export interface TurnResult {
+    /** What the model said to the person, possibly empty when the turn stopped early. */
+    reply: string;
+    /** Why the turn ended before the model replied, if it did. */
+    stopped?: TurnStop;
+    detail?: string;
+}
+export interface Session {
+    readonly id: WorkId;
+    /** The name the agent goes by in this conversation and in the works it starts. */
+    readonly agentName: string;
+    /** Records what the person said and runs the model until it replies or the turn stops. */
+    turn(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<TurnResult>;
+    /** Ends the conversation. The record stays. */
+    close(): Promise<Work>;
+}
+/** Opens a conversation, recorded as a work of type "session", between the person and the model. */
+export declare function createSession(runtime: Runtime, options?: SessionOptions): Promise<Session>;