/**
 * Helpers beside a deep agent: helpers it delegates to and waits for, helpers that run in the
 * background while it goes on, and helpers it creates during a run from instructions it writes.
 *
 * A background helper runs on a thread of its own, named after the call that started it, and writes
 * its checkpoints to the deep agent's checkpointer. A crash leaves the helper's finished steps behind
 * it: collecting the task in a new process carries the helper on from its last checkpoint, and a call
 * the agent repeats after the crash finds the same thread instead of starting the helper again.
 *
 * The helpers an agent creates are recorded on a thread of their own beside its own, before the call
 * that creates one returns, so an agent resumed in another process counts them against its `max` and
 * delegates to them again by name.
 *
 * A remote helper runs on another agent server, as a run that server's workers lease: when the worker
 * running it stops, another takes it over. The agent starts it under a key made from the call that
 * started it, so delegating again or collecting it, in this process or another, finds that same run.
 */
import { type CreateAgentOptions } from '../agent/create-agent.js';
import type { PermissionPolicyLike } from '../agent/permissions.js';
import type { GraphCheckpointer } from '../types/graph.js';
import type { ToolDefinition } from '../types/messages.js';
/** Limits on the helpers a deep agent creates during a run, from instructions it writes. */
export interface DeepHelperLimits {
    /**
     * The tools a created helper may use, by name, from the agent's own. Defaults to all of them. A tool
     * that needs approval is never a helper's.
     */
    tools?: readonly string[];
    /** The model a created helper runs on. Defaults to the agent's. */
    model?: string;
    /** Model calls a created helper may make. Defaults to 10. */
    maxIterations?: number;
    /** How many helpers the agent may create in one thread. Defaults to 5. */
    max?: number;
}
/** How a run on another agent server ended, as `createRemoteGraph()` reports it. */
export interface DeepRemoteRunResult {
    /** The run's id on that server. */
    runId: string;
    /** Where it ended: `succeeded`, `failed`, `cancelled`, `expired`, or `awaiting_input`. */
    status: string;
    /** What it produced. */
    output?: unknown;
    /** Why it failed. */
    error?: {
        message?: string;
    };
}
/**
 * A helper on another agent server: what `createRemoteGraph()` returns, or anything that runs an input
 * there and waits for it.
 */
export interface DeepRemoteHelper {
    /**
     * Runs an input there and waits for it to end. A second call with the same `idempotencyKey` waits
     * for the run the first started, as the agent server does, rather than starting another.
     */
    invoke(input: unknown, options: {
        idempotencyKey: string;
        signal?: AbortSignal;
    }): Promise<DeepRemoteRunResult>;
}
/** What the deep agent hands the helper tools. */
export interface HelperSetup {
    /** The helpers the application declared. */
    declared: ReadonlyArray<{
        name: string;
        description: string;
        instructions: string;
        tools?: readonly string[];
        model?: string;
        maxIterations?: number;
        remote?: DeepRemoteHelper;
    }>;
    /** Limits on created helpers, when the agent may create them. */
    create?: DeepHelperLimits;
    /** The tools a helper may be given: the agent's own, less any that need approval. */
    tools: readonly ToolDefinition[];
    /** `createAgent()` options every helper shares. */
    agentOptions: Omit<CreateAgentOptions, 'interruptOn' | 'tools' | 'systemPrompt' | 'permissions' | 'checkpointer'>;
    /** The policy every helper runs under. */
    permissions?: PermissionPolicyLike;
    /** Where background helpers keep their checkpoints. */
    checkpointer?: GraphCheckpointer;
    /** The deep agent's name, for the helpers' names. */
    name: string;
    /** Appended to every helper's instructions. */
    note: string;
    /** How many helpers may run in the background in one thread at once. */
    maxBackground: number;
}
/** `delegate` and `collect_helper`, sharing the helpers they run. */
export declare function helperTools(setup: HelperSetup): ToolDefinition[];