import type { SessionEvent } from "../events.ts";
import { AcpConnection } from "./jsonrpc.ts";
import { type AcpPromptCapabilities } from "./protocol.ts";
import type { AcpTransport } from "./transport.ts";
/**
 * The narrow port the ingestion client writes canonical events to. A Slice-1
 * {@link SessionAdapter} (e.g. a `SessionBackend`) satisfies it structurally, so
 * the ACP stream can feed the authoritative log directly; a test can pass a
 * plain collector.
 */
export interface SessionEventSink {
    emit(event: SessionEvent): void;
}
/** A single ACP content block sent in a prompt. `text` is the baseline shape. */
export interface AcpTextContentBlock {
    readonly type: "text";
    readonly text: string;
}
/** The prompt payload: a content-block array, or a bare string (wrapped as text). */
export type AcpPromptInput = string | readonly AcpTextContentBlock[];
/** The durable-resume capability probe read from the `initialize` handshake. */
export interface AcpCapabilityProbe {
    /** The protocol version the agent negotiated. */
    readonly protocolVersion: number;
    /** The raw `agentCapabilities.loadSession` flag. */
    readonly loadSession: boolean;
    /**
     * The nano-workforce enrolment-gate signal (slice 5): `true` iff the agent can
     * durably resume via `session/load`. Equal to {@link loadSession} — named for
     * the gate that consumes it, so the enrolment site reads intent, not wire detail.
     */
    readonly durableResume: boolean;
    /** The agent's advertised prompt-content capabilities. */
    readonly promptCapabilities: AcpPromptCapabilities;
    /** The full, unmodified `agentCapabilities` object for consumers that need more. */
    readonly agentCapabilities: unknown;
}
/** The result of a completed `session/prompt`, plus the events it produced. */
export interface AcpPromptResult {
    /** The agent's stop reason (`end_turn`, `cancelled`, …) when it reports one. */
    readonly stopReason: string | null;
    /** The canonical events emitted while this prompt ran, in emission order. */
    readonly events: readonly SessionEvent[];
}
/** Parameters shared by `session/new` and `session/load`. */
export interface AcpSessionParams {
    /** The session working directory (absolute path). */
    readonly cwd: string;
    /** MCP servers to attach; defaults to none. */
    readonly mcpServers?: readonly unknown[];
}
export interface AcpSessionClientOptions {
    /** Injectable event-id generator (deterministic tests). Default `crypto.randomUUID`. */
    readonly newEventId?: () => string;
    /** Client name/version reported in `initialize`. */
    readonly clientInfo?: {
        readonly name: string;
        readonly version: string;
    };
    /**
     * How to answer an agent's `session/request_permission`. Default: select the
     * first "allow"-flavoured option the agent offers (or a cancel outcome when
     * none is), so a driven session is never silently blocked on approval.
     */
    readonly onPermissionRequest?: (params: unknown) => unknown;
}
/**
 * The ACP ingestion client. Bind it to a transport and a sink, `initialize`, then
 * either `newSession` + `prompt` (drive) or `restore` an existing session id.
 */
export declare class AcpSessionClient {
    #private;
    constructor(connection: AcpConnection, sink: SessionEventSink, options?: AcpSessionClientOptions);
    /** The active session id (after `newSession`/`restore`), or `undefined`. */
    get sessionId(): string | undefined;
    /**
     * Perform the `initialize` handshake and return the durable-resume capability
     * probe. Must be called before any `session/*` method.
     */
    initialize(): Promise<AcpCapabilityProbe>;
    /** Open a fresh session (`session/new`); stores and returns its id. */
    newSession(params: AcpSessionParams): Promise<string>;
    /**
     * **restore** — load an existing session (`session/load`). The agent replays its
     * prior history as `session/update` notifications, which this client ingests
     * into the sink; when the load resolves, the pending message is flushed. Returns
     * the canonical events reconstructed from the replayed history, in order.
     *
     * Only valid against an agent whose probe reported `durableResume: true`.
     */
    restore(sessionId: string, params: AcpSessionParams): Promise<readonly SessionEvent[]>;
    /**
     * **drive** — send a prompt (`session/prompt`) and resolve when the turn ends.
     * All assistant output arrives as `session/update` notifications and is emitted
     * to the sink during the call; the final buffered message is flushed on
     * completion.
     */
    prompt(input: AcpPromptInput): Promise<AcpPromptResult>;
    /** **steer** — request cancellation of the running turn (`session/cancel`, a notification). */
    cancel(): void;
    /** Close the underlying connection and flush any pending buffered message. */
    close(): void;
}
/**
 * Open an ACP ingestion client over `transport`, emitting into `sink`. Wraps the
 * transport in an {@link AcpConnection} and returns the ready client; call
 * {@link AcpSessionClient.initialize} first.
 */
export declare function openAcpSession(transport: AcpTransport, sink: SessionEventSink, options?: AcpSessionClientOptions): AcpSessionClient;