/**
 * BackgroundTaskManager — the single registry for all background execution.
 *
 * Every background unit of work (forked agent, backgrounded shell command,
 * dream consolidation) registers here so that:
 *   1. The TaskStore holds its lifecycle state (task.updated notifications fire)
 *   2. The LLM can query status/output via the task tool ("output" action)
 *   3. Completion is queued as a <task_notification> for the next turn
 *   4. Cancellation actually kills the underlying process / aborts the agent
 *
 * This is the ONLY producer surface for TaskStore background tasks.
 * Do not register tasks into the store directly from feature code.
 */
import type { LocalAgentTaskState, LocalBashTaskState, TaskState } from "../tasks/task-types.js";
import { type TaskStore } from "./task-runtime.js";
/** Result contract for a background agent runner. */
export interface AgentRunOutcome {
    ok: boolean;
    output?: string;
    error?: string;
}
/** Structural handle for a backgrounded shell process (avoids skills-layer import). */
export interface BashTaskHandle {
    kill(): void;
    result: Promise<{
        code: number;
        stdout: string;
        stderr: string;
    }>;
    taskOutput: {
        taskId: string;
        path: string;
    };
}
export interface StartAgentTaskOptions {
    agentName: string;
    label: string;
    depth: number;
    maxTurns: number;
    parentTaskId?: string;
    /** The actual work. Receives the task's own abort signal and task id. */
    run(signal: AbortSignal, taskId: string): Promise<AgentRunOutcome>;
}
export interface RegisterBashTaskOptions {
    command: string;
    cwd: string;
    label?: string;
    pid?: number;
    handle: BashTaskHandle;
}
export interface TaskOutputSnapshot {
    task: TaskState;
    /** Current output: final result for terminal tasks, live tail for running bash tasks. */
    output: string;
    running: boolean;
}
/**
 * Control surface for a task whose EXECUTION lives outside this manager — e.g. a
 * team-member subprocess owned by AgentProcessManager. The manager holds the task
 * in the unified panel (list/output/cancel) and routes those three actions here;
 * lifecycle settlement is driven by the owner via settleExternalTask().
 */
export interface ExternalTaskControl {
    /** Kill / tear down the external executor (invoked by `task cancel`). */
    cancel(): void;
    /** Optional live status snapshot for `task output` while the task runs. */
    readStatus?(): string;
}
export declare class BackgroundTaskManager {
    private readonly store;
    private readonly controllers;
    private readonly bashHandles;
    private readonly externalControls;
    private readonly settledListeners;
    constructor(store: TaskStore);
    /** Subscribe to natural task settlement (completed/failed). Returns unregister fn. */
    onTaskSettled(listener: (task: TaskState) => void): () => void;
    private fireSettled;
    /**
     * Start a background forked agent. Registers a local_agent task,
     * floats the runner, and settles the task when the runner finishes.
     */
    startAgentTask(opts: StartAgentTaskOptions): LocalAgentTaskState;
    /**
     * Register an already-backgrounded shell command. The handle's result
     * promise settles the task; live output is readable from outputPath.
     */
    registerBashTask(opts: RegisterBashTaskOptions): LocalBashTaskState;
    /**
     * Register a task whose executor lives OUTSIDE this manager (team-member
     * subprocess). It joins the unified panel immediately; `task output` calls
     * control.readStatus(), `task cancel` calls control.cancel(). The owner MUST
     * drive settlement via settleExternalTask() when the executor exits.
     */
    registerExternalTask(task: TaskState, control: ExternalTaskControl): void;
    /**
     * Settle an external task (owner observed exit / teardown). Idempotent: a task
     * already terminal (e.g. cancelled by the user just before its process exited)
     * is left untouched. Drops the control entry either way.
     */
    settleExternalTask(taskId: string, lifecycle: "completed" | "failed" | "cancelled", output?: string): void;
    private settle;
    getTask(taskId: string): TaskState | undefined;
    listTasks(): TaskState[];
    /**
     * Read a task's output. For running bash tasks this reads the live
     * output file; for everything else it returns the stored final output.
     */
    readOutput(taskId: string): Promise<TaskOutputSnapshot | null>;
    /**
     * Cancel a running task: kills the shell process / aborts the agent,
     * then marks the task cancelled. Returns false if not found or already terminal.
     */
    cancelTask(taskId: string): boolean;
}
