@aragon-agent/core 0.1.3

package/dist/tools/registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Tool System — Tool Registry
+ *
+ * Manages dynamic registration and lookup of AgentTools.
+ * Supports change notification so consumers (e.g. the Agent engine)
+ * can react when tools are added or removed at runtime.
+ */
+import type { AgentTool, ToolDefinition, ToolRegistryEvent } from './types.js';
+/** Listener callback type for registry change events. */
+export type ToolRegistryListener = (event: ToolRegistryEvent) => void;
+/**
+ * A registry that holds AgentTool instances indexed by name.
+ * Provides lookup, filtering, and LLM tool-definition export.
+ */
+export declare class ToolRegistry {
+    /** Internal tool storage, keyed by tool name. */
+    private readonly tools;
+    /** Registered change listeners. */
+    private readonly listeners;
+    /**
+     * Register a single tool. Throws if a tool with the same name
+     * is already registered.
+     */
+    register(tool: AgentTool): void;
+    /**
+     * Register multiple tools at once. Throws on the first duplicate
+     * name encountered (tools registered before the error remain).
+     */
+    registerAll(tools: AgentTool[]): void;
+    /**
+     * Remove a tool by name.
+     * @returns `true` if the tool existed and was removed; `false` otherwise.
+     */
+    unregister(name: string): boolean;
+    /** Retrieve a tool by name, or `undefined` if not found. */
+    get(name: string): AgentTool | undefined;
+    /** Return all registered tools as an array (snapshot). */
+    getAll(): AgentTool[];
+    /** Return tools that include the specified tag. */
+    getByTag(tag: string): AgentTool[];
+    /** Return tools marked as bridgeable (for CodeAct sandbox). */
+    getBridgeable(): AgentTool[];
+    /** Check whether a tool with the given name is registered. */
+    has(name: string): boolean;
+    /** Number of registered tools. */
+    get size(): number;
+    /**
+     * Export all registered tools as provider-agnostic ToolDefinitions
+     * suitable for passing to any LLM provider adapter.
+     */
+    toToolDefinitions(): ToolDefinition[];
+    /**
+     * Subscribe to registry change events.
+     * @returns An unsubscribe function.
+     */
+    onChange(listener: ToolRegistryListener): () => void;
+    private emit;
+}

package/dist/tools/registry.js

