import type { BackgroundToolCallContext, BackgroundToolCallHandoff } from "@caupulican/pi-agent-core";
import type { SessionManager } from "@caupulican/pi-agent-core/node";
import type { Usage } from "@caupulican/pi-ai";
import type { ArtifactStore } from "./context/context-artifacts.ts";
export declare const DEFAULT_BACKGROUND_TOOL_CALL_AFTER_MS = 15000;
export declare const DEFAULT_BACKGROUND_TOOL_TASK_WAIT_TIMEOUT_MS = 30000;
export declare const BACKGROUND_TOOL_TASK_CUSTOM_TYPE = "background_tool_task";
export type BackgroundToolTaskStatus = "running" | "completed" | "failed" | "canceled";
export type BackgroundToolTerminalDelivery = "pending" | "delivered";
export type BackgroundToolTaskRef = Pick<BackgroundToolTaskRecord, "taskId" | "toolCallId" | "goalId" | "status">;
/** Match a goal/task_steps evidence uri to a session background tool task by task id or toolCallId. */
export declare function findBackgroundToolTask<T extends BackgroundToolTaskRef>(records: readonly T[], uri: string): T | undefined;
/** True only when the cited background task finished successfully. Undefined when no task matches. */
export declare function isCompletedBackgroundToolEvidence(records: readonly BackgroundToolTaskRef[], uri: string): boolean | undefined;
export declare function collectCitedRunningToolTaskIds(args: {
    records: readonly BackgroundToolTaskRef[];
    uris: readonly string[];
}): string[];
export interface BackgroundToolTaskRecord {
    sessionId: string;
    taskId: string;
    toolCallId: string;
    toolName: string;
    /** Goal execution that owned the foreground tool call when it was handed off. */
    goalId?: string;
    status: BackgroundToolTaskStatus;
    startedAt: string;
    completedAt?: string;
    elapsedBeforeHandoffMs: number;
    summary: string;
    output: string;
    artifactId?: string;
    usage?: Usage;
    cancellationRequested?: boolean;
    /** Durable terminal handoff state. Undefined on legacy records, which are treated as delivered. */
    terminalDelivery?: BackgroundToolTerminalDelivery;
    /** Runtime-only receipt; never serialized into the durable task record. */
    observedAt?: string;
}
export interface BackgroundToolTaskLiveView {
    taskId: string;
    toolCallId: string;
    toolName: string;
    description: string;
}
export interface BackgroundToolTerminalMessage {
    customType: "background-tool-completion";
    content: string;
    display: true;
    details: {
        records: Array<{
            taskId: string;
            status: BackgroundToolTaskStatus;
            toolName: string;
            artifactId?: string;
        }>;
    };
}
export interface BackgroundToolTaskControllerDeps {
    getSessionId(): string;
    /** Authoritative goal execution attribution at the tool handoff boundary. */
    getGoalId?(): string | undefined;
    /** Current session followed by the authoritative fork ancestry whose branch records remain visible. */
    getSessionLineageIds?(): readonly string[];
    getArtifactStore(): ArtifactStore | undefined;
    /** Durable task records on the active branch, newest first, without rebuilding full model context. */
    loadPersistedRecordsNewestFirst?(): readonly unknown[];
    persist(record: BackgroundToolTaskRecord): void;
    notifyTerminal(records: readonly BackgroundToolTaskRecord[], options: {
        wakeParent: boolean;
    }): Promise<void> | void;
    onLiveTasksChanged?(tasks: readonly BackgroundToolTaskLiveView[]): void;
    recordUsage?(taskId: string, usage: Usage): void;
    onError?(message: string, error: unknown): void;
    now?(): Date;
    /** Event-wait watchdog; completion still arrives through the terminal handoff after this bound. */
    waitTimeoutMs?: number;
}
/** Read only task records on the active branch without allocating or hydrating the full branch context. */
export declare function loadBackgroundToolTaskRecordsNewestFirst(sessionManager: Pick<SessionManager, "getLatestCustomEntryOnBranch">): unknown[];
export declare function createBackgroundToolTerminalMessage(records: readonly BackgroundToolTaskRecord[], options?: {
    wakeParent?: boolean;
}): BackgroundToolTerminalMessage;
/**
 * Session-owned registry for foreground tool calls transferred into background execution.
 * It emits edge records for durability and a replace-style live-task signal for UI consumers.
 */
export declare class BackgroundToolTaskController {
    private readonly deps;
    private readonly tasks;
    private readonly handoffRequests;
    private readonly queuedNotifications;
    private readonly activeNotificationRecords;
    private notificationDrain;
    private notificationRetryTimer;
    private notificationRetryCompletion;
    private resolveNotificationRetry;
    private notificationRetryCount;
    private readonly waitTimeoutMs;
    private nextTaskId;
    private disposed;
    constructor(deps: BackgroundToolTaskControllerDeps);
    handoff(context: BackgroundToolCallContext): BackgroundToolCallHandoff | undefined;
    list(): BackgroundToolTaskRecord[];
    /** Model-facing read that consumes terminal delivery without approving its outcome. */
    observe(taskIds?: string | readonly string[]): BackgroundToolTaskRecord[];
    wait(taskId: string, signal?: AbortSignal): Promise<BackgroundToolTaskRecord>;
    cancel(taskId: string): boolean;
    subscribeHandoffRequest(toolCallId: string, request: () => void): () => void;
    requestHandoff(toolCallId?: string): number;
    waitForNotifications(): Promise<void>;
    shutdown(): Promise<void>;
    private settle;
    private settleRejected;
    private restorePersistedTasks;
    private createState;
    private finishState;
    private persist;
    private notify;
    private markNotificationDelivered;
    private observeState;
    private scheduleNotificationDrain;
    private scheduleNotificationRetry;
    private drainNotifications;
    private emitLiveTasks;
    private pruneTerminalTasks;
    private now;
}
//# sourceMappingURL=background-tool-task-controller.d.ts.map