@kuralle-agents/core 0.4.1 → 0.6.0

package/dist/testing/mocks.js

@@ -1,7 +1,14 @@
+import { createUIMessageStreamResponse } from 'ai';
+import { harnessToUIMessageStream } from '../ai-sdk/uiMessageStream.js';
 export function createMockTurnHandle(events, settled = { text: '', toolResults: [] }) {
     return Object.assign(Promise.resolve(settled), {
         events,
         toResponseStream: () => new ReadableStream(),
+        toUIMessageStreamResponse(opts) {
+            return createUIMessageStreamResponse({
+                stream: harnessToUIMessageStream(events, opts),
+            });
+        },
         cancel: () => { },
     });
 }

package/dist/tools/effect/defineTool.js

@@ -25,7 +25,7 @@ export function toolToAiSdk(def) {
 // `buildToolSet` produces a model-facing ToolSet whose entries are schema-only
 // (`toolToAiSdk` strips `execute`). Stash the raw effect tools (with executors),
 // keyed by the returned ToolSet, so a flow node can recover its executors for
-// in-flow execution without separately registering them on `agent.effectTools`
+// in-flow execution without separately registering them on `agent.tools`.
 // (see `resolveReplyNode`). The WeakMap is GC-friendly and invisible to callers.
 const rawToolsBySet = new WeakMap();
 export function buildToolSet(tools) {

package/dist/tools/effect/index.d.ts

@@ -1,4 +1,5 @@
 export { defineTool, toolToAiSdk, buildToolSet } from './defineTool.js';
+export { wrapAiSdkTool } from './wrapAiSdkTool.js';
 export { CoreToolExecutor } from './ToolExecutor.js';
 export type { CoreToolExecutorConfig, CoreExecuteArgs } from './ToolExecutor.js';
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';

package/dist/tools/effect/index.js

@@ -1,4 +1,5 @@
 export { defineTool, toolToAiSdk, buildToolSet } from './defineTool.js';
+export { wrapAiSdkTool } from './wrapAiSdkTool.js';
 export { CoreToolExecutor } from './ToolExecutor.js';
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';
 export { validateAndSanitize, validateOutput, ToolValidationError } from './schema.js';

package/dist/tools/effect/wrapAiSdkTool.d.ts

@@ -0,0 +1,3 @@
+import type { Tool as AiTool } from 'ai';
+import type { AnyTool } from '../../types/effectTool.js';
+export declare function wrapAiSdkTool(name: string, aiTool: AiTool): AnyTool;

package/dist/tools/effect/wrapAiSdkTool.js

@@ -0,0 +1,12 @@
+export function wrapAiSdkTool(name, aiTool) {
+    const exec = aiTool.execute;
+    if (typeof exec !== 'function') {
+        throw new Error(`wrapAiSdkTool("${name}"): AI SDK tool has no execute; use defineTool for schema-only tools.`);
+    }
+    return {
+        name,
+        description: aiTool.description ?? name,
+        input: aiTool.inputSchema,
+        execute: (args, ctx) => exec(args, ctx),
+    };
+}

package/dist/tools/fs/createFsTool.d.ts

@@ -0,0 +1,30 @@
+import type { AnyTool } from '../../types/effectTool.js';
+import { type FileSystem } from '../../types/filesystem.js';
+export interface CreateFsToolOptions {
+    fs: FileSystem;
+    readOnly?: boolean;
+    timeoutMs?: number;
+}
+export interface GrepHit {
+    path: string;
+    line: number;
+    text: string;
+}
+export interface FsSearchHit {
+    slug: string;
+    chunkIndex: number;
+    text: string;
+}
+export interface FsWithSearch extends FileSystem {
+    search?(pattern: string, opts?: {
+        limit?: number;
+        path?: string;
+    }): Promise<FsSearchHit[]>;
+}
+/**
+ * One durable `workspace` tool over a {@link FileSystem} (ls/cat/grep/find/read/write/edit).
+ * Lives in core (not `@kuralle-agents/fs`) because it needs only `defineTool` + the
+ * `FileSystem` interface — both core-owned — so the runtime can auto-register it with a
+ * static import and no core->fs dependency (RFC-02 §5.2). `@kuralle-agents/fs` re-exports it.
+ */
+export declare function createFsTool(opts: CreateFsToolOptions): AnyTool;

package/dist/tools/fs/createFsTool.js

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+import { defineTool } from '../effect/defineTool.js';
+import { fsErrorCode } from '../../types/filesystem.js';
+const DEFAULT_READ_ONLY = true;
+const workspaceInput = z.object({
+    op: z.enum(['ls', 'cat', 'grep', 'find', 'read', 'write', 'edit']),
+    path: z.string().optional(),
+    pattern: z.string().optional(),
+    root: z.string().optional(),
+    glob: z.string().optional(),
+    flags: z.string().optional(),
+    content: z.string().optional(),
+    find: z.string().optional(),
+    replace: z.string().optional(),
+});
+function normalizeFsPath(path, fallback = '/') {
+    if (!path || path.trim() === '')
+        return fallback;
+    return path;
+}
+function requireField(args, field, op) {
+    const value = args[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`EINVAL: missing ${String(field)} for workspace op '${op}'`);
+    }
+    return value;
+}
+function eroFs(path) {
+    return new Error(`EROFS: read-only filesystem, write '${path}'`);
+}
+function assertWritable(readOnly, path) {
+    if (readOnly)
+        throw eroFs(path);
+}
+async function listFiles(fs, root) {
+    const normalized = root === '' ? '/' : root;
+    const out = [];
+    const stack = [normalized];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (!(await fs.exists(dir))) {
+            throw new Error(`ENOENT: no such file or directory, find '${dir}'`);
+        }
+        const stat = await fs.stat(dir);
+        if (stat.type !== 'directory') {
+            out.push(dir);
+            continue;
+        }
+        const entries = await fs.readdirWithFileTypes(dir);
+        for (const entry of entries) {
+            const child = fs.resolvePath(dir, entry.name);
+            if (entry.type === 'directory') {
+                stack.push(child);
+            }
+            else {
+                out.push(child);
+            }
+        }
+    }
+    return out.sort();
+}
+async function grepFiles(fs, pattern, root, flags) {
+    let re;
+    try {
+        re = new RegExp(pattern, flags?.includes('i') ? 'i' : undefined);
+    }
+    catch {
+        throw new Error(`EINVAL: invalid grep pattern '${pattern}'`);
+    }
+    const searchable = fs;
+    if (searchable.search) {
+        const coarse = await searchable.search(pattern, { limit: 500, path: root });
+        const slugs = [...new Set(coarse.map((hit) => hit.slug))];
+        const hits = [];
+        for (const filePath of slugs) {
+            let content;
+            try {
+                content = await fs.readFile(filePath);
+            }
+            catch (err) {
+                if (fsErrorCode(err) === 'EISDIR')
+                    continue;
+                throw err;
+            }
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                if (re.test(lines[i])) {
+                    hits.push({ path: filePath, line: i + 1, text: lines[i] });
+                }
+            }
+        }
+        return hits;
+    }
+    const candidates = await listFiles(fs, root);
+    const hits = [];
+    for (const filePath of candidates) {
+        let content;
+        try {
+            content = await fs.readFile(filePath);
+        }
+        catch (err) {
+            if (fsErrorCode(err) === 'EISDIR')
+                continue;
+            throw err;
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (re.test(lines[i])) {
+                hits.push({ path: filePath, line: i + 1, text: lines[i] });
+            }
+        }
+    }
+    return hits;
+}
+/**
+ * One durable `workspace` tool over a {@link FileSystem} (ls/cat/grep/find/read/write/edit).
+ * Lives in core (not `@kuralle-agents/fs`) because it needs only `defineTool` + the
+ * `FileSystem` interface — both core-owned — so the runtime can auto-register it with a
+ * static import and no core->fs dependency (RFC-02 §5.2). `@kuralle-agents/fs` re-exports it.
+ */
+export function createFsTool(opts) {
+    const { fs, readOnly = DEFAULT_READ_ONLY, timeoutMs } = opts;
+    return defineTool({
+        name: 'workspace',
+        description: 'Explore and edit the agent workspace. Ops: ls, cat, grep, find, read, write, edit.',
+        timeoutMs,
+        input: workspaceInput,
+        execute: async (args) => {
+            switch (args.op) {
+                case 'ls': {
+                    const path = normalizeFsPath(args.path);
+                    const entries = await fs.readdirWithFileTypes(path);
+                    return {
+                        op: args.op,
+                        ok: true,
+                        path,
+                        entries,
+                    };
+                }
+                case 'cat':
+                case 'read': {
+                    const path = requireField(args, 'path', args.op);
+                    const content = await fs.readFile(path);
+                    return { op: args.op, ok: true, path, content };
+                }
+                case 'find': {
+                    const root = normalizeFsPath(args.root);
+                    const glob = requireField(args, 'glob', args.op);
+                    const paths = await fs.glob(glob);
+                    const rooted = paths.filter((p) => {
+                        const normalizedRoot = root === '/' ? '/' : root.replace(/\/$/, '');
+                        return p === normalizedRoot || p.startsWith(`${normalizedRoot}/`);
+                    });
+                    return {
+                        op: args.op,
+                        ok: true,
+                        root,
+                        glob,
+                        paths: rooted,
+                    };
+                }
+                case 'grep': {
+                    const pattern = requireField(args, 'pattern', args.op);
+                    const path = normalizeFsPath(args.path);
+                    const hits = await grepFiles(fs, pattern, path, args.flags);
+                    return {
+                        op: args.op,
+                        ok: true,
+                        pattern,
+                        path,
+                        hits,
+                    };
+                }
+                case 'write': {
+                    const path = requireField(args, 'path', args.op);
+                    const content = requireField(args, 'content', args.op);
+                    assertWritable(readOnly, path);
+                    await fs.writeFile(path, content);
+                    return { op: args.op, ok: true, path };
+                }
+                case 'edit': {
+                    const path = requireField(args, 'path', args.op);
+                    const find = requireField(args, 'find', args.op);
+                    const replace = requireField(args, 'replace', args.op);
+                    assertWritable(readOnly, path);
+                    const current = await fs.readFile(path);
+                    if (!current.includes(find)) {
+                        throw new Error(`ENOENT: find string not found in file, edit '${path}'`);
+                    }
+                    const next = current.replace(find, replace);
+                    await fs.writeFile(path, next);
+                    return { op: args.op, ok: true, path };
+                }
+                default: {
+                    throw new Error(`EINVAL: unknown workspace op '${String(args.op)}'`);
+                }
+            }
+        },
+    });
+}

