@falai/agent 1.1.3 → 1.2.1

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

@@ -0,0 +1,268 @@
+/**
+ * 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

@@ -0,0 +1,283 @@
+/**
+ * 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",