@threaded/ai 1.0.29 → 1.1.0

package/dist/types.d.ts

@@ -0,0 +1,193 @@
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_call_id?: string;
+}
+export interface ToolCall {
+    id: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolCallResult {
+    name: string;
+    inputs: any;
+    results: any;
+}
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: Record<string, any>;
+            required?: string[];
+        };
+    };
+}
+export interface ToolConfig {
+    name: string;
+    description: string;
+    schema: Record<string, SchemaProperty> | StandardSchema;
+    execute: (args: any) => Promise<any> | any;
+    _maxCalls?: number;
+}
+export interface SchemaProperty {
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description?: string;
+    enum?: string[];
+    optional?: boolean;
+    items?: SchemaProperty;
+    properties?: Record<string, SchemaProperty>;
+}
+export interface ToolExecutionConfig {
+    /** require user approval before executing tools */
+    requireApproval?: boolean;
+    /**
+     * custom callback to handle tool approval, return true to approve
+     *
+     * @example
+     * // simple callback
+     * approvalCallback: (call) => call.function.name !== 'dangerousTool'
+     *
+     * @example
+     * // event-driven (SSE): server sends approval request, waits for client POST
+     * approvalCallback: (call) => new Promise((resolve) => {
+     *   pendingApprovals.set(call.id, resolve);
+     *   res.write(`data: ${JSON.stringify({ type: 'approval_needed', call })}\n\n`);
+     * })
+     * // then: app.post('/approve/:id', (req) => pendingApprovals.get(id)(req.body.approved))
+     */
+    approvalCallback?: (call: ToolCall) => boolean | Promise<boolean>;
+    /** execute tools in parallel instead of sequentially */
+    parallel?: boolean;
+    /** number of times to retry failed tool executions */
+    retryCount?: number;
+    /** identifier for approval requests, useful for managing multiple approval flows */
+    approvalId?: string;
+    /** execute tools immediately upon approval instead of waiting for all approvals (default: false, only applies when requireApproval is true) */
+    executeOnApproval?: boolean;
+}
+export type StreamEvent = {
+    type: 'content';
+    content: string;
+} | {
+    type: 'tool_calls_ready';
+    calls: ToolCall[];
+} | {
+    type: 'tool_executing';
+    call: ToolCall;
+} | {
+    type: 'tool_complete';
+    call: ToolCall;
+    result: any;
+} | {
+    type: 'tool_error';
+    call: ToolCall;
+    error: string;
+} | {
+    type: 'approval_requested';
+    call: ToolCall;
+    requestId: string;
+} | {
+    type: 'usage';
+    usage: TokenUsage;
+};
+export interface ConversationContext {
+    history: Message[];
+    lastRequest?: Message;
+    lastResponse?: Message & {
+        tool_calls?: ToolCall[];
+    };
+    tools?: ToolDefinition[];
+    toolExecutors?: Record<string, Function>;
+    stream?: (event: StreamEvent) => void;
+    stopReason?: string;
+    toolCallCounts?: Record<string, number>;
+    toolLimits?: Record<string, number>;
+    toolConfig?: ToolExecutionConfig;
+    abortSignal?: AbortSignal;
+    usage?: TokenUsage;
+}
+export declare enum Inherit {
+    Nothing = 0,
+    Conversation = 1,
+    Tools = 2,
+    All = 3
+}
+export interface ScopeConfig {
+    inherit?: number;
+    tools?: ToolConfig[];
+    toolConfig?: ToolExecutionConfig;
+    system?: string;
+    silent?: boolean;
+    until?: (ctx: ConversationContext) => boolean;
+    stream?: (event: StreamEvent) => void;
+}
+export type StepFunction = (ctx: ConversationContext) => Promise<ConversationContext>;
+export type ComposedFunction = (ctxOrMessage: ConversationContext | string) => Promise<ConversationContext>;
+export interface JsonSchema {
+    name: string;
+    schema: Record<string, any>;
+}
+export interface StandardSchema {
+    "~standard": any;
+    [key: string]: any;
+}
+export interface ProviderConfig {
+    model: string;
+    instructions?: string;
+    schema?: JsonSchema;
+    apiKey?: string;
+    baseUrl?: string;
+}
+export interface ParsedModel {
+    provider: string;
+    model: string;
+}
+export interface ApiKeys {
+    openai?: string;
+    anthropic?: string;
+    google?: string;
+    [provider: string]: string | undefined;
+}
+export interface ThreadStore {
+    get(threadId: string): Promise<Message[]>;
+    set(threadId: string, messages: Message[]): Promise<void>;
+}
+export interface Thread {
+    id: string;
+    store: ThreadStore;
+    generate(step: StepFunction): Promise<ConversationContext>;
+    message(content: string, workflow?: StepFunction, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<ConversationContext>;
+}
+export interface RetryOptions {
+    times?: number;
+}
+export interface ImageConfig {
+    n?: number;
+    size?: string;
+    quality?: "standard" | "hd" | "low" | "medium" | "high" | "auto";
+    style?: "vivid" | "natural";
+    responseFormat?: "url" | "b64_json";
+    aspectRatio?: string;
+    outputFormat?: "png" | "jpeg" | "webp";
+    outputCompression?: number;
+    background?: "transparent" | "opaque" | "auto";
+    moderation?: "auto" | "low";
+    imageSize?: "1K" | "2K";
+}
+export interface ImageResult {
+    data: string;
+    revisedPrompt?: string;
+}
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,8 @@
+export var Inherit;
+(function (Inherit) {
+    Inherit[Inherit["Nothing"] = 0] = "Nothing";
+    Inherit[Inherit["Conversation"] = 1] = "Conversation";
+    Inherit[Inherit["Tools"] = 2] = "Tools";
+    Inherit[Inherit["All"] = 3] = "All";
+})(Inherit || (Inherit = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwGA,MAAM,CAAN,IAAY,OAKX;AALD,WAAY,OAAO;IACjB,2CAAW,CAAA;IACX,qDAAqB,CAAA;IACrB,uCAAc,CAAA;IACd,mCAA0B,CAAA;AAC5B,CAAC,EALW,OAAO,KAAP,OAAO,QAKlB"}

package/dist/utils/rateLimited.d.ts

@@ -0,0 +1,27 @@
+type RateLimitConfig = {
+    rps: number;
+    burst: number;
+    concurrency: number;
+};
+/**
+ * creates a rate limiter that wraps async functions with burst, rate, and concurrency controls
+ *
+ * @param config - rate limit configuration
+ * @param config.rps - maximum requests per second
+ * @param config.burst - maximum burst size (initial token bucket capacity)
+ * @param config.concurrency - maximum concurrent in-flight requests
+ *
+ * @example
+ * const limiter = rateLimited({ rps: 10, burst: 20, concurrency: 5 });
+ *
+ * const workflow = limiter(
+ *   compose(
+ *     scope({ tools: [searchTool] }, model())
+ *   )
+ * );
+ *
+ * await workflow("hello");
+ */
+export declare const rateLimited: (config: RateLimitConfig) => <T extends (...args: any[]) => Promise<any>>(fn: T) => T;
+export {};
+//# sourceMappingURL=rateLimited.d.ts.map

package/dist/utils/rateLimited.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimited.d.ts","sourceRoot":"","sources":["../../src/utils/rateLimited.ts"],"names":[],"mappings":"AAAA,KAAK,eAAe,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GACrB,QAAQ,eAAe,MACvB,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,KAAG,CA6DpD,CAAC"}

package/dist/utils/rateLimited.js

@@ -0,0 +1,74 @@
+/**
+ * creates a rate limiter that wraps async functions with burst, rate, and concurrency controls
+ *
+ * @param config - rate limit configuration
+ * @param config.rps - maximum requests per second
+ * @param config.burst - maximum burst size (initial token bucket capacity)
+ * @param config.concurrency - maximum concurrent in-flight requests
+ *
+ * @example
+ * const limiter = rateLimited({ rps: 10, burst: 20, concurrency: 5 });
+ *
+ * const workflow = limiter(
+ *   compose(
+ *     scope({ tools: [searchTool] }, model())
+ *   )
+ * );
+ *
+ * await workflow("hello");
+ */
+export const rateLimited = (config) => (fn) => {
+    const { rps, burst, concurrency } = config;
+    let tokens = burst;
+    let inFlight = 0;
+    const queue = [];
+    let intervalId = null;
+    const refillTokens = () => {
+        tokens = Math.min(tokens + 1, burst);
+        processQueue();
+    };
+    const startInterval = () => {
+        if (!intervalId) {
+            intervalId = setInterval(refillTokens, 1000 / rps);
+        }
+    };
+    const stopInterval = () => {
+        if (intervalId && queue.length === 0 && inFlight === 0) {
+            clearInterval(intervalId);
+            intervalId = null;
+        }
+    };
+    const processQueue = () => {
+        while (queue.length > 0 && tokens > 0 && inFlight < concurrency) {
+            tokens--;
+            inFlight++;
+            const item = queue.shift();
+            item
+                .fn()
+                .then((result) => {
+                inFlight--;
+                item.resolve(result);
+                processQueue();
+                stopInterval();
+            })
+                .catch((error) => {
+                inFlight--;
+                item.reject(error);
+                processQueue();
+                stopInterval();
+            });
+        }
+    };
+    return (async (...args) => {
+        return new Promise((resolve, reject) => {
+            queue.push({
+                fn: () => fn(...args),
+                resolve,
+                reject,
+            });
+            startInterval();
+            processQueue();
+        });
+    });
+};
+//# sourceMappingURL=rateLimited.js.map

package/dist/utils/rateLimited.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimited.js","sourceRoot":"","sources":["../../src/utils/rateLimited.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB,CAAC,MAAuB,EAAE,EAAE,CAC5B,CAA6C,EAAK,EAAK,EAAE;IACvD,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAE3C,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,IAAI,UAAU,GAA0B,IAAI,CAAC;IAE7C,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACrC,YAAY,EAAE,CAAC;IACjB,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,GAAG,EAAE;QACzB,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,UAAU,GAAG,WAAW,CAAC,YAAY,EAAE,IAAI,GAAG,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,IAAI,UAAU,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;YACvD,aAAa,CAAC,UAAU,CAAC,CAAC;YAC1B,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,QAAQ,GAAG,WAAW,EAAE,CAAC;YAChE,MAAM,EAAE,CAAC;YACT,QAAQ,EAAE,CAAC;YAEX,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YAE5B,IAAI;iBACD,EAAE,EAAE;iBACJ,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;gBACf,QAAQ,EAAE,CAAC;gBACX,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACrB,YAAY,EAAE,CAAC;gBACf,YAAY,EAAE,CAAC;YACjB,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACf,QAAQ,EAAE,CAAC;gBACX,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACnB,YAAY,EAAE,CAAC;gBACf,YAAY,EAAE,CAAC;YACjB,CAAC,CAAC,CAAC;QACP,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,CAAC,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;QAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;gBACrB,OAAO;gBACP,MAAM;aACP,CAAC,CAAC;YACH,aAAa,EAAE,CAAC;YAChB,YAAY,EAAE,CAAC;QACjB,CAAC,CAAC,CAAC;IACL,CAAC,CAAM,CAAC;AACV,CAAC,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+import { ApiKeys, ParsedModel, TokenUsage, ToolConfig, ToolDefinition } from "./types";
+export declare const toolConfigToToolDefinition: (tool: ToolConfig) => ToolDefinition;
+export declare const parseModelName: (model: string) => ParsedModel;
+export declare const setKeys: (keys: ApiKeys) => void;
+export declare const getKey: (provider: string) => string;
+export declare const maxCalls: (toolConfig: ToolConfig, maxCalls: number) => ToolConfig;
+export declare const addUsage: (existing: TokenUsage | undefined, promptTokens: number, completionTokens: number, totalTokens: number) => TokenUsage;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,WAAW,EAEX,UAAU,EACV,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,eAAO,MAAM,0BAA0B,GACrC,MAAM,UAAU,KACf,cA2BF,CAAC;AA6BF,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,WAW9C,CAAC;AAIF,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,KAAG,IAEvC,CAAC;AAEF,eAAO,MAAM,MAAM,GAAI,UAAU,MAAM,KAAG,MAMzC,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,YAAY,UAAU,EAAE,UAAU,MAAM,KAAG,UAGlE,CAAC;AAEH,eAAO,MAAM,QAAQ,GACnB,UAAU,UAAU,GAAG,SAAS,EAChC,cAAc,MAAM,EACpB,kBAAkB,MAAM,EACxB,aAAa,MAAM,KAClB,UAID,CAAC"}

package/dist/utils.js

@@ -0,0 +1,78 @@
+import { isStandardSchema, convertStandardSchemaToSchemaProperties } from "./schema";
+export const toolConfigToToolDefinition = (tool) => {
+    const schema = isStandardSchema(tool.schema)
+        ? convertStandardSchemaToSchemaProperties(tool.schema)
+        : tool.schema;
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(schema)) {
+        properties[key] = convertSchemaProperty(prop);
+        if (!prop.optional) {
+            required.push(key);
+        }
+    }
+    return {
+        type: "function",
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: {
+                type: "object",
+                properties,
+                ...(required.length > 0 && { required }),
+            },
+        },
+    };
+};
+const convertSchemaProperty = (prop) => {
+    const result = {
+        type: prop.type,
+    };
+    if (prop.description) {
+        result.description = prop.description;
+    }
+    if (prop.enum) {
+        result.enum = prop.enum;
+    }
+    if (prop.items) {
+        result.items = convertSchemaProperty(prop.items);
+    }
+    if (prop.properties) {
+        result.properties = {};
+        for (const [key, childProp] of Object.entries(prop.properties)) {
+            result.properties[key] = convertSchemaProperty(childProp);
+        }
+    }
+    return result;
+};
+export const parseModelName = (model) => {
+    const parts = model.split("/");
+    if (parts.length === 1) {
+        return { provider: "huggingface", model: parts[0] };
+    }
+    return {
+        provider: parts[0],
+        model: parts.slice(1).join("/"),
+    };
+};
+let globalKeys = {};
+export const setKeys = (keys) => {
+    globalKeys = { ...globalKeys, ...keys };
+};
+export const getKey = (provider) => {
+    const key = globalKeys[provider.toLowerCase()];
+    if (!key) {
+        throw new Error(`No API key configured for provider: ${provider}`);
+    }
+    return key;
+};
+export const maxCalls = (toolConfig, maxCalls) => ({
+    ...toolConfig,
+    _maxCalls: maxCalls,
+});
+export const addUsage = (existing, promptTokens, completionTokens, totalTokens) => ({
+    promptTokens: (existing?.promptTokens || 0) + promptTokens,
+    completionTokens: (existing?.completionTokens || 0) + completionTokens,
+    totalTokens: (existing?.totalTokens || 0) + totalTokens,
+});
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

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

package/package.json

@@ -1,27 +1,49 @@
 {
   "name": "@threaded/ai",
-  "version": "1.0.29",
-  "main": "dist/index.js",
+  "version": "1.1.0",
+  "description": "Composable LLM inference with multi-provider support, tool execution, streaming, and approval workflows",
   "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "build": "tsup",
-    "test": "vitest",
-    "test:ui": "vitest --ui"
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest --reporter=verbose --run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
   },
-  "keywords": [],
-  "author": "",
+  "author": "nvms",
   "license": "ISC",
-  "description": "",
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
-    "@huggingface/transformers": "^3.7.5",
     "zod": "^4.1.11"
   },