package/dist/types/agentConfig.d.ts

@@ -1,4 +1,4 @@
-import type { LanguageModel, ToolSet } from 'ai';
+import type { LanguageModel } from 'ai';
 import type { AgentPrompt } from '../prompts/AgentPrompt.js';
 import type { Flow } from './flow.js';
 import type { Route, RoutingPolicy } from './route.js';
@@ -7,6 +7,12 @@ import type { AgentKnowledge, AgentMemory } from './grounding.js';
 import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { AnyTool } from './effectTool.js';
+import type { FileSystem } from './filesystem.js';
+import type { SkillSource } from './skills.js';
+export type AgentWorkspaceConfig = FileSystem | {
+    fs: FileSystem;
+    readOnly?: boolean;
+};
 export type Instructions = string | AgentPrompt | ((ctx: {
     state: Record<string, unknown>;
 }) => Instructions | Promise<Instructions>);
@@ -20,8 +26,8 @@ export interface AgentConfig {
      *  temperature 0 for determinism. Defaults to `model` (the speaker) when unset.
      *  Set this to pin control to a reliable provider independent of the speaker. */
     controlModel?: LanguageModel;
-    tools?: ToolSet;
-    effectTools?: Record<string, AnyTool>;
+    /** Durable, model-callable effect tools (exactly-once on replay). Wrap raw AI SDK tools with wrapAiSdkTool(). */
+    tools?: Record<string, AnyTool>;
     /** Safe, always-available tools made model-visible in EVERY speaking node turn
      *  (the agent "base layer", ADR 0001) — e.g. a returns/FAQ knowledge-base
      *  lookup the user might ask for mid-flow. This is an explicit allow-list:
@@ -45,5 +51,12 @@ export interface AgentConfig {
         /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1). Default OFF. */
         outOfBandControl?: boolean;
     };
