@openshain/agent 0.2.0 → 0.4.0

package/NOTICE

@@ -0,0 +1,4 @@
+openshain
+Copyright 2026 openshain contributors
+
+Licensed under the Apache License, Version 2.0.

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

@@ -1,5 +1,5 @@
-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, AnthropicProvider, type AnthropicProviderOptions, anthropicProvider, } from "./providers/anthropic.ts";
 export { OPENAI_COMPATIBLE_PROVIDER_ID, OpenAICompatibleProvider, type OpenAICompatibleProviderOptions, openaiCompatibleProvider, } from "./providers/openai-compatible.ts";
-export { createSession, SESSION_TOOLS, type Session, type SessionOptions, TURN_LIMITS, type TurnResult, type TurnStop, } from "./session.ts";
+export { type ApprovalAnswer, type ApprovalChoice, createSession, type HeldApproval, type Session, type SessionOptions, TURN_LIMITS, type TurnResult, type TurnStop, } from "./session.ts";

package/dist/index.js

@@ -1,6 +1,6 @@
-// @openshain/agent: Tool loop and model providers (bring your own key)
-export { ASK_USER, countToolCalls, pendingQuestions, RUNTIME_PROVIDER_ID, runWork, } from "./loop.js";
+// @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, SESSION_TOOLS, TURN_LIMITS, } from "./session.js";
+export { createSession, TURN_LIMITS, } from "./session.js";

package/dist/session.d.ts

@@ -1,30 +1,65 @@
-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. */
+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: 5;
-    readonly toolCalls: 10;
+    readonly modelCalls: 25;
+    readonly toolCalls: 40;
 };
-/** 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 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 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>;
+    /** 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>;
+    /**
+     * Asks the person about a call the policy held, while the turn waits. Without it, the turn
+     * ends and the call stays held for `/approve` or for another client.
+     */
+    onApproval?: (held: HeldApproval) => Promise<ApprovalAnswer>;
+}
+export type TurnStop = "turn_limit" | "aborted" | "max_tokens" | "refusal" | "model_error" | "approval";
+/** A tool call the policy holds until a person decides on it. */
+export interface HeldApproval {
+    approvalId: string;
+    workId: WorkId;
+    name: string;
+    input: unknown;
+    /** The rule that held it: the unit a person can say yes to for the rest of the conversation. */
+    ruleId: string;
+    /** review when a qualified reviewer has to decide; a person cannot stand in for one. */
+    kind: "approval" | "review";
+    reviewer?: {
+        role: string;
+        name?: string;
+    };
+}
+/**
+ * What the person answered about a held call. `always` approves this one and every later call
+ * the same rule holds, for this conversation only: nothing is written to authority/, and every
+ * call is still recorded as requested and decided.
+ */
+export type ApprovalChoice = "approve" | "always" | "reject";
+/** The person's answer: what they chose, and what they want the agent to know. */
+export interface ApprovalAnswer {
+    choice: ApprovalChoice;
+    /** Why, in the person's words. Recorded with the decision and handed to the model. */
+    comment?: 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;
+    /** The call held for approval, when the turn stopped for one. */
+    approval?: HeldApproval;
 }
 export interface Session {
     readonly id: WorkId;
@@ -34,8 +69,41 @@ export interface Session {
     turn(text: string, options?: {
         signal?: AbortSignal;
     }): Promise<TurnResult>;
-    /** Ends the conversation. The record stays. */
+    /** Names a stopped work as the candidate for the next request. The model decides whether to continue it. */
+    select(workId: WorkId): Promise<Work>;
+    /** Decides a held call as the person. approve runs it; either way the work becomes the candidate. */
+    decide(approvalId: string, decision: "approve" | "reject", comment?: string): Promise<{
+        workId: WorkId;
+        text: string;
+    }>;
+    /** Records what a qualified reviewer decided about a call held for review. */
+    review(input: {
+        approvalId: string;
+        decision: "approve" | "reject";
+        reviewer: {
+            name: string;
+            role: string;
+            qualification?: string;
+        };
+        interpretation: string;
+        appliesTo?: {
+            action?: string;
+            path?: string;
+        };
+    }): Promise<{
+        workId: WorkId;
+        text: string;
+    }>;
+    /** The calls held for approval across the workspace. */
+    approvals(): Promise<HeldApproval[]>;
+    /** 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. */
-export declare function createSession(runtime: Runtime, options?: SessionOptions): Promise<Session>;
+/**
+ * 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>;