import { type PlatformFetch } from '../core/openapi-client.js';
import type { components, operations } from '../generated/api.js';
import { WorkspaceScopedResource } from './base.js';
export type ConversationDetail = components['schemas']['ConversationDetail'];
export type ConversationListResponse = components['schemas']['ConversationListResponse'];
export type ConversationSummary = components['schemas']['src__routes__conversations__ConversationSummary'];
export type ConversationTurn = components['schemas']['ConversationTurn'];
export type ConversationTurnAvailableAction = components['schemas']['ConversationTurnAvailableAction'];
export type ConversationTurnStateTransition = components['schemas']['ConversationTurnStateTransition'];
export type CreateConversationRequest = components['schemas']['CreateConversationRequest'];
export type TurnRequest = components['schemas']['TurnRequest'];
export type TurnResponse = components['schemas']['TurnResponse'];
export type TurnConversationSnapshot = components['schemas']['TurnConversationSnapshot'];
export type TurnStreamEvent = components['schemas']['TurnStreamEvent'];
export type TurnTokenEvent = components['schemas']['TurnTokenEvent'];
export type TurnToolCallStartedEvent = components['schemas']['TurnToolCallStartedEvent'];
export type TurnToolCallCompletedEvent = components['schemas']['TurnToolCallCompletedEvent'];
export type TurnThinkingEvent = components['schemas']['TurnThinkingEvent'];
export type TurnMessageEvent = components['schemas']['TurnMessageEvent'];
export type TurnDoneEvent = components['schemas']['TurnDoneEvent'];
export type TurnErrorEvent = components['schemas']['TurnErrorEvent'];
/**
 * Hand-authored because the text-stream WebSocket endpoint is intentionally
 * outside the generated OpenAPI REST snapshot.
 * TODO: replace with generated types when `/agent/text-stream` is added to
 * openapi.json.
 *
 * @beta The text-stream WebSocket contract may evolve independently of the REST API.
 */
export interface TextStreamUrlParams {
    serviceId: string;
    conversationId?: string;
    entityId?: string;
    /**
     * Enable `tool_call_started` and `tool_call_completed` frames on the
     * text-stream WebSocket so the client can render tool invocations in
     * real time.
     */
    toolEvents?: boolean;
    /**
     * Bearer token query-param fallback for clients whose API key cannot be sent
     * as a WebSocket subprotocol token. Prefer textStreamAuthProtocols() when
     * the token is subprotocol-safe so secrets do not appear in URLs. The SDK
     * intentionally accepts only the server-supported text-stream token alphabet
     * (letters, digits, `.`, `_`, `+`, `=`, `/`, `:`, `-`) even though
     * URLSearchParams can percent-encode additional characters.
     */
    token?: string;
    /**
     * Full text-stream URL override for preview/custom ingress.
     * Defaults to `${baseUrl origin}/agent/text-stream` with
     * `http` mapped to `ws` and `https` mapped to `wss`.
     */
    textStreamUrl?: string;
}
/** @beta The text-stream WebSocket contract may evolve independently of the REST API. */
export type TextStreamAuthProtocols = readonly ['auth', string];
/**
 * Hand-authored because the workspace-scoped session-connect WebSocket is
 * intentionally outside the generated OpenAPI REST snapshot.
 *
 * Path: ``WS /v1/{workspace_id}/sessions/connect``. Authentication is delivered
 * via the ``Sec-WebSocket-Protocol: auth, <token>`` subprotocol header — the
 * server rejects query-param tokens to keep credentials out of URLs and proxy
 * logs. ``serviceId`` and ``entityId`` are required path/query inputs.
 *
 * @beta The session-connect WebSocket contract may evolve independently of the REST API.
 */