@@ -0,0 +1,119 @@
+/**
+ * Tool System — Tool Registry
+ *
+ * Manages dynamic registration and lookup of AgentTools.
+ * Supports change notification so consumers (e.g. the Agent engine)
+ * can react when tools are added or removed at runtime.
+ */
+/**
+ * A registry that holds AgentTool instances indexed by name.
+ * Provides lookup, filtering, and LLM tool-definition export.
+ */
+export class ToolRegistry {
+    /** Internal tool storage, keyed by tool name. */
+    tools = new Map();
+    /** Registered change listeners. */
+    listeners = new Set();
+    // -----------------------------------------------------------------------
+    // Registration
+    // -----------------------------------------------------------------------
+    /**
+     * Register a single tool. Throws if a tool with the same name
+     * is already registered.
+     */
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`ToolRegistry: tool "${tool.name}" is already registered. ` +
+                'Unregister it first or use a different name.');
+        }
+        this.tools.set(tool.name, tool);
+        this.emit({ type: 'registered', tool });
+    }
+    /**
+     * Register multiple tools at once. Throws on the first duplicate
+     * name encountered (tools registered before the error remain).
+     */
+    registerAll(tools) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+    }
+    /**
+     * Remove a tool by name.
+     * @returns `true` if the tool existed and was removed; `false` otherwise.
+     */
+    unregister(name) {
+        const existed = this.tools.delete(name);
+        if (existed) {
+            this.emit({ type: 'unregistered', name });
+        }
+        return existed;
+    }
+    // -----------------------------------------------------------------------
+    // Lookup
+    // -----------------------------------------------------------------------
+    /** Retrieve a tool by name, or `undefined` if not found. */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** Return all registered tools as an array (snapshot). */
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    /** Return tools that include the specified tag. */
+    getByTag(tag) {
+        return this.getAll().filter((t) => t.tags !== undefined && t.tags.includes(tag));
+    }
+    /** Return tools marked as bridgeable (for CodeAct sandbox). */
+    getBridgeable() {
+        return this.getAll().filter((t) => t.bridgeable === true);
+    }
+    /** Check whether a tool with the given name is registered. */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /** Number of registered tools. */
+    get size() {
+        return this.tools.size;
+    }
+    // -----------------------------------------------------------------------
+    // Export
+    // -----------------------------------------------------------------------
+    /**
+     * Export all registered tools as provider-agnostic ToolDefinitions
+     * suitable for passing to any LLM provider adapter.
+     */
+    toToolDefinitions() {
+        return this.getAll().map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        }));
+    }
+    // -----------------------------------------------------------------------
+    // Change Notification
+    // -----------------------------------------------------------------------
+    /**
+     * Subscribe to registry change events.
+     * @returns An unsubscribe function.
+     */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Swallow listener errors to avoid disrupting the registry.
+            }
+        }
+    }
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Tool System — Core Type Definitions
+ *
+ * Defines the AgentTool interface and related types.
+ * Parameters use standard JSON Schema 7.
+ */
+/**
+ * A JSON Schema 7 object used to describe tool parameters.
+ *
+ * This is intentionally a structural subset — it covers the shapes
+ * actually used in tool parameter definitions (object schemas with
+ * typed properties) while remaining compatible with full JSON Schema 7
+ * validators such as ajv.
+ */
+export interface JSONSchema7 {
+    type?: string | string[];
+    description?: string;
+    properties?: Record<string, JSONSchema7>;
+    required?: string[];
+    items?: JSONSchema7 | JSONSchema7[];
+    enum?: unknown[];
+    const?: unknown;
+    default?: unknown;
+    additionalProperties?: boolean | JSONSchema7;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    format?: string;
+    oneOf?: JSONSchema7[];
+    anyOf?: JSONSchema7[];
+    allOf?: JSONSchema7[];
+    not?: JSONSchema7;
+    if?: JSONSchema7;
+    then?: JSONSchema7;
+    else?: JSONSchema7;
+    /** Allow arbitrary additional keywords for full JSON Schema 7 compat. */
+    [key: string]: unknown;
+}
+/** A single content block within a tool result. */
+export type ToolResultContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+};
+/** The result returned by a tool execution. */
+export interface ToolResult {
+    content: ToolResultContent[];
+    isError?: boolean;
+}
+/** Progress information emitted by long-running tools. */
+export interface ToolProgressUpdate {
+    message?: string;
+    percentage?: number;
+    detail?: unknown;
+}
+/**
+ * Execution context passed to every tool invocation.
+ * Provides cancellation signaling and progress reporting.
+ */
+export interface ToolExecutionContext {
+    /** AbortSignal for cooperative cancellation (timeout + external abort). */
+    signal?: AbortSignal;
+    /** Optional callback for reporting incremental progress. */
+    onProgress?: (update: ToolProgressUpdate) => void;
+}
+/**
+ * The function signature every tool must implement.
+ *
+ * @param toolCallId - Unique identifier for this tool invocation (from the LLM).
+ * @param params     - Validated parameters matching the tool's JSON Schema.
+ * @param context    - Execution context with signal and progress callback.
+ */
+export type ToolExecuteFn<TParams = Record<string, unknown>> = (toolCallId: string, params: TParams, context: ToolExecutionContext) => Promise<ToolResult>;
+/**
+ * A self-contained tool that can be registered in the ToolRegistry,
+ * exposed to LLMs as a callable function, and optionally bridged
+ * into the CodeAct sandbox.
+ */
+export interface AgentTool<TParams = Record<string, unknown>> {
+    /** Unique tool identifier (used in LLM tool_use calls). */
+    name: string;
+    /** Human-readable display label (UI and logs). */
+    label: string;
+    /** Description injected into the LLM's tool definition. */
+    description: string;
+    /** JSON Schema 7 describing the tool's parameters. */
+    parameters: JSONSchema7;
+    /** The tool's execution function. */
+    execute: ToolExecuteFn<TParams>;
+    /** Optional classification tags for filtering (e.g. 'filesystem', 'network'). */
+    tags?: string[];
+    /**
+     * Whether this tool should be exposed as a bridged async function
+     * inside the CodeAct JS sandbox. Defaults to false.
+     */
+    bridgeable?: boolean;
+    /**
+     * The function name used in the CodeAct sandbox when bridged.
+     * Defaults to the tool's `name` if not specified.
+     * Example: name='read_file', bridgeName='readFile'
+     */
+    bridgeName?: string;
+}
+/**
+ * A minimal, provider-agnostic tool definition suitable for passing
+ * to any LLM provider adapter.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: JSONSchema7;
+}
+/** Events emitted by ToolRegistry when tools are added or removed. */
+export type ToolRegistryEvent = {
+    type: 'registered';
+    tool: AgentTool;
+} | {
+    type: 'unregistered';
+    name: string;
+};
+/**
+ * Extended result from ToolExecutor.execute() that includes metadata
+ * about the execution (timing, tool identification, error status).
+ */
+export interface ToolExecutionResult {
+    result: ToolResult;
+    /** Wall-clock duration in milliseconds. */
+    duration: number;
+    /** Whether the execution resulted in an error. */
+    isError: boolean;
+    /** The name of the tool that was executed. */
+    toolName: string;
+    /** The tool call ID from the LLM. */
+    toolCallId: string;
+}