+  "peerDependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@huggingface/transformers": "^3.7.5",
     "@modelcontextprotocol/sdk": "^1.18.2",
     "@types/node": "^24.5.2",
-    "@vitest/ui": "^3.2.4",
-    "tsup": "^8.5.0",
-    "tsx": "^4.20.6",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   }

package/.claude/settings.local.json

@@ -1,15 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebSearch",
-      "WebFetch(domain:platform.openai.com)",
-      "WebFetch(domain:docs.anthropic.com)",
-      "WebFetch(domain:ai.google.dev)",
-      "WebFetch(domain:docs.x.ai)",
-      "WebFetch(domain:docs.cloud.google.com)",
-      "WebFetch(domain:latenode.com)",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:docs.aimlapi.com)"
-    ]
-  }
-}

package/.lore

@@ -1,65 +0,0 @@
--- core pattern --
-
-everything is built on compose/scope/model. compose chains steps, scope isolates context, model calls an LLM.
-
-```js
-const workflow = compose(
-  scope({ system: "...", tools: [...] }, model({ model: "openai/gpt-4o" }))
-)
-const ctx = await workflow("user message")
-```
-
--- key setup --
-
-must call setKeys() before any model() call, or set env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, XAI_API_KEY)
-
-```js
-import { setKeys } from "@threaded/ai"
-setKeys({ openai: process.env.OPENAI_API_KEY })
-```
-
--- model naming --
-
-always "provider/model-name": openai/gpt-4o, anthropic/claude-sonnet-4-5-20250929, google/gemini-2.5-flash, xai/grok-4-1-fast-non-reasoning. no prefix defaults to huggingface.
-
--- structured output --
-
-pass schema (zod or json schema) to model(). response comes back as JSON in lastResponse.content. claude wraps it in markdown code fences - strip them before JSON.parse.
-
-```js
-function extractResult(ctx) {
-  const last = ctx.history?.findLast(m => m.role === 'assistant')
-  if (!last?.content) return null
-  let text = typeof last.content === 'string' ? last.content : last.content[0]?.text || ''
-  const fenced = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/)
-  if (fenced) text = fenced[1]
-  return JSON.parse(text.trim())
-}
-```
-
--- pitfalls --
-
-do NOT use Inherit.Nothing - it drops the user prompt entirely. use Inherit.Conversation (default) instead.
-
-until: noToolsCalled() loops can cause runaway API calls (5-6+ per invocation). use maxCalls() on tools to limit.
-
-silent scopes run analysis without polluting chat history but still accumulate token usage on ctx.usage.
-
-events are local only in the scope where stream callback is set. nested silent scopes with their own stream get their own events.
-
--- rate limiting --
-
-anthropic tier 1 has very low limits (30K input tokens/min). when using anthropic, add delays between calls and use maxCalls() aggressively. 90s backoff on rate limit errors.
-
--- token usage --
-
-ctx.usage accumulates across all model() calls, tool loops, and nested scopes. always available after workflow completes:
-{ promptTokens, completionTokens, totalTokens }
-
--- integration patterns --
-
-SSE streaming: pass stream callback in scope config, write events to res as `data: ${JSON.stringify(event)}\n\n`
-
-tool approval: use toolConfig.requireApproval + approvalCallback for gating dangerous tool execution in web UIs
-
-MCP tools: createMCPTools(client) converts MCP server tools to native format. tools are prefixed with server name.