@openshain/agent 0.1.1 → 0.3.1

package/dist/session.js

@@ -0,0 +1,428 @@
+import { ASK_USER_TOOL_NAME, buildProjection, eventToFile, isTerminal, newEventId, SESSION_WORK_TYPE, } from "@openshain/core";
+import { jsonOf } from "./client.js";
+import { pickAgentName } from "./names.js";
+/** How much one turn of the conversation may do before it stops and the person is told. */
+export const TURN_LIMITS = { modelCalls: 25, toolCalls: 40 };
+/** The tools of the runtime that the loop itself drives; the model never sees them. */
+const LOOP_ONLY_TOOLS = new Set(["work_record", "work_answer"]);
+const ROLE = "あなたはこの会社の社員エージェントとして、受付の役で、この人と話す。作業が要るときは work_create で Work を作り(objective は人の言葉で書き、会話で分かった前提を添える)、その Work の中で Tool を呼び、終わったら work_complete で summary を人の言葉で書いて閉じる。会話の中では Tool を呼べないので、ファイルの中身を見ないと答えられない質問も Work を作って調べる。件数や金額は Tool が返した値をそのまま書き、計算し直さない。/work resume で候補として示された Work は、人の依頼がその objective に沿うときだけ work_select で続ける。沿わなければ続けず、その旨を伝えて新しい Work を作るか work_list で探し直す。返答は端末の画面に出るので、Markdown の記法や絵文字は使わず、短い文で書く。過去の作業は work_list と work_get で答える。";
+/**
+ * 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 async function createSession(client, options) {
+    const { model, config } = options;
+    const agentName = options.agentName ?? pickAgentName(config.company.language, await namesInUse(client));
+    const opened = await client.call("work_create", {
+        objective: "会話",
+        type: SESSION_WORK_TYPE,
+        agent_name: agentName,
+    });
+    if (opened.isError)
+        throw new Error(`could not open a session: ${opened.text}`);
+    const session = jsonOf(opened);
+    const id = session.id;
+    /** The session's events as the projection needs them, kept in memory; the runtime holds the record. */
+    const events = [];
+    let seq = 0;
+    const local = (type, payload) => {
+        const now = new Date().toISOString();
+        seq += 1;
+        return {
+            v: 1,
+            id: newEventId(),
+            workId: id,
+            seq,
+            type,
+            payload,
+            occurredAt: now,
+            recordedAt: now,
+        };
+    };
+    events.push(local("work.created", {
+        objective: "会話",
+        principal: config.principal.id,
+        profession: config.profession.id,
+        type: SESSION_WORK_TYPE,
+        agentName,
+    }));
+    let task;
+    let candidate;
+    /** Records one of the client's own events on a work through the runtime, and reports it. */
+    const record = async (workId, type, payload) => {
+        const event = local(type, payload);
+        const file = eventToFile({ ...event, workId });
+        const result = await client.call("work_record", {
+            work_id: workId,
+            type,
+            payload: file.payload,
+        });
+        if (result.isError)
+            throw new Error(`work_record failed: ${result.text}`);
+        await options.onEvent?.(workId, { ...event, workId });
+    };
+    /** Records a model event on the session and, while a work is open, on that work as well. */
+    const recordModelEvent = async (type, payload) => {
+        events.push(local(type, payload));
+        await record(id, type, payload);
+        if (task)
+            await record(task.id, type, payload);
+    };
+    const describedTools = async () => (await client.listTools()).filter((t) => !LOOP_ONLY_TOOLS.has(t.name));
+    const promptConfig = {
+        ...config,
+        profession: {
+            ...config.profession,
+            instructions: `${config.profession.instructions.trim()}\n\n${ROLE}`,
+        },
+    };
+    async function runTurn(signal) {
+        const description = model.describe();
+        const tools = await describedTools();
+        let modelCalls = 0;
+        let toolCalls = 0;
+        for (;;) {
+            if (signal?.aborted)
+                return { reply: "", stopped: "aborted" };
+            if (modelCalls >= TURN_LIMITS.modelCalls) {
+                return {
+                    reply: "",
+                    stopped: "turn_limit",
+                    detail: `model calls in one turn (${TURN_LIMITS.modelCalls})`,
+                };
+            }
+            const projection = buildProjection({
+                events,
+                config: promptConfig,
+                tools,
+                providerId: model.id,
+                budget: {
+                    modelCallsLeft: TURN_LIMITS.modelCalls - modelCalls,
+                    toolCallsLeft: TURN_LIMITS.toolCalls - toolCalls,
+                },
+            });
+            if (task && task.modelCalls >= config.limits.maxModelCalls) {
+                await callTool({
+                    id: `call_limit_${task.id}`,
+                    name: "work_fail",
+                    input: {
+                        reason: "limit_reached",
+                        detail: `${config.limits.maxModelCalls} model calls`,
+                    },
+                }, signal);
+                return {
+                    reply: "",
+                    stopped: "turn_limit",
+                    detail: `model calls in one work (${config.limits.maxModelCalls})`,
+                };
+            }
+            await recordModelEvent("model.requested", {
+                provider: model.id,
+                model: description.model,
+                messageCount: projection.messages.length,
+                toolNames: tools.map((t) => t.name),
+            });
+            modelCalls += 1;
+            if (task)
+                task.modelCalls += 1;
+            let response;
+            try {
+                response = await model.generate({
+                    system: projection.system,
+                    messages: projection.messages,
+                    tools: projection.tools,
+                    maxOutputTokens: config.limits.maxOutputTokens,
+                    budget: projection.budget,
+                    stableMessages: projection.messages.length - 1,
+                    ...(config.model?.options && { providerOptions: config.model.options }),
+                }, signal);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                await recordModelEvent("model.failed", { code: "model_error", message });
+                return { reply: "", stopped: signal?.aborted ? "aborted" : "model_error", detail: message };
+            }
+            await recordModelEvent("model.completed", {
+                stopReason: response.stopReason,
+                content: response.message.content,
+                ...(config.debug?.persistRaw && response.raw !== undefined && { raw: response.raw }),
+            });
+            await recordModelEvent("usage.recorded", {
+                kind: "model_inference",
+                provider: model.id,
+                model: description.model,
+                usage: response.usage,
+            });
+            const text = textOf(response.message.content);
+            switch (response.stopReason) {
+                case "end_turn":
+                    return { reply: text };
+                case "tool_call": {
+                    const calls = response.message.content.filter((p) => p.type === "tool_call");
+                    for (const call of calls) {
+                        if (signal?.aborted)
+                            return { reply: text, stopped: "aborted" };
+                        if (toolCalls >= TURN_LIMITS.toolCalls) {
+                            return {
+                                reply: text,
+                                stopped: "turn_limit",
+                                detail: `tool calls in one turn (${TURN_LIMITS.toolCalls})`,
+                            };
+                        }
+                        toolCalls += 1;
+                        const outcome = await callTool(call, signal);
+                        if (outcome === "withdrawn")
+                            return { reply: text, stopped: "aborted" };
+                    }
+                    break;
+                }
+                case "max_tokens":
+                    return { reply: text, stopped: "max_tokens" };
+                case "refusal":
+                    return { reply: text, stopped: "refusal" };
+                default:
+                    return {
+                        reply: text,
+                        stopped: "model_error",
+                        detail: `unexpected stop reason "${response.stopReason}"`,
+                    };
+            }
+        }
+    }
+    /**
+     * One tool call of the model, through the runtime. Keeps track of the work the model is on,
+     * asks the person when the runtime says a question is pending, and mirrors the call and its
+     * result into the session's projection.
+     */
+    async function callTool(call, signal) {
+        const workId = task?.id ?? id;
+        // The loop drives these itself; a model that calls them is refused before the runtime sees it.
+        const refusal = LOOP_ONLY_TOOLS.has(call.name)
+            ? `${call.name} is the loop's own; it is not a tool for the model`
+            : !task && (call.name === "work_complete" || call.name === "work_fail")
+                ? `${call.name} needs a work of its own: no work is open; start one with work_create`
+                : undefined;
+        if (refusal) {
+            finish(call.id, { content: [{ type: "text", text: refusal }], isError: true, text: "" });
+            return "done";
+        }
+        events.push(local("tool.called", {
+            callId: call.id,
+            provider: "runtime",
+            name: call.name,
+            input: call.input,
+        }));
+        await options.onEvent?.(workId, events.at(-1));
+        const input = call.name === "work_create" && call.input && typeof call.input === "object"
+            ? { ...call.input, parent: id, agent_name: agentName }
+            : call.input;
+        let result;
+        try {
+            result = await client.call(call.name, input, signal);
+        }
+        catch (err) {
+            result = {
+                content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
+                isError: true,
+                text: "",
+            };
+        }
+        task?.callIds.add(call.id);
+        const data = result.isError
+            ? undefined
+            : jsonOf(result);
+        if (!result.isError &&
+            (call.name === "work_create" || call.name === "work_select") &&
+            data?.id) {
+            const workId = data.id;
+            const history = data.history;
+            task = {
+                id: workId,
+                modelCalls: typeof history?.modelCalls === "number" ? history.modelCalls : 0,
+                callIds: new Set([call.id]),
+            };
+            candidate = undefined;
+            await options.onEvent?.(workId, local("work.status_changed", {
+                from: "queued",
+                to: String(data.status ?? "in_progress"),
+                reason: call.name,
+            }));
+            // A selected work that waits for an answer gets it now, oldest question first.
+            if (call.name === "work_select" && data.status === "waiting_input") {
+                const answered = await answerPending(workId, signal);
+                if (answered === "withdrawn") {
+                    finish(call.id, result);
+                    return "withdrawn";
+                }
+                if (answered.length > 0) {
+                    result = {
+                        ...result,
+                        text: "",
+                        content: [
+                            ...result.content,
+                            { type: "text", text: `answers recorded: ${JSON.stringify(answered)}` },
+                        ],
+                    };
+                }
+            }
+        }
+        if (!result.isError && call.name === ASK_USER_TOOL_NAME && data?.pending === true && task) {
+            const asked = task.id;
+            const question = String(data.question ?? "");
+            if (!options.onInput) {
+                result = {
+                    ...result,
+                    text: "",
+                    content: [
+                        {
+                            type: "text",
+                            text: "the work waits for the person's answer; it can be resumed later",
+                        },
+                    ],
+                };
+            }
+            else {
+                let answer;
+                try {
+                    answer = await options.onInput(asked, question);
+                }
+                catch {
+                    // The person took the question back: the work stays waiting_input.
+                    finish(call.id, {
+                        content: [{ type: "text", text: "the person withdrew the question; the work waits" }],
+                        isError: true,
+                        text: "",
+                    });
+                    return "withdrawn";
+                }
+                const answered = await client.call("work_answer", { call_id: data.call_id, answer }, signal);
+                result = answered.isError
+                    ? answered
+                    : { content: [{ type: "text", text: answer }], isError: false, text: answer };
+            }
+        }
+        finish(call.id, result);
+        if (!result.isError && (call.name === "work_complete" || call.name === "work_fail") && task) {
+            const closed = task;
+            task = undefined;
+            foldAway(closed, call.id);
+            await options.onEvent?.(closed.id, local(call.name === "work_complete" ? "work.completed" : "work.failed", call.name === "work_complete"
+                ? { summary: String(call.input?.summary ?? "") }
+                : { reason: String(call.input?.reason ?? ""), detail: "" }));
+        }
+        return "done";
+    }
+    /** Asks the person every question the work still waits on and records the answers. */
+    async function answerPending(workId, signal) {
+        if (!options.onInput)
+            return [];
+        const got = await client.call("work_get", { id: workId, history: true }, signal);
+        const history = jsonOf(got)?.history;
+        const answers = [];
+        for (const { callId, question } of history?.pending ?? []) {
+            let answer;
+            try {
+                answer = await options.onInput(workId, question);
+            }
+            catch {
+                return "withdrawn";
+            }
+            const recorded = await client.call("work_answer", { call_id: callId, answer }, signal);
+            if (recorded.isError)
+                throw new Error(recorded.text);
+            answers.push({ question, answer });
+        }
+        return answers;
+    }
+    function finish(callId, result) {
+        const event = local("tool.completed", {
+            callId,
+            content: result.content,
+            isError: result.isError,
+        });
+        events.push(event);
+        void options.onEvent?.(task?.id ?? id, event);
+    }
+    /** Once a work is closed, only its summary stays in the conversation: the tool results are folded away. */
+    function foldAway(closed, closingCallId) {
+        for (const event of events) {
+            if (event.type !== "tool.completed")
+                continue;
+            const payload = event.payload;
+            if (!closed.callIds.has(payload.callId) || payload.callId === closingCallId)
+                continue;
+            payload.content = [
+                {
+                    type: "text",
+                    text: `(この結果は Work ${closed.id} を閉じたので省略。要点は work_complete の summary にある)`,
+                },
+            ];
+        }
+    }
+    return {
+        id,
+        agentName,
+        async turn(text, turnOptions = {}) {
+            events.push(local("human.message", { text }));
+            await record(id, "human.message", { text });
+            if (candidate) {
+                const note = `候補の Work: ${candidate.id}(status: ${candidate.status}、objective: ${candidate.objective})。この依頼がその objective に沿うなら work_select で続ける。沿わなければ続けず、その旨を伝えて新しい Work を作るか work_list で探し直す。`;
+                events.push(local("prompt.expanded", { name: "work resume", source: "builtin", text: note }));
+                await record(id, "prompt.expanded", { name: "work resume", source: "builtin", text: note });
+            }
+            try {
+                const result = await runTurn(turnOptions.signal);
+                return task ? { ...result, work: task.id } : result;
+            }
+            finally {
+                // Whatever the turn did, the next one starts from the conversation: a work it left open
+                // stays as it is and comes back as a candidate through select; a declined candidate is dropped.
+                candidate = undefined;
+                if (task) {
+                    task = undefined;
+                    await client.call("work_select", { id }).catch(() => undefined);
+                }
+            }
+        },
+        async select(workId) {
+            const got = await client.call("work_get", { id: workId });
+            if (got.isError)
+                throw new Error(got.text);
+            const work = jsonOf(got);
+            if (isTerminal(work.status))
+                throw new Error(`${work.id} は ${work.status} で、続けられません`);
+            candidate = { id: work.id, objective: work.objective, status: work.status };
+            return work;
+        },
+        currentWork: () => task?.id,
+        async close() {
+            const selected = await client.call("work_select", { id });
+            if (selected.isError) {
+                const got = await client.call("work_get", { id });
+                return jsonOf(got);
+            }
+            const closed = await client.call("work_complete", { summary: "会話を終了" });
+            if (closed.isError)
+                throw new Error(closed.text);
+            return jsonOf(closed);
+        },
+    };
+}
+/** The names of the sessions still open, so two people talking at once do not get the same one. */
+async function namesInUse(client) {
+    const listed = await client.call("work_list", {});
+    if (listed.isError)
+        return [];
+    const { works } = jsonOf(listed);
+    return works
+        .filter((w) => w.type === SESSION_WORK_TYPE && !isTerminal(w.status))
+        .flatMap((w) => (w.agentName ? [w.agentName] : []));
+}
+function textOf(content) {
+    return content
+        .filter((p) => p.type === "text")
+        .map((p) => p.text)
+        .join("\n")
+        .trim();
+}