export interface SessionConnectUrlParams {
    serviceId: string;
    entityId: string;
    conversationId?: string;
    /**
     * Emit ``tool_call_started`` and ``tool_call_completed`` frames so the client
     * can render tool invocations in real time. Server defaults to ``true`` when
     * the param is omitted; the SDK only sets it explicitly when the caller asks
     * to disable tool events.
     */
    toolEvents?: boolean;
    /**
     * Full session-connect URL override for preview/custom ingress. Defaults to
     * ``${baseUrl origin}/v1/{workspace_id}/sessions/connect`` with ``http`` mapped
     * to ``ws`` and ``https`` mapped to ``wss``. The override must be an
     * absolute ws/wss URL with no query string or fragment — SDK-managed query
     * params are appended by the helper.
     */
    sessionConnectUrl?: string;
}
export type ListConversationsParams = NonNullable<operations['list_conversations_v1__workspace_id__conversations_get']['parameters']['query']>;
/** Access text conversation APIs and text-stream URL helpers. */
export declare class ConversationsResource extends WorkspaceScopedResource {
    private readonly agentBaseUrl;
    constructor(client: PlatformFetch, workspaceId: string, agentBaseUrl?: string);
    list(params?: ListConversationsParams): Promise<ConversationListResponse>;
    create(request: CreateConversationRequest): Promise<ConversationDetail>;
    /**
     * Fetch a conversation's detail, including its turns.
     *
     * Pass `options.includeToolCalls: true` to include per-turn `tool_calls`
     * metadata on the returned turns. Server-side default is `false` — without
     * this opt-in the `tool_calls` arrays will be empty even when the agent
     * invoked tools, matching the `createTurn` opt-in.
     */
    get(conversationId: string, options?: {
        includeToolCalls?: boolean;
    }): Promise<ConversationDetail>;
    close(conversationId: string): Promise<void>;
    /**
     * Send a user message and receive the agent's synchronous JSON response.
     *
     * Pass `options.includeToolCalls: true` to request tool-call metadata
     * alongside the response turns. Server-side default is `false` — without
     * this opt-in the `tool_calls` array on the `TurnResponse` will be empty
     * even when the agent invoked tools during the turn.
     *
     * Pass `options.poll: true` for a no-message drain-and-report poll (see
     * {@link pollTurn} for the ergonomic wrapper): the agent surfaces any
     * background tool results that completed since the last turn. A poll must
     * NOT carry a `request.message` (the server rejects it 422); prefer
     * {@link pollTurn}.
     */
    createTurn(conversationId: string, request: TurnRequest, options?: {
        includeToolCalls?: boolean;
        poll?: boolean;
    }): Promise<TurnResponse>;
    /**
     * Poll a conversation for background tool results without sending a user
     * message. Drains any background tool calls that completed since the last
     * turn and returns the agent's report; when nothing is pending the response
     * has empty `output` and `tool_calls` (the idle case) — treat that as "keep
     * polling". Poll no more than once every ~5s per conversation.
     *
     * @example
     * ```ts
     * const res = await client.conversations.pollTurn(convId, { includeToolCalls: true });
     * if (res.output.length || res.tool_calls?.length) render(res); // else poll again later
     * ```
     */
    pollTurn(conversationId: string, options?: {
        includeToolCalls?: boolean;
    }): Promise<TurnResponse>;
    /**
     * Send a message and receive the agent's response as an SSE byte stream.
     *
     * Targets the explicit always-SSE endpoint
     * `POST /v1/{ws}/conversations/{id}/turns/stream`, so the response is
     * always `text/event-stream` regardless of `Accept` negotiation. Returns
     * a `ReadableStream` of raw bytes; use `EventSourceParserStream` (from
     * `eventsource-parser/stream`) to parse into typed `TurnStreamEvent`,
     * or use the higher-level {@link streamTurn} which hides the parser.
     *
     * @example
     * ```ts
     * const stream = await client.conversations.createTurnStream(convId, { message: "Hello" });
     * const events = stream
     *   .pipeThrough(new TextDecoderStream())
     *   .pipeThrough(new EventSourceParserStream());
     * for await (const event of events) {
     *   const parsed = JSON.parse(event.data) as TurnStreamEvent;
     *   if (parsed.event === "token") console.log(parsed.text);
     * }
     * ```
     */
    createTurnStream(conversationId: string, request: TurnRequest, options?: {
        signal?: AbortSignal;
        includeToolCalls?: boolean;
    }): Promise<ReadableStream<Uint8Array>>;
    /**
     * Send a message and receive the agent's response as a typed
     * `TurnStreamEvent` async iterable.
     *
     * The bytes-and-parser dance from `createTurnStream` is now hidden inside
     * the SDK — consumers iterate strongly typed events directly. Each yielded
     * value is a member of the `TurnStreamEvent` discriminated union (`token`,
     * `thinking`, `tool_call_started`, `tool_call_completed`, `message`,
     * `done`, `error`), validated as a record with a known `event`
     * discriminator. Unknown / malformed frames are dropped silently — this
     * matches the wire-format-drift behavior of the lower-level
     * `createTurnStream` while keeping the strict `TurnStreamEvent` static
     * contract intact for consumers.
     *
     * @example
     * ```ts
     * for await (const event of client.conversations.streamTurn(convId, { message: "Hello" })) {
     *   if (event.event === "token") process.stdout.write(event.text);
     *   else if (event.event === "done") break;
     * }
     * ```
     */
    streamTurn(conversationId: string, request: TurnRequest, options?: {
        signal?: AbortSignal;
        includeToolCalls?: boolean;
    }): AsyncGenerator<TurnStreamEvent>;
    /** Build the real-time text WebSocket URL for browser or custom clients. */
    textStreamUrl(params: TextStreamUrlParams): string;
    /**
     * Build the URL for the workspace-scoped session-connect WebSocket
     * (``WS /v1/{workspace_id}/sessions/connect``).
     *
     * Pair the returned URL with {@link sessionConnectAuthProtocols} so the
     * bearer token is delivered via the ``Sec-WebSocket-Protocol`` header — the
     * endpoint rejects query-param tokens to keep credentials out of URLs.
     *
     * @example
     * ```ts
     * const url = client.conversations.sessionConnectUrl({
     *   serviceId: SERVICE_ID,
     *   entityId: ENTITY_ID,
     *   conversationId: existingConversationId, // optional resume
     * });
     * const ws = new WebSocket(url, sessionConnectAuthProtocols(apiKey));
     * ```
     */
    sessionConnectUrl(params: SessionConnectUrlParams): string;
}
/**
 * Build browser WebSocket subprotocols for text-stream authentication.
 *
 * @remarks The returned tuple contains the raw API key. Do not log, persist,
 * serialize, or otherwise expose this value.
 *
 * @security The second subprotocol entry is the bearer secret.
 */
export declare function textStreamAuthProtocols(apiKey: string): TextStreamAuthProtocols;
/**
 * Build browser WebSocket subprotocols for the workspace-scoped session-connect
 * endpoint (``WS /v1/{workspace_id}/sessions/connect``).
 *
 * The wire format is identical to {@link textStreamAuthProtocols} — both
 * endpoints expect ``Sec-WebSocket-Protocol: auth, <token>`` — but the
 * session-connect endpoint has no query-param token fallback, so the API key
 * MUST round-trip through this subprotocol pair. Keys containing characters
 * browsers reject in subprotocols (e.g. ``:``, ``/``, ``=``) cannot be used
 * with the session-connect endpoint and must instead use the legacy
 * ``textStreamUrl`` path.
 *
 * @remarks The returned tuple contains the raw API key. Do not log, persist,
 * serialize, or otherwise expose this value.
 *
 * @security The second subprotocol entry is the bearer secret.
 */
export declare function sessionConnectAuthProtocols(apiKey: string): TextStreamAuthProtocols;
//# sourceMappingURL=conversations.d.ts.map