@roll-agent/sdk 0.5.0 → 0.6.0

package/dist/app-output.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { type AppOutputContract, type AppOutputDeclaration } from "@roll-agent/protocol/app-output";
+import type { AnyToolDefinition } from "./types/index.ts";
+export declare function prepareAppOutput(tool: AnyToolDefinition): {
+    readonly declaration: AppOutputDeclaration;
+    readonly contract: AppOutputContract;
+} | undefined;
+export declare function projectAppOutput(schema: z.ZodType, result: unknown): Promise<{
+    isError: true;
+    _meta: {
+        "roll/appOutputStatus": "invalid" | "too_large";
+        "roll/executionStatus": string;
+    };
+    content: [{
+        type: "text";
+        text: string;
+    }];
+} | {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    structuredContent: Record<string, unknown>;
+}>;

package/dist/define-agent.d.ts

@@ -37,6 +37,8 @@ type McpToolResult = {
         type: "text";
         text: string;
     }, ...McpToolContentBlock[]];
+    structuredContent?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
 };
 export declare function executeToolForMcp(tool: AnyToolDefinition, ctx: AgentContext, params: Record<string, unknown>, signal?: AbortSignal): Promise<McpToolResult>;
 export {};

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export { StructuredToolError, isStructuredToolError } from "./tool-error.ts";
 export type { StructuredToolErrorPayload } from "./tool-error.ts";
 export type { AnyToolDefinition, ToolDefinition, AgentDefinition, RunnableAgent, TransportConfig, ListenOptions, ToolResourceAccessMode, ToolResourceHint, ToolResourceHintKind, } from "./types/index.ts";
 export { TOOL_RESOURCE_ACCESS_MODES, TOOL_RESOURCE_HINT_KINDS } from "./types/index.ts";
+export type { AppOutputDeclaration, AppOutputContract } from "@roll-agent/protocol/app-output";

package/dist/index.js

