@roll-agent/sdk 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,30 @@
+# @roll-agent/sdk
+
+用于开发 Roll 子 Agent 的 TypeScript SDK。  
+SDK 当前负责封装 MCP Server 的 `stdio` 运行时；远程 `streamable-http` 服务端能力仍由业务方自行实现或部署。
+
+如果你的 tool 需要开放对象或复杂 JSON payload，建议同时考虑 `roll run --input-json` / `--input-file` 的调用体验；`roll ask` 更适合参数可以从自然语言可靠提取的 tool。
+
+最近 `roll-core` 已经演进出一套更明确的调用模型：
+
+- `ask` 采用“两阶段”：先选 tool，再按真实 `inputSchema` 提参
+- tool 参数会经过统一的 `tool-runtime` preflight 校验
+- 对开放对象/复杂 payload，commander 会要求显式输入，而不是让 LLM 猜
+
+## 安装
+
+```bash
+npm install @roll-agent/sdk zod
+```
+
+## 文档导航（Diátaxis）
+
+- Tutorial（新手跟做）: [Build your first agent](./docs/tutorial-build-first-agent.md)
+- How-to（任务指南）: [Register and run an agent with roll](./docs/how-to-register-agent-with-roll.md)
+- Reference（查阅手册）: [SDK API reference](./docs/reference-api.md)
+- Explanation（设计说明）: [SDK design and architecture](./docs/explanation-design.md)
+
+## 快速入口
+
+如果你第一次接入，请先看 Tutorial：  
+[Build your first agent](./docs/tutorial-build-first-agent.md)

package/dist/define-agent.d.ts

@@ -4,12 +4,15 @@ import type { LogLevel } from "./context.ts";
 export interface DefineAgentOptions {
     /** 最低日志级别，默认 "info" */
     readonly logLevel?: LogLevel;
+    /** 关闭 MCP Server 之前执行的资源清理回调 */
+    readonly onShutdown?: () => Promise<void>;
 }
 /**
  * 定义一个 Agent 并返回可运行实例。
  *
- * `listen()` 会启动一个 MCP Server (stdio 模式)，
- * 将所有 tool 注册为 MCP tool，通过 stdin/stdout 通信。
+ * `listen()` 支持两种传输模式：
+ * - stdio（默认）：通过 stdin/stdout 通信，适合 roll-core 以子进程方式调用
+ * - http：启动 Streamable HTTP 服务，适合浏览器 Agent 等需要持久进程的场景
  */
 export declare function defineAgent(definition: AgentDefinition, options?: DefineAgentOptions): RunnableAgent;
 //# sourceMappingURL=define-agent.d.ts.map