+    /** Portable workspace filesystem; auto-registers the durable `workspace` tool when set.
+     *  Defaults to read-only; pass `{ fs, readOnly: false }` for write/edit. Read-only workspaces
+     *  are exposed in globalTools (ADR 0001); read-write ones are executor-only. */
+    workspace?: AgentWorkspaceConfig;
+    /** Bundled procedural skills (Anthropic Agent Skill model): Level-1 name+description in prompt,
+     *  body via `load_skill`, resources via `read_skill_resource`. Scripts = `allowedTools` only. */
+    skills?: SkillSource;
 }
 export declare function defineAgent(config: AgentConfig): AgentConfig;

package/dist/types/filesystem.d.ts

@@ -0,0 +1,85 @@
+export type FileSystemEntryType = 'file' | 'directory' | 'symlink';
+export type BufferEncoding = 'utf8' | 'utf-8' | 'ascii' | 'binary' | 'base64' | 'hex' | 'latin1';
+export type FileContent = string | Uint8Array;
+export interface FsStat {
+    type: FileSystemEntryType;
+    size: number;
+    mtime: Date;
+    mode?: number;
+}
+export interface FileSystemDirent {
+    name: string;
+    type: FileSystemEntryType;
+}
+export interface MkdirOptions {
+    recursive?: boolean;
+}
+export interface RmOptions {
+    recursive?: boolean;
+    force?: boolean;
+}
+export interface CpOptions {
+    recursive?: boolean;
+}
+export interface FileSystem {
+    readFile(path: string): Promise<string>;
+    readFileBytes(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    writeFileBytes(path: string, content: Uint8Array): Promise<void>;
+    appendFile(path: string, content: string | Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<FileSystemDirent[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    resolvePath(base: string, path: string): string;
+    glob(pattern: string): Promise<string[]>;
+}
+export interface ReadFileOptions {
+    encoding?: BufferEncoding | null;
+}
+export interface WriteFileOptions {
+    encoding?: BufferEncoding;
+}
+export interface FileEntry {
+    type: 'file';
+    content: string | Uint8Array;
+    mode: number;
+    mtime: Date;
+}
+export interface DirectoryEntry {
+    type: 'directory';
+    mode: number;
+    mtime: Date;
+}
+export interface SymlinkEntry {
+    type: 'symlink';
+    target: string;
+    mode: number;
+    mtime: Date;
+}
+export interface LazyFileEntry {
+    type: 'file';
+    lazy: () => string | Uint8Array | Promise<string | Uint8Array>;
+    mode: number;
+    mtime: Date;
+}
+export type FsEntry = FileEntry | LazyFileEntry | DirectoryEntry | SymlinkEntry;
+export interface FileInit {
+    content: FileContent;
+    mode?: number;
+    mtime?: Date;
+}
+export type LazyFileProvider = () => string | Uint8Array | Promise<string | Uint8Array>;
+export type InitialFiles = Record<string, FileContent | FileInit | LazyFileProvider>;
+export interface FsError extends Error {
+    code?: string;
+}
+export declare function fsErrorCode(err: unknown): string | undefined;

package/dist/types/filesystem.js

@@ -0,0 +1,6 @@
+export function fsErrorCode(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const match = err.message.match(/^([A-Z]+):/);
+    return match?.[1];
+}

package/dist/types/grounding.d.ts

@@ -1,7 +1,17 @@
+import type { MemoryBlockScope, PersistentMemoryConfig } from '../memory/blocks/types.js';
 export interface AgentKnowledge {
     autoRetrieve?: boolean;
     sources?: string[];
 }
+export interface WorkingMemoryBlockSpec {
+    scope: MemoryBlockScope;
+    key: string;
+    /** Seed content when the block is missing or empty (persisted on first write, not on read). */
+    template?: string;
+}
+export interface WorkingMemoryConfig extends Omit<PersistentMemoryConfig, 'autoLoad'> {
+    autoLoad?: WorkingMemoryBlockSpec[];
+}
 export interface AgentMemory {
     preload?: {
         enabled?: boolean;
@@ -10,4 +20,6 @@ export interface AgentMemory {
     ingest?: {
         enabled?: boolean;
     };
+    /** Persistent markdown blocks (USER/MEMORY) loaded at session start and editable via memory_block. */
+    workingMemory?: WorkingMemoryConfig;
 }

package/dist/types/index.d.ts

@@ -2,6 +2,8 @@ export * from './selection.js';
 export * from './telemetry.js';
 export * from './processors.js';
 export * from './agentConfig.js';
+export * from './filesystem.js';
+export * from './skills.js';
 export * from './flow.js';
 export * from './session.js';
 export * from './tool.js';

package/dist/types/index.js

@@ -2,6 +2,8 @@ export * from './selection.js';
 export * from './telemetry.js';
 export * from './processors.js';
 export * from './agentConfig.js';
+export * from './filesystem.js';
+export * from './skills.js';
 export * from './flow.js';
 export * from './session.js';
 export * from './tool.js';

package/dist/types/run-context.d.ts

@@ -8,6 +8,7 @@ import type { RefinementCapability } from '../capabilities/RefinementCapability.
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
+import type { FileSystem } from './filesystem.js';
 import type { Instructions } from './agentConfig.js';
 import type { AgentKnowledgeOverrides, SourceRef } from './voice.js';
 export interface GatherScope {
@@ -85,6 +86,14 @@ export interface RunContext {
      *  in every speaking turn. */
     baseInstructions?: Instructions;
     globalTools?: Record<string, AnyTool>;
+    /** Level-1 skill metadata injected by `SkillsCapability` when `AgentConfig.skills` is set. */
+    skillPrompt?: string;
+    /** Frozen persistent memory blocks loaded at session start (`AgentMemory.workingMemory`). */
+    workingMemoryPrompt?: string;
+    /** Model-visible tools from working memory wiring (not in globalTools — mutating but scoped). */
+    workingMemoryTools?: Record<string, AnyTool>;
+    /** Agent workspace filesystem (same instance as `AgentConfig.workspace`). */
+    fs?: FileSystem;
     tool(name: string, args: unknown, options?: {
         toolCallId?: string;
         def?: AnyTool;
@@ -104,6 +113,6 @@ export interface RunContext {
     now(): Promise<number>;
     uuid(): Promise<string>;
 }
-export type ActionContext = Pick<RunContext, 'tool' | 'approve' | 'signal' | 'now' | 'uuid' | 'emit'>;
-export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit'>;
+export type ActionContext = Pick<RunContext, 'tool' | 'approve' | 'signal' | 'now' | 'uuid' | 'emit' | 'fs'>;
+export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit' | 'fs'>;
 export type { ModelMessage };

package/dist/types/skills.d.ts

@@ -0,0 +1,19 @@
+export interface SkillMeta {
+    name: string;
+    description: string;
+}
+export interface SkillLike {
+    name: string;
+    description: string;
+    body: string;
+    resources?: Record<string, string | Uint8Array>;
+    allowedTools?: string[];
+}
+export interface SkillStoreLike {
+    list(): Promise<SkillMeta[]>;
+    loadBody(name: string): Promise<string>;
+    loadResource(name: string, path: string): Promise<string | Uint8Array>;
+    getAllSkills?(): SkillLike[] | Promise<SkillLike[]>;
+    loadAllSkills?(): Promise<SkillLike[]>;
+}
+export type SkillSource = SkillLike | SkillLike[] | SkillStoreLike;

package/dist/types/skills.js

@@ -0,0 +1 @@
+export {};

package/dist/types/stream.d.ts

@@ -91,5 +91,8 @@ export type HarnessStreamPart = {
 export interface TurnHandle extends Promise<import('./channel.js').TurnResult> {
     readonly events: AsyncIterable<HarnessStreamPart>;
     toResponseStream(format?: 'sse' | 'ndjson'): ReadableStream;
+    toUIMessageStreamResponse(opts?: {
+        sessionId?: string;
+    }): Response;
     cancel(reason?: string): void;
 }

package/guides/AGENTS.md

@@ -16,7 +16,7 @@ const model = openai('gpt-4o-mini');
 | Fields | Effect |
 |--------|--------|
 | `id`, `model`, `instructions` | Base conversational agent |
-| `tools`, `effectTools` | Tool access during free conversation and flow nodes |
+| `tools`, `globalTools` | Durable tool access during free conversation and flow nodes |
 | `flows` | Structured multi-step SOPs (`defineFlow` + node builders) |
 | `routes`, `routing` | Route to flows or specialist agents |
 | `agents` | Nested sub-agent configs for composition |
@@ -210,8 +210,7 @@ const lead = defineAgent({
   instructions:
     'Research assistant. Use consult_weather for weather and consult_news for news. Combine answers clearly.',
   model,
-  tools: buildToolSet(tools),
-  effectTools: tools,
+  tools: tools,
 });
 
 const runtime = createRuntime({

package/guides/FLOWS.md

@@ -29,7 +29,7 @@ const collectDate = defineTool({
 const greeting = reply({
   id: 'greeting',
   instructions: 'Welcome. What date would you like to book?',
-  tools: { collect_date: collectDate }, // wire via effectTools + ToolSet in production
+  tools: { collect_date: collectDate }, // wire via tools + ToolSet in production
   next: (turn) => {
     const r = turn.toolResults.find((t) => t.name === 'collect_date');
     return r?.result ? { goto: confirm, data: r.result as Record<string, unknown> } : 'stay';
@@ -46,7 +46,7 @@ const agent = defineAgent({
   id: 'booking',
   instructions: 'You are a booking assistant.',
   model,
-  effectTools: { collect_date: collectDate },
+  tools: { collect_date: collectDate },
   flows: [
     defineFlow({
       name: 'booking',

package/guides/RUNTIME.md

@@ -11,7 +11,24 @@
 
 ## Stream Events
 
-`runtime.run()` returns a `TurnHandle` with an `.events` async iterable of `HarnessStreamPart` items. Typical UI usage only renders `text-delta`.
+`runtime.run()` returns a `TurnHandle` with an `.events` async iterable of `HarnessStreamPart` items.
+
+### Web UI (AI SDK native, 0.5.0+)
+
+For React/web consumers, return a native `UIMessageStream` — `useChat` works with no bridge:
+
+```ts
+const handle = runtime.run({ input, sessionId });
+return handle.toUIMessageStreamResponse({ sessionId });
+```
+
+Kuralle orchestration events map to typed `data-kuralle-*` parts (see `docs/adr/0005-ai-sdk-native-uimessage-default.md`). Import `KuralleUIMessage` for compile-time-safe `message.parts`.
+
+With `@kuralle-agents/hono-server`, `POST /api/chat/sse` defaults to this native wire. Append `?format=raw` for legacy `HarnessStreamPart` JSON-SSE.
+
+### Direct `HarnessStreamPart` consumption
+
+For CLI scripts, cascaded voice, messaging, or custom transports, iterate `handle.events` directly. Typical usage renders `text-delta` chunks via `part.delta`.
 
 Common types:
 - `text-delta`