package/dist/tools/types.js

@@ -0,0 +1,7 @@
+/**
+ * Tool System — Core Type Definitions
+ *
+ * Defines the AgentTool interface and related types.
+ * Parameters use standard JSON Schema 7.
+ */
+export {};

package/dist/tools/validator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Tool System — Parameter Validator
+ *
+ * Validates tool parameters against their JSON Schema 7 definitions.
+ * Uses `ajv` when available for full JSON Schema validation; falls back
+ * to a minimal inline validator for basic type checking when ajv is
+ * not yet installed.
+ */
+import type { JSONSchema7 } from './types.js';
+/**
+ * Structured validation error with a JSON pointer path and message.
+ */
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+/**
+ * Error thrown when parameter validation fails.
+ */
+export declare class ToolValidationError extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+/**
+ * Validates tool call parameters against a JSON Schema 7 definition.
+ *
+ * Attempts to use `ajv` for full schema validation. If ajv is not
+ * available at runtime (not yet installed), falls back to a lightweight
+ * inline validator that covers basic type and required-field checks.
+ */
+export declare class ToolParamValidator {
+    private strategy;
+    private strategyReady;
+    /**
+     * Validate `params` against the given JSON Schema.
+     *
+     * @returns The validated (and potentially coerced) parameters.
+     * @throws {ToolValidationError} if validation fails.
+     */
+    validate(schema: JSONSchema7, params: unknown): Promise<Record<string, unknown>>;
+    private getStrategy;
+}
+/**
+ * Format validation errors into a single human-readable string.
+ */
+export declare function formatValidationErrors(errors: ValidationError[]): string;

package/dist/tools/validator.js