package/dist/testing/fake-model.d.ts

@@ -0,0 +1,29 @@
+import type { ModelProvider, ModelRequest, ModelResponse } from "@openshain/core";
+/** One scripted answer: a response, or a function that builds one from the request. */
+export type FakeStep = ModelResponse | ((request: ModelRequest) => ModelResponse);
+/**
+ * A model that answers from a script, one response per call, and remembers
+ * every request it saw. For tests and for trying tools without a real model.
+ */
+export declare class FakeModelProvider implements ModelProvider {
+    readonly id = "fake";
+    readonly requests: ModelRequest[];
+    private readonly steps;
+    constructor(steps: FakeStep[]);
+    describe(): {
+        provider: string;
+        model: string;
+        capabilities: {
+            tools: boolean;
+        };
+    };
+    generate(request: ModelRequest): Promise<ModelResponse>;
+}
+/** A response that ends the turn with text. */
+export declare function say(text: string): ModelResponse;
+/** A response that asks for one or more tool calls. */
+export declare function callTools(...calls: {
+    id: string;
+    name: string;
+    input: unknown;
+}[]): ModelResponse;

package/dist/testing/fake-model.js

@@ -0,0 +1,39 @@
+/**
+ * A model that answers from a script, one response per call, and remembers
+ * every request it saw. For tests and for trying tools without a real model.
+ */
+export class FakeModelProvider {
+    id = "fake";
+    requests = [];
+    steps;
+    constructor(steps) {
+        this.steps = [...steps];
+    }
+    describe() {
+        return { provider: "fake", model: "fake-1", capabilities: { tools: true } };
+    }
+    async generate(request) {
+        this.requests.push(request);
+        const step = this.steps.shift();
+        if (!step)
+            throw new Error("the fake model ran out of scripted responses");
+        return typeof step === "function" ? step(request) : step;
+    }
+}
+/** A response that ends the turn with text. */
+export function say(text) {
+    return {
+        message: { role: "assistant", content: [{ type: "text", text }] },
+        stopReason: "end_turn",
+        usage: { inputTokens: 10, outputTokens: 5 },
+    };
+}
+/** A response that asks for one or more tool calls. */
+export function callTools(...calls) {
+    const content = calls.map((c) => ({ type: "tool_call", ...c }));
+    return {
+        message: { role: "assistant", content },
+        stopReason: "tool_call",
+        usage: { inputTokens: 10, outputTokens: 5 },
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1 @@
+export { callTools, FakeModelProvider, type FakeStep, say } from "./fake-model.ts";

package/dist/testing/index.js

@@ -0,0 +1 @@
+export { callTools, FakeModelProvider, say } from "./fake-model.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/agent",
-  "version": "0.1.1",
+  "version": "0.3.1",
   "description": "Tool loop and model providers (bring your own key)",
   "keywords": [
     "openshain",
@@ -21,27 +21,44 @@
   "bugs": "https://github.com/openshain/openshain/issues",
   "type": "module",
   "engines": {
+    "node": ">=22",
     "bun": ">=1.3"
   },
   "files": [
+    "dist",
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "README.md",
     "LICENSE"
   ],
   "exports": {
-    ".": "./src/index.ts",
-    "./testing": "./src/testing/index.ts"
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "bun": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
   },
-  "publishConfig": {
-    "access": "public"
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p tsconfig.build.json",
+    "prepublishOnly": "rm -rf dist && ../../node_modules/.bin/tsc -p tsconfig.build.json"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.123.0",
-    "@openshain/core": "0.1.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@openshain/core": "0.3.1",
     "openai": "7.10.0"
   },
   "devDependencies": {
-    "@openshain/tools": "0.1.0"
+    "@openshain/mcp": "0.3.1",
+    "@openshain/tools": "0.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/client.ts

@@ -0,0 +1,73 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { JsonSchema, ToolContent, ToolDefinition } from "@openshain/core";
+import pkg from "../package.json" with { type: "json" };
+
+/** 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 async function connectInMemory(server: Server): Promise<RuntimeClient> {
+  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: Client): RuntimeClient {
+  return {
+    async listTools() {
+      const { tools } = await client.listTools();
+      return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? "",
+        inputSchema: tool.inputSchema as JsonSchema,
+        effect: tool.annotations?.readOnlyHint === true ? "observe" : "mutate",
+      }));
+    },
+    async call(name, input, signal) {
+      const result = await client.callTool(
+        { name, arguments: (input ?? {}) as Record<string, unknown> },
+        undefined,
+        signal ? { signal } : undefined,
+      );
+      const parts = (result.content ?? []) as { type: string; text?: string }[];
+      const content: ToolContent[] = 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: ClientResult): unknown {
+  try {
+    return JSON.parse(result.text);
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -1,15 +1,6 @@
-// @openshain/agent: Tool loop and model providers (bring your own key)
+// @openshain/agent: The conversation loop that drives the runtime as an MCP client, and the model providers (bring your own key)
 
-export {
-  ASK_USER,
-  countToolCalls,
-  type FailureReason,
-  type PendingQuestion,
-  pendingQuestions,
-  RUNTIME_PROVIDER_ID,
-  type RunWorkOptions,
-  runWork,
-} from "./loop.ts";
+export { type ClientResult, connectInMemory, jsonOf, type RuntimeClient, wrap } from "./client.ts";
 export { AGENT_NAMES, pickAgentName } from "./names.ts";
 export {
   ANTHROPIC_PROVIDER_ID,
@@ -25,7 +16,6 @@ export {
 } from "./providers/openai-compatible.ts";
 export {
   createSession,
-  SESSION_TOOLS,
   type Session,
   type SessionOptions,
   TURN_LIMITS,