@mastra/core/dist/harness/tools.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

import { z } from 'zod/v4';
import { Agent } from '../agent/index.js';
import type { ToolsInput, ToolsetsInput } from '../agent/types.js';
import type { MastraLanguageModel } from '../llm/model/shared.types.js';
import { RequestContext } from '../request-context/index.js';
import type { HarnessSubagent } from './types.js';
/**
 * Built-in harness tool: ask the user a question and wait for their response.
 *
 * The tool supports three prompt shapes. Omitting `options` asks an open-ended
 * free-text question. Providing `options` without `selectionMode` asks the UI to
 * render a single-select prompt for backwards compatibility. Providing
 * `selectionMode: 'multi_select'` lets the UI return multiple selected option labels
 * as a string array through `respondToQuestion()`.
 *
 * During normal harness execution the tool emits an `ask_question` event, registers a
 * resolver, and pauses until the UI answers. When the tool is executed without harness
 * callbacks, it returns a readable fallback prompt so non-UI execution paths still
 * expose the question and available choices to the model.
 */
export declare const askUserTool: import("../tools").Tool<{
    question: string;
    options?: {
        label: string;
        description?: string | undefined;
    }[] | undefined;
    selectionMode?: "single_select" | "multi_select" | undefined;
}, unknown, unknown, unknown, import("../tools").ToolExecutionContext<unknown, unknown, unknown>, "ask_user", unknown>;
/**
 * Built-in harness tool: submit a plan for user review.
 * The plan renders in the UI with approve/reject options.
 * On approval, the harness switches to the default mode.
 */
export declare const submitPlanTool: import("../tools").Tool<{
    plan: string;
    title?: string | undefined;
}, unknown, unknown, unknown, import("../tools").ToolExecutionContext<unknown, unknown, unknown>, "submit_plan", unknown>;
declare const taskItemInputSchema: z.ZodObject<{
    id: z.ZodOptional<z.ZodString>;
    content: z.ZodString;
    status: z.ZodEnum<{
        pending: "pending";
        completed: "completed";
        in_progress: "in_progress";
    }>;
    activeForm: z.ZodString;
}, z.core.$strip>;
declare const taskItemSchema: z.ZodObject<{
    content: z.ZodString;
    status: z.ZodEnum<{
        pending: "pending";
        completed: "completed";
        in_progress: "in_progress";
    }>;
    activeForm: z.ZodString;
    id: z.ZodString;
}, z.core.$strip>;
export type TaskItemInput = z.infer<typeof taskItemInputSchema>;
export type TaskItem = z.infer<typeof taskItemSchema>;
export type TaskItemSnapshot = TaskItem;
declare const taskCheckSummarySchema: z.ZodObject<{
    total: z.ZodNumber;
    completed: z.ZodNumber;
    inProgress: z.ZodNumber;
    pending: z.ZodNumber;
    incomplete: z.ZodNumber;
    hasTasks: z.ZodBoolean;
    allCompleted: z.ZodBoolean;
}, z.core.$strip>;
declare const taskCheckResultSchema: z.ZodObject<{
    content: z.ZodString;
    tasks: z.ZodArray<z.ZodObject<{
        content: z.ZodString;
        status: z.ZodEnum<{
            pending: "pending";
            completed: "completed";
            in_progress: "in_progress";
        }>;
        activeForm: z.ZodString;
        id: z.ZodString;
    }, z.core.$strip>>;
    isError: z.ZodBoolean;
    summary: z.ZodObject<{
        total: z.ZodNumber;
        completed: z.ZodNumber;
        inProgress: z.ZodNumber;
        pending: z.ZodNumber;
        incomplete: z.ZodNumber;
        hasTasks: z.ZodBoolean;
        allCompleted: z.ZodBoolean;
    }, z.core.$strip>;
    incompleteTasks: z.ZodArray<z.ZodObject<{
        content: z.ZodString;
        status: z.ZodEnum<{
            pending: "pending";
            completed: "completed";
            in_progress: "in_progress";
        }>;
        activeForm: z.ZodString;
        id: z.ZodString;
    }, z.core.$strip>>;
}, z.core.$strip>;
export type TaskCheckSummary = z.infer<typeof taskCheckSummarySchema>;
export type TaskCheckResult = z.infer<typeof taskCheckResultSchema>;
export declare function assignTaskIds(tasks: TaskItemInput[], previousTasks?: TaskItemSnapshot[]): TaskItemSnapshot[];
/**
 * Built-in harness tool: manage a structured task list for the coding session.
 * Full-replacement semantics: each call replaces the entire task list.
 * Prefer task_update or task_complete for changing existing tasks by ID.
 */
export declare const taskWriteTool: import("../tools").Tool<{
    tasks: {
        content: string;
        status: "pending" | "completed" | "in_progress";
        activeForm: string;
        id?: string | undefined;
    }[];
}, {
    content: string;
    tasks: {
        content: string;
        status: "pending" | "completed" | "in_progress";
        activeForm: string;
        id: string;
    }[];
    isError: boolean;
}, unknown, unknown, import("../tools").ToolExecutionContext<unknown, unknown, unknown>, "task_write", unknown>;
/**
 * Built-in harness tool: update one tracked task by stable ID.
 */
