@openshain/agent 0.1.1 → 0.3.1

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,50 @@
+import { type AnyEvent, type Config, type ModelProvider, type Work, type WorkId } from "@openshain/core";
+import { type RuntimeClient } from "./client.ts";
+/** How much one turn of the conversation may do before it stops and the person is told. */
+export declare const TURN_LIMITS: {
+    readonly modelCalls: 25;
+    readonly toolCalls: 40;
+};
+export interface SessionOptions {
+    /** The model the conversation runs on. The client owns it; the runtime never calls one. */
+    model: ModelProvider;
+    /** The workspace's configuration, for the prompt, the limits and the provider options. */
+    config: Pick<Config, "company" | "principal" | "profession" | "limits" | "model" | "debug">;
+    /** The name the agent goes by. Picked from the list, avoiding open sessions' names, when omitted. */
+    agentName?: string;
+    /** Called for every event the session records or sees: the session's own and the works'. A returned promise is awaited. */
+    onEvent?: (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;
+    /** The work the turn left open, when it stopped inside one. It can be continued with select. */
+    work?: WorkId;
+}
+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>;
+    /** Names a stopped work as the candidate for the next request. The model decides whether to continue it. */
+    select(workId: WorkId): Promise<Work>;
+    /** The work the model is on right now, if any. */
+    currentWork(): WorkId | undefined;
+    /** Ends the conversation. The record stays; a work left in progress stays in progress. */
+    close(): Promise<Work>;
+}
+/**
+ * Opens a conversation, recorded as a work of type "session", between the person and the model.
+ * The loop is a client of the runtime: it creates works, calls tools and closes works through
+ * the same MCP tools any other agent uses, and records its own model calls with work_record.
+ */
+export declare function createSession(client: RuntimeClient, options: SessionOptions): Promise<Session>;