@falai/agent 1.2.8 → 2.0.1

package/examples/tools/enhanced-tool-metadata.ts

@@ -1,268 +0,0 @@
-/**
- * Enhanced Tool Metadata Example
- *
- * Demonstrates the EnhancedTool interface with rich metadata for concurrency
- * control, input validation, permission gating, and result size budgeting.
- *
- * Key concepts:
- * - `isConcurrencySafe` — classify tools for parallel vs serial execution
- * - `validateInput` — reject bad inputs before the handler runs
- * - `checkPermissions` — gate execution behind authorization checks
- * - `maxResultSizeChars` — cap result size to prevent context overflow
- * - `interruptBehavior` — control abort signal handling ('cancel' vs 'block')
- * - Backward compatibility: plain `Tool` objects work without any metadata
- */
-
-import {
-    Agent,
-    GeminiProvider,
-    type EnhancedTool,
-    type Tool,
-    type ToolContext,
-} from "../../src/index";
-
-// --- Context type for permission checks ---
-
-interface AppContext {
-    userRole: "admin" | "editor" | "viewer";
-    userId: string;
-}
-
-// --- 1. Read-only tool with concurrency metadata ---
-
-const fetchUserTool: EnhancedTool<AppContext> = {
-    id: "fetch_user",
-    name: "Fetch User",
-    description: "Fetch user profile by ID",
-    parameters: {
-        type: "object",
-        properties: { userId: { type: "string" } },
-        required: ["userId"],
-    },
-    handler: async (_ctx, args) => {
-        const userId = args?.userId as string;
-        return { data: `User ${userId}: Alice (admin)`, success: true };
-    },
-
-    // Concurrency metadata — safe to run alongside other reads
-    isConcurrencySafe: () => true,
-    isReadOnly: () => true,
-    isDestructive: () => false,
-    interruptBehavior: () => "cancel",
-
-    // Cap result size to 10k chars
-    maxResultSizeChars: 10_000,
-};
-
-// --- 2. Write tool with validation and permissions ---
-
-const deleteResourceTool: EnhancedTool<AppContext> = {
-    id: "delete_resource",
-    name: "Delete Resource",
-    description: "Permanently delete a resource",
-    parameters: {
-        type: "object",
-        properties: { resourceId: { type: "string" } },
-        required: ["resourceId"],
-    },
-    handler: async (_ctx, args) => {
-        const id = args?.resourceId as string;
-        return { data: `Resource ${id} deleted`, success: true };
-    },
-
-    // Not concurrency-safe — must run exclusively
-    isConcurrencySafe: () => false,
-    isReadOnly: () => false,
-    isDestructive: () => true,
-    interruptBehavior: () => "block", // don't abort mid-delete
-
-    maxResultSizeChars: 500,
-
-    // Input validation — runs before handler
-    validateInput: (input) => {
-        const id = input.resourceId;
-        if (!id || typeof id !== "string" || id.trim().length === 0) {
-            return { valid: false, error: "resourceId must be a non-empty string" };
-        }
-        // Suggest correction for common prefix mistake
-        if (typeof id === "string" && !id.startsWith("res_")) {
-            return {
-                valid: false,
-                error: "resourceId must start with 'res_'",
-                correctedInput: { resourceId: `res_${id}` },
-            };
-        }
-        return { valid: true };
-    },
-
-    // Permission check — runs before handler
-    checkPermissions: (_input, ctx) => {
-        if (ctx.context.userRole !== "admin") {
-            return {
-                allowed: false,
-                reason: "Only admins can delete resources",
-                canOverride: false,
-            };
-        }
-        return { allowed: true };
-    },
-};
-
-// --- 3. Tool with input-dependent concurrency ---
-
-const queryDatabaseTool: EnhancedTool<AppContext> = {
-    id: "query_database",
-    name: "Query Database",
-    description: "Run a database query (SELECT is concurrent-safe, mutations are not)",
-    parameters: {
-        type: "object",
-        properties: {
-            sql: { type: "string" },
-            readonly: { type: "boolean" },
-        },
-        required: ["sql"],
-    },
-    handler: async (_ctx, args) => {
-        const sql = args?.sql as string;
-        return { data: `Query result for: ${sql}`, success: true };
-    },
-
-    // Concurrency depends on the query type
-    isConcurrencySafe: (input) => input?.readonly === true,
-    isReadOnly: (input) => input?.readonly === true,
-    isDestructive: (input) => {
-        const sql = (input?.sql as string)?.toUpperCase() ?? "";
-        return sql.includes("DROP") || sql.includes("DELETE") || sql.includes("TRUNCATE");
-    },
-    interruptBehavior: () => "block",
-
-    // Validate SQL isn't empty
-    validateInput: (input) => {
-        if (!input.sql || typeof input.sql !== "string") {
-            return { valid: false, error: "sql must be a non-empty string" };
-        }
-        return { valid: true };
-    },
-
-    // Large query results get truncated
-    maxResultSizeChars: 50_000,
-};
-
-// --- 4. Plain Tool (backward compatible, no metadata) ---
-
-const echoTool: Tool<AppContext> = {
-    id: "echo",
-    name: "Echo",
-    description: "Echo back the input (plain Tool, no EnhancedTool metadata)",
-    parameters: {
-        type: "object",
-        properties: { message: { type: "string" } },
-        required: ["message"],
-    },
-    handler: async (_ctx, args) => {
-        return { data: args?.message as string, success: true };
-    },
-    // No isConcurrencySafe, validateInput, checkPermissions, etc.
-    // Defaults: isConcurrencySafe → false, interruptBehavior → 'block'
-};
-
-// --- Demo functions ---
-
-function demonstrateMetadata() {
-    console.log("=== EnhancedTool Metadata ===\n");
-
-    const tools = [fetchUserTool, deleteResourceTool, queryDatabaseTool, echoTool];
-
-    for (const tool of tools) {
-        const enhanced = tool as EnhancedTool;
-        console.log(`${tool.id}:`);
-        console.log(`  concurrencySafe:  ${enhanced.isConcurrencySafe?.() ?? "default (false)"}`);
-        console.log(`  readOnly:         ${enhanced.isReadOnly?.() ?? "default (false)"}`);
-        console.log(`  destructive:      ${enhanced.isDestructive?.() ?? "default (false)"}`);
-        console.log(`  interruptBehavior: ${enhanced.interruptBehavior?.() ?? "default (block)"}`);
-        console.log(`  maxResultSizeChars: ${enhanced.maxResultSizeChars ?? "none"}`);
-        console.log(`  hasValidateInput: ${!!enhanced.validateInput}`);
-        console.log(`  hasCheckPermissions: ${!!enhanced.checkPermissions}`);
-        console.log();
-    }
-}
-
-function demonstrateInputDependentConcurrency() {
-    console.log("=== Input-Dependent Concurrency ===\n");
-
-    const selectInput = { sql: "SELECT * FROM users", readonly: true };
-    const insertInput = { sql: "INSERT INTO users VALUES (...)", readonly: false };
-    const dropInput = { sql: "DROP TABLE users", readonly: false };
-
-    console.log(`SELECT query: concurrencySafe=${queryDatabaseTool.isConcurrencySafe!(selectInput)}`);
-    console.log(`INSERT query: concurrencySafe=${queryDatabaseTool.isConcurrencySafe!(insertInput)}`);
-    console.log(`DROP query:   destructive=${queryDatabaseTool.isDestructive!(dropInput)}`);
-    console.log();
-}
-
-async function demonstrateValidation() {
-    console.log("=== Input Validation ===\n");
-
-    const cases = [
-        { label: "valid ID", input: { resourceId: "res_123" } },
-        { label: "missing prefix", input: { resourceId: "123" } },
-        { label: "empty string", input: { resourceId: "" } },
-    ];
-
-    for (const { label, input } of cases) {
-        const result = deleteResourceTool.validateInput!(input, {} as any);
-        const resolved = result instanceof Promise ? await result : result;
-        console.log(`  ${label}: valid=${resolved.valid}${resolved.error ? `, error="${resolved.error}"` : ""}${resolved.correctedInput ? `, corrected=${JSON.stringify(resolved.correctedInput)}` : ""}`);
-    }
-    console.log();
-}
-
-async function demonstratePermissions() {
-    console.log("=== Permission Gating ===\n");
-
-    const roles: Array<"admin" | "editor" | "viewer"> = ["admin", "editor", "viewer"];
-
-    for (const role of roles) {
-        const mockCtx = { context: { userRole: role, userId: "u1" } } as ToolContext<AppContext>;
-        const result = deleteResourceTool.checkPermissions!({ resourceId: "res_1" }, mockCtx);
-        const resolved = result instanceof Promise ? await result : result;
-        console.log(`  role=${role}: allowed=${resolved.allowed}${resolved.reason ? `, reason="${resolved.reason}"` : ""}`);
-    }
-    console.log();
-}
-
-function demonstrateAgentRegistration() {
-    console.log("=== Agent Registration ===\n");
-
-    const agent = new Agent<AppContext>({
-        name: "MetadataDemo",
-        description: "Demonstrates EnhancedTool metadata",
-        provider: new GeminiProvider({
-            apiKey: process.env.GEMINI_API_KEY || "demo-key",
-            model: "models/gemini-2.5-flash",
-        }),
-        context: { userRole: "admin", userId: "u1" },
-        // Mix of EnhancedTool and plain Tool — both accepted seamlessly
-        tools: [fetchUserTool, deleteResourceTool, queryDatabaseTool, echoTool],
-    });
-
-    console.log("Registered tools:");
-    for (const t of agent.getTools()) {
-        console.log(`  - ${t.id}`);
-    }
-    console.log("\nPlain Tool objects work alongside EnhancedTool without changes.");
-}
-
-async function main() {
-    demonstrateMetadata();
-    demonstrateInputDependentConcurrency();
-    await demonstrateValidation();
-    await demonstratePermissions();
-    demonstrateAgentRegistration();
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-    main().catch(console.error);
-}
-
-export { main };