@@ -0,0 +1,210 @@
+/**
+ * Tool System — Parameter Validator
+ *
+ * Validates tool parameters against their JSON Schema 7 definitions.
+ * Uses `ajv` when available for full JSON Schema validation; falls back
+ * to a minimal inline validator for basic type checking when ajv is
+ * not yet installed.
+ */
+/**
+ * Error thrown when parameter validation fails.
+ */
+export class ToolValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Parameter validation failed: ${formatValidationErrors(errors)}`);
+        this.errors = errors;
+        this.name = 'ToolValidationError';
+    }
+}
+// ---------------------------------------------------------------------------
+// ToolParamValidator
+// ---------------------------------------------------------------------------
+/**
+ * Validates tool call parameters against a JSON Schema 7 definition.
+ *
+ * Attempts to use `ajv` for full schema validation. If ajv is not
+ * available at runtime (not yet installed), falls back to a lightweight
+ * inline validator that covers basic type and required-field checks.
+ */
+export class ToolParamValidator {
+    strategy = null;
+    strategyReady = null;
+    /**
+     * Validate `params` against the given JSON Schema.
+     *
+     * @returns The validated (and potentially coerced) parameters.
+     * @throws {ToolValidationError} if validation fails.
+     */
+    async validate(schema, params) {
+        const strategy = await this.getStrategy();
+        return strategy.validate(schema, params);
+    }
+    // -----------------------------------------------------------------------
+    // Strategy Resolution
+    // -----------------------------------------------------------------------
+    getStrategy() {
+        if (this.strategyReady) {
+            return this.strategyReady;
+        }
+        this.strategyReady = (async () => {
+            try {
+                // Dynamic import for ESM compatibility.
+                const AjvModule = await import('ajv');
+                const Ajv = AjvModule.default ?? AjvModule;
+                this.strategy = new AjvStrategy(Ajv);
+            }
+            catch {
+                // ajv not installed — use the fallback.
+                this.strategy = new FallbackStrategy();
+            }
+            return this.strategy;
+        })();
+        return this.strategyReady;
+    }
+}
+// ---------------------------------------------------------------------------
+// Ajv-based Strategy
+// ---------------------------------------------------------------------------
+class AjvStrategy {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ajvInstance;
+    /** Cache of compiled validators keyed by a stable schema fingerprint. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    compiledCache = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(Ajv) {
+        this.ajvInstance = new Ajv({
+            allErrors: true,
+            coerceTypes: true,
+            useDefaults: true,
+            strict: false,
+        });
+    }
+    validate(schema, params) {
+        // Ensure we validate an object even if params is null/undefined.
+        const data = params !== null && typeof params === 'object' && !Array.isArray(params)
+            ? { ...params }
+            : {};
+        const validateFn = this.getOrCompile(schema);
+        const valid = validateFn(data);
+        if (!valid) {
+            const errors = (validateFn.errors ?? []).map((err) => ({
+                path: err.instancePath || '/',
+                message: err.message ?? 'unknown error',
+            }));
+            throw new ToolValidationError(errors);
+        }
+        return data;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getOrCompile(schema) {
+        const key = JSON.stringify(schema);
+        let fn = this.compiledCache.get(key);
+        if (!fn) {
+            fn = this.ajvInstance.compile(schema);
+            this.compiledCache.set(key, fn);
+        }
+        return fn;
+    }
+}
+// ---------------------------------------------------------------------------
+// Fallback Strategy (no ajv)
+// ---------------------------------------------------------------------------
+/**
+ * A lightweight validator that covers the most common schema shapes
+ * used in tool parameter definitions:
+ *  - top-level `type: 'object'` with `properties` and `required`
+ *  - per-property primitive type checks (string, number, boolean, array, object)
+ *
+ * This is NOT a full JSON Schema 7 implementation — it exists solely
+ * as a safety net until ajv is installed.
+ */
+class FallbackStrategy {
+    validate(schema, params) {
+        const data = params !== null && typeof params === 'object' && !Array.isArray(params)
+            ? { ...params }
+            : {};
+        const errors = [];
+        // Check required fields.
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (data[key] === undefined || data[key] === null) {
+                    errors.push({
+                        path: `/${key}`,
+                        message: `required property '${key}' is missing`,
+                    });
+                }
+            }
+        }
+        // Check property types.
+        if (schema.properties) {
+            for (const [key, propSchema] of Object.entries(schema.properties)) {
+                const value = data[key];
+                if (value === undefined || value === null) {
+                    // Apply defaults if specified.
+                    if (propSchema.default !== undefined) {
+                        data[key] = propSchema.default;
+                    }
+                    continue;
+                }
+                const typeError = checkPrimitiveType(key, value, propSchema);
+                if (typeError) {
+                    errors.push(typeError);
+                }
+            }
+        }
+        if (errors.length > 0) {
+            throw new ToolValidationError(errors);
+        }
+        return data;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function checkPrimitiveType(key, value, schema) {
+    const expectedType = schema.type;
+    if (!expectedType || typeof expectedType !== 'string') {
+        return null;
+    }
+    const actualType = Array.isArray(value) ? 'array' : typeof value;
+    switch (expectedType) {
+        case 'string':
+            if (typeof value !== 'string') {
+                return { path: `/${key}`, message: `expected string, got ${actualType}` };
+            }
+            break;
+        case 'number':
+        case 'integer':
+            if (typeof value !== 'number') {
+                return { path: `/${key}`, message: `expected number, got ${actualType}` };
+            }
+            break;
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                return { path: `/${key}`, message: `expected boolean, got ${actualType}` };
+            }
+            break;
+        case 'array':
+            if (!Array.isArray(value)) {
+                return { path: `/${key}`, message: `expected array, got ${actualType}` };
+            }
+            break;
+        case 'object':
+            if (typeof value !== 'object' || Array.isArray(value) || value === null) {
+                return { path: `/${key}`, message: `expected object, got ${actualType}` };
+            }
+            break;
+        // 'null' and unknown types are not checked — let them pass.
+    }
+    return null;
+}
+/**
+ * Format validation errors into a single human-readable string.
+ */
+export function formatValidationErrors(errors) {
+    return errors
+        .map((e) => `${e.path}: ${e.message}`)
+        .join('; ');
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Core Agent event types.
+ *
+ * These events are emitted by the Agent engine during execution and consumed
+ * by subscribers (e.g. SelfAgentService) to drive UI updates and persistence.
+ */
+import type { AssistantMessage, Message, StreamEvent, TokenUsage } from './llm/types.js';
+import type { ToolResult } from './tools/types.js';
+export interface AgentStartEvent {
+    type: 'agent_start';
+}
+export interface AgentEndEvent {
+    type: 'agent_end';
+    messages: Message[];
+}
+export interface TurnStartEvent {
+    type: 'turn_start';
+}
+export interface TurnEndEvent {
+    type: 'turn_end';
+    message: AssistantMessage;
+    usage: TokenUsage;
+}
+export interface MessageUpdateEvent {
+    type: 'message_update';
+    streamEvent: StreamEvent;
+}
+export interface ToolExecutionStartEvent {
+    type: 'tool_execution_start';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+export interface ToolExecutionEndEvent {
+    type: 'tool_execution_end';
+    toolCallId: string;
+    toolName: string;
+    result: ToolResult;
+    isError: boolean;
+    duration: number;
+}
+export interface CodeExecutionStartEvent {
+    type: 'code_execution_start';
+    code: string;
+    language: string;
+}
+export interface CodeExecutionEndEvent {
+    type: 'code_execution_end';
+    output: string;
+    error?: string;
+    duration: number;
+}
+/** Union of all events emitted by the Agent engine. */
+export type AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageUpdateEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | CodeExecutionStartEvent | CodeExecutionEndEvent;
+/** Callback signature for Agent event listeners. */
+export type AgentEventListener = (event: AgentEvent) => void;

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Core Agent event types.
+ *
+ * These events are emitted by the Agent engine during execution and consumed
+ * by subscribers (e.g. SelfAgentService) to drive UI updates and persistence.
+ */
+export {};