export declare const taskUpdateTool: import("../tools").Tool<{
    id: string;
    content?: string | undefined;
    status?: "pending" | "completed" | "in_progress" | undefined;
    activeForm?: string | undefined;
}, {
    content: string;
    tasks: {
        content: string;
        status: "pending" | "completed" | "in_progress";
        activeForm: string;
        id: string;
    }[];
    isError: boolean;
}, unknown, unknown, import("../tools").ToolExecutionContext<unknown, unknown, unknown>, "task_update", unknown>;
/**
 * Built-in harness tool: mark one tracked task completed by stable ID.
 */
export declare const taskCompleteTool: import("../tools").Tool<{
    id: string;
}, {
    content: string;
    tasks: {
        content: string;
        status: "pending" | "completed" | "in_progress";
        activeForm: string;
        id: string;
    }[];
    isError: boolean;
}, unknown, unknown, import("../tools").ToolExecutionContext<unknown, unknown, unknown>, "task_complete", unknown>;
/**
 * Built-in harness tool: check the completion status of the current task list.
 * Helps the agent determine if all tasks are completed before ending work.
 */
export declare const taskCheckTool: import("../tools").Tool<Record<string, never>, {
    content: string;
    tasks: {
        content: string;
        status: "pending" | "completed" | "in_progress";
        activeForm: string;
        id: string;
    }[];
    isError: boolean;
    summary: {
        total: number;
        completed: number;
        inProgress: number;
        pending: number;
        incomplete: number;
        hasTasks: boolean;
        allCompleted: boolean;
    };
    incompleteTasks: {
        content: string;
        status: "pending" | "completed" | "in_progress";
        activeForm: string;
        id: string;
    }[];
}, unknown, unknown, import("../tools").ToolExecutionContext<unknown, unknown, unknown>, "task_check", unknown>;
export interface CreateSubagentToolOptions {
    subagents: HarnessSubagent[];
    resolveModel: (modelId: string) => MastraLanguageModel;
    /** Resolved harness tools (already evaluated from DynamicArgument) */
    harnessTools?: ToolsInput;
    /** Fallback model ID when subagent definition has no defaultModelId */
    fallbackModelId?: string;
    /** Returns the parent model ID for display when a subagent call is forked. */
    getParentModelId?: () => string;
    /**
     * Returns the parent Agent that owns the current run. Invoked when a
     * subagent call is forked so the fork can reuse the parent's
     * instructions, tools, and model to preserve prompt-cache prefix.
     */
    getParentAgent?: () => Agent | undefined;
    /**
     * Clones the parent thread so a forked subagent can run on a copy
     * without polluting the parent conversation. Typically delegates to
     * `Harness.cloneThread`. Returns the new thread metadata.
     */
    cloneThreadForFork?: (opts: {
        sourceThreadId: string;
        resourceId?: string;
        title?: string;
    }) => Promise<{
        id: string;
        resourceId: string;
    }>;
    /**
     * Resolves the toolsets the parent agent runs with for the current request.
     * When set, forked subagents inherit the parent's toolsets so harness-injected
     * tools like `ask_user` / `submit_plan` / user-configured harness tools remain
     * available inside the fork. The `subagent` entry is preserved for prompt-cache
     * stability, but its runtime execute function is patched to block recursion.
     */
    getParentToolsets?: (requestContext?: RequestContext) => Promise<ToolsetsInput | undefined>;
}
/**
 * Creates a `subagent` tool from registered subagent definitions.
 * The tool spawns a fresh Agent per invocation with constrained tools,
 * streams the response, and forwards events to the harness.
 */
export declare function createSubagentTool(opts: CreateSubagentToolOptions): import("../tools").Tool<{
    agentType: string;
    task: string;
    modelId?: string | undefined;
    forked?: boolean | undefined;
}, unknown, unknown, unknown, import("../tools").ToolExecutionContext<unknown, unknown, unknown>, "subagent", unknown>;
/**
 * Parse subagent metadata from a tool result string.
 *
 * Older persisted threads may have an internal `<subagent-meta />` tag
 * appended to the subagent tool result content (carrying modelId / durationMs
 * / sub-tool-call summary, used by history-render UIs to reconstruct the
 * subagent activity box when live events aren't available).
 *
 * New runs no longer append the tag — the metadata leaked into model context
 * and could be echoed back as visible assistant text — but this parser is
 * retained so existing threads continue to render cleanly. It also strips the
 * tag so callers never display it to users.
 *
 * Returns the cleaned text plus any parsed metadata.
 */
export declare function parseSubagentMeta(content: string): {
    text: string;
    modelId?: string;
    durationMs?: number;
    toolCalls?: Array<{
        name: string;
        isError: boolean;
    }>;
};
export {};
//# sourceMappingURL=tools.d.ts.map