package/dist/define-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-agent.d.ts","sourceRoot":"","sources":["../src/define-agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAqB,MAAM,kBAAkB,CAAC;AAE1F,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE3D,uBAAuB;AACvB,MAAM,WAAW,kBAAkB;IACjC,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AA+DD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,GAAE,kBAAuB,GAAG,aAAa,CA+BxG"}
+{"version":3,"file":"define-agent.d.ts","sourceRoot":"","sources":["../src/define-agent.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAGd,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE3D,uBAAuB;AACvB,MAAM,WAAW,kBAAkB;IACjC,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AA+DD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,eAAe,EAC3B,OAAO,GAAE,kBAAuB,GAC/B,aAAa,CAcf"}

package/dist/define-agent.js

@@ -1,5 +1,8 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
 import { createAgentLogger } from "./context.js";
 /**
@@ -59,37 +62,177 @@ function extractSamplingText(content) {
 /**
  * 定义一个 Agent 并返回可运行实例。
  *
- * `listen()` 会启动一个 MCP Server (stdio 模式)，
- * 将所有 tool 注册为 MCP tool，通过 stdin/stdout 通信。
+ * `listen()` 支持两种传输模式：
+ * - stdio（默认）：通过 stdin/stdout 通信，适合 roll-core 以子进程方式调用
+ * - http：启动 Streamable HTTP 服务，适合浏览器 Agent 等需要持久进程的场景
  */
 export function defineAgent(definition, options = {}) {
     return {
         ...definition,
-        listen: async () => {
-            const server = new McpServer({
+        listen: async (listenOptions) => {
+            const transport = listenOptions?.transport ?? { type: "stdio" };
+            const logLevel = options.logLevel ?? "info";
+            if (transport.type === "http") {
+                await listenHttp(definition, logLevel, transport.port, transport.host, options.onShutdown);
+            }
+            else {
+                await listenStdio(definition, logLevel, options.onShutdown);
+            }
+        },
+    };
+}
+function registerShutdownHandlers(shutdown) {
+    let inFlightShutdown;
+    const handleSignal = (signal) => {
+        inFlightShutdown ??= shutdown(signal).catch(() => {
+            process.exit(1);
+        });
+    };
+    process.once("SIGTERM", () => {
+        handleSignal("SIGTERM");
+    });
+    process.once("SIGINT", () => {
+        handleSignal("SIGINT");
+    });
+}
+// ========== Stdio Transport ==========
+async function listenStdio(definition, logLevel, onShutdown) {
+    const server = new McpServer({
+        name: definition.name,
+        version: "0.0.1",
+    });
+    const ctx = createContext(definition.name, logLevel, server);
+    for (const tool of definition.tools) {
+        registerTool(server, tool, ctx);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    ctx.logger.info("MCP Server running on stdio");
+    const shutdown = async (signal) => {
+        ctx.logger.info(`${signal} received, shutting down...`);
+        if (onShutdown) {
+            await onShutdown();
+        }
+        await server.close();
+        process.exit(0);
+    };
+    registerShutdownHandlers(shutdown);
+}
+// ========== HTTP Transport ==========
+/**
+ * 启动 Streamable HTTP MCP Server。
+ *
+ * 每个客户端 session 独立创建 McpServer + StreamableHTTPServerTransport，
+ * 因为 McpServer.connect(transport) 是 1:1 绑定。
+ * 但所有 session 共享同一个 AgentContext 的模块级状态（如 BrowserRuntime）。
+ */
+async function listenHttp(definition, logLevel, port, host, onShutdown) {
+    const logger = createAgentLogger(definition.name, logLevel);
+    const sessions = new Map();
+    const httpServer = createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        // 只处理 /mcp 路径
+        if (url.pathname !== "/mcp") {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not found" }));
+            return;
+        }
+        const sessionId = typeof req.headers["mcp-session-id"] === "string" ? req.headers["mcp-session-id"] : undefined;
+        // 已有 session → 路由到对应 transport
+        if (sessionId) {
+            const session = sessions.get(sessionId);
+            if (session) {
+                try {
+                    await session.transport.handleRequest(req, res);
+                }
+                catch (err) {
+                    logger.error(`Error handling request for session ${sessionId}: ${String(err)}`);
+                    if (!res.headersSent) {
+                        res.writeHead(500, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "Internal server error" }));
+                    }
+                }
+                return;
+            }
+            // session ID 未找到 → 404
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Session not found" }));
+            return;
+        }
+        // 无 session ID → 新建 session
+        try {
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+            });
+            const mcpServer = new McpServer({
                 name: definition.name,
                 version: "0.0.1",
             });
-            const ctx = createContext(definition.name, options.logLevel ?? "info", server);
-            // 注册所有 tool 到 MCP Server
+            const ctx = createContext(definition.name, logLevel, mcpServer);
             for (const tool of definition.tools) {
-                registerTool(server, tool, ctx);
+                registerTool(mcpServer, tool, ctx);
             }
-            // 启动 stdio 传输
-            const transport = new StdioServerTransport();
-            await server.connect(transport);
-            ctx.logger.info("MCP Server running on stdio");
-            // Graceful shutdown：收到 SIGTERM/SIGINT 时清理 MCP Server
-            const shutdown = async (signal) => {
-                ctx.logger.info(`${signal} received, shutting down...`);
-                await server.close();
-                process.exit(0);
+            // onclose / onerror 必须在 connect() 之前设置，避免竞态
+            transport.onclose = () => {
+                const id = transport.sessionId;
+                if (id) {
+                    sessions.delete(id);
+                    logger.info(`Session ${id} closed`);
+                }
             };
-            process.on("SIGTERM", () => { shutdown("SIGTERM").catch(() => process.exit(1)); });
-            process.on("SIGINT", () => { shutdown("SIGINT").catch(() => process.exit(1)); });
-        },
+            transport.onerror = (err) => {
+                logger.error(`Transport error (session ${transport.sessionId ?? "unknown"}): ${err.message}`);
+            };
+            // MCP SDK 的 StreamableHTTPServerTransport.onclose 类型为 (() => void) | undefined
+            // 而 Transport.onclose 期望 () => void（exactOptionalPropertyTypes 不兼容）
+            // 这是上游类型定义问题，此处安全地 cast
+            await mcpServer.connect(transport);
+            // 处理当前请求（initialization）— sessionId 在 handleRequest 内由 sessionIdGenerator 生成
+            await transport.handleRequest(req, res);
+            // Node.js 单线程保证：handleRequest 完成前不会处理下一个 HTTP 请求，
+            // 因此这里注册 session 不存在竞态
+            if (transport.sessionId) {
+                sessions.set(transport.sessionId, { transport, server: mcpServer });
+            }
+        }
+        catch (err) {
+            logger.error(`Error creating new session: ${String(err)}`);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Failed to create session" }));
+            }
+        }
+    });
+    // HTTP server 错误处理
+    httpServer.on("error", (err) => {
+        logger.error(`HTTP server error: ${err.message}`);
+    });
+    const listenHost = host ?? "127.0.0.1";
+    httpServer.listen(port, listenHost, () => {
+        logger.info(`MCP Server running on http://${listenHost}:${port}/mcp`);
+    });
+    // Graceful shutdown：先停止接收新请求 → 再关闭 MCP session
+    const shutdown = async (signal) => {
+        logger.info(`${signal} received, shutting down HTTP server...`);
+        // 1. 停止接收新连接
+        await new Promise((resolve) => {
+            httpServer.close(() => resolve());
+        });
+        // 2. 关闭所有 MCP session
+        const closePromises = [];
+        for (const [, session] of sessions) {
+            closePromises.push(session.server.close());
+        }
+        await Promise.all(closePromises);
+        sessions.clear();
+        if (onShutdown) {
+            await onShutdown();
+        }
+        process.exit(0);
     };
