@aragon-agent/core 0.1.3

package/dist/skills/validate.js

@@ -0,0 +1,264 @@
+/**
+ * Skill validation — frontmatter contract (§4.4) and staged-install safety (§8.3).
+ *
+ * Pure functions only: no filesystem, no process. The staged validator takes a
+ * pre-listed file table so the same rules run identically over a real staging
+ * directory (CLI) and over a fixture (tests).
+ */
+import { SKILL_ALLOWED_TOOLS_MAX, SKILL_DESC_MAX, SKILL_KEYWORDS_MAX, SKILL_KEYWORD_LEN_MAX, SKILL_META_MAX, SKILL_NAME_MAX, SKILL_NAME_PATTERN, STAGED_MAX_DEPTH, STAGED_MAX_FILE_BYTES, STAGED_MAX_FILES, STAGED_MAX_TOTAL_BYTES, WINDOWS_RESERVED_NAMES, } from './constants.js';
+const ACTIVATIONS = ['auto', 'always', 'manual'];
+const SEMVER = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+/**
+ * Characters that let a description escape the `<available_skills>` block.
+ *
+ * WARN, NOT ERROR — and that asymmetry is load-bearing (§4.4). Community skills
+ * under `.claude/skills` legitimately write `<div>` in a description; failing
+ * them would break interop (D8). Escaping is enforced UNCONDITIONALLY at every
+ * render point by `sanitizeForPromptBlock()`; validation only tells the user.
+ * Never let "validation passed" become a licence to skip sanitizing.
+ */
+function isControlCode(code) {
+    return code < 0x20 || code === 0x7f;
+}
+/** True when `s` holds a C0/DEL control character. */
+export function hasControlChar(s) {
+    for (let i = 0; i < s.length; i += 1) {
+        if (isControlCode(s.charCodeAt(i)))
+            return true;
+    }
+    return false;
+}
+/** True when `s` holds an angle bracket or a control character. */
+function hasAngleOrControl(s) {
+    for (let i = 0; i < s.length; i += 1) {
+        const code = s.charCodeAt(i);
+        if (code === 0x3c || code === 0x3e || isControlCode(code))
+            return true;
+    }
+    return false;
+}
+function asString(v) {
+    if (typeof v === 'string')
+        return v;
+    return undefined;
+}
+function asArray(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === 'string' && v.trim().length > 0)
+        return [v.trim()];
+    return undefined;
+}
+/**
+ * Validate a parsed frontmatter map against the §4.2 contract.
+ *
+ * Error codes are a stable public surface — the UI and the tests both key off
+ * them, so renaming one is a breaking change.
+ */
+export function validateSkillFrontmatter(data, dirName) {
+    const issues = [];
+    const err = (code, message) => {
+        issues.push({ level: 'error', code, message });
+    };
+    const warn = (code, message) => {
+        issues.push({ level: 'warn', code, message });
+    };
+    const name = asString(data.name)?.trim();
+    if (!name) {
+        err('SKILL_NAME_MISSING', 'name is required');
+    }
+    else if (!SKILL_NAME_PATTERN.test(name) || name.length > SKILL_NAME_MAX) {
+        err('SKILL_NAME_INVALID', `name "${name}" must be kebab-case ([a-z0-9-], no leading/trailing/double dash) and at most ${SKILL_NAME_MAX} characters`);
+    }
+    else if (name !== dirName) {
+        warn('SKILL_NAME_DIR_MISMATCH', `frontmatter name "${name}" does not match directory "${dirName}"`);
+    }
+    const description = asString(data.description)?.trim();
+    if (!description) {
+        err('SKILL_DESC_MISSING', 'description is required');
+    }
+    else if (description.length > SKILL_DESC_MAX) {
+        err('SKILL_DESC_TOO_LONG', `description is ${description.length} characters (max ${SKILL_DESC_MAX})`);
+    }
+    else if (hasAngleOrControl(description)) {
+        warn('SKILL_DESC_UNSAFE_CHARS', 'description contains angle brackets or control characters; they will be neutralized before reaching the model');
+    }
+    const version = asString(data.version)?.trim();
+    if (version && !SEMVER.test(version)) {
+        warn('SKILL_VERSION_INVALID', `version "${version}" is not semver; falling back to 0.0.0`);
+    }
+    const activation = asString(data.activation)?.trim();
+    if (activation && !ACTIVATIONS.includes(activation)) {
+        warn('SKILL_ACTIVATION_INVALID', `unknown activation "${activation}"; falling back to auto`);
+    }
+    const allowedTools = data['allowed-tools'] ?? data.allowedTools;
+    if (allowedTools !== undefined && !Array.isArray(allowedTools) && typeof allowedTools !== 'string') {
+        warn('SKILL_ALLOWED_TOOLS_INVALID', 'allowed-tools must be a list of tool names');
+    }
+    else if (Array.isArray(allowedTools) && allowedTools.length > SKILL_ALLOWED_TOOLS_MAX) {
+        warn('SKILL_ALLOWED_TOOLS_INVALID', `allowed-tools has more than ${SKILL_ALLOWED_TOOLS_MAX} entries`);
+    }
+    return issues;
+}
+/** Build the normalized frontmatter view, applying every documented default. */
+export function normalizeFrontmatter(data, fallbackName) {
+    const activationRaw = asString(data.activation)?.trim();
+    const activation = ACTIVATIONS.includes(activationRaw ?? '')
+        ? activationRaw
+        : 'auto';
+    const versionRaw = asString(data.version)?.trim();
+    const version = versionRaw && SEMVER.test(versionRaw) ? versionRaw : '0.0.0';
+    const keywords = (asArray(data.keywords) ?? [])
+        .slice(0, SKILL_KEYWORDS_MAX)
+        .map((k) => k.slice(0, SKILL_KEYWORD_LEN_MAX));
+    const allowedTools = (asArray(data['allowed-tools'] ?? data.allowedTools) ?? []).slice(0, SKILL_ALLOWED_TOOLS_MAX);
+    const meta = (key) => {
+        const v = asString(data[key])?.trim();
+        return v && v.length > 0 ? v.slice(0, SKILL_META_MAX) : undefined;
+    };
+    return {
+        name: asString(data.name)?.trim() || fallbackName,
+        description: asString(data.description)?.trim() ?? '',
+        version,
+        ...(meta('license') ? { license: meta('license') } : {}),
+        ...(meta('author') ? { author: meta('author') } : {}),
+        ...(meta('homepage') ? { homepage: meta('homepage') } : {}),
+        keywords,
+        allowedTools,
+        activation,
+        raw: data,
+    };
+}
+// ---------------------------------------------------------------------------
+// Staged install validation (§8.3 step 2)
+// ---------------------------------------------------------------------------
+/**
+ * Reject a relative path that could escape the staging root or is unusable on
+ * Windows. This is the SECOND line of defence — the archive extractor applies
+ * the same rules while writing (§9.2.1). Both are required: the extractor
+ * guards what lands on disk, this guards what we then promote into the skills
+ * root (a plain local-directory source never goes through the extractor).
+ */
+export function checkStagedPath(path) {
+    const normalized = path.replace(/\\/g, '/');
+    if (normalized.length === 0) {
+        return { level: 'error', code: 'SKILL_PATH_EMPTY', message: 'empty entry path' };
+    }
+    if (/^[A-Za-z]:/.test(normalized) || normalized.startsWith('/')) {
+        return {
+            level: 'error',
+            code: 'SKILL_PATH_ABSOLUTE',
+            message: `absolute path not allowed: ${path}`,
+        };
+    }
+    const segments = normalized.split('/').filter((s) => s.length > 0);
+    if (segments.some((s) => s === '..')) {
+        return {
+            level: 'error',
+            code: 'SKILL_PATH_TRAVERSAL',
+            message: `path escapes the skill directory: ${path}`,
+        };
+    }
+    if (hasControlChar(normalized)) {
+        return {
+            level: 'error',
+            code: 'SKILL_PATH_CONTROL_CHARS',
+            message: `control characters in path: ${JSON.stringify(path)}`,
+        };
+    }
+    for (const segment of segments) {
+        const base = (segment.split('.')[0] ?? '').toLowerCase();
+        if (WINDOWS_RESERVED_NAMES.has(base)) {
+            return {
+                level: 'error',
+                code: 'SKILL_PATH_RESERVED_NAME',
+                message: `Windows reserved name in path: ${path}`,
+            };
+        }
+    }
+    if (segments.length > STAGED_MAX_DEPTH) {
+        return {
+            level: 'error',
+            code: 'SKILL_PATH_TOO_DEEP',
+            message: `path nests deeper than ${STAGED_MAX_DEPTH} levels: ${path}`,
+        };
+    }
+    return null;
+}
+/**
+ * Validate a staged skill before it is promoted into a skills root.
+ *
+ * `entryText` is the raw SKILL.md; `files` is the full staged file table
+ * (SKILL.md included). Returns `ok: false` if ANY error-level issue is found —
+ * the installer must then abort and leave the target untouched.
+ */
+export function validateStagedSkill(entryText, files, dirName, parse) {
+    const issues = [];
+    let totalBytes = 0;
+    if (entryText === null) {
+        issues.push({
+            level: 'error',
+            code: 'SKILL_MD_MISSING',
+            message: 'SKILL.md not found in the source',
+        });
+    }
+    if (files.length > STAGED_MAX_FILES) {
+        issues.push({
+            level: 'error',
+            code: 'SKILL_TOO_MANY_FILES',
+            message: `${files.length} files exceeds the limit of ${STAGED_MAX_FILES}`,
+        });
+    }
+    for (const file of files) {
+        if (file.isSymlink) {
+            issues.push({
+                level: 'error',
+                code: 'SKILL_SYMLINK_REJECTED',
+                message: `symbolic links are not allowed: ${file.path}`,
+            });
+            continue;
+        }
+        const pathIssue = checkStagedPath(file.path);
+        if (pathIssue) {
+            issues.push(pathIssue);
+            continue;
+        }
+        if (file.bytes > STAGED_MAX_FILE_BYTES) {
+            issues.push({
+                level: 'error',
+                code: 'SKILL_FILE_TOO_LARGE',
+                message: `${file.path} is ${file.bytes} bytes (max ${STAGED_MAX_FILE_BYTES})`,
+            });
+        }
+        totalBytes += file.bytes;
+    }
+    if (totalBytes > STAGED_MAX_TOTAL_BYTES) {
+        issues.push({
+            level: 'error',
+            code: 'SKILL_TOTAL_TOO_LARGE',
+            message: `total size ${totalBytes} bytes exceeds ${STAGED_MAX_TOTAL_BYTES}`,
+        });
+    }
+    let frontmatter = null;
+    if (entryText !== null) {
+        const parsed = parse(entryText);
+        if (!parsed) {
+            issues.push({
+                level: 'error',
+                code: 'SKILL_FRONTMATTER_MISSING',
+                message: 'SKILL.md has no parseable YAML frontmatter block',
+            });
+        }
+        else {
+            issues.push(...validateSkillFrontmatter(parsed.data, dirName));
+            frontmatter = normalizeFrontmatter(parsed.data, dirName);
+        }
+    }
+    return {
+        ok: !issues.some((i) => i.level === 'error'),
+        issues,
+        frontmatter,
+        fileCount: files.length,
+        totalBytes,
+    };
+}

package/dist/tools/executor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool System — Tool Executor
+ *
+ * Orchestrates the full lifecycle of a tool invocation:
+ *   1. Tool lookup from registry
+ *   2. Parameter validation against JSON Schema
+ *   3. Timeout wrapping via AbortController
+ *   4. Execution with merged AbortSignal
+ *   5. Output truncation
+ *   6. Error capture into ToolResult
+ */
+import type { ToolRegistry } from './registry.js';
+import type { ToolExecutionResult, ToolProgressUpdate } from './types.js';
+/** Options for configuring the ToolExecutor. */
+export interface ToolExecutorOptions {
+    /** Default per-tool execution timeout in milliseconds. Defaults to 120_000 (2 minutes). */
+    defaultTimeout?: number;
+    /** Per-tool timeout overrides, keyed by tool name. */
+    timeoutOverrides?: Record<string, number>;
+    /** Maximum size (in bytes) of combined text output before truncation. Defaults to 100_000 (100 KB). */
+    maxOutputSize?: number;
+}
+/**
+ * Executes tool calls with validation, timeout management,
+ * output truncation, and comprehensive error handling.
+ */
+export declare class ToolExecutor {
+    private readonly registry;
+    private readonly validator;
+    private readonly defaultTimeout;
+    private readonly timeoutOverrides;
+    private readonly maxOutputSize;
+    constructor(registry: ToolRegistry, options?: ToolExecutorOptions);
+    /**
+     * Execute a tool call end-to-end.
+     *
+     * Never throws — all errors are captured as error ToolResults.
+     *
+     * @param toolCallId - The LLM-generated tool call ID.
+     * @param toolName   - Name of the tool to execute.
+     * @param rawArgs    - Raw parameter object from the LLM.
+     * @param signal     - Optional external AbortSignal for cancellation.
+     * @param onProgress - Optional progress callback forwarded to the tool.
+     */
+    execute(toolCallId: string, toolName: string, rawArgs: Record<string, unknown>, signal?: AbortSignal, onProgress?: (update: ToolProgressUpdate) => void): Promise<ToolExecutionResult>;
+    /**
+     * Truncate text content blocks that exceed `maxOutputSize` bytes.
+     */
+    private truncateResult;
+    /**
+     * Build a ToolExecutionResult with computed duration and error flag.
+     */
+    private buildResult;
+}

package/dist/tools/executor.js

@@ -0,0 +1,206 @@
+/**
+ * Tool System — Tool Executor
+ *
+ * Orchestrates the full lifecycle of a tool invocation:
+ *   1. Tool lookup from registry
+ *   2. Parameter validation against JSON Schema
+ *   3. Timeout wrapping via AbortController
+ *   4. Execution with merged AbortSignal
+ *   5. Output truncation
+ *   6. Error capture into ToolResult
+ */
+import { ToolParamValidator, ToolValidationError } from './validator.js';
+import { errorResult } from './helpers.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_OUTPUT_SIZE = 100_000;
+const TRUNCATION_SUFFIX = '\n... [truncated]';
+/** Sentinel symbol used to identify timeout aborts vs external aborts. */
+const TIMEOUT_REASON = Symbol('tool-timeout');
+// ---------------------------------------------------------------------------
+// ToolExecutor
+// ---------------------------------------------------------------------------
+/**
+ * Executes tool calls with validation, timeout management,
+ * output truncation, and comprehensive error handling.
+ */
+export class ToolExecutor {
+    registry;
+    validator = new ToolParamValidator();
+    defaultTimeout;
+    timeoutOverrides;
+    maxOutputSize;
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        this.defaultTimeout = options.defaultTimeout ?? DEFAULT_TIMEOUT_MS;
+        this.timeoutOverrides = options.timeoutOverrides ?? {};
+        this.maxOutputSize = options.maxOutputSize ?? DEFAULT_MAX_OUTPUT_SIZE;
+    }
+    /**
+     * Execute a tool call end-to-end.
+     *
+     * Never throws — all errors are captured as error ToolResults.
+     *
+     * @param toolCallId - The LLM-generated tool call ID.
+     * @param toolName   - Name of the tool to execute.
+     * @param rawArgs    - Raw parameter object from the LLM.
+     * @param signal     - Optional external AbortSignal for cancellation.
+     * @param onProgress - Optional progress callback forwarded to the tool.
+     */
+    async execute(toolCallId, toolName, rawArgs, signal, onProgress) {
+        const startTime = Date.now();
+        // 1. Look up tool in registry.
+        const tool = this.registry.get(toolName);
+        if (!tool) {
+            return this.buildResult(toolCallId, toolName, errorResult(`Tool "${toolName}" not found`), startTime);
+        }
+        // 2. Detect malformed JSON from the LLM provider (streaming truncation).
+        if (rawArgs.__parse_error) {
+            return this.buildResult(toolCallId, toolName, errorResult('Tool call failed: the LLM returned incomplete JSON for the parameters ' +
+                '(likely hit the max_tokens limit mid-generation). ' +
+                'Please retry by writing the content in smaller pieces or reducing output size.'), startTime);
+        }
+        // 3. Validate parameters.
+        let validatedParams;
+        try {
+            validatedParams = await this.validator.validate(tool.parameters, rawArgs);
+        }
+        catch (err) {
+            if (err instanceof ToolValidationError) {
+                return this.buildResult(toolCallId, toolName, errorResult(`Invalid parameters: ${err.message}`), startTime);
+            }
+            return this.buildResult(toolCallId, toolName, errorResult(`Parameter validation error: ${err instanceof Error ? err.message : String(err)}`), startTime);
+        }
+        // 4. Set up timeout and merged abort signal.
+        const timeoutMs = this.timeoutOverrides[toolName] ?? this.defaultTimeout;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(TIMEOUT_REASON), timeoutMs);
+        // Propagate external signal to our controller.
+        const externalAbortHandler = () => {
+            controller.abort(signal?.reason ?? new Error('aborted'));
+        };
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(timeoutId);
+                return this.buildResult(toolCallId, toolName, errorResult('Execution aborted before start'), startTime);
+            }
+            signal.addEventListener('abort', externalAbortHandler, { once: true });
+        }
+        // 5. Execute the tool.
+        let result;
+        try {
+            const context = {
+                signal: controller.signal,
+                onProgress,
+            };
+            result = await tool.execute(toolCallId, validatedParams, context);
+        }
+        catch (err) {
+            if (isAbortError(err) || controller.signal.aborted) {
+                const isTimeout = controller.signal.reason === TIMEOUT_REASON;
+                result = errorResult(isTimeout
+                    ? `Tool "${toolName}" timed out after ${timeoutMs}ms`
+                    : `Tool "${toolName}" was aborted`);
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                result = errorResult(`Tool "${toolName}" threw an error: ${message}`);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+            if (signal) {
+                signal.removeEventListener('abort', externalAbortHandler);
+            }
+        }
+        // 6. Truncate output if necessary.
+        result = this.truncateResult(result);
+        return this.buildResult(toolCallId, toolName, result, startTime);
+    }
+    // -----------------------------------------------------------------------
+    // Internal Helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Truncate text content blocks that exceed `maxOutputSize` bytes.
+     */
+    truncateResult(result) {
+        let totalSize = 0;
+        for (const block of result.content) {
+            if (block.type === 'text') {
+                totalSize += Buffer.byteLength(block.text, 'utf-8');
+            }
+        }
+        if (totalSize <= this.maxOutputSize) {
+            return result;
+        }
+        // Rebuild content with truncated text blocks.
+        let remainingBudget = this.maxOutputSize;
+        const truncatedContent = result.content.map((block) => {
+            if (block.type !== 'text')
+                return block;
+            const blockSize = Buffer.byteLength(block.text, 'utf-8');
+            if (blockSize <= remainingBudget) {
+                remainingBudget -= blockSize;
+                return block;
+            }
+            // Truncate this block.
+            if (remainingBudget <= 0) {
+                return { type: 'text', text: TRUNCATION_SUFFIX };
+            }
+            // Find a safe character boundary to cut at.
+            const truncated = truncateUtf8(block.text, remainingBudget);
+            remainingBudget = 0;
+            return { type: 'text', text: truncated + TRUNCATION_SUFFIX };
+        });
+        return {
+            content: truncatedContent,
+            isError: result.isError,
+        };
+    }
+    /**
+     * Build a ToolExecutionResult with computed duration and error flag.
+     */
+    buildResult(toolCallId, toolName, result, startTime) {
+        return {
+            result,
+            duration: Date.now() - startTime,
+            isError: result.isError === true,
+            toolName,
+            toolCallId,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Utility Functions
+// ---------------------------------------------------------------------------
+/**
+ * Check whether an error is an AbortError (from AbortController.abort()).
+ */
+function isAbortError(err) {
+    if (err instanceof DOMException && err.name === 'AbortError')
+        return true;
+    if (err instanceof Error && err.name === 'AbortError')
+        return true;
+    return false;
+}
+/**
+ * Truncate a UTF-8 string to fit within `maxBytes`, respecting
+ * character boundaries.
+ */
+function truncateUtf8(text, maxBytes) {
+    const buf = Buffer.from(text, 'utf-8');
+    if (buf.length <= maxBytes)
+        return text;
+    // Slice the buffer and decode — Node handles incomplete multibyte
+    // sequences by replacing them, which is acceptable here.
+    const sliced = buf.subarray(0, maxBytes);
+    // Decode, stripping any replacement character at the end.
+    let result = sliced.toString('utf-8');
+    // Remove trailing replacement character if the slice broke a multibyte char.
+    if (result.endsWith('\uFFFD')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}

package/dist/tools/helpers.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Tool System — Convenience Helpers
+ *
+ * Provides factory functions for creating ToolResult values and
+ * a builder function for defining tools with less boilerplate.
+ */
+import type { AgentTool, JSONSchema7, ToolExecuteFn, ToolResult, ToolResultContent } from './types.js';
+/**
+ * Create a successful text result.
+ *
+ * @param text - The text content to return.
+ */
+export declare function textResult(text: string): ToolResult;
+/**
+ * Create an error result.
+ * Sets `isError: true` and prepends "Error: " to the message.
+ *
+ * @param message - Human-readable error description.
+ */
+export declare function errorResult(message: string): ToolResult;
+/**
+ * Create a result containing a base64-encoded image.
+ *
+ * @param mediaType - MIME type (e.g. 'image/png', 'image/jpeg').
+ * @param data      - Base64-encoded image data.
+ */
+export declare function imageResult(mediaType: string, data: string): ToolResult;
+/**
+ * Create a result with multiple content blocks.
+ *
+ * @param blocks  - Array of content blocks.
+ * @param isError - Whether this result represents an error.
+ */
+export declare function multiResult(blocks: ToolResultContent[], isError?: boolean): ToolResult;
+/**
+ * Configuration for `defineTool()` — all fields that make up an AgentTool.
+ */
+export interface DefineToolConfig<TParams = Record<string, unknown>> {
+    name: string;
+    label: string;
+    description: string;
+    parameters: JSONSchema7;
+    execute: ToolExecuteFn<TParams>;
+    tags?: string[];
+    bridgeable?: boolean;
+    bridgeName?: string;
+}
+/**
+ * Convenience builder that creates a fully-typed AgentTool from a
+ * plain configuration object.
+ *
+ * Usage:
+ * ```ts
+ * const myTool = defineTool({
+ *   name: 'greet',
+ *   label: 'Greeter',
+ *   description: 'Greets the user.',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { name: { type: 'string' } },
+ *     required: ['name'],
+ *   },
+ *   async execute(_id, params, _ctx) {
+ *     return textResult(`Hello, ${params.name}!`);
+ *   },
+ * });
+ * ```
+ */
+export declare function defineTool<TParams = Record<string, unknown>>(config: DefineToolConfig<TParams>): AgentTool<TParams>;

package/dist/tools/helpers.js

@@ -0,0 +1,87 @@
+/**
+ * Tool System — Convenience Helpers
+ *
+ * Provides factory functions for creating ToolResult values and
+ * a builder function for defining tools with less boilerplate.
+ */
+// ---------------------------------------------------------------------------
+// Result Factories
+// ---------------------------------------------------------------------------
+/**
+ * Create a successful text result.
+ *
+ * @param text - The text content to return.
+ */
+export function textResult(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Create an error result.
+ * Sets `isError: true` and prepends "Error: " to the message.
+ *
+ * @param message - Human-readable error description.
+ */
+export function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+/**
+ * Create a result containing a base64-encoded image.
+ *
+ * @param mediaType - MIME type (e.g. 'image/png', 'image/jpeg').
+ * @param data      - Base64-encoded image data.
+ */
+export function imageResult(mediaType, data) {
+    return {
+        content: [{ type: 'image', mediaType, data }],
+    };
+}
+/**
+ * Create a result with multiple content blocks.
+ *
+ * @param blocks  - Array of content blocks.
+ * @param isError - Whether this result represents an error.
+ */
+export function multiResult(blocks, isError) {
+    return {
+        content: blocks,
+        ...(isError ? { isError } : {}),
+    };
+}
+/**
+ * Convenience builder that creates a fully-typed AgentTool from a
+ * plain configuration object.
+ *
+ * Usage:
+ * ```ts
+ * const myTool = defineTool({
+ *   name: 'greet',
+ *   label: 'Greeter',
+ *   description: 'Greets the user.',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { name: { type: 'string' } },
+ *     required: ['name'],
+ *   },
+ *   async execute(_id, params, _ctx) {
+ *     return textResult(`Hello, ${params.name}!`);
+ *   },
+ * });
+ * ```
+ */
+export function defineTool(config) {
+    return {
+        name: config.name,
+        label: config.label,
+        description: config.description,
+        parameters: config.parameters,
+        execute: config.execute,
+        ...(config.tags ? { tags: config.tags } : {}),
+        ...(config.bridgeable !== undefined ? { bridgeable: config.bridgeable } : {}),
+        ...(config.bridgeName ? { bridgeName: config.bridgeName } : {}),
+    };
+}