@openshain/agent 0.1.1 → 0.2.0

package/dist/session.js

@@ -0,0 +1,394 @@
+import { buildProjection, compileInputValidator, isOpenshainError, isTerminal, parseWorkId, SESSION_WORK_TYPE, } from "@openshain/core";
+import { countToolCalls, pendingQuestions, RUNTIME_PROVIDER_ID, runWork } from "./loop.js";
+import { pickAgentName } from "./names.js";
+/** How much one turn of a session may do before the person hears back. */
+export const TURN_LIMITS = { modelCalls: 5, toolCalls: 10 };
+/** What the session's model may do: hand work out and look work up. It never touches files itself. */
+export const SESSION_TOOLS = Object.freeze([
+    {
+        name: "work_run",
+        description: "Start a work for the person's request and drive it until it completes, fails or stops to ask the person a question. Write the objective in the person's own words and add what the conversation established that the work needs to know. Returns the work's id, status, summary, artifacts and usage, or the question it is waiting on.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                objective: {
+                    type: "string",
+                    minLength: 1,
+                    description: "The request, in the person's words.",
+                },
+                type: {
+                    type: "string",
+                    description: "A short label for the kind of work. Defaults to request.",
+                },
+            },
+            required: ["objective"],
+            additionalProperties: false,
+        },
+        effect: "mutate",
+    },
+    {
+        name: "work_list",
+        description: "The most recent works in this workspace, newest first, without sessions.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        effect: "observe",
+    },
+    {
+        name: "work_show",
+        description: "One work by id: its status, summary, artifacts, usage, and who has to act next.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string", minLength: 1 } },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        effect: "observe",
+    },
+]);
+const validators = new Map(SESSION_TOOLS.map((tool) => [tool.name, compileInputValidator(tool.inputSchema)]));
+const ROLE = "あなたはこの会社の社員エージェントとして、受付の役で、この人と話す。作業が要るときは work_run に objective を渡して Work にする。objective は人の言葉で書き、会話で分かった前提を添える。会社のファイルは自分では変更しない。ファイルの中身を見ないと答えられない質問も、work_run で Work にして調べる。作業の結果は要約して伝える。件数や金額は Work の結果の数字をそのまま書き、計算し直さない。返答は端末の画面に出るので、Markdown の記法や絵文字は使わず、短い文で書く。過去の作業は work_list と work_show で答える。";
+/** Opens a conversation, recorded as a work of type "session", between the person and the model. */
+export async function createSession(runtime, options = {}) {
+    const model = options.model ?? runtime.model;
+    const { principal, profession } = runtime.config;
+    const agentName = options.agentName ?? pickAgentName(runtime.config.company.language, await namesInUse(runtime));
+    const created = await runtime.works.create({
+        objective: "会話",
+        principal: principal.id,
+        profession: profession.id,
+        type: SESSION_WORK_TYPE,
+        agentName,
+    });
+    await withHandle(runtime, created.id, options, (handle) => handle.transition("in_progress", "session opened"));
+    return {
+        id: created.id,
+        agentName,
+        turn: (text, turnOptions = {}) => withHandle(runtime, created.id, options, async (handle) => {
+            await handle.append({ type: "human.message", payload: { text } });
+            return runTurn(runtime, handle, model, options, turnOptions.signal);
+        }),
+        close: () => withHandle(runtime, created.id, options, async (handle) => {
+            if (isTerminal((await handle.current()).status))
+                return handle.current();
+            await handle.append({
+                type: "evidence.recorded",
+                payload: { claim: "会話を終了", refs: [], artifacts: [] },
+            });
+            await handle.append({ type: "work.completed", payload: { summary: "会話を終了" } });
+            return handle.current();
+        }),
+    };
+}
+/** The names of the sessions still open, so two people talking at once do not get the same one. */
+async function namesInUse(runtime) {
+    const { works } = await runtime.works.list();
+    return works
+        .filter((w) => w.type === SESSION_WORK_TYPE && !isTerminal(w.status))
+        .flatMap((w) => (w.agentName ? [w.agentName] : []));
+}
+async function withHandle(runtime, id, options, fn) {
+    const opened = await runtime.works.open(id);
+    const handle = options.onEvent ? observed(opened, options.onEvent) : opened;
+    try {
+        return await fn(handle);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function runTurn(runtime, handle, model, options, signal) {
+    const description = model.describe();
+    const config = {
+        ...runtime.config,
+        profession: {
+            ...runtime.config.profession,
+            instructions: `${runtime.config.profession.instructions.trim()}\n\n${ROLE}`,
+        },
+    };
+    const turnStart = (await handle.events()).length;
+    const tools = [...SESSION_TOOLS];
+    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 events = await handle.events();
+        const projection = buildProjection({
+            events,
+            config,
+            tools,
+            providerId: model.id,
+            budget: {
+                modelCallsLeft: TURN_LIMITS.modelCalls - modelCalls,
+                toolCallsLeft: TURN_LIMITS.toolCalls - toolCalls,
+            },
+        });
+        await handle.append({
+            type: "model.requested",
+            payload: {
+                provider: model.id,
+                model: description.model,
+                messageCount: projection.messages.length,
+                toolNames: tools.map((t) => t.name),
+            },
+        });
+        modelCalls += 1;
+        let response;
+        try {
+            response = await model.generate({
+                system: projection.system,
+                messages: projection.messages,
+                tools: projection.tools,
+                maxOutputTokens: runtime.config.limits.maxOutputTokens,
+                budget: projection.budget,
+                stableMessages: projection.messages.length - 1,
+                ...(runtime.config.model.options && { providerOptions: runtime.config.model.options }),
+            }, signal);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await handle.append({
+                type: "model.failed",
+                payload: { code: isOpenshainError(err) ? err.code : "model_error", message },
+            });
+            return { reply: "", stopped: signal?.aborted ? "aborted" : "model_error", detail: message };
+        }
+        await handle.append({
+            type: "model.completed",
+            payload: {
+                stopReason: response.stopReason,
+                content: response.message.content,
+                ...(runtime.config.debug.persistRaw && response.raw !== undefined && { raw: response.raw }),
+            },
+        });
+        await handle.append({
+            type: "usage.recorded",
+            payload: {
+                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;
+                    await callSessionTool(runtime, handle, model, options, signal, call);
+                }
+                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}"`,
+                };
+        }
+        // Nothing of the turn's own events is needed below; the projection rebuilds from the log.
+        void turnStart;
+    }
+}
+async function callSessionTool(runtime, handle, model, options, signal, call) {
+    const validate = validators.get(call.name);
+    if (!validate) {
+        await handle.append({
+            type: "tool.rejected",
+            payload: {
+                callId: call.id,
+                name: call.name,
+                code: "unknown_tool",
+                reason: `no tool named "${call.name}"; the session offers ${SESSION_TOOLS.map((t) => t.name).join(", ")}`,
+            },
+        });
+        return;
+    }
+    const validation = validate(call.input);
+    if (!validation.ok) {
+        await handle.append({
+            type: "tool.rejected",
+            payload: {
+                callId: call.id,
+                name: call.name,
+                code: "schema_mismatch",
+                reason: `input does not match the schema of ${call.name}: ${validation.reason}`,
+            },
+        });
+        return;
+    }
+    await handle.append({
+        type: "tool.called",
+        payload: { callId: call.id, provider: RUNTIME_PROVIDER_ID, name: call.name, input: call.input },
+    });
+    let result;
+    try {
+        result = await runSessionTool(runtime, handle, model, options, signal, call.name, call.input);
+    }
+    catch (err) {
+        result = {
+            content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
+            isError: true,
+        };
+    }
+    await handle.append({
+        type: "tool.completed",
+        payload: { callId: call.id, content: result.content, isError: result.isError ?? false },
+    });
+}
+async function runSessionTool(runtime, handle, model, options, signal, name, input) {
+    switch (name) {
+        case "work_run": {
+            const type = typeof input.type === "string" && input.type !== "" ? input.type : "request";
+            if (type === SESSION_WORK_TYPE) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `type "${SESSION_WORK_TYPE}" is reserved for conversations; use another label, such as request`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const agentName = (await handle.current()).agentName;
+            const child = await runtime.works.create({
+                objective: String(input.objective),
+                principal: runtime.config.principal.id,
+                profession: runtime.config.profession.id,
+                type,
+                parent: handle.id,
+                ...(agentName !== undefined && { agentName }),
+            });
+            const done = await runWork(runtime, child.id, {
+                model,
+                ...(options.onInput && {
+                    onInput: (q) => options.onInput?.(child.id, q),
+                }),
+                ...(options.onWorkEvent && {
+                    onEvent: (e) => options.onWorkEvent?.(child.id, e),
+                }),
+                ...(signal && { signal }),
+            });
+            return {
+                content: [
+                    { type: "json", value: await describeWork(runtime, done, signal?.aborted === true) },
+                ],
+            };
+        }
+        case "work_list": {
+            const { works } = await runtime.works.list();
+            const recent = works
+                .filter((w) => w.type !== SESSION_WORK_TYPE)
+                .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+                .slice(0, 20)
+                .map((w) => ({
+                id: w.id,
+                status: w.status,
+                type: w.type,
+                objective: w.objective,
+                createdAt: w.createdAt,
+            }));
+            return { content: [{ type: "json", value: { works: recent } }] };
+        }
+        case "work_show": {
+            let id;
+            try {
+                id = parseWorkId(String(input.id));
+            }
+            catch {
+                return {
+                    content: [{ type: "text", text: `"${String(input.id)}" is not a work id` }],
+                    isError: true,
+                };
+            }
+            const work = await runtime.works.get(id);
+            return { content: [{ type: "json", value: await describeWork(runtime, work, false) }] };
+        }
+        default:
+            return { content: [{ type: "text", text: `no tool named "${name}"` }], isError: true };
+    }
+}
+/** A work as the session's model needs to see it: outcome, cost, and who acts next. */
+async function describeWork(runtime, work, interrupted) {
+    const events = await runtime.works.events(work.id);
+    const usage = {
+        modelCalls: 0,
+        toolCalls: countToolCalls(events),
+        inputTokens: 0,
+        outputTokens: 0,
+    };
+    for (const event of events) {
+        if (event.type === "model.requested")
+            usage.modelCalls += 1;
+        if (event.type === "usage.recorded") {
+            const { payload } = event;
+            if (payload.kind === "model_inference") {
+                usage.inputTokens += payload.usage.inputTokens;
+                usage.outputTokens += payload.usage.outputTokens;
+            }
+        }
+    }
+    const question = work.status === "waiting_input" ? pendingQuestions(events).map((q) => q.question) : [];
+    return {
+        id: work.id,
+        status: work.status,
+        ...(work.outcome && { summary: work.outcome.summary, artifacts: work.outcome.artifacts }),
+        ...(work.failure && { failure: work.failure }),
+        ...(question.length > 0 && { waitingFor: question }),
+        ...(interrupted &&
+            work.status === "in_progress" && {
+            interrupted: "the person stopped this work; it can be resumed",
+        }),
+        nextActor: isTerminal(work.status)
+            ? "nobody"
+            : work.status === "waiting_input"
+                ? "person"
+                : "model",
+        usage,
+    };
+}
+function textOf(content) {
+    return content
+        .filter((p) => p.type === "text")
+        .map((p) => p.text)
+        .join("\n")
+        .trim();
+}
+function observed(handle, onEvent) {
+    return {
+        ...handle,
+        async append(event) {
+            const recorded = await handle.append(event);
+            await onEvent(recorded);
+            return recorded;
+        },
+        async transition(to, reason) {
+            const recorded = await handle.transition(to, reason);
+            await onEvent(recorded);
+            return recorded;
+        },
+    };
+}

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.2.0",
   "description": "Tool loop and model providers (bring your own key)",
   "keywords": [
     "openshain",
@@ -21,27 +21,42 @@
   "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",
+    "@openshain/core": "0.2.0",
     "openai": "7.10.0"
   },
   "devDependencies": {
-    "@openshain/tools": "0.1.0"
+    "@openshain/tools": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/session.ts

@@ -72,7 +72,7 @@ const validators = new Map(
 );
 
 const ROLE =
-  "あなたはこの会社の社員エージェントとして、受付の役で、この人と話す。作業が要るときは work_run に objective を渡して Work にする。objective は人の言葉で書き、会話で分かった前提を添える。会社のファイルは自分では触らない。ファイルの中身を見ないと答えられない質問も、work_run で Work にして調べる。作業の結果は要約して伝える。件数や金額は Work の結果の数字をそのまま書き、計算し直さない。返答は端末の画面に出るので、Markdown の記法や絵文字は使わず、短い文で書く。過去の作業は work_list と work_show で答える。";
+  "あなたはこの会社の社員エージェントとして、受付の役で、この人と話す。作業が要るときは work_run に objective を渡して Work にする。objective は人の言葉で書き、会話で分かった前提を添える。会社のファイルは自分では変更しない。ファイルの中身を見ないと答えられない質問も、work_run で Work にして調べる。作業の結果は要約して伝える。件数や金額は Work の結果の数字をそのまま書き、計算し直さない。返答は端末の画面に出るので、Markdown の記法や絵文字は使わず、短い文で書く。過去の作業は work_list と work_show で答える。";
 
 export interface SessionOptions {
   /** Defaults to the runtime's model, for the session and for the works it starts. */