@@ -1 +1 @@
-import{createServer as e}from"node:http";import{randomUUID as n}from"node:crypto";import{McpServer as t}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as r}from"@modelcontextprotocol/sdk/server/stdio.js";import{StreamableHTTPServerTransport as o}from"@modelcontextprotocol/sdk/server/streamableHttp.js";var s={debug:0,info:1,warn:2,error:3};function i(e,n="info"){const t=s[n],r=(n,r)=>{if(s[n]<t)return;const o=(new Date).toISOString(),i=n.toUpperCase().padEnd(5);console.error(`${o} [${i}] [${e}] ${r}`)};return{debug:e=>r("debug",e),info:e=>r("info",e),warn:e=>r("warn",e),error:e=>r("error",e)}}import{z as a}from"zod";var c=8;function l(e){let n=e;for(let e=0;e<c;e+=1)if(n instanceof a.ZodEffects)n=n.innerType();else if(n instanceof a.ZodOptional||n instanceof a.ZodNullable||n instanceof a.ZodBranded||n instanceof a.ZodReadonly)n=n.unwrap();else if(n instanceof a.ZodDefault)n=n.removeDefault();else{if(!(n instanceof a.ZodCatch))return n;n=n.removeCatch()}return n}async function p(e,n){const t=await e.safeParseAsync(n);if(!t.success)throw new Error(`Tool input validation failed: ${f(t.error)}`);return t.data}function f(e){return e.issues.map(e=>{const n=e.path.join(".");return n.length>0?`${n}: ${e.message}`:e.message}).join("; ")}var d=class extends Error{payload;constructor(e){super(e.message),this.name="StructuredToolError",this.payload=e}};function u(e){return e instanceof d||e instanceof Error&&"payload"in e&&y(e.payload)}function y(e){if("object"!=typeof e||null===e||Array.isArray(e))return!1;const n=e,t=n.details;return"string"==typeof n.code&&"string"==typeof n.message&&(void 0===t||"object"==typeof t&&null!==t&&!Array.isArray(t))}var m="roll/resourceHints";function g(e){return e??w()??"info"}function w(){const e=process.env.ROLL_AGENT_LOG_LEVEL;if("debug"===e||"info"===e||"warn"===e||"error"===e)return e}function h(e,n,t){return{llm:{generateText:async e=>{try{const n=v((await t.server.createMessage({messages:[{role:"user",content:{type:"text",text:e}}],maxTokens:1024})).content);if(void 0===n)throw new Error("Sampling response did not include text content");return n}catch(e){throw new Error("LLM sampling unavailable. Ensure roll-core client enables sampling capability.",{cause:e})}}},logger:i(e,n)}}function v(e){if("object"==typeof e&&null!==e&&"type"in e&&"text"===e.type&&"text"in e){const n=e.text;return"string"==typeof n?n:void 0}if(Array.isArray(e))for(const n of e){const e=v(n);if(void 0!==e)return e}}function S(e,n={}){return{...e,listen:async t=>{const r=t?.transport??{type:"stdio"},o=g(n.logLevel);"http"===r.type?await $(e,o,r.port,r.host,n.onShutdown):await x(e,o,n.onShutdown)}}}function T(e){let n;const t=t=>{n??=e(t).catch(()=>{process.exit(1)})};process.once("SIGTERM",()=>{t("SIGTERM")}),process.once("SIGINT",()=>{t("SIGINT")})}async function x(e,n,o){const s=new t({name:e.name,version:"0.0.1"}),i=h(e.name,n,s);for(const n of e.tools)b(s,n,i);const a=new r;await s.connect(a),i.logger.info("MCP Server running on stdio");T(async e=>{i.logger.info(`${e} received, shutting down...`),o&&await o(),await s.close(),process.exit(0)})}async function $(r,s,a,c,l){const p=i(r.name,s),f=new Map,d=e(async(e,i)=>{if("/mcp"!==new URL(e.url??"/",`http://${e.headers.host??"localhost"}`).pathname)return i.writeHead(404,{"Content-Type":"application/json"}),void i.end(JSON.stringify({error:"Not found"}));const a="string"==typeof e.headers["mcp-session-id"]?e.headers["mcp-session-id"]:void 0;if(a){const n=f.get(a);if(n){try{await n.transport.handleRequest(e,i)}catch(e){p.error(`Error handling request for session ${a}: ${String(e)}`),i.headersSent||(i.writeHead(500,{"Content-Type":"application/json"}),i.end(JSON.stringify({error:"Internal server error"})))}return}return i.writeHead(404,{"Content-Type":"application/json"}),void i.end(JSON.stringify({error:"Session not found"}))}try{const a=new o({sessionIdGenerator:()=>n()}),c=new t({name:r.name,version:"0.0.1"}),l=h(r.name,s,c);for(const e of r.tools)b(c,e,l);a.onclose=()=>{const e=a.sessionId;e&&(f.delete(e),p.info(`Session ${e} closed`))},a.onerror=e=>{p.error(`Transport error (session ${a.sessionId??"unknown"}): ${e.message}`)},await c.connect(a),await a.handleRequest(e,i),a.sessionId&&f.set(a.sessionId,{transport:a,server:c})}catch(e){p.error(`Error creating new session: ${String(e)}`),i.headersSent||(i.writeHead(500,{"Content-Type":"application/json"}),i.end(JSON.stringify({error:"Failed to create session"})))}});d.on("error",e=>{p.error(`HTTP server error: ${e.message}`)});const u=c??"127.0.0.1";d.listen(a,u,()=>{p.info(`MCP Server running on http://${u}:${a}/mcp`)});T(async e=>{p.info(`${e} received, shutting down HTTP server...`),await new Promise(e=>{d.close(()=>e())});const n=[];for(const[,e]of f)n.push(e.server.close());await Promise.all(n),f.clear(),l&&await l(),process.exit(0)})}function b(e,n,t){const r={...n._meta??{},...n.resourceHints&&n.resourceHints.length>0?{[m]:n.resourceHints}:{}};e.registerTool(n.name,{description:n.description,inputSchema:l(n.input),...n.annotations?{annotations:n.annotations}:{},...Object.keys(r).length>0?{_meta:r}:{}},async(e,r)=>await j(n,t,e,r.signal))}function E(e){if("object"!=typeof e||null===e||Array.isArray(e))return{payload:e,images:[]};const n=e,t=n.mcpImages;if(!Array.isArray(t))return{payload:e,images:[]};const r=t.filter(e=>"object"==typeof e&&null!==e&&"string"==typeof e.data&&"string"==typeof e.mimeType),{mcpImages:o,...s}=n;return{payload:s,images:r}}async function j(e,n,t,r){const o=await p(e.input,t),s=void 0===r?n:{...n,signal:r};try{const n=await e.execute(o,s),{payload:t,images:r}=E(n);return{content:[{type:"text",text:JSON.stringify(t)},...r.map(e=>({type:"image",data:e.data,mimeType:e.mimeType}))]}}catch(e){if(u(e))return{isError:!0,content:[{type:"text",text:JSON.stringify(e.payload)}]};throw e}}function I(e){return e}var A={read:"read",write:"write"},H={file:"file",browserSession:"browser-session",conversation:"conversation",custom:"custom"};export{d as StructuredToolError,A as TOOL_RESOURCE_ACCESS_MODES,H as TOOL_RESOURCE_HINT_KINDS,i as createAgentLogger,S as defineAgent,I as defineTool,u as isStructuredToolError};
+import{APP_OUTPUT_META_KEY as e}from"@roll-agent/protocol/app-output";import{AjvJsonSchemaValidator as t}from"@modelcontextprotocol/sdk/validation/ajv";import{isDeepStrictEqual as o}from"node:util";import{z as n}from"zod";import{toJsonSchemaCompat as r}from"@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";import{APP_OUTPUT_LIMITS as s,APP_OUTPUT_STATUS_META_KEY as a,appOutputDeclarationSchema as i,validateAppOutputContract as c}from"@roll-agent/protocol/app-output";function f(e,t=new Set){if(!t.has(e))if(t.add(e),e instanceof n.ZodObject){for(const o of Object.values(e.shape))o instanceof n.ZodType&&f(o,t);e._def.catchall instanceof n.ZodNever||f(e._def.catchall,t)}else if(e instanceof n.ZodArray)f(e.element,t);else if(e instanceof n.ZodOptional||e instanceof n.ZodNullable||e instanceof n.ZodReadonly||e instanceof n.ZodBranded)f(e.unwrap(),t);else if(e instanceof n.ZodUnion)for(const o of e.options)f(o,t);else if(e instanceof n.ZodDiscriminatedUnion)for(const o of e.options)f(o,t);else if(e instanceof n.ZodTuple){for(const o of e.items)f(o,t);e._def.rest&&f(e._def.rest,t)}else if(e instanceof n.ZodRecord)f(e.keySchema,t),f(e.valueSchema,t);else if(e instanceof n.ZodString||e instanceof n.ZodNumber||e instanceof n.ZodBoolean){if(e._def.coerce)throw new Error("appOutput does not support coercion");if(e instanceof n.ZodString)for(const t of e._def.checks)if(["trim","toLowerCase","toUpperCase"].includes(t.kind)||"regex"===t.kind&&""!==t.regex.flags)throw new Error("appOutput cannot represent string transformations or regex flags")}else if(e instanceof n.ZodLiteral){const t=e.value;if(null!==t&&"string"!=typeof t&&"boolean"!=typeof t&&("number"!=typeof t||!Number.isFinite(t)))throw new Error("appOutput requires JSON-compatible literals")}else if(!(e instanceof n.ZodNull||e instanceof n.ZodEnum||e instanceof n.ZodNativeEnum))throw new Error(`appOutput cannot represent ${e.constructor.name} as JSON Schema`)}function p(e){if(!e.appOutput)return;if(!(e.output instanceof n.ZodObject))throw new Error("appOutput requires an object output schema");f(e.output);const o=i.parse(e.appOutput),s=c({...o,outputSchema:r(e.output,{pipeStrategy:"output"})});return(new t).getValidator(s.outputSchema),{declaration:o,contract:s}}function u(e){return{isError:!0,_meta:{[a]:e,"roll/executionStatus":"completed"},content:[{type:"text",text:"Tool execution completed; application output unavailable. Do not repeat the operation."}]}}async function l(e,t){try{const n=await e.safeParseAsync(t);if(!n.success||!o(n.data,t))return u("invalid");const r=JSON.stringify(t);if(void 0===r)return u("invalid");if(Buffer.byteLength(r,"utf8")>s.resultBytes)return u("too_large");const a=JSON.parse(r);return!o(a,t)||"object"!=typeof a||null===a||Array.isArray(a)?u("invalid"):{content:[{type:"text",text:r}],structuredContent:a}}catch{return u("invalid")}}import{createServer as d}from"node:http";import{randomUUID as m}from"node:crypto";import{McpServer as y}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as g}from"@modelcontextprotocol/sdk/server/stdio.js";import{StreamableHTTPServerTransport as w}from"@modelcontextprotocol/sdk/server/streamableHttp.js";var h={debug:0,info:1,warn:2,error:3};function v(e,t="info"){const o=h[t],n=(t,n)=>{if(h[t]<o)return;const r=(new Date).toISOString(),s=t.toUpperCase().padEnd(5);console.error(`${r} [${s}] [${e}] ${n}`)};return{debug:e=>n("debug",e),info:e=>n("info",e),warn:e=>n("warn",e),error:e=>n("error",e)}}import{z as S}from"zod";var x=8;function b(e){let t=e;for(let e=0;e<x;e+=1)if(t instanceof S.ZodEffects)t=t.innerType();else if(t instanceof S.ZodOptional||t instanceof S.ZodNullable||t instanceof S.ZodBranded||t instanceof S.ZodReadonly)t=t.unwrap();else if(t instanceof S.ZodDefault)t=t.removeDefault();else{if(!(t instanceof S.ZodCatch))return t;t=t.removeCatch()}return t}async function Z(e,t){const o=await e.safeParseAsync(t);if(!o.success)throw new Error(`Tool input validation failed: ${O(o.error)}`);return o.data}function O(e){return e.issues.map(e=>{const t=e.path.join(".");return t.length>0?`${t}: ${e.message}`:e.message}).join("; ")}var T=class extends Error{payload;constructor(e){super(e.message),this.name="StructuredToolError",this.payload=e}};function E(e){return e instanceof T||e instanceof Error&&"payload"in e&&j(e.payload)}function j(e){if("object"!=typeof e||null===e||Array.isArray(e))return!1;const t=e,o=t.details;return"string"==typeof t.code&&"string"==typeof t.message&&(void 0===o||"object"==typeof o&&null!==o&&!Array.isArray(o))}var N="roll/resourceHints";function $(e){return e??A()??"info"}function A(){const e=process.env.ROLL_AGENT_LOG_LEVEL;if("debug"===e||"info"===e||"warn"===e||"error"===e)return e}function I(e,t,o){return{llm:{generateText:async e=>{try{const t=_((await o.server.createMessage({messages:[{role:"user",content:{type:"text",text:e}}],maxTokens:1024})).content);if(void 0===t)throw new Error("Sampling response did not include text content");return t}catch(e){throw new Error("LLM sampling unavailable. Ensure roll-core client enables sampling capability.",{cause:e})}}},logger:v(e,t)}}function _(e){if("object"==typeof e&&null!==e&&"type"in e&&"text"===e.type&&"text"in e){const t=e.text;return"string"==typeof t?t:void 0}if(Array.isArray(e))for(const t of e){const e=_(t);if(void 0!==e)return e}}function k(e,t={}){return{...e,listen:async o=>{const n=o?.transport??{type:"stdio"},r=$(t.logLevel);"http"===n.type?await H(e,r,n.port,n.host,t.onShutdown):await L(e,r,t.onShutdown)}}}function C(e){let t;const o=o=>{t??=e(o).catch(()=>{process.exit(1)})};process.once("SIGTERM",()=>{o("SIGTERM")}),process.once("SIGINT",()=>{o("SIGINT")})}async function L(e,t,o){const n=new y({name:e.name,version:"0.0.1"}),r=I(e.name,t,n);for(const t of e.tools)J(n,t,r);const s=new g;await n.connect(s),r.logger.info("MCP Server running on stdio");C(async e=>{r.logger.info(`${e} received, shutting down...`),o&&await o(),await n.close(),process.exit(0)})}async function H(e,t,o,n,r){const s=v(e.name,t),a=new Map,i=d(async(o,n)=>{if("/mcp"!==new URL(o.url??"/",`http://${o.headers.host??"localhost"}`).pathname)return n.writeHead(404,{"Content-Type":"application/json"}),void n.end(JSON.stringify({error:"Not found"}));const r="string"==typeof o.headers["mcp-session-id"]?o.headers["mcp-session-id"]:void 0;if(r){const e=a.get(r);if(e){try{await e.transport.handleRequest(o,n)}catch(e){s.error(`Error handling request for session ${r}: ${String(e)}`),n.headersSent||(n.writeHead(500,{"Content-Type":"application/json"}),n.end(JSON.stringify({error:"Internal server error"})))}return}return n.writeHead(404,{"Content-Type":"application/json"}),void n.end(JSON.stringify({error:"Session not found"}))}try{const r=new w({sessionIdGenerator:()=>m()}),i=new y({name:e.name,version:"0.0.1"}),c=I(e.name,t,i);for(const t of e.tools)J(i,t,c);r.onclose=()=>{const e=r.sessionId;e&&(a.delete(e),s.info(`Session ${e} closed`))},r.onerror=e=>{s.error(`Transport error (session ${r.sessionId??"unknown"}): ${e.message}`)},await i.connect(r),await r.handleRequest(o,n),r.sessionId&&a.set(r.sessionId,{transport:r,server:i})}catch(e){s.error(`Error creating new session: ${String(e)}`),n.headersSent||(n.writeHead(500,{"Content-Type":"application/json"}),n.end(JSON.stringify({error:"Failed to create session"})))}});i.on("error",e=>{s.error(`HTTP server error: ${e.message}`)});const c=n??"127.0.0.1";i.listen(o,c,()=>{s.info(`MCP Server running on http://${c}:${o}/mcp`)});C(async e=>{s.info(`${e} received, shutting down HTTP server...`),await new Promise(e=>{i.close(()=>e())});const t=[];for(const[,e]of a)t.push(e.server.close());await Promise.all(t),a.clear(),r&&await r(),process.exit(0)})}function J(t,o,n){const r=p(o),s={...o._meta??{},...r?{[e]:r.declaration}:{},...o.resourceHints&&o.resourceHints.length>0?{[N]:o.resourceHints}:{}};t.registerTool(o.name,{description:o.description,inputSchema:b(o.input),...r?{outputSchema:o.output}:{},...o.annotations?{annotations:o.annotations}:{},...Object.keys(s).length>0?{_meta:s}:{}},async(e,t)=>await P(o,n,e,t.signal))}function R(e){if("object"!=typeof e||null===e||Array.isArray(e))return{payload:e,images:[]};const t=e,o=t.mcpImages;if(!Array.isArray(o))return{payload:e,images:[]};const n=o.filter(e=>"object"==typeof e&&null!==e&&"string"==typeof e.data&&"string"==typeof e.mimeType),{mcpImages:r,...s}=t;return{payload:s,images:n}}async function P(e,t,o,n){const r=p(e),s=await Z(e.input,o),a=void 0===n?t:{...t,signal:n};try{const t=await e.execute(s,a);if(r)return await l(e.output,t);const{payload:o,images:n}=R(t);return{content:[{type:"text",text:JSON.stringify(o)},...n.map(e=>({type:"image",data:e.data,mimeType:e.mimeType}))]}}catch(e){if(E(e))return{isError:!0,content:[{type:"text",text:JSON.stringify(e.payload)}]};throw e}}function G(e){return e}var M={read:"read",write:"write"},q={file:"file",browserSession:"browser-session",conversation:"conversation",custom:"custom"};export{T as StructuredToolError,M as TOOL_RESOURCE_ACCESS_MODES,q as TOOL_RESOURCE_HINT_KINDS,v as createAgentLogger,k as defineAgent,G as defineTool,E as isStructuredToolError};

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+import type { AppOutputDeclaration } from "@roll-agent/protocol/app-output";
 import type { z } from "zod";
 import type { ToolAnnotations as McpToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import type { AgentContext } from "../context.ts";
@@ -29,6 +30,10 @@ export interface AnyToolDefinition {
     readonly output: z.ZodType;
     readonly annotations?: McpToolAnnotations;
     readonly resourceHints?: readonly ToolResourceHint[];
+    /** Explicit opt-in to the persistent application result channel. */
+    readonly appOutput?: Omit<AppOutputDeclaration, "remoteReadable"> & {
+        readonly remoteReadable?: boolean;
+    };
     readonly _meta?: Readonly<Record<string, unknown>>;
     readonly execute: (input: never, ctx: AgentContext) => Promise<unknown>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,8 +26,9 @@
     "node": ">=22.6.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.25.76"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.76",
+    "@roll-agent/protocol": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"