package/examples/tools/streaming-tool-execution.ts

@@ -1,283 +0,0 @@
-/**
- * Streaming Tool Execution Example
- *
- * Demonstrates the StreamingToolExecutor with mixed read-only and write tools,
- * showing how read-only tools execute in parallel while write tools run serially.
- *
- * Key concepts:
- * - EnhancedTool with `isConcurrencySafe` metadata
- * - Parallel execution of concurrent-safe (read-only) tools
- * - Serial execution of non-concurrent-safe (write) tools
- * - Result ordering preserved regardless of completion order
- * - Progress reporting from long-running tools
- * - Abort signal support
- */
-
-import {
-    Agent,
-    GeminiProvider,
-    StreamingToolExecutor,
-    type EnhancedTool,
-    type ToolCallRequest,
-} from "../../src/index";
-
-// --- Read-only tools (concurrency-safe, run in parallel) ---
-
-const readFileTool: EnhancedTool = {
-    id: "read_file",
-    name: "Read File",
-    description: "Read a file from disk",
-    parameters: {
-        type: "object",
-        properties: { path: { type: "string" } },
-        required: ["path"],
-    },
-    handler: async (_ctx, args) => {
-        const path = args?.path as string;
-        // Simulate file read latency
-        await new Promise((r) => setTimeout(r, 200));
-        return { data: `Contents of ${path}: [mock file data]`, success: true };
-    },
-    isConcurrencySafe: () => true,
-    isReadOnly: () => true,
-    isDestructive: () => false,
-    interruptBehavior: () => "cancel",
-    maxResultSizeChars: 50_000,
-};
-
-const listDirectoryTool: EnhancedTool = {
-    id: "list_directory",
-    name: "List Directory",
-    description: "List files in a directory",
-    parameters: {
-        type: "object",
-        properties: { path: { type: "string" } },
-        required: ["path"],
-    },
-    handler: async (_ctx, args) => {
-        const path = args?.path as string;
-        await new Promise((r) => setTimeout(r, 150));
-        return {
-            data: `Files in ${path}: index.ts, utils.ts, types.ts`,
-            success: true,
-        };
-    },
-    isConcurrencySafe: () => true,
-    isReadOnly: () => true,
-    isDestructive: () => false,
-    interruptBehavior: () => "cancel",
-};
-
-const searchCodeTool: EnhancedTool = {
-    id: "search_code",
-    name: "Search Code",
-    description: "Search for patterns in the codebase",
-    parameters: {
-        type: "object",
-        properties: { query: { type: "string" } },
-        required: ["query"],
-    },
-    handler: async (_ctx, args) => {
-        const query = args?.query as string;
-        await new Promise((r) => setTimeout(r, 300));
-        return {
-            data: `Found 3 matches for "${query}" in src/`,
-            success: true,
-        };
-    },
-    isConcurrencySafe: () => true,
-    isReadOnly: () => true,
-    isDestructive: () => false,
-    interruptBehavior: () => "cancel",
-};
-
-// --- Write tools (NOT concurrency-safe, run serially) ---
-
-const writeFileTool: EnhancedTool = {
-    id: "write_file",
-    name: "Write File",
-    description: "Write content to a file",
-    parameters: {
-        type: "object",
-        properties: {
-            path: { type: "string" },
-            content: { type: "string" },
-        },
-        required: ["path", "content"],
-    },
-    handler: async (_ctx, args) => {
-        const path = args?.path as string;
-        await new Promise((r) => setTimeout(r, 250));
-        return { data: `Wrote to ${path}`, success: true };
-    },
-    isConcurrencySafe: () => false,
-    isReadOnly: () => false,
-    isDestructive: (input) => true,
-    interruptBehavior: () => "block",
-    maxResultSizeChars: 1_000,
-};
-
-const deleteFileTool: EnhancedTool = {
-    id: "delete_file",
-    name: "Delete File",
-    description: "Delete a file from disk",
-    parameters: {
-        type: "object",
-        properties: { path: { type: "string" } },
-        required: ["path"],
-    },
-    handler: async (_ctx, args) => {
-        const path = args?.path as string;
-        await new Promise((r) => setTimeout(r, 100));
-        return { data: `Deleted ${path}`, success: true };
-    },
-    isConcurrencySafe: () => false,
-    isReadOnly: () => false,
-    isDestructive: () => true,
-    interruptBehavior: () => "block",
-};
-
-// Helper: create a minimal ToolContext for standalone executor usage
-function createMockToolContext() {
-    return {
-        context: {},
-        data: {},
-        history: [],
-        updateContext: async () => { },
-        updateData: async () => { },
-        getField: () => undefined,
-        setField: async () => { },
-        hasField: () => false,
-    } as any;
-}
-
-// --- Direct StreamingToolExecutor usage ---
-
-async function demonstrateDirectExecutor() {
-    console.log("=== Direct StreamingToolExecutor Demo ===\n");
-
-    const toolMap = new Map<string, EnhancedTool>([
-        ["read_file", readFileTool],
-        ["list_directory", listDirectoryTool],
-        ["search_code", searchCodeTool],
-        ["write_file", writeFileTool],
-    ]);
-
-    // Simulate a sequence of tool calls from an LLM response:
-    // 3 reads (parallel) followed by 1 write (serial)
-    const toolCalls: ToolCallRequest[] = [
-        { id: "call_1", toolName: "read_file", arguments: { path: "src/index.ts" } },
-        { id: "call_2", toolName: "list_directory", arguments: { path: "src/" } },
-        { id: "call_3", toolName: "search_code", arguments: { query: "import" } },
-        { id: "call_4", toolName: "write_file", arguments: { path: "out.ts", content: "// generated" } },
-    ];
-
-    const executor = new StreamingToolExecutor<unknown, unknown>(
-        createMockToolContext(),
-        { maxParallel: 5 },
-    );
-
-    console.log("Queueing tools as they arrive from the LLM stream...\n");
-
-    for (const call of toolCalls) {
-        const tool = toolMap.get(call.toolName)!;
-        const safe = tool.isConcurrencySafe?.() ? "parallel" : "serial";
-        console.log(`  + Queued: ${call.toolName} (${safe})`);
-        executor.addTool(call, tool);
-    }
-
-    console.log("\nResults (yielded in original request order):\n");
-
-    for await (const update of executor.getRemainingResults()) {
-        if (update.progress) {
-            console.log(`  [progress] ${update.toolCallId}: ${update.progress}`);
-        }
-        if (update.result) {
-            console.log(`  [result]   ${update.toolCallId}: ${update.result.data}`);
-        }
-    }
-
-    console.log("\nAll tools complete.");
-}
-
-// --- Agent-level integration ---
-
-async function demonstrateAgentIntegration() {
-    console.log("\n=== Agent Integration Demo ===\n");
-
-    const agent = new Agent({
-        name: "CodeAssistant",
-        description: "An assistant with streaming tool execution",
-        provider: new GeminiProvider({
-            apiKey: process.env.GEMINI_API_KEY || "demo-key",
-            model: "models/gemini-2.5-flash",
-        }),
-        tools: [readFileTool, listDirectoryTool, searchCodeTool, writeFileTool, deleteFileTool],
-    });
-
-    console.log("Tools registered:");
-    for (const t of agent.getTools()) {
-        const enhanced = t as EnhancedTool;
-        const safe = enhanced.isConcurrencySafe?.() ?? false;
-        console.log(`  - ${t.id} (concurrencySafe: ${safe})`);
-    }
-
-    console.log("\nStreaming tool execution happens automatically during respondStream().");
-    console.log("Read-only tools run in parallel; write tools wait for exclusive access.\n");
-
-    // In a real scenario you'd call agent.stream() or agent.respondStream()
-    // and the StreamingToolExecutor handles concurrency internally.
-    console.log("Example streaming usage:");
-    console.log('  for await (const chunk of agent.stream("Read index.ts and list src/")) {');
-    console.log("    process.stdout.write(chunk.delta);");
-    console.log("  }");
-}
-
-// --- Abort signal demo ---
-
-async function demonstrateAbortSignal() {
-    console.log("\n=== Abort Signal Demo ===\n");
-
-    const controller = new AbortController();
-    const executor = new StreamingToolExecutor<unknown, unknown>(
-        createMockToolContext(),
-        { maxParallel: 5, signal: controller.signal },
-    );
-
-    // Queue a slow read and a write
-    executor.addTool(
-        { id: "slow_read", toolName: "search_code", arguments: { query: "TODO" } },
-        searchCodeTool
-    );
-    executor.addTool(
-        { id: "slow_write", toolName: "write_file", arguments: { path: "tmp.ts", content: "x" } },
-        writeFileTool
-    );
-
-    // Abort after 100ms — 'cancel' tools abort immediately, 'block' tools finish
-    setTimeout(() => {
-        console.log("  Aborting...");
-        controller.abort();
-    }, 100);
-
-    for await (const update of executor.getRemainingResults()) {
-        if (update.result) {
-            const status = update.result.success ? "ok" : "aborted";
-            console.log(`  ${update.toolCallId}: ${status} — ${update.result.data ?? update.result.error}`);
-        }
-    }
-
-    console.log("  Done (abort handled gracefully).");
-}
-
-async function main() {
-    await demonstrateDirectExecutor();
-    await demonstrateAgentIntegration();
-    await demonstrateAbortSignal();
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-    main().catch(console.error);
-}
-
-export { main };