@agentick/core 0.0.1

package/dist/testing/test-model.js

@@ -0,0 +1,260 @@
+/**
+ * Test Model Factory
+ *
+ * Creates mock models for testing agents without making real API calls.
+ */
+import { createModel } from "../model/model";
+import { fromEngineState, toEngineState } from "../model/utils/language-model";
+import { BlockType } from "@tentickle/shared";
+import { vi } from "vitest";
+import { randomUUID } from "crypto";
+// ============================================================================
+// Stream Event Helpers
+// ============================================================================
+let sequenceCounter = 0;
+function createStreamEvent(type, fields) {
+    sequenceCounter++;
+    return {
+        type,
+        id: randomUUID(),
+        sequence: sequenceCounter,
+        tick: 1,
+        timestamp: new Date().toISOString(),
+        ...fields,
+    };
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a test model for use in tests.
+ *
+ * @example
+ * ```tsx
+ * const model = createTestModel({
+ *   defaultResponse: "Hello from test!",
+ *   delay: 10,
+ * });
+ *
+ * const { send } = renderAgent(MyAgent, { model });
+ * await act(() => send("Hi"));
+ *
+ * expect(model.getCapturedInputs()).toHaveLength(1);
+ * ```
+ *
+ * @example Dynamic responses
+ * ```tsx
+ * const model = createTestModel({
+ *   responseGenerator: (input) => {
+ *     const lastMessage = input.messages.at(-1);
+ *     if (lastMessage?.content.includes("weather")) {
+ *       return "It's sunny today!";
+ *     }
+ *     return "I don't understand.";
+ *   },
+ * });
+ * ```
+ */
+export function createTestModel(options = {}) {
+    const { defaultResponse = "Test response", delay = 0, onExecute } = options;
+    // Mutable state
+    let currentResponse = options.responseGenerator
+        ? defaultResponse
+        : defaultResponse;
+    let currentToolCalls = options.toolCalls ?? [];
+    let currentError = options.throwError ?? null;
+    let responseGenerator = options.responseGenerator;
+    const capturedInputs = [];
+    // Streaming state
+    let streamingEnabled = options.streaming?.enabled ?? false;
+    let streamingChunkSize = options.streaming?.chunkSize ?? 10;
+    let streamingChunkDelay = options.streaming?.chunkDelay ?? 5;
+    // Helper to build message from string or Message
+    const buildMessage = (response) => {
+        if (typeof response === "string") {
+            return {
+                role: "assistant",
+                content: [{ type: "text", text: response }],
+            };
+        }
+        return response;
+    };
+    // Helper to get response
+    const getResponse = (input) => {
+        if (responseGenerator) {
+            return buildMessage(responseGenerator(input));
+        }
+        return buildMessage(currentResponse);
+    };
+    // Mock functions
+    const executeMock = vi.fn();
+    const executeStreamMock = vi.fn();
+    const model = createModel({
+        metadata: {
+            id: "test-model",
+            provider: "test",
+            capabilities: [],
+        },
+        executors: {
+            execute: async (input) => {
+                executeMock(input);
+                capturedInputs.push(input);
+                onExecute?.(input);
+                if (delay > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                if (currentError) {
+                    throw currentError;
+                }
+                const message = getResponse(input);
+                return {
+                    model: "test-model",
+                    createdAt: new Date().toISOString(),
+                    message,
+                    usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+                    stopReason: (options.stopReason ?? "stop"),
+                    raw: {},
+                };
+            },
+            executeStream: async function* (input) {
+                executeStreamMock(input);
+                capturedInputs.push(input);
+                onExecute?.(input);
+                // Reset sequence counter for this stream
+                sequenceCounter = 0;
+                if (delay > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                if (currentError) {
+                    throw currentError;
+                }
+                const message = getResponse(input);
+                const textContent = message.content
+                    .filter((c) => c.type === "text")
+                    .map((c) => c.text)
+                    .join("");
+                // Use mutable streaming state
+                const chunkSize = streamingChunkSize;
+                const chunkDelay = streamingChunkDelay;
+                // Yield message_start
+                yield createStreamEvent("message_start", {
+                    role: "assistant",
+                });
+                // Yield text content
+                if (textContent) {
+                    // Yield content_start
+                    yield createStreamEvent("content_start", {
+                        blockType: BlockType.TEXT,
+                        blockIndex: 0,
+                    });
+                    if (streamingEnabled) {
+                        // Simulate realistic streaming: yield chunks progressively
+                        for (let i = 0; i < textContent.length; i += chunkSize) {
+                            const chunk = textContent.slice(i, i + chunkSize);
+                            yield createStreamEvent("content_delta", {
+                                blockType: BlockType.TEXT,
+                                blockIndex: 0,
+                                delta: chunk,
+                            });
+                            if (chunkDelay > 0 && i + chunkSize < textContent.length) {
+                                await new Promise((resolve) => setTimeout(resolve, chunkDelay));
+                            }
+                        }
+                    }
+                    else {
+                        // Default: yield entire response as single chunk
+                        yield createStreamEvent("content_delta", {
+                            blockType: BlockType.TEXT,
+                            blockIndex: 0,
+                            delta: textContent,
+                        });
+                    }
+                    // Yield content_end
+                    yield createStreamEvent("content_end", {
+                        blockType: BlockType.TEXT,
+                        blockIndex: 0,
+                    });
+                }
+                // Yield tool calls
+                let toolBlockIndex = textContent ? 1 : 0;
+                for (const toolCall of currentToolCalls) {
+                    yield createStreamEvent("tool_call_start", {
+                        // blockType: BlockType.TOOL_USE,
+                        blockIndex: toolBlockIndex,
+                        callId: toolCall.id,
+                        name: toolCall.name,
+                    });
+                    yield createStreamEvent("tool_call_delta", {
+                        // blockType: BlockType.TOOL_USE,
+                        blockIndex: toolBlockIndex,
+                        callId: toolCall.id,
+                        delta: JSON.stringify(toolCall.input),
+                    });
+                    yield createStreamEvent("tool_call_end", {
+                        // blockType: BlockType.TOOL_USE,
+                        blockIndex: toolBlockIndex,
+                        callId: toolCall.id,
+                        // name: toolCall.name,
+                        // input: toolCall.input,
+                    });
+                    toolBlockIndex++;
+                }
+                // Yield message_end
+                yield createStreamEvent("message_end", {
+                    stopReason: (options.stopReason ?? "stop"),
+                    usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+                });
+            },
+        },
+        transformers: {
+            processStream: async (chunks) => {
+                let text = "";
+                for (const chunk of chunks) {
+                    if (chunk.type === "content_delta" && typeof chunk.delta === "string") {
+                        text += chunk.delta;
+                    }
+                }
+                return {
+                    model: "test-model",
+                    createdAt: new Date().toISOString(),
+                    message: { role: "assistant", content: [{ type: "text", text }] },
+                    usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+                    stopReason: (options.stopReason ?? "stop"),
+                    raw: {},
+                };
+            },
+        },
+        fromEngineState,
+        toEngineState,
+    });
+    // Extend with test utilities
+    const testModel = model;
+    testModel.getCapturedInputs = () => [...capturedInputs];
+    testModel.clearCapturedInputs = () => {
+        capturedInputs.length = 0;
+    };
+    testModel.setResponse = (response) => {
+        currentResponse = response;
+        responseGenerator = undefined;
+    };
+    testModel.setToolCalls = (toolCalls) => {
+        currentToolCalls = toolCalls;
+    };
+    testModel.setError = (error) => {
+        currentError = error;
+    };
+    testModel.setStreaming = (opts) => {
+        if (opts.enabled !== undefined)
+            streamingEnabled = opts.enabled;
+        if (opts.chunkSize !== undefined)
+            streamingChunkSize = opts.chunkSize;
+        if (opts.chunkDelay !== undefined)
+            streamingChunkDelay = opts.chunkDelay;
+    };
+    testModel.mocks = {
+        execute: executeMock,
+        executeStream: executeStreamMock,
+    };
+    return testModel;
+}
+//# sourceMappingURL=test-model.js.map

package/dist/testing/test-model.js.map

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

package/dist/tool/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * # Agentick Tools
+ *
+ * Tool definition and execution for Agentick agents. Tools are the bridge between
+ * LLM reasoning and real-world actions.
+ *
+ * ## Features
+ *
+ * - **Type-Safe Definition** - Zod schema validation for inputs/outputs
+ * - **Execution Modes** - SERVER, CLIENT, PROVIDER, MCP routing
+ * - **JSX Integration** - Tools as components that register on mount
+ * - **Hook System** - Middleware for validation, logging, metrics
+ * - **Confirmation Flow** - User approval for sensitive operations
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createTool, ToolExecutionType } from 'agentick';
+ * import { z } from 'zod';
+ *
+ * // Server-side tool
+ * const searchTool = createTool({
+ *   name: 'search',
+ *   description: 'Search the database',
+ *   input: z.object({
+ *     query: z.string(),
+ *     limit: z.number().optional().default(10),
+ *   }),
+ *   handler: async ({ query, limit }) => {
+ *     return await db.search(query, limit);
+ *   },
+ * });
+ *
+ * // Client-side tool (runs in browser)
+ * const confirmTool = createTool({
+ *   name: 'confirm',
+ *   description: 'Ask user for confirmation',
+ *   type: ToolExecutionType.CLIENT,
+ *   input: z.object({ message: z.string() }),
+ *   // Handler runs on client, result sent back to server
+ * });
+ * ```
+ *
+ * ## Execution Types
+ *
+ * | Type | Description |
+ * |------|-------------|
+ * | `SERVER` | Executes on the server (default) |
+ * | `CLIENT` | Executes in the browser, result sent back |
+ * | `PROVIDER` | Handled by the model provider (e.g., web search) |
+ * | `MCP` | Routed to Model Context Protocol server |
+ *
+ * @see {@link createTool} - Create type-safe tools
+ * @see {@link ToolDefinition} - Tool definition interface
+ * @see {@link ToolExecutionType} - Execution type enum
+ *
+ * @module agentick/tool
+ */
+export * from "./tool";
+export * from "./tool-hooks";
+//# sourceMappingURL=index.d.ts.map

package/dist/tool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC"}

package/dist/tool/index.js

@@ -0,0 +1,63 @@
+/**
+ * # Agentick Tools
+ *
+ * Tool definition and execution for Agentick agents. Tools are the bridge between
+ * LLM reasoning and real-world actions.
+ *
+ * ## Features
+ *
+ * - **Type-Safe Definition** - Zod schema validation for inputs/outputs
+ * - **Execution Modes** - SERVER, CLIENT, PROVIDER, MCP routing
+ * - **JSX Integration** - Tools as components that register on mount
+ * - **Hook System** - Middleware for validation, logging, metrics
+ * - **Confirmation Flow** - User approval for sensitive operations
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createTool, ToolExecutionType } from 'agentick';
+ * import { z } from 'zod';
+ *
+ * // Server-side tool
+ * const searchTool = createTool({
+ *   name: 'search',
+ *   description: 'Search the database',
+ *   input: z.object({
+ *     query: z.string(),
+ *     limit: z.number().optional().default(10),
+ *   }),
+ *   handler: async ({ query, limit }) => {
+ *     return await db.search(query, limit);
+ *   },
+ * });
+ *
+ * // Client-side tool (runs in browser)
+ * const confirmTool = createTool({
+ *   name: 'confirm',
+ *   description: 'Ask user for confirmation',
+ *   type: ToolExecutionType.CLIENT,
+ *   input: z.object({ message: z.string() }),
+ *   // Handler runs on client, result sent back to server
+ * });
+ * ```
+ *
+ * ## Execution Types
+ *
+ * | Type | Description |
+ * |------|-------------|
+ * | `SERVER` | Executes on the server (default) |
+ * | `CLIENT` | Executes in the browser, result sent back |
+ * | `PROVIDER` | Handled by the model provider (e.g., web search) |
+ * | `MCP` | Routed to Model Context Protocol server |
+ *
+ * @see {@link createTool} - Create type-safe tools
+ * @see {@link ToolDefinition} - Tool definition interface
+ * @see {@link ToolExecutionType} - Execution type enum
+ *
+ * @module agentick/tool
+ */
+export * from "./tool";
+export * from "./tool-hooks";
+// Note: createComponentTool has been removed in Mark II.
+// Use Harness component for sub-agent execution instead.
+//# sourceMappingURL=index.js.map

package/dist/tool/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,yDAAyD;AACzD,yDAAyD"}

package/dist/tool/tool-hooks.d.ts

@@ -0,0 +1,45 @@
+import type { Middleware } from "@agentick/kernel";
+import type { ContentBlock } from "@agentick/shared";
+import { BaseHookRegistry } from "../hooks/base-hook-registry";
+import type { ComponentHookArgs, ComponentHookName, ComponentHookReturn } from "../component/component-hooks";
+/**
+ * Tool operation names.
+ */
+export type ToolHookName = "run";
+/**
+ * Tool selector for hook registration.
+ * For now, we only support global hooks (all tools).
+ * Future: Could support tool-specific hooks by tool name or metadata.
+ */
+export type ToolSelector = undefined;
+/**
+ * Hook middleware type for tool operations.
+ */
+export type ToolHookMiddleware<T extends ToolHookName | ComponentHookName> = Middleware<T extends ToolHookName ? ToolHookArgs<T> : ComponentHookArgs<Exclude<T, ToolHookName>>>;
+/**
+ * Arguments for tool hooks.
+ */
+export type ToolHookArgs<T extends ToolHookName> = T extends "run" ? [input: unknown] : never;
+/**
+ * Return type for tool hooks.
+ */
+export type ToolHookReturn<T extends ToolHookName | ComponentHookName> = T extends ToolHookName ? Promise<ContentBlock[]> : ComponentHookReturn<Extract<T, ComponentHookName>>;
+/**
+ * Tool-specific hook registry.
+ * Uses BaseHookRegistry to reduce code duplication.
+ *
+ * Note: Global hooks via configureEngine() have been deprecated.
+ * Use Agentick.use() for middleware registration instead.
+ */
+export declare class ToolHookRegistry extends BaseHookRegistry<ToolHookName | ComponentHookName, ToolSelector, ToolHookMiddleware<ToolHookName | ComponentHookName>> {
+    protected getAllHookNames(): readonly (ToolHookName | ComponentHookName)[];
+    /**
+     * Get all middleware for a tool hook.
+     * Returns instance-specific hooks only.
+     *
+     * Note: Global hooks via configureEngine() have been deprecated.
+     * Use Agentick.use() for middleware registration instead.
+     */
+    getMiddleware(hookName: ToolHookName | ComponentHookName): ToolHookMiddleware<ToolHookName | ComponentHookName>[];
+}
+//# sourceMappingURL=tool-hooks.d.ts.map

package/dist/tool/tool-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hooks.d.ts","sourceRoot":"","sources":["../../src/tool/tool-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAEtC;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,YAAY,GAAG,iBAAiB,IAAI,UAAU,CACrF,CAAC,SAAS,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CACvF,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,YAAY,IAAI,CAAC,SAAS,KAAK,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC;AAE9F;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,YAAY,GAAG,iBAAiB,IAAI,CAAC,SAAS,YAAY,GAC3F,OAAO,CAAC,YAAY,EAAE,CAAC,GACvB,mBAAmB,CAAC,OAAO,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAEvD;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,gBAAgB,CACpD,YAAY,GAAG,iBAAiB,EAChC,YAAY,EACZ,kBAAkB,CAAC,YAAY,GAAG,iBAAiB,CAAC,CACrD;IACC,SAAS,CAAC,eAAe,IAAI,SAAS,CAAC,YAAY,GAAG,iBAAiB,CAAC,EAAE;IAe1E;;;;;;OAMG;IACH,aAAa,CACX,QAAQ,EAAE,YAAY,GAAG,iBAAiB,GACzC,kBAAkB,CAAC,YAAY,GAAG,iBAAiB,CAAC,EAAE;CAM1D"}

package/dist/tool/tool-hooks.js

@@ -0,0 +1,35 @@
+import { BaseHookRegistry } from "../hooks/base-hook-registry";
+/**
+ * Tool-specific hook registry.
+ * Uses BaseHookRegistry to reduce code duplication.
+ *
+ * Note: Global hooks via configureEngine() have been deprecated.
+ * Use Agentick.use() for middleware registration instead.
+ */
+export class ToolHookRegistry extends BaseHookRegistry {
+    getAllHookNames() {
+        const toolHookNames = ["run"];
+        const componentHookNames = [
+            "onMount",
+            "onUnmount",
+            "onStart",
+            "onTickStart",
+            "render",
+            "onTickEnd",
+            "onComplete",
+            "onError",
+        ];
+        return [...toolHookNames, ...componentHookNames];
+    }
+    /**
+     * Get all middleware for a tool hook.
+     * Returns instance-specific hooks only.
+     *
+     * Note: Global hooks via configureEngine() have been deprecated.
+     * Use Agentick.use() for middleware registration instead.
+     */
+    getMiddleware(hookName) {
+        return this.registry.getMiddleware(hookName, () => []);
+    }
+}
+//# sourceMappingURL=tool-hooks.js.map

package/dist/tool/tool-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hooks.js","sourceRoot":"","sources":["../../src/tool/tool-hooks.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAsC/D;;;;;;GAMG;AACH,MAAM,OAAO,gBAAiB,SAAQ,gBAIrC;IACW,eAAe;QACvB,MAAM,aAAa,GAAmB,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,kBAAkB,GAAwB;YAC9C,SAAS;YACT,WAAW;YACX,SAAS;YACT,aAAa;YACb,QAAQ;YACR,WAAW;YACX,YAAY;YACZ,SAAS;SACV,CAAC;QACF,OAAO,CAAC,GAAG,aAAa,EAAE,GAAG,kBAAkB,CAAU,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CACX,QAA0C;QAE1C,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,CAChC,QAAQ,EACR,GAAG,EAAE,CAAC,EAAE,CACT,CAAC;IACJ,CAAC;CACF"}