+    registerShutdownHandlers(shutdown);
 }
+// ========== Tool Registration ==========
 /** 将单个 tool 注册到 MCP Server */
 function registerTool(server, tool, ctx) {
     // MCP SDK 的 registerTool 要求 ZodObject，但 AnyToolDefinition.input 是更宽泛的 ZodType（类型擦除代价）

package/dist/define-agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-agent.js","sourceRoot":"","sources":["../src/define-agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define-agent.js","sourceRoot":"","sources":["../src/define-agent.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export type { DefineAgentOptions } from "./define-agent.ts";
 export { defineTool } from "./define-tool.ts";
 export { createAgentLogger } from "./context.ts";
 export type { AgentContext, AgentLogger, AgentLLM, LogLevel } from "./context.ts";
-export type { AnyToolDefinition, ToolDefinition, AgentDefinition, RunnableAgent, } from "./types/index.ts";
+export type { AnyToolDefinition, ToolDefinition, AgentDefinition, RunnableAgent, TransportConfig, ListenOptions, } from "./types/index.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAClF,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAClF,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,kBAAkB,CAAC"}

package/dist/types/index.d.ts

@@ -18,9 +18,19 @@ export interface AgentDefinition {
     readonly name: string;
     readonly tools: ReadonlyArray<AnyToolDefinition>;
 }
+export type TransportConfig = {
+    readonly type: "stdio";
+} | {
+    readonly type: "http";
+    readonly port: number;
+    readonly host?: string;
+};
+export interface ListenOptions {
+    readonly transport?: TransportConfig;
+}
 /** defineAgent() 返回的可运行 Agent */
 export interface RunnableAgent extends AgentDefinition {
-    /** 启动 MCP Server (stdio 模式)，阻塞直到连接关闭 */
-    readonly listen: () => Promise<void>;
+    /** 启动 MCP Server，阻塞直到连接关闭 */
+    readonly listen: (options?: ListenOptions) => Promise<void>;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,6BAA6B;AAC7B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzE;AAED,oBAAoB;AACpB,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,CAAE,SAAQ,iBAAiB;IAC5F,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CAClD;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,6BAA6B;AAC7B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzE;AAED,oBAAoB;AACpB,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,CAAE,SAAQ,iBAAiB;IAC5F,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CAClD;AAID,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;CACtC;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D"}

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@roll-agent/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/steveoon/roll-agent"
+  },
+  "homepage": "https://github.com/steveoon/roll-agent",
+  "bugs": {
+    "url": "https://github.com/steveoon/roll-agent/issues"
+  },
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "publishConfig": {
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
-    }
+    "access": "public"
   },
   "files": [
     "dist"
@@ -22,17 +25,17 @@
   "engines": {
     "node": ">=22.6.0"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\"",
-    "clean": "rm -rf dist"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.25.0"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\"",
+    "clean": "rm -rf dist"
   }
-}
+}