/**
 * The pool: where a workflow's turns are played.
 *
 * A combinator says who speaks and what it is asked. The pool does the rest -
 * who is spawned, who is reused, who is closed, with which signal and deadline
 * every turn runs, and what the turns add up to. That is written here once, so
 * that a combinator cannot forget half of it.
 */
import { type Agent } from "./../agent.ts";
import { type Result } from "./../result.ts";
import type { WorkflowOptions } from "./options.ts";
import { Trail } from "./trail.ts";
/** Which subagent a turn goes to. */
export type TurnOptions = {
    /**
     * Who shares a memory. Defaults to the agent's name.
     *
     * In a persistent lifetime, two turns under one key reach the same
     * subagent: a chain keys by name so the same reviewer comes back with its
     * remarks in mind. A fan-out keys by branch, because two branches must never
     * share a context.
     */
    key?: string;
};
/**
 * A subagent held for a conversation.
 *
 * What a caller gets from {@link SubagentPool.hold}: enough to address it and
 * to ask it several things in a row, with the workflow's signal and deadline
 * on every turn. Not the `Subagent` itself - closing it stays the pool's job.
 *
 * A hold refused on a signal already aborted is addressed by its key, and
 * every `ask` answers the same refusal without spawning anything.
 */
export type Held = {
    /** The subagent's id, which is its name wherever it is addressed. */
    readonly id: string;
    /** One turn, with the workflow's `signal` and `timeoutMs`. */
    ask(task: string): Promise<Result>;
};
/**
 * Holds the subagents a workflow created, plays their turns, and closes them
 * all.
 *
 * The lifetime rule lives here, in one place, and it is decided per agent:
 * the workflow's `lifetime` when it names one, else the agent's frontmatter,
 * else `"task"`.
 * - `"task"`: a fresh subagent per turn, closed as soon as the turn is over.
 * - anything else: one subagent per key, reused, closed at the end.
 *
 * A held subagent is the exception: a conversation is not a task, so it lives
 * until {@link closeAll} whatever the lifetime.
 */
export declare class SubagentPool {
    /**
     * Every turn this pool played, refusals included, and what they add up to.
     *
     * A combinator that keeps its own list, its own clock and its own sum next
     * to this one has three chances to drift from it; reading these is how it
     * reports what it did.
     */
    readonly trail: Trail;
    private readonly live;
    private readonly owned;
    /** What the workflow asked for. Absent, each agent's own lifetime applies. */
    private readonly lifetime;
    private readonly spawnFn;
    private readonly spawnOptions;
    private readonly askOptions;
    private readonly customTools;
    /**
     * `trail` is the caller's when its clock has to start before the pool can
     * exist, or when it records steps of its own beside the pool's.
     */
    constructor(options: WorkflowOptions, trail?: Trail);
    /**
     * Plays one turn: the agent is asked `task`, and what it said comes back.
     *
     * A signal already aborted is answered without spawning anything, and the
     * refusal is a step on the trail like any other turn: a chain that was
     * called off says so where the answer would have been. Whatever happens
     * during the turn, the subagent is given back - which in `"task"` lifetime
     * means closed.
     */
    turn(agent: Agent, task: string, options?: TurnOptions): Promise<Result>;
    /**
     * Holds a subagent for a conversation of several turns.
     *
     * Where {@link turn} gives a subagent back after one answer, this keeps it
     * until {@link closeAll}: an interviewer that forgot the previous question,
     * or a swarm member with a new name every round, would not be a conversation.
     *
     * A signal already aborted is refused here, before the spawn, the way a turn
     * is: a held subagent is spawned before it is asked anything, so a check on
     * its first `ask` would come after the session it was meant to spare.
     */
    hold(agent: Agent, options?: TurnOptions): Promise<Held>;
    /**
     * Closes everything this pool opened. Whoever opens, closes - including on
     * cancellation, which is why callers put this in a `finally`.
     */
    closeAll(): Promise<void>;
    /** One turn, with the workflow's options, recorded on the trail. */
    private play;
    /** The answer to a turn nobody will play: a failure that says so, on the trail. */
    private refuse;
    /** Gets a subagent for this key, creating it if the lifetime calls for it. */
    private acquire;
}
//# sourceMappingURL=pool.d.ts.map