@nuvin/nuvin-core 1.5.1 → 1.6.0

package/dist/index.d.ts

@@ -54,12 +54,14 @@ type SpecialistAgentResult = {
     result: string;
     metadata: {
         agentId: string;
+        agentName: string;
         tokensUsed?: number;
         toolCallsExecuted: number;
         executionTimeMs: number;
         conversationHistory?: Message[];
         events?: AgentEvent[];
         errorMessage?: string;
+        metrics?: MetricsSnapshot;
     };
 };
 /**
@@ -193,6 +195,220 @@ declare class AgentRegistry {
     exists(agentId: string): boolean;
 }
 
+/**
+ * Type definitions for tool call arguments/parameters
+ * These types represent the parameters passed to each tool
+ *
+ * These are useful for:
+ * - Type-safe tool call argument parsing
+ * - UI rendering of tool calls with proper parameter display
+ * - Validation of tool inputs
+ */
+type BashToolArgs = {
+    cmd: string;
+    cwd?: string;
+    timeoutMs?: number;
+    description?: string;
+};
+type FileReadArgs = {
+    path: string;
+    lineStart?: number;
+    lineEnd?: number;
+    description?: string;
+};
+type FileEditArgs = {
+    file_path: string;
+    old_text: string;
+    new_text: string;
+    dry_run?: boolean;
+    description?: string;
+};
+type FileNewArgs = {
+    file_path: string;
+    content: string;
+    description?: string;
+};
+type DirLsArgs = {
+    path?: string;
+    limit?: number;
+    description?: string;
+};
+type WebSearchArgs = {
+    query: string;
+    count?: number;
+    offset?: number;
+    domains?: string[];
+    recencyDays?: number;
+    lang?: string;
+    region?: string;
+    safe?: boolean;
+    type?: 'web' | 'images';
+    hydrateMeta?: boolean;
+    description?: string;
+};
+type WebFetchArgs = {
+    url: string;
+    description?: string;
+};
+type TodoWriteArgs = {
+    todos: Array<{
+        id: string;
+        content: string;
+        status: 'pending' | 'in_progress' | 'completed';
+        priority: 'high' | 'medium' | 'low';
+        createdAt?: string;
+    }>;
+    description?: string;
+};
+type AssignTaskArgs = {
+    agent: string;
+    task: string;
+    description: string;
+};
+type ToolArguments = BashToolArgs | FileReadArgs | FileEditArgs | FileNewArgs | DirLsArgs | WebSearchArgs | WebFetchArgs | TodoWriteArgs | AssignTaskArgs;
+/**
+ * Type guard to safely parse tool arguments
+ */
+declare function parseToolArguments(args: string | unknown): ToolArguments;
+/**
+ * Type guards for specific tool arguments
+ */
+declare function isBashToolArgs(args: ToolArguments): args is BashToolArgs;
+declare function isFileReadArgs(args: ToolArguments): args is FileReadArgs;
+declare function isFileEditArgs(args: ToolArguments): args is FileEditArgs;
+declare function isFileNewArgs(args: ToolArguments): args is FileNewArgs;
+declare function isTodoWriteArgs(args: ToolArguments): args is TodoWriteArgs;
+declare function isAssignTaskArgs(args: ToolArguments): args is AssignTaskArgs;
+declare function isWebSearchArgs(args: ToolArguments): args is WebSearchArgs;
+declare function isWebFetchArgs(args: ToolArguments): args is WebFetchArgs;
+declare function isDirLsArgs(args: ToolArguments): args is DirLsArgs;
+type ToolParameterMap = {
+    bash_tool: BashToolArgs;
+    file_read: FileReadArgs;
+    file_edit: FileEditArgs;
+    file_new: FileNewArgs;
+    dir_ls: DirLsArgs;
+    web_search: WebSearchArgs;
+    web_fetch: WebFetchArgs;
+    todo_write: TodoWriteArgs;
+    assign_task: AssignTaskArgs;
+};
+type ToolName = keyof ToolParameterMap;
+type TypedToolInvocation<T extends ToolName = ToolName> = {
+    id: string;
+    name: T;
+    parameters: ToolParameterMap[T];
+};
+
+type FileMetadata = {
+    path: string;
+    created?: string;
+    modified?: string;
+    size?: number;
+};
+type LineRangeMetadata = {
+    lineStart: number;
+    lineEnd: number;
+    linesTotal?: number;
+};
+type CommandMetadata = {
+    cwd?: string;
+    code?: number | null;
+    signal?: string | null;
+    timedOut?: boolean;
+};
+type ErrorMetadata = {
+    errorReason?: ErrorReason;
+    code?: string | number;
+    stackTrace?: string;
+    retryable?: boolean;
+};
+type DelegationMetadata = {
+    agentId: string;
+    agentName: string;
+    delegationDepth: number;
+    status: 'success' | 'error' | 'timeout';
+    executionTimeMs: number;
+    toolCallsExecuted: number;
+    tokensUsed?: number;
+    metrics?: MetricsSnapshot;
+    taskDescription: string;
+    provider?: string;
+    model?: string;
+    conversationHistoryLength?: number;
+    eventsEmitted?: number;
+};
+
+type BashToolMetadata = CommandMetadata & {
+    stdout?: string;
+    stderr?: string;
+    stripped?: boolean;
+};
+type FileReadMetadata = FileMetadata & {
+    lineRange?: LineRangeMetadata;
+    encoding?: string;
+    bomStripped?: boolean;
+};
+type FileEditMetadata = FileMetadata & {
+    changesMade?: {
+        linesAdded: number;
+        linesRemoved: number;
+        bytesChanged: number;
+    };
+    backup?: {
+        path: string;
+        created: string;
+    };
+};
+type FileNewMetadata = FileMetadata & {
+    overwritten?: boolean;
+};
+type DirLsMetadata = {
+    path: string;
+    totalEntries?: number;
+    entriesReturned?: number;
+    truncated?: boolean;
+};
+type WebSearchMetadata = {
+    query: string;
+    totalResults?: number;
+    resultsReturned: number;
+    searchTime?: number;
+    provider?: string;
+};
+type WebFetchMetadata = {
+    url: string;
+    statusCode?: number;
+    contentType?: string;
+    contentLength?: number;
+    fetchTime?: number;
+    markdown?: boolean;
+};
+type TodoWriteMetadata = {
+    todosWritten: number;
+    conversationId?: string;
+};
+type AssignTaskMetadata = DelegationMetadata;
+type ToolErrorMetadata = {
+    errorReason?: ErrorReason;
+    path?: string;
+    agentId?: string;
+    code?: string | number;
+    stackTrace?: string;
+    retryable?: boolean;
+};
+type ToolMetadataMap = {
+    bash_tool: BashToolMetadata;
+    file_read: FileReadMetadata;
+    file_edit: FileEditMetadata;
+    file_new: FileNewMetadata;
+    dir_ls: DirLsMetadata;
+    web_search: WebSearchMetadata;
+    web_fetch: WebFetchMetadata;
+    todo_write: TodoWriteMetadata;
+    assign_task: AssignTaskMetadata;
+};
+
 type ToolCall = {
     id: string;
     type: 'function';
@@ -366,6 +582,42 @@ type ToolDefinition = {
     };
 };
 type ToolInvocation = {
+    id: string;
+    name: 'bash_tool';
+    parameters: BashToolArgs;
+} | {
+    id: string;
+    name: 'file_read';
+    parameters: FileReadArgs;
+} | {
+    id: string;
+    name: 'file_edit';
+    parameters: FileEditArgs;
+} | {
+    id: string;
+    name: 'file_new';
+    parameters: FileNewArgs;
+} | {
+    id: string;
+    name: 'dir_ls';
+    parameters: DirLsArgs;
+} | {
+    id: string;
+    name: 'web_search';
+    parameters: WebSearchArgs;
+} | {
+    id: string;
+    name: 'web_fetch';
+    parameters: WebFetchArgs;
+} | {
+    id: string;
+    name: 'todo_write';
+    parameters: TodoWriteArgs;
+} | {
+    id: string;
+    name: 'assign_task';
+    parameters: AssignTaskArgs;
+} | {
     id: string;
     name: string;
     parameters: Record<string, unknown>;
@@ -383,14 +635,92 @@ declare enum ErrorReason {
     Unknown = "unknown"
 }
 type ToolExecutionResult = {
+    id: string;
+    name: 'bash_tool';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: BashToolMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'file_read';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: FileReadMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'file_edit';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: FileEditMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'file_new';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: FileNewMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'dir_ls';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: DirLsMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'web_search';
+    status: 'success';
+    type: 'json';
+    result: Record<string, unknown> | unknown[];
+    metadata?: WebSearchMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'web_fetch';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: WebFetchMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'todo_write';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: TodoWriteMetadata;
+    durationMs?: number;
+} | {
+    id: string;
+    name: 'assign_task';
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata: AssignTaskMetadata;
+    durationMs?: number;
+} | {
     id: string;
     name: string;
-    status: 'success' | 'error';
+    status: 'success';
     type: 'text' | 'json';
-    result: string | object;
-    metadata?: Record<string, unknown> & {
-        errorReason?: ErrorReason;
-    };
+    result: string | Record<string, unknown> | unknown[];
+    metadata?: Record<string, unknown>;
+    durationMs?: number;
+} | {
+    id: string;
+    name: string;
+    status: 'error';
+    type: 'text';
+    result: string;
+    metadata?: ToolErrorMetadata;
     durationMs?: number;
 };
 interface ToolPort {
@@ -484,6 +814,7 @@ type AgentConfig = {
     maxToolConcurrency?: number;
     requireToolApproval?: boolean;
     reasoningEffort?: string;
+    strictToolValidation?: boolean;
 };
 declare const MessageRoles: {
     readonly System: "system";
@@ -507,6 +838,7 @@ declare const AgentEventTypes: {
     readonly SubAgentToolCall: "sub_agent_tool_call";
     readonly SubAgentToolResult: "sub_agent_tool_result";
     readonly SubAgentCompleted: "sub_agent_completed";
+    readonly SubAgentMetrics: "sub_agent_metrics";
 };
 type ToolApprovalDecision = 'approve' | 'deny' | 'approve_all';
 type AgentEvent = {
@@ -609,6 +941,13 @@ type AgentEvent = {
     status: 'success' | 'error' | 'timeout';
     resultMessage: string;
     totalDurationMs: number;
+} | {
+    type: typeof AgentEventTypes.SubAgentMetrics;
+    conversationId: string;
+    messageId: string;
+    agentId: string;
+    toolCallId: string;
+    metrics: MetricsSnapshot;
 };
 interface EventPort {
     emit(event: AgentEvent): void | Promise<void>;
@@ -932,7 +1271,26 @@ type TodoItem = {
     updatedAt?: string;
 };
 
-type ExecResult = Omit<ToolExecutionResult, 'id' | 'name'>;
+type ExecResultSuccess = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: Record<string, unknown>;
+} | {
+    status: 'success';
+    type: 'json';
+    result: Record<string, unknown> | unknown[];
+    metadata?: Record<string, unknown>;
+};
+type ExecResultError = {
+    status: 'error';
+    type: 'text';
+    result: string;
+    metadata?: Record<string, unknown> & {
+        errorReason?: ErrorReason;
+    };
+};
+type ExecResult = ExecResultSuccess | ExecResultError;
 type ToolExecutionContext = {
     conversationId?: string;
     agentId?: string;
@@ -943,11 +1301,11 @@ type ToolExecutionContext = {
     eventPort?: EventPort;
     signal?: AbortSignal;
 } & Record<string, unknown>;
-interface FunctionTool<P = Record<string, unknown>, C = ToolExecutionContext> {
+interface FunctionTool<P = Record<string, unknown>, C = ToolExecutionContext, R extends ExecResult = ExecResult> {
     name: string;
     parameters: object;
     definition(): ToolDefinition['function'];
-    execute(params: P, context?: C): Promise<ExecResult> | ExecResult;
+    execute(params: P, context?: C): Promise<R> | R;
 }
 
 interface AgentCatalog {
@@ -1093,10 +1451,12 @@ declare class DefaultDelegationResultFormatter implements DelegationResultFormat
         summary: string;
         metadata: {
             agentId: string;
+            agentName: string;
             status: "success" | "error" | "timeout";
             executionTimeMs: number;
             toolCallsExecuted: number;
             tokensUsed: number | undefined;
+            metrics: MetricsSnapshot | undefined;
         };
     };
     formatError(error: unknown): string;
@@ -1167,7 +1527,23 @@ type BashParams = {
     cwd?: string;
     timeoutMs?: number;
 };
-declare class BashTool implements FunctionTool<BashParams, ToolExecutionContext> {
+type BashSuccessResult$1 = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: CommandMetadata & {
+        stdout?: string;
+        stderr?: string;
+        stripped?: boolean;
+    };
+};
+type BashErrorResult = ExecResultError & {
+    metadata?: CommandMetadata & {
+        errorReason?: ErrorReason;
+    };
+};
+type BashResult = BashSuccessResult$1 | BashErrorResult;
+declare class BashTool implements FunctionTool<BashParams, ToolExecutionContext, BashResult> {
     name: "bash_tool";
     parameters: {
         readonly type: "object";
@@ -1193,13 +1569,378 @@ declare class BashTool implements FunctionTool<BashParams, ToolExecutionContext>
         readonly required: readonly ["cmd"];
     };
     definition(): ToolDefinition['function'];
-    execute(p: BashParams, ctx?: ToolExecutionContext): Promise<ExecResult>;
+    /**
+     * Execute bash command with timeout protection
+     *
+     * @param p - Command parameters including cmd, cwd, and optional timeout
+     * @param ctx - Execution context with optional abort signal
+     * @returns Structured result with command output and execution metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await bashTool.execute({ cmd: 'ls -la' });
+     * if (result.status === 'success' && result.type === 'text') {
+     *   console.log(result.result); // command output
+     *   console.log(result.metadata?.code); // exit code
+     *   console.log(result.metadata?.cwd); // working directory
+     * }
+     * ```
+     */
+    execute(p: BashParams, ctx?: ToolExecutionContext): Promise<BashResult>;
     private execOnce;
     private defaultShell;
     private shellExists;
     private shellArgs;
 }
 
+type ParseResult<T = unknown> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+declare function parseJSON(jsonString: string): ParseResult<Record<string, unknown>>;
+
+type ValidationResult<T = unknown> = {
+    valid: true;
+    data: T;
+} | {
+    valid: false;
+    errors: string[];
+};
+type ToolValidator<T extends ToolName> = (params: Record<string, unknown>) => ValidationResult<ToolParameterMap[T]>;
+declare const toolValidators: Partial<{
+    [K in ToolName]: ToolValidator<K>;
+}>;
+
+type ToolCallValidation = {
+    valid: true;
+    invocation: ToolInvocation;
+} | {
+    valid: false;
+    error: string;
+    errorType: 'parse' | 'validation' | 'unknown';
+    callId: string;
+    toolName: string;
+    rawArguments?: string;
+};
+declare function convertToolCall(toolCall: ToolCall, options?: {
+    strict?: boolean;
+}): ToolCallValidation;
+declare function convertToolCalls(toolCalls: ToolCall[], options?: {
+    strict?: boolean;
+    throwOnError?: boolean;
+}): ToolInvocation[];
+
+type FileReadParams = {
+    path: string;
+    lineStart?: number;
+    lineEnd?: number;
+};
+type FileReadSuccessResult$1 = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata?: FileMetadata & {
+        lineRange?: LineRangeMetadata;
+        encoding?: string;
+        bomStripped?: boolean;
+    };
+};
+type FileReadErrorResult = ExecResultError & {
+    metadata?: {
+        path?: string;
+        errorReason?: ErrorReason;
+    };
+};
+type FileReadResult = FileReadSuccessResult$1 | FileReadErrorResult;
+
+type FileEditSuccessResult$1 = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata: FileMetadata & {
+        eol: 'lf' | 'crlf';
+        oldTextLength: number;
+        newTextLength: number;
+        bytesWritten: number;
+        beforeSha: string;
+        afterSha: string;
+        dryRun: boolean;
+        lineNumbers: {
+            oldStartLine: number;
+            oldEndLine: number;
+            newStartLine: number;
+            newEndLine: number;
+            oldLineCount: number;
+            newLineCount: number;
+        };
+        noChange?: boolean;
+    };
+};
+type FileEditResult = FileEditSuccessResult$1 | ExecResultError;
+
+type FileNewParams = {
+    file_path: string;
+    content: string;
+};
+type FileNewSuccessResult$1 = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata: {
+        file_path: string;
+        bytes: number;
+        created: string;
+        overwritten?: boolean;
+    };
+};
+type FileNewResult = FileNewSuccessResult$1 | ExecResultError;
+
+type DirLsParams = {
+    path?: string;
+    limit?: number;
+};
+type DirEntry = {
+    name: string;
+    type: 'file' | 'directory' | 'symlink' | 'other';
+    size?: number;
+    mtime?: number;
+    mode?: number;
+    lineCount?: number;
+};
+type DirLsSuccessResult$1 = {
+    status: 'success';
+    type: 'json';
+    result: {
+        path: string;
+        entries: DirEntry[];
+        truncated: boolean;
+        total: number;
+    };
+    metadata?: {
+        limit: number;
+        includeHidden: boolean;
+    };
+};
+type DirLsResult = DirLsSuccessResult$1 | ExecResultError;
+
+/**
+ * WebSearchTool — Google Programmable Search Engine (CSE) ONLY
+ * -----------------------------------------------------------------
+ * - Requires env: GOOGLE_CSE_KEY, GOOGLE_CSE_CX
+ * - Supports: count (1..50, paginated 10/req), offset (0-based), domains[] -> site:
+ *             recencyDays -> dateRestrict, lang (hl/lr), region (gl), safe, type: web|images
+ * - No HTML scraping fallback. If keys are missing, returns an error.
+ */
+interface WebSearchParams {
+    query: string;
+    count?: number;
+    offset?: number;
+    domains?: string[];
+    recencyDays?: number;
+    lang?: string;
+    region?: string;
+    safe?: boolean;
+    type?: 'web' | 'images';
+    hydrateMeta?: boolean;
+}
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet?: string;
+    displayUrl?: string;
+    favicon?: string;
+    publishedAt?: string;
+    source: {
+        engine: 'google-cse';
+        rank: number;
+    };
+}
+type WebSearchSuccessResult$1 = {
+    status: 'success';
+    type: 'json';
+    result: {
+        engine: 'google-cse';
+        count: number;
+        items: WebSearchResult[];
+        query: string;
+        appliedFilters?: {
+            domains?: string[];
+            recencyDays?: number;
+            lang?: string;
+            region?: string;
+        };
+    };
+    metadata?: {
+        offset: number;
+        totalRequested: number;
+        hydrated: boolean;
+    };
+};
+type WebSearchToolResult = WebSearchSuccessResult$1 | ExecResultError;
+
+type WebFetchParams = {
+    url: string;
+};
+type WebFetchSuccessResult$1 = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata: {
+        url: string;
+        contentType: string;
+        statusCode: number;
+        format: 'markdown' | 'json' | 'text';
+        size: number;
+        fetchedAt: string;
+    };
+};
+type WebFetchResult = WebFetchSuccessResult$1 | ExecResultError;
+
+type TodoWriteSuccessResult$1 = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata: {
+        recentChanges: boolean;
+        stats: {
+            total: number;
+            pending: number;
+            inProgress: number;
+            completed: number;
+        };
+        progress: string;
+        allCompleted: boolean;
+        conversationId: string;
+    };
+};
+type TodoWriteResult = TodoWriteSuccessResult$1 | ExecResultError;
+
+type AssignSuccessResult$1 = {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata: DelegationMetadata;
+};
+type AssignErrorResult = ExecResultError & {
+    metadata?: {
+        agentId?: string;
+        errorReason?: ErrorReason;
+        delegationDepth?: number;
+        policyDenied?: boolean;
+        agentNotFound?: boolean;
+    };
+};
+type AssignResult = AssignSuccessResult$1 | AssignErrorResult;
+
+declare function isSuccess(result: ExecResult): result is ExecResultSuccess;
+declare function isError(result: ExecResult): result is ExecResultError;
+declare function isTextResult(result: ExecResult): result is Extract<ExecResult, {
+    type: 'text';
+}>;
+declare function isJsonResult(result: ExecResult): result is Extract<ExecResult, {
+    type: 'json';
+}>;
+declare function isSuccessText(result: ExecResult): result is Extract<ExecResultSuccess, {
+    type: 'text';
+}>;
+declare function isSuccessJson(result: ExecResult): result is Extract<ExecResultSuccess, {
+    type: 'json';
+}>;
+
+type WithToolExecutionFields<T extends {
+    status: string;
+    type: string;
+    result: unknown;
+    metadata?: unknown;
+}> = Omit<T, 'metadata'> & {
+    id: string;
+    name: string;
+    durationMs?: number;
+    metadata: T['metadata'];
+};
+type BashSuccessResult = WithToolExecutionFields<BashSuccessResult$1>;
+type FileReadSuccessResult = WithToolExecutionFields<FileReadSuccessResult$1>;
+type FileEditSuccessResult = WithToolExecutionFields<FileEditSuccessResult$1>;
+type FileNewSuccessResult = WithToolExecutionFields<FileNewSuccessResult$1>;
+type DirLsSuccessResult = WithToolExecutionFields<DirLsSuccessResult$1>;
+type WebSearchSuccessResult = WithToolExecutionFields<WebSearchSuccessResult$1>;
+type WebFetchSuccessResult = WithToolExecutionFields<WebFetchSuccessResult$1>;
+type TodoWriteSuccessResult = WithToolExecutionFields<TodoWriteSuccessResult$1>;
+type AssignSuccessResult = WithToolExecutionFields<AssignSuccessResult$1>;
+declare function isBashResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isBashSuccess(result: ToolExecutionResult): result is BashSuccessResult;
+declare function isFileReadResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isFileReadSuccess(result: ToolExecutionResult): result is FileReadSuccessResult;
+declare function isFileEditResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isFileEditSuccess(result: ToolExecutionResult): result is FileEditSuccessResult;
+declare function isFileNewResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isFileNewSuccess(result: ToolExecutionResult): result is FileNewSuccessResult;
+declare function isDirLsResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isDirLsSuccess(result: ToolExecutionResult): result is DirLsSuccessResult;
+declare function isWebSearchResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isWebSearchSuccess(result: ToolExecutionResult): result is WebSearchSuccessResult;
+declare function isWebFetchResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isWebFetchSuccess(result: ToolExecutionResult): result is WebFetchSuccessResult;
+declare function isTodoWriteResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isTodoWriteSuccess(result: ToolExecutionResult): result is TodoWriteSuccessResult;
+declare function isAssignResult(result: ToolExecutionResult): result is ToolExecutionResult;
+declare function isAssignSuccess(result: ToolExecutionResult): result is AssignSuccessResult;
+
+declare function okText<M extends Record<string, unknown> = Record<string, unknown>>(result: string, metadata: M): {
+    status: 'success';
+    type: 'text';
+    result: string;
+    metadata: M;
+};
+declare function okJson<T extends Record<string, unknown> | unknown[], M extends Record<string, unknown> = Record<string, unknown>>(result: T, metadata?: M): {
+    status: 'success';
+    type: 'json';
+    result: T;
+    metadata?: M;
+};
+declare function err(result: string, metadata?: Record<string, unknown>, errorReason?: ErrorReason): ExecResultError;
+
+/**
+ * Sub-agent related types
+ * These types track the state and execution of delegated specialist agents
+ */
+
+/**
+ * Represents a tool call made by a sub-agent during execution
+ */
+type SubAgentToolCall = {
+    id: string;
+    name: string;
+    arguments?: string;
+    durationMs?: number;
+    status?: 'success' | 'error';
+    result?: string;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * State tracking for a sub-agent execution
+ * Used by UIs to display real-time sub-agent activity
+ */
+type SubAgentState = {
+    agentId: string;
+    agentName: string;
+    status: 'starting' | 'running' | 'completed';
+    toolCalls: SubAgentToolCall[];
+    resultMessage?: string;
+    totalDurationMs?: number;
+    finalStatus?: 'success' | 'error' | 'timeout';
+    toolCallMessageId?: string;
+    toolCallId?: string;
+    metrics?: MetricsSnapshot;
+};
+/**
+ * Parse tool call arguments from string to typed object
+ */
+declare function parseSubAgentToolCallArguments(argsString?: string): Record<string, unknown>;
+
 type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
 type LogFormat = 'json' | 'structured';
 type PersistOptions = {
@@ -1470,4 +2211,4 @@ declare function resolveBackspaces(s: string): string;
 declare function stripAnsiAndControls(s: string): string;
 declare function canonicalizeTerminalPaste(raw: string): string;
 
-export { AGENT_CREATOR_SYSTEM_PROMPT, type AgentAwareToolPort, type AgentCatalog, type AgentConfig, type AgentEvent, AgentEventTypes, AgentFilePersistence, AgentManager, AgentManagerCommandRunner, AgentOrchestrator, AgentRegistry, type AgentTemplate, AnthropicAISDKLLM, type AssignParams, BashTool, type CompleteAgent, CompositeToolPort, type Conversation, ConversationContext, type ConversationMetadata, type ConversationSnapshot, ConversationStore, CoreMCPClient, DefaultDelegationPolicy, DefaultDelegationResultFormatter, DefaultDelegationService, DefaultSpecialistAgentFactory, type DelegationService, type DelegationServiceConfig, DelegationServiceFactory, ErrorReason, type FolderTreeOptions, GithubLLM, InMemoryMemory, InMemoryMetadata, InMemoryMetricsPort, JsonFileMemoryPersistence, type LLMConfig, LLMError, type LLMFactory, type LLMOptions, type LLMPort, LLMResolver, type MCPConfig, type MCPServerConfig, MCPToolPort, type MemoryPort, MemoryPortMetadataAdapter, type Message, type MessageContent, type MessageContentPart, type MetadataPort, type MetricsChangeHandler, type MetricsPort, type MetricsSnapshot, type ModelInfo, type ModelLimits, NoopMetricsPort, NoopReminders, type OrchestratorAwareToolPort, PersistedMemory, PersistingConsoleEventPort, RuntimeEnv, type SendMessageOptions, SimpleContextBuilder, SimpleCost, SimpleId, type SpecialistAgentConfig, type SpecialistAgentResult, SystemClock, type ToolApprovalDecision, type ToolCall, type ToolExecutionResult, type ToolPort, ToolRegistry, type UsageData, type UserAttachment, type UserMessagePayload, buildAgentCreationPrompt, buildInjectedSystem, canonicalizeTerminalPaste, createEmptySnapshot, createLLM, generateFolderTree, getAvailableProviders, getFallbackLimits, getProviderLabel, loadMCPConfig, normalizeModelInfo, normalizeModelLimits, normalizeNewlines, renderTemplate, resolveBackspaces, resolveCarriageReturns, stripAnsiAndControls, supportsGetModels };
+export { AGENT_CREATOR_SYSTEM_PROMPT, type AgentAwareToolPort, type AgentCatalog, type AgentConfig, type AgentEvent, AgentEventTypes, AgentFilePersistence, AgentManager, AgentManagerCommandRunner, AgentOrchestrator, AgentRegistry, type AgentTemplate, AnthropicAISDKLLM, type AssignErrorResult, type AssignParams, type AssignResult, type AssignSuccessResult$1 as AssignSuccessResult, type AssignTaskArgs, type AssignTaskMetadata, type BashErrorResult, type BashParams, type BashResult, type BashSuccessResult$1 as BashSuccessResult, BashTool, type BashToolArgs, type BashToolMetadata, type CommandMetadata, type CompleteAgent, CompositeToolPort, type Conversation, ConversationContext, type ConversationMetadata, type ConversationSnapshot, ConversationStore, CoreMCPClient, DefaultDelegationPolicy, DefaultDelegationResultFormatter, DefaultDelegationService, DefaultSpecialistAgentFactory, type DelegationMetadata, type DelegationService, type DelegationServiceConfig, DelegationServiceFactory, type DirEntry, type DirLsArgs, type DirLsMetadata, type DirLsParams, type DirLsResult, type DirLsSuccessResult$1 as DirLsSuccessResult, type ErrorMetadata, ErrorReason, type ExecResult, type ExecResultError, type ExecResultSuccess, type FileEditArgs, type FileEditMetadata, type FileEditResult, type FileEditSuccessResult$1 as FileEditSuccessResult, type FileMetadata, type FileNewArgs, type FileNewMetadata, type FileNewParams, type FileNewResult, type FileNewSuccessResult$1 as FileNewSuccessResult, type FileReadArgs, type FileReadErrorResult, type FileReadMetadata, type FileReadParams, type FileReadResult, type FileReadSuccessResult$1 as FileReadSuccessResult, type FolderTreeOptions, type FunctionTool, GithubLLM, InMemoryMemory, InMemoryMetadata, InMemoryMetricsPort, JsonFileMemoryPersistence, type LLMConfig, LLMError, type LLMFactory, type LLMOptions, type LLMPort, LLMResolver, type LineRangeMetadata, type MCPConfig, type MCPServerConfig, MCPToolPort, type MemoryPort, MemoryPortMetadataAdapter, type Message, type MessageContent, type MessageContentPart, type MetadataPort, type MetricsChangeHandler, type MetricsPort, type MetricsSnapshot, type ModelInfo, type ModelLimits, NoopMetricsPort, NoopReminders, type OrchestratorAwareToolPort, type ParseResult, PersistedMemory, PersistingConsoleEventPort, RuntimeEnv, type SendMessageOptions, SimpleContextBuilder, SimpleCost, SimpleId, type SpecialistAgentConfig, type SpecialistAgentResult, type SubAgentState, type SubAgentToolCall, SystemClock, type TodoWriteArgs, type TodoWriteMetadata, type TodoWriteResult, type TodoWriteSuccessResult$1 as TodoWriteSuccessResult, type ToolApprovalDecision, type ToolArguments, type ToolCall, type ToolCallValidation, type ToolErrorMetadata, type ToolExecutionContext, type ToolExecutionResult, type ToolMetadataMap, type ToolName, type ToolParameterMap, type ToolPort, ToolRegistry, type ToolValidator, type TypedToolInvocation, type UsageData, type UserAttachment, type UserMessagePayload, type ValidationResult, type WebFetchArgs, type WebFetchMetadata, type WebFetchParams, type WebFetchResult, type WebFetchSuccessResult$1 as WebFetchSuccessResult, type WebSearchArgs, type WebSearchMetadata, type WebSearchParams, type WebSearchResult, type WebSearchSuccessResult$1 as WebSearchSuccessResult, type WebSearchToolResult, buildAgentCreationPrompt, buildInjectedSystem, canonicalizeTerminalPaste, convertToolCall, convertToolCalls, createEmptySnapshot, createLLM, err, generateFolderTree, getAvailableProviders, getFallbackLimits, getProviderLabel, isAssignResult, isAssignSuccess, isAssignTaskArgs, isBashResult, isBashSuccess, isBashToolArgs, isDirLsArgs, isDirLsResult, isDirLsSuccess, isError, isFileEditArgs, isFileEditResult, isFileEditSuccess, isFileNewArgs, isFileNewResult, isFileNewSuccess, isFileReadArgs, isFileReadResult, isFileReadSuccess, isJsonResult, isSuccess, isSuccessJson, isSuccessText, isTextResult, isTodoWriteArgs, isTodoWriteResult, isTodoWriteSuccess, isWebFetchArgs, isWebFetchResult, isWebFetchSuccess, isWebSearchArgs, isWebSearchResult, isWebSearchSuccess, loadMCPConfig, normalizeModelInfo, normalizeModelLimits, normalizeNewlines, okJson, okText, parseJSON, parseSubAgentToolCallArguments, parseToolArguments, renderTemplate, resolveBackspaces, resolveCarriageReturns, stripAnsiAndControls, supportsGetModels, toolValidators };