@openshain/agent 0.1.1 → 0.3.1

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ToolContent, ToolDefinition } from "@openshain/core";
+/** What a tool call returned, as the client sees it: MCP content, and the same as text. */
+export interface ClientResult {
+    content: ToolContent[];
+    isError: boolean;
+    text: string;
+}
+/**
+ * The runtime as a client sees it: the tools it offers and a way to call them. The interactive
+ * CLI's loop talks to the runtime through this and nothing else, the way Claude Code does over MCP.
+ */
+export interface RuntimeClient {
+    listTools(): Promise<ToolDefinition[]>;
+    call(name: string, input: unknown, signal?: AbortSignal): Promise<ClientResult>;
+    close(): Promise<void>;
+}
+/** Connects an MCP client to a server in the same process, over the SDK's in-memory transport. */
+export declare function connectInMemory(server: Server): Promise<RuntimeClient>;
+/** Adapts any connected MCP client to the runtime client the loop uses. */
+export declare function wrap(client: Client): RuntimeClient;
+/** Parses a JSON result. Returns undefined when the text is not JSON. */
+export declare function jsonOf(result: ClientResult): unknown;

package/dist/client.js

@@ -0,0 +1,48 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import pkg from "../package.json" with { type: "json" };
+/** Connects an MCP client to a server in the same process, over the SDK's in-memory transport. */
+export async function connectInMemory(server) {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+    const client = new Client({ name: "openshain", version: pkg.version });
+    await client.connect(clientTransport);
+    return wrap(client);
+}
+/** Adapts any connected MCP client to the runtime client the loop uses. */
+export function wrap(client) {
+    return {
+        async listTools() {
+            const { tools } = await client.listTools();
+            return tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description ?? "",
+                inputSchema: tool.inputSchema,
+                effect: tool.annotations?.readOnlyHint === true ? "observe" : "mutate",
+            }));
+        },
+        async call(name, input, signal) {
+            const result = await client.callTool({ name, arguments: (input ?? {}) }, undefined, signal ? { signal } : undefined);
+            const parts = (result.content ?? []);
+            const content = parts.map((part) => ({
+                type: "text",
+                text: part.type === "text" ? (part.text ?? "") : JSON.stringify(part),
+            }));
+            return {
+                content,
+                isError: result.isError === true,
+                text: content.map((c) => (c.type === "text" ? c.text : "")).join(""),
+            };
+        },
+        close: () => client.close(),
+    };
+}
+/** Parses a JSON result. Returns undefined when the text is not JSON. */
+export function jsonOf(result) {
+    try {
+        return JSON.parse(result.text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type ClientResult, connectInMemory, jsonOf, type RuntimeClient, wrap } from "./client.ts";
+export { AGENT_NAMES, pickAgentName } from "./names.ts";
+export { ANTHROPIC_PROVIDER_ID, AnthropicProvider, type AnthropicProviderOptions, anthropicProvider, } from "./providers/anthropic.ts";
+export { OPENAI_COMPATIBLE_PROVIDER_ID, OpenAICompatibleProvider, type OpenAICompatibleProviderOptions, openaiCompatibleProvider, } from "./providers/openai-compatible.ts";
+export { createSession, type Session, type SessionOptions, TURN_LIMITS, type TurnResult, type TurnStop, } from "./session.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+// @openshain/agent: The conversation loop that drives the runtime as an MCP client, and the model providers (bring your own key)
+export { connectInMemory, jsonOf, wrap } from "./client.js";
+export { AGENT_NAMES, pickAgentName } from "./names.js";
+export { ANTHROPIC_PROVIDER_ID, AnthropicProvider, anthropicProvider, } from "./providers/anthropic.js";
+export { OPENAI_COMPATIBLE_PROVIDER_ID, OpenAICompatibleProvider, openaiCompatibleProvider, } from "./providers/openai-compatible.js";
+export { createSession, TURN_LIMITS, } from "./session.js";

package/dist/names.d.ts

@@ -0,0 +1,9 @@
+import type { Language } from "@openshain/core";
+/**
+ * Names a session's agent may go by, per language of the company. Given names that are also words
+ * of nature, so they read as a person to talk to without pointing at anyone real, and lean on no
+ * gender. Thirty each.
+ */
+export declare const AGENT_NAMES: Readonly<Record<Language, readonly string[]>>;
+/** A name for a new session's agent in the company's language, avoiding the ones open sessions use while any is free. */
+export declare function pickAgentName(language: Language, taken: Iterable<string>, random?: () => number): string;

package/dist/names.js

@@ -0,0 +1,79 @@
+/**
+ * Names a session's agent may go by, per language of the company. Given names that are also words
+ * of nature, so they read as a person to talk to without pointing at anyone real, and lean on no
+ * gender. Thirty each.
+ */
+export const AGENT_NAMES = Object.freeze({
+    ja: Object.freeze([
+        "あおい",
+        "あかね",
+        "あさひ",
+        "いずみ",
+        "いぶき",
+        "うみ",
+        "かえで",
+        "かすみ",
+        "こはる",
+        "さくら",
+        "しおん",
+        "しずく",
+        "すばる",
+        "すみれ",
+        "そら",
+        "つばき",
+        "つばさ",
+        "なぎ",
+        "なずな",
+        "はづき",
+        "ひかり",
+        "ひなた",
+        "ほたる",
+        "みお",
+        "みずき",
+        "みなと",
+        "みのり",
+        "もみじ",
+        "ゆずき",
+        "わかば",
+    ]),
+    en: Object.freeze([
+        "Ash",
+        "Aspen",
+        "Bay",
+        "Birch",
+        "Cedar",
+        "Clover",
+        "Coral",
+        "Dawn",
+        "Ember",
+        "Fern",
+        "Hazel",
+        "Holly",
+        "Indigo",
+        "Iris",
+        "Ivy",
+        "Jade",
+        "Juniper",
+        "Laurel",
+        "Maple",
+        "Moss",
+        "Olive",
+        "Rain",
+        "Reed",
+        "River",
+        "Robin",
+        "Rowan",
+        "Sage",
+        "Sky",
+        "Willow",
+        "Wren",
+    ]),
+});
+/** A name for a new session's agent in the company's language, avoiding the ones open sessions use while any is free. */
+export function pickAgentName(language, taken, random = Math.random) {
+    const names = AGENT_NAMES[language];
+    const used = new Set(taken);
+    const free = names.filter((name) => !used.has(name));
+    const pool = free.length > 0 ? free : names;
+    return pool[Math.min(pool.length - 1, Math.floor(random() * pool.length))];
+}

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,40 @@
+import Anthropic, { type ClientOptions } from "@anthropic-ai/sdk";
+import { type ModelDescription, type ModelProvider, type ModelRequest, type ModelResponse, type RuntimeProviders } from "@openshain/core";
+export declare const ANTHROPIC_PROVIDER_ID = "anthropic";
+type ModelSection = Parameters<RuntimeProviders["models"][string]>[0];
+export interface AnthropicProviderOptions {
+    model: string;
+    apiKey: string;
+    baseUrl?: string;
+    /** 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. */
+export declare function anthropicProvider(model: ModelSection, env?: Record<string, string | undefined>): AnthropicProvider;
+/** Claude through the Messages API. Thinking blocks travel as opaque parts and go back unchanged. */
+export declare class AnthropicProvider implements ModelProvider {
+    readonly id = "anthropic";
+    private readonly client;
+    private readonly model;
+    constructor(options: AnthropicProviderOptions);
+    describe(): ModelDescription;
+    generate(request: ModelRequest, signal?: AbortSignal): Promise<ModelResponse>;
+}
+/**
+ * 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 declare function toParams(request: ModelRequest, model: string): Anthropic.MessageCreateParamsNonStreaming;
+/** The SDK appends /v1/messages itself, so a base URL that ends in /v1 loses that part. */
+export declare function baseUrlRoot(baseUrl: string): string;
+/**
+ * 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 declare function fromMessage(message: Anthropic.Message): ModelResponse;
+export {};

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 {};