/**
 * Read and message helpers for one Builder agent branch.
 *
 * `runBuilderAgent` starts a branch; these cover what a caller needs
 * afterwards: the state of the branch's agent, and a way to send it a
 * follow-up. Each returns a typed result or throws `BuilderBranchError`, and
 * neither ever creates a project or branch.
 *
 * Both routes sit under Builder's `/projects` OAuth policy, so they take the
 * project scopes, not the `builder:agents:run` scope the start route needs.
 * Legacy private keys also send the space/public key as `apiKey`.
 */
export type BuilderBranchAgentState = "running" | "waiting" | "idle";
export type BuilderBranchState = "active" | "archived" | "deleted";
export type BuilderBranchPrStatus = "open" | "closed" | "merged" | "draft" | "approved";
export interface BuilderBranchRef {
    projectId: string;
    branchName: string;
}
export interface GetBuilderBranchStatusOptions extends BuilderBranchRef {
    timeoutMs?: number;
}
export interface BuilderBranchStatus {
    /** `null` when Builder has recorded no agent state for the branch. */
    agentState: BuilderBranchAgentState | null;
    /** Epoch milliseconds; `null` when Builder has recorded no activity. */
    lastActivityAt: number | null;
    state: BuilderBranchState;
    archived: boolean;
    prStatus: BuilderBranchPrStatus | null;
    prUrl: string | null;
}
export interface SendBuilderBranchMessageOptions extends BuilderBranchRef {
    message: string;
    timeoutMs?: number;
}
export interface SendBuilderBranchMessageResult {
    /** Builder handed the message to the branch agent, queued or started. */
    accepted: true;
}
export type BuilderBranchOperation = "status" | "message";
export type BuilderBranchErrorCode = "invalid_request" | "not_connected" | "credentials_unavailable" | "unauthorized" | "forbidden" | "branch_not_found" | "rate_limited" | "server_error" | "timeout" | "network_error" | "invalid_response" | "incomplete_response" | "request_rejected" | "container_unavailable" | "message_rejected";
/**
 * Every failure from the branch helpers. `retryable` means the failure looks
 * transient, not that a retry is free: after `timeout`, `network_error` or
 * `incomplete_response` on `sendBuilderBranchMessage` the request was already
 * on the wire and Builder may have delivered the message, so a retry can send
 * it twice. Messages never carry response bodies or credentials.
 */
export declare class BuilderBranchError extends Error {
    readonly code: BuilderBranchErrorCode;
    readonly retryable: boolean;
    readonly operation: BuilderBranchOperation;
    readonly status: number | null;
    constructor(code: BuilderBranchErrorCode, operation: BuilderBranchOperation, message: string, options?: {
        status?: number;
        cause?: unknown;
    });
}
export declare function getBuilderBranchStatus(options: GetBuilderBranchStatusOptions): Promise<BuilderBranchStatus>;
export declare function sendBuilderBranchMessage(options: SendBuilderBranchMessageOptions): Promise<SendBuilderBranchMessageResult>;