@qoniai/qoni 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,1362 @@
+type Headers = Record<string, string>;
+type Params = Record<string, unknown>;
+declare function buildStringToSign(method: string, pathname: string, headers: Headers, params: Params): string;
+declare function buildSignature(secretKey: string, stringToSign: string): string;
+declare function buildAuthorization(accessKey: string, secretKey: string, stringToSign: string): string;
+
+/**
+ * The interaction `type` discriminator — the single field a consumer
+ * switches on to pick a card / typed handle.
+ */
+declare const InteractionTypes: {
+    readonly SiteLogin: "site_login";
+    readonly Clarification: "clarification";
+    readonly Confirmation: "confirmation";
+    readonly TakeControl: "take_control";
+    readonly Wait: "wait";
+};
+type InteractionType = (typeof InteractionTypes)[keyof typeof InteractionTypes];
+/**
+ * Interaction lifecycle status (backend-authoritative):
+ * pending → active → resolved | expired | canceled.
+ */
+declare const InteractionStatuses: {
+    readonly Pending: "pending";
+    readonly Active: "active";
+    readonly Resolved: "resolved";
+    readonly Expired: "expired";
+    readonly Canceled: "canceled";
+};
+type InteractionStatus = (typeof InteractionStatuses)[keyof typeof InteractionStatuses];
+/**
+ * Action-contract kinds — what a consumer can do to an interaction.
+ * Each maps to a typed method on InteractionHandle.
+ */
+declare const ActionKinds: {
+    readonly answer: "answer";
+    readonly skip: "skip";
+    readonly confirm: "confirm";
+    readonly reject: "reject";
+    readonly openLogin: "open_login";
+    readonly confirmSignedIn: "confirm_signed_in";
+    readonly connectControl: "connect_control";
+    readonly refreshControl: "refresh_control";
+    readonly releaseControl: "release_control";
+    readonly retry: "retry";
+    readonly switchProfile: "switch_profile";
+};
+type ActionKind = (typeof ActionKinds)[keyof typeof ActionKinds];
+
+type JsonObject = Record<string, unknown>;
+type DelegationMode = "silent" | "interactive";
+type QoniService = "qoni" | "genauth" | "gumem" | "webagent";
+type QoniHttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+interface QoniOptions {
+    accessKey?: string;
+    secretKey?: string;
+    host?: string;
+    /** Overrides the GenAuth URL returned by runtime-config. Prefer host for normal discovery. */
+    genauthHost?: string;
+    /** Overrides the GUMem URL returned by runtime-config. Prefer host for normal discovery. */
+    gumemHost?: string;
+    /** Overrides the WebAgent URL returned by runtime-config. Prefer host for normal discovery. */
+    webAgentHost?: string;
+    /** @deprecated Use accessKey. */
+    accessKeyId?: string;
+    /** @deprecated Use secretKey. */
+    accessKeySecret?: string;
+    /** @deprecated Prefer host runtime discovery for normal Qoni Console gateway access. */
+    qoniBaseUrl?: string;
+    /** @deprecated Use host for normal Qoni Gateway access. */
+    genauthBaseUrl?: string;
+    /** @deprecated Use host for normal Qoni Gateway access. */
+    gumemBaseUrl?: string;
+    /** @deprecated Use host for normal Qoni Gateway access. */
+    webAgentBaseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    /**
+     * Max automatic reconnect attempts for SSE streams (`events()`) after a
+     * dropped connection. Each reconnect resumes from the last seen event id
+     * via the `last-event-id` header. Defaults to 5; set 0 to disable.
+     */
+    sseMaxRetries?: number;
+}
+interface QoniRuntimeConfig {
+    /** Current control-plane wire field. Keep until the server contract migrates. */
+    eakBaseUrl?: string;
+    genauthBaseUrl?: string;
+    gumemBaseUrl?: string;
+    webAgentBaseUrl?: string;
+    services?: {
+        eak?: string | {
+            baseUrl?: string;
+            url?: string;
+            host?: string;
+        };
+        genauth?: string | {
+            baseUrl?: string;
+            url?: string;
+            host?: string;
+        };
+        gumem?: string | {
+            baseUrl?: string;
+            url?: string;
+            host?: string;
+        };
+        webAgent?: string | {
+            baseUrl?: string;
+            url?: string;
+            host?: string;
+        };
+        webagent?: string | {
+            baseUrl?: string;
+            url?: string;
+            host?: string;
+        };
+    };
+}
+interface QoniMeta {
+    requestId?: string;
+    traceId?: string;
+    auditId?: string;
+    service?: QoniService;
+    [key: string]: unknown;
+}
+interface QoniResponse<T = unknown> {
+    data: T;
+    meta: QoniMeta;
+}
+interface UserRef {
+    id: string;
+    subject?: string;
+    name?: string;
+    email?: string;
+    avatarUrl?: string;
+    [key: string]: unknown;
+}
+interface DelegateTokenBaseInput {
+    /** Audit label for this delegation. Defaults to "sdk". */
+    agent?: string;
+    /** Fine-grained scopes. May be combined with `products`. */
+    scopes?: readonly string[];
+    /** Per-product authorization sugar — expands to the product's scope set. */
+    products?: readonly QoniProductName[];
+    expiresIn?: string | number;
+    idempotencyKey?: string;
+}
+/**
+ * Product names accepted by `delegateToken({ products })`. Mirrors
+ * `QoniProduct` in scopes.ts (duplicated to keep this module import-free).
+ */
+type QoniProductName = "doAnything" | "webSearch" | "deepResearch" | "track";
+type DelegateTokenSilentInput = DelegateTokenBaseInput & {
+    mode?: "silent";
+    redirectUri?: string;
+    state?: string;
+} & ({
+    user: UserRef;
+    /** @deprecated Use user. */
+    userId?: string;
+} | {
+    user?: UserRef;
+    /** @deprecated Use user. */
+    userId: string;
+});
+interface DelegateTokenInteractiveInput extends DelegateTokenBaseInput {
+    mode: "interactive";
+    redirectUri: string;
+    state: string;
+    user?: UserRef;
+    /** @deprecated Use user. */
+    userId?: string;
+}
+type DelegateTokenInput = DelegateTokenSilentInput | DelegateTokenInteractiveInput;
+/** @deprecated Use DelegateTokenInput. */
+type DelegateAgentInput = DelegateTokenInput;
+interface CompleteDelegateTokenInput {
+    grantId: string;
+    code: string;
+    state: string;
+}
+/** @deprecated Use CompleteDelegateTokenInput. */
+type CompleteDelegateAgentInput = CompleteDelegateTokenInput;
+interface DelegateTokenResponse {
+    mode: DelegationMode;
+    tokenType: "Bearer";
+    token: string;
+    /** @deprecated Use token. */
+    delegateAgentToken: string;
+    /** @deprecated Use token. */
+    delegationToken?: string;
+    expiresIn: number;
+    grantId: string;
+    auditId: string;
+    grantedScopes?: string[];
+}
+type DelegateTokenSilentResponse = DelegateTokenResponse & {
+    mode: "silent";
+};
+/** @deprecated Use DelegateTokenResponse. */
+type DelegateAgentTokenResponse = DelegateTokenResponse;
+/** @deprecated Use DelegateTokenResponse. */
+type DelegationTokenResponse = DelegateTokenResponse;
+interface InteractiveDelegationResponse {
+    mode: "interactive";
+    authorizationUrl: string;
+    grantId: string;
+    grantState: string;
+    state: string;
+    requestedScopes?: string[];
+}
+type DelegateAgentResponse = DelegateTokenResponse | InteractiveDelegationResponse;
+type DelegateTokenResult = DelegateAgentResponse;
+interface TokenInput {
+    /** Delegation/runtime token to authorize the call with. */
+    token?: string;
+}
+type RuntimeTokenInput = TokenInput;
+interface RawRequestInput extends TokenInput {
+    method: QoniHttpMethod;
+    path: string;
+    query?: JsonObject;
+    body?: JsonObject;
+    headers?: Record<string, string>;
+}
+interface RequestPayload {
+    query?: JsonObject;
+    body?: JsonObject | BodyInit;
+    headers?: Record<string, string>;
+    requiredScopes?: readonly string[];
+}
+interface QoniEvent<T = unknown> {
+    id?: string;
+    event?: string;
+    data: T;
+}
+type QoniSSEEvent<T = unknown> = QoniEvent<T>;
+interface QoniTransport {
+    qoniJson<T>(method: QoniHttpMethod, path: string, token?: string, payload?: RequestPayload): Promise<QoniResponse<T>>;
+    genauthJson<T>(method: QoniHttpMethod, path: string, token?: string, payload?: RequestPayload): Promise<QoniResponse<T>>;
+    gumemJson<T>(method: QoniHttpMethod, path: string, token?: string, payload?: RequestPayload): Promise<QoniResponse<T>>;
+    gumemSSE<T>(path: string, token?: string, payload?: RequestPayload & {
+        lastEventId?: string;
+        signal?: AbortSignal;
+    }): AsyncIterable<QoniEvent<T>>;
+    webAgentJson<T>(method: QoniHttpMethod, path: string, token?: string, payload?: RequestPayload): Promise<QoniResponse<T>>;
+    /** Binary GET — used for artifact content downloads. */
+    webAgentBytes(path: string, token?: string, payload?: RequestPayload): Promise<{
+        bytes: Uint8Array;
+        mime: string;
+    }>;
+    webAgentSSE<T>(path: string, token?: string, payload?: RequestPayload & {
+        lastEventId?: string;
+        signal?: AbortSignal;
+        onReconnect?: (info: {
+            attempt: number;
+            lastEventId?: string;
+            error: unknown;
+        }) => void;
+    }): AsyncIterable<QoniEvent<T>>;
+}
+
+/**
+ * Curated interaction surface (axis B of the interaction model, see
+ * webagentbackend/docs/qoni-interaction-model.md §2.3). A single wire event
+ * `run.interaction` carries the complete, typed object across its whole
+ * lifecycle (created / updated / resolved), discriminated by `type` and driven
+ * by a backend-authoritative `status`. This replaces the old `run.input_request`
+ * + `run.take_control_*` family — consumers no longer rebuild a state machine
+ * from an event sequence.
+ *
+ * Wire is snake_case; this layer is camelCase. The `actions[]` contract carries
+ * each action's endpoint, so the typed methods on {@link InteractionHandle}
+ * post to the right route without the consumer hard-coding any path — and a
+ * button/method only exists when the backend declared the action (structurally
+ * closing off "dead recovery affordances").
+ */
+/** A declared action a consumer can take on an interaction. */
+interface Action {
+    /** What this action does — maps to a typed method on {@link InteractionHandle}. */
+    kind: ActionKind;
+    /** Human-readable button label. */
+    label: string;
+    /** HTTP method to invoke the endpoint with (defaults to POST on the wire). */
+    method: string;
+    /** Endpoint to invoke (run-relative path); the consumer never hard-codes it. */
+    endpoint: string;
+    /** JSON schema for the action's input body, when the action needs one. */
+    inputSchema?: JsonObject | null;
+}
+/** Optional evidence image attached to an interaction. */
+interface InteractionEvidence {
+    artifactId: string;
+}
+/** A site the agent needs the user to sign in to (`site_login`). */
+interface InteractionSite {
+    siteId: string;
+    displayName: string;
+    loginUrl: string;
+}
+interface SiteLoginPayload {
+    sites: InteractionSite[];
+    /** Set when the login is for a Track monitor (monitor.needs_login reuse). */
+    monitorId?: string;
+}
+interface ClarificationPayload {
+    question: string;
+    /** Hint for how the answer should be collected (e.g. "text", "choice"). */
+    inputType?: string;
+}
+interface ConfirmationPayload {
+    summary: string;
+}
+interface TakeControlPayload {
+    liveUrl: string;
+    surface?: string;
+    reason?: string;
+}
+type WaitKind = "rate_limit" | "external" | "sleep";
+interface WaitPayload {
+    waitKind: WaitKind;
+    /** ISO 8601 — when the wait is expected to end. */
+    until?: string;
+    retryable?: boolean;
+}
+/** Maps each interaction `type` to its narrowed payload shape. */
+interface InteractionPayloadByType {
+    site_login: SiteLoginPayload;
+    clarification: ClarificationPayload;
+    confirmation: ConfirmationPayload;
+    take_control: TakeControlPayload;
+    wait: WaitPayload;
+}
+/**
+ * A typed interaction object. Generic over `type` so the `payload` narrows to
+ * the matching shape; the bare `Interaction` (T = InteractionType) is the union
+ * a consumer switches on.
+ */
+interface Interaction<T extends InteractionType = InteractionType> {
+    /** Stable identity across the interaction's lifecycle. */
+    id: string;
+    /** The discriminator — the single field a consumer switches on. */
+    type: T;
+    /** Backend-authoritative lifecycle status. */
+    status: InteractionStatus;
+    createdAt: string;
+    resolvedAt?: string | null;
+    expiresAt?: string | null;
+    /** Human-readable title (e.g. "Agent needs you to sign in"). */
+    title: string;
+    /** Detail / question text. */
+    prompt?: string | null;
+    /** Optional evidence image. */
+    evidence?: InteractionEvidence | null;
+    /** Declared actions — drives the typed methods + UI buttons. */
+    actions: Action[];
+    /** Type-specific fields. */
+    payload: InteractionPayloadByType[T];
+}
+/**
+ * Posts an interaction action to its declared endpoint. The product namespace
+ * supplies this (token + run addressing already bound); the handle below uses
+ * it to invoke `action.endpoint` without the consumer touching HTTP.
+ */
+type InteractionActionPoster = (action: Action, body: JsonObject | undefined) => Promise<void>;
+/**
+ * Typed wrapper over an {@link Interaction} that exposes one method per
+ * action kind. Each method finds the matching declared action and posts to its
+ * endpoint; calling a method whose action the backend did NOT declare throws
+ * (so "dead recovery affordances" are impossible — if you can call it, the
+ * backend offered it).
+ */
+declare class InteractionHandle<T extends InteractionType = InteractionType> {
+    private readonly post;
+    readonly interaction: Interaction<T>;
+    constructor(interaction: Interaction<T>, post: InteractionActionPoster);
+    get id(): string;
+    get type(): T;
+    get status(): InteractionStatus;
+    get actions(): Action[];
+    /** Whether the backend declared an action of this kind on the interaction. */
+    can(kind: ActionKind): boolean;
+    /** Answer a clarification ask. */
+    answer(text: string): Promise<void>;
+    /** Skip / dismiss the interaction (proceed without acting on it). */
+    skip(): Promise<void>;
+    /** Confirm a pending confirmation (approve the plan / destructive op). */
+    confirm(): Promise<void>;
+    /** Reject a pending confirmation. */
+    reject(): Promise<void>;
+    /** Open the login surface for a site_login interaction. */
+    openLogin(): Promise<void>;
+    /** Tell the agent the user has finished signing in. */
+    confirmSignedIn(): Promise<void>;
+    /** Connect to the live browser for a take_control interaction. */
+    connectControl(): Promise<void>;
+    /** Refresh the live control surface / live url. */
+    refreshControl(): Promise<void>;
+    /** Hand control back to the agent. */
+    releaseControl(): Promise<void>;
+    /** Retry a wait interaction now. */
+    retry(): Promise<void>;
+    /** Switch the profile a wait/login interaction is bound to. */
+    switchProfile(): Promise<void>;
+    /**
+     * Invoke an action by kind with an optional body. `async` so a missing-action
+     * error surfaces as a rejected promise (not a synchronous throw), keeping the
+     * method contract uniformly promise-based.
+     */
+    private invoke;
+}
+
+/**
+ * Semantic run events — the public event surface for doAnything / webSearch /
+ * deepResearch run handles and Track monitor handles. Wire envelopes
+ * (`{ type, task_id, session_id, occurred_at, data }`, snake_case payloads,
+ * data-URI screenshots) are normalized here; the original wire event stays
+ * reachable on `event.raw`.
+ */
+/**
+ * `QoniEventTypes` — the complete set of `event.type` values, as named
+ * constants. This is THE thing a developer matches on. Import it for
+ * autocomplete + typo-safety instead of hand-typing strings:
+ *
+ *     import { QoniEventTypes } from "@qoniai/qoni";
+ *     for await (const event of run.events()) {
+ *       switch (event.type) {
+ *         case QoniEventTypes.Results: …
+ *         case QoniEventTypes.Done: …
+ *       }
+ *     }
+ *
+ * The raw wire types (supervisor orchestration, sub-agent execution, protocol
+ * markers) are internal: all that churn folds into `QoniEventTypes.Progress`,
+ * and only the handful a developer reacts to get a distinct value. The exact
+ * wire string is on `event.raw.event` if ever needed.
+ */
+declare const QoniEventTypes: {
+    /** The agent is working — folds ALL internal steps (actions, plan/subtask, sections, telemetry, take-control, …); `event.data` is a best-effort human-readable line (string). */
+    readonly Progress: "progress";
+    /** The agent produced a user-facing chat message. */
+    readonly Message: "message";
+    /** HITL — a typed interaction needs the user (login / clarification / confirmation / take-control / wait); `event.data` is the full {@link Interaction} object. Act on it via the action methods (`run.interactionHandle(event.data).answer(…)` etc). */
+    readonly Interaction: "interaction";
+    /** A live screenshot frame (opt in with `capture: { screenshots: true }`); image on `event.image`. */
+    readonly Screenshot: "screenshot";
+    /** Terminal — the run finished; outcome + output in `event.data` (cost is on the `RunResult`). */
+    readonly Done: "done";
+    /** Web Search results are ready; `event.data` is the count (the list is in `done.output`). */
+    readonly ResultsReady: "resultsReady";
+    /** Deep Research coarse phase changed (brief → gather → synthesize …). */
+    readonly Phase: "phase";
+    /** A Deep Research outline section was completed (stream sections as they finish). */
+    readonly SectionReady: "sectionReady";
+    /** A Track monitor was created (e.g. Do Anything handed a recurring request to Track). */
+    readonly MonitorCreated: "monitorCreated";
+    /** A monitor detected a change worth acting on (the Track signal you react to). */
+    readonly Triggered: "triggered";
+    /** A monitor's scheduled check finished (`event.data` is whether it found a change). */
+    readonly CheckCompleted: "checkCompleted";
+};
+/** Every `event.type` value. Derived from {@link QoniEventTypes} — the single source. */
+type QoniEventType = (typeof QoniEventTypes)[keyof typeof QoniEventTypes];
+/** A decoded screenshot frame. `bytes` are the raw image bytes. */
+interface RunImage {
+    bytes: Uint8Array;
+    mime: string;
+    pageUrl?: string;
+    step?: number;
+}
+interface RunEventBase {
+    /** The run this event belongs to. */
+    runId: string;
+    /** ISO 8601 timestamp of when the event occurred. */
+    at: string;
+    /** The original wire event (escape hatch — shape may evolve with the API). */
+    raw: QoniEvent<unknown>;
+}
+/** `message` — an assistant/user chat message. */
+interface RunMessageData {
+    text: string;
+    role: string;
+}
+/** `screenshot` — page metadata; the decoded image is on `event.image`. */
+interface RunScreenshotData {
+    pageUrl?: string;
+    step?: number;
+}
+/** `done` — terminal outcome + final output. (Total cost is on the `RunResult`.) */
+interface RunDoneData {
+    output?: unknown;
+    succeeded: boolean | null;
+    terminalReason: string;
+}
+type RunEvent = (RunEventBase & {
+    type: "progress";
+    data: string;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "message";
+    data: RunMessageData;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "interaction";
+    data: Interaction;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "screenshot";
+    data: RunScreenshotData;
+    image: RunImage;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "done";
+    data: RunDoneData;
+    isTerminal: true;
+}) | (RunEventBase & {
+    type: "resultsReady";
+    data: number;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "phase";
+    data: string;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "sectionReady";
+    data: string;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "monitorCreated";
+    data: string;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "triggered";
+    data: string;
+    isTerminal: false;
+}) | (RunEventBase & {
+    type: "checkCompleted";
+    data: boolean;
+    isTerminal: false;
+});
+/** Events any product run can emit. */
+type CoreRunEvent = Extract<RunEvent, {
+    type: "progress" | "message" | "interaction" | "screenshot" | "done";
+}>;
+/** Do Anything — core events only. */
+type DoAnythingEvent = CoreRunEvent;
+/** Web Search — core + `resultsReady`. */
+type WebSearchEvent = CoreRunEvent | Extract<RunEvent, {
+    type: "resultsReady";
+}>;
+/** Deep Research — core + `phase` / `sectionReady`. */
+type DeepResearchEvent = CoreRunEvent | Extract<RunEvent, {
+    type: "phase" | "sectionReady";
+}>;
+/** Track monitor — core + `monitorCreated` / `triggered` / `checkCompleted`. */
+type MonitorEvent = CoreRunEvent | Extract<RunEvent, {
+    type: "monitorCreated" | "triggered" | "checkCompleted";
+}>;
+
+/** Opaque reference to a backend browser/context session a run executed in. */
+interface SessionRef {
+    sessionId: string;
+}
+/** Semantic capture switch — controls which media events the stream delivers. */
+interface CaptureOptions {
+    screenshots?: boolean;
+    videoFrames?: boolean;
+}
+interface RunEventsOptions {
+    lastEventId?: string;
+    signal?: AbortSignal;
+    /**
+     * Receives every original SSE frame before semantic normalization/filtering.
+     * Use this for audit logs and observability evidence that must retain internal
+     * Agent/tool lifecycle payloads. Some frames do not become semantic events.
+     */
+    onWireEvent?: (event: QoniEvent<unknown>) => void | Promise<void>;
+    /** Called whenever the SDK reconnects a dropped SSE stream. */
+    onReconnect?: (info: RunReconnectInfo) => void;
+}
+interface RunReconnectInfo {
+    attempt: number;
+    lastEventId?: string;
+    error: unknown;
+}
+/** A refreshed snapshot of a run's state, as returned by `run.status()`. */
+interface RunStatus {
+    id: string;
+    /** pending | running | awaiting_input | succeeded | failed | canceled */
+    status: string;
+    sessionId?: string;
+    output?: unknown;
+    /** Full wire run envelope (escape hatch — shape may evolve with the API). */
+    raw: JsonObject;
+}
+/** A deliverable produced by a run. Content is fetched lazily via `content()`. */
+interface Artifact {
+    id: string;
+    name?: string;
+    mime?: string;
+    sizeBytes?: number;
+    createdAt?: string;
+    content(): Promise<Uint8Array>;
+}
+/** Settled outcome of `run.wait()`. */
+interface RunResult {
+    runId: string;
+    status: "succeeded" | "failed" | "canceled";
+    /** Final answer / output payload (shape is task-specific). */
+    output?: unknown;
+    /** Deliverables (deepResearch reports etc). Empty array for products without artifacts. */
+    artifacts: Artifact[];
+    terminalReason?: string;
+    isTaskSuccessful?: boolean;
+    /** Full wire run envelope (escape hatch — shape may evolve with the API). */
+    raw: JsonObject;
+}
+interface RunWaitOptions {
+    /** Client-side wall-clock cap. On elapse, `wait` throws `QoniTimeoutError`; the run keeps executing server-side. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onEvent?: (event: RunEvent) => void | Promise<void>;
+    /** Every original SSE frame, including frames filtered from the semantic stream. */
+    onWireEvent?: (event: QoniEvent<unknown>) => void | Promise<void>;
+    /** Reconnect telemetry for the underlying resumable SSE stream. */
+    onReconnect?: (info: RunReconnectInfo) => void;
+    /**
+     * Fires on `event.type === "interaction"` (HITL). The handle exposes typed
+     * action methods (`interaction.answer(…)` / `confirmSignedIn()` /
+     * `releaseControl()` / …) that post to the action's declared endpoint.
+     */
+    onInteraction?: (interaction: InteractionHandle, event: RunEvent) => void | Promise<void>;
+    onScreenshot?: (image: RunImage, index: number) => void | Promise<void>;
+}
+/**
+ * Product-specific wire operations a `RunHandle` is built on. Each product
+ * namespace constructs one of these from its `api.*` escape-hatch methods
+ * with the token + run addressing already bound.
+ */
+interface RunWireOps {
+    getDetail(): Promise<JsonObject>;
+    streamEvents(opts: RunEventsOptions): AsyncIterable<QoniEvent<unknown>>;
+    /**
+     * Invoke an interaction action by posting to its declared endpoint. The
+     * Interaction model's `actions[]` carry the endpoint + method, so the SDK
+     * never hard-codes a HITL route — it forwards what the backend declared.
+     */
+    postAction(action: Action, body: JsonObject | undefined): Promise<void>;
+    cancel(reason?: string): Promise<JsonObject>;
+    /** Products without artifacts leave this undefined → `result.artifacts` is []. */
+    listArtifacts?(): Promise<Artifact[]>;
+}
+/**
+ * Handle to a single run. Generic over the product's event set (分型): a
+ * `RunHandle<DeepResearchEvent>` only ever yields Deep Research events, so
+ * `switch (event.type)` autocompletes just that product's events and a
+ * wrong-product case is a compile error. The runtime is identical across
+ * products; the generic only narrows the public type surface.
+ */
+declare class RunHandle<E extends RunEvent = RunEvent> {
+    #private;
+    private readonly ops;
+    readonly id: string;
+    /** Pass back to `run({ session })` to reuse the same backend session. */
+    sessionRef?: SessionRef;
+    private readonly capture;
+    constructor(ops: RunWireOps, init: {
+        id: string;
+        sessionRef?: SessionRef;
+        capture?: CaptureOptions;
+    });
+    /** Refresh and return the run's current state. */
+    status(): Promise<RunStatus>;
+    /**
+     * Stream semantic events. Ends automatically at the run's terminal event.
+     * Reconnects with `Last-Event-ID` catch-up are handled internally.
+     */
+    events(opts?: RunEventsOptions): AsyncIterable<E>;
+    /** Drive the run to a terminal state and return the settled result. */
+    wait(opts?: RunWaitOptions): Promise<RunResult>;
+    /**
+     * Wrap an {@link Interaction} (from `event.data` of an `interaction` event)
+     * in a typed {@link InteractionHandle} bound to this run. The handle's action
+     * methods (`answer` / `confirmSignedIn` / `releaseControl` / …) post to the
+     * endpoint the backend declared for that action.
+     */
+    interactionHandle(interaction: Interaction): InteractionHandle;
+    /**
+     * Cancel the run. Idempotent: cancelling an already-terminal run returns
+     * its terminal state instead of throwing.
+     */
+    cancel(reason?: string): Promise<RunStatus>;
+}
+
+/**
+ * A structured snapshot of the agent's state at a single step — not just an
+ * image. The screenshot is one field (an inline reference/data), alongside the
+ * metadata and extracted page state captured at that moment.
+ */
+interface DoAnythingSnapshot {
+    /** When the snapshot was captured (ISO 8601). */
+    capturedAt?: string;
+    /** Which step of the run this snapshot belongs to. */
+    stepIndex?: number;
+    /** The page the agent was on. */
+    url?: string;
+    /** Title of the page, if known. */
+    title?: string;
+    /** The screenshot image — carried in JSON (base64) and/or by reference. */
+    image?: SnapshotImage;
+    /** What the agent was doing at this step. */
+    action?: SnapshotAction;
+}
+interface SnapshotImage {
+    /** Base64-encoded image bytes (no data: prefix). */
+    base64?: string;
+    /** MIME type, e.g. "image/jpeg". */
+    contentType?: string;
+    /** Direct URL to the image, when the backend exposes one. */
+    url?: string;
+    /** Artifact id, when the image is stored as an artifact. */
+    artifactId?: string;
+    width?: number;
+    height?: number;
+}
+interface SnapshotAction {
+    /** "navigate" | "click" | "type" | ... */
+    kind?: string;
+    /** The element/URL/value the action targeted. */
+    target?: string;
+    /** Human-readable summary of the action. */
+    summary?: string;
+}
+interface RunLimits {
+    maxDurationMinutes?: number;
+}
+interface DoAnythingRunOptions {
+    /** Delegation token — passed once here; the returned handle holds it. */
+    token: string;
+    /** Natural-language task for the agent to carry out. */
+    prompt: string;
+    capture?: CaptureOptions;
+    limits?: RunLimits;
+    /**
+     * Reuse an existing browser session (follow-up run); a new one is created
+     * around the run by default. Maps to `session_id` on the wire create body.
+     */
+    session?: SessionRef;
+    profileId?: string;
+    keepAlive?: boolean;
+    allowedActions?: string[];
+    skills?: string[];
+    [key: string]: unknown;
+}
+interface DoAnythingAttachOptions {
+    token: string;
+    /**
+     * Optional — runs are addressed by `run_id` alone; resolution happens via
+     * `GET /do_anything/runs/{run_id}`. Accepted for callers that already hold
+     * a `sessionRef`; otherwise it is adopted from the run detail envelope.
+     */
+    session?: SessionRef;
+    capture?: CaptureOptions;
+}
+declare function createDoAnythingNamespace(transport: QoniTransport): {
+    /** Start a run. Returns a handle — see `RunHandle` for the run lifecycle. */
+    run: (input: DoAnythingRunOptions) => Promise<RunHandle<DoAnythingEvent>>;
+    /**
+     * Reconnect to an existing run by id. Verifies the run exists before
+     * returning; `sessionRef` is adopted from the run detail envelope when
+     * not supplied.
+     */
+    attach: (runId: string, opts: DoAnythingAttachOptions) => Promise<RunHandle<DoAnythingEvent>>;
+    api: {
+        createSession: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+        /**
+         * `POST /do_anything/runs` — one call creates the run. Without
+         * `session_id` a fresh session is created around the run; with it the
+         * run is a follow-up in that session (409 while the prior run is
+         * non-terminal).
+         */
+        createRun: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+        getRun: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+        }) => Promise<QoniResponse<T>>;
+        events: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+            lastEventId?: string;
+            signal?: AbortSignal;
+            /**
+             * Forwarded as the `include_screenshots` query flag — set false to
+             * skip `run.screenshot` rows in the replay/backfill window.
+             */
+            includeScreenshots?: boolean;
+            /**
+             * Drop events for internal sub-runs (planning / grading) and yield only
+             * the top-level run's events. Matches on `event.data.task_id`.
+             * Default false.
+             */
+            onlyTopLevel?: boolean;
+            onReconnect?: (info: {
+                attempt: number;
+                lastEventId?: string;
+                error: unknown;
+            }) => void;
+        }) => AsyncIterable<QoniEvent<T>>;
+        intervene: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+        } & JsonObject) => Promise<QoniResponse<T>>;
+        cancel: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+            reason?: string;
+        }) => Promise<QoniResponse<T>>;
+        readArtifacts: <T = DoAnythingSnapshot>(input: RuntimeTokenInput & {
+            sessionId: string;
+            artifactId: string;
+        }) => Promise<QoniResponse<T>>;
+        readRecording: <T = unknown>(input: RuntimeTokenInput & {
+            sessionId: string;
+        }) => Promise<QoniResponse<T>>;
+    };
+};
+
+interface DeepResearchRunOptions {
+    /** Delegation token — passed once here; the returned handle holds it. */
+    token: string;
+    /** The research topic. */
+    prompt: string;
+    capture?: CaptureOptions;
+    limits?: RunLimits;
+    /**
+     * Reuse an existing research session — a follow-up run that inherits the
+     * prior run's context. Pass `prior.sessionRef`.
+     */
+    session?: SessionRef;
+    depth?: "light" | "standard" | "deep";
+    outputFormat?: string;
+    targetAudience?: string;
+    domainWhitelist?: string[];
+    domainBlacklist?: string[];
+    [key: string]: unknown;
+}
+interface DeepResearchAttachOptions {
+    token: string;
+    capture?: CaptureOptions;
+}
+/**
+ * DeepResearch capability namespace — runs are created with a research
+ * `topic`, gated by an optional HITL outline approval, then stream events
+ * until a cited report is produced. Mirrors the backend contract at
+ * `/api/v1/projects/{tenant}/deep_research/...`.
+ */
+declare function createDeepResearchNamespace(transport: QoniTransport): {
+    /**
+     * Start a research run. Pass `session: prior.sessionRef` to start a
+     * follow-up run that inherits the prior run's context.
+     */
+    run: (input: DeepResearchRunOptions) => Promise<RunHandle<DeepResearchEvent>>;
+    /** Reconnect to an existing run. Verifies the run exists before returning. */
+    attach: (runId: string, opts: DeepResearchAttachOptions) => Promise<RunHandle<DeepResearchEvent>>;
+    api: {
+        run: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+        get: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+        }) => Promise<QoniResponse<T>>;
+        events: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+            lastEventId?: string;
+            signal?: AbortSignal;
+            onReconnect?: (info: {
+                attempt: number;
+                lastEventId?: string;
+                error: unknown;
+            }) => void;
+        }) => AsyncIterable<QoniEvent<T>>;
+        followUp: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+            text: string;
+        }) => Promise<QoniResponse<T>>;
+        cancel: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+        }) => Promise<QoniResponse<T>>;
+        feedback: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+        } & JsonObject) => Promise<QoniResponse<T>>;
+        listArtifacts: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+        }) => Promise<QoniResponse<T>>;
+        getArtifact: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+            artifactId: string;
+        }) => Promise<QoniResponse<T>>;
+    };
+};
+
+type DelegateToken = {
+    (input: DelegateTokenInteractiveInput): Promise<QoniResponse<InteractiveDelegationResponse>>;
+    (input: DelegateTokenSilentInput): Promise<QoniResponse<DelegateTokenSilentResponse>>;
+    (input: DelegateTokenInput): Promise<QoniResponse<DelegateAgentResponse>>;
+};
+type CompleteDelegateToken = (input: CompleteDelegateTokenInput) => Promise<QoniResponse<DelegateTokenResponse>>;
+declare function createQoniNamespace(_transport: QoniTransport, delegateToken: DelegateToken, completeDelegateToken: CompleteDelegateToken): {
+    delegateToken: DelegateToken;
+    /** @deprecated Use delegateToken. */
+    delegateAgent: (input: DelegateAgentInput) => Promise<QoniResponse<DelegateAgentResponse>>;
+    completeDelegateToken: CompleteDelegateToken;
+    /** @deprecated Use completeDelegateToken. */
+    completeDelegateAgent: (input: CompleteDelegateAgentInput) => Promise<QoniResponse<DelegateTokenResponse>>;
+};
+
+interface GenAuthAccessTokenInput {
+    accessToken: string;
+}
+interface GenAuthDelegationIntrospectionInput {
+    token?: string;
+    /** @deprecated Use token. */
+    delegateAgentToken?: string;
+}
+interface GenAuthAdminToken {
+    accessToken: string;
+    userPoolId: string;
+}
+type GenAuthAdminTokenProvider = () => Promise<GenAuthAdminToken>;
+interface GenAuthAdminTokenOverrideInput {
+    adminToken?: string;
+    userPoolId?: string;
+}
+type GenAuthUserListInput = GenAuthAdminTokenOverrideInput & {
+    page?: number;
+    limit?: number;
+    options?: JsonObject & {
+        pagination?: JsonObject;
+    };
+} & JsonObject;
+type GenAuthUserGetInput = GenAuthAdminTokenOverrideInput & {
+    userId: string;
+};
+type GenAuthUserGetBatchInput = GenAuthAdminTokenOverrideInput & {
+    userIds: string[];
+};
+type GenAuthUserCreateInput = GenAuthAdminTokenOverrideInput & JsonObject;
+type GenAuthUserCreateBatchInput = GenAuthAdminTokenOverrideInput & {
+    users?: JsonObject[];
+    list?: JsonObject[];
+    options?: JsonObject;
+};
+type GenAuthUserUpdateInput = GenAuthAdminTokenOverrideInput & {
+    userId: string;
+} & JsonObject;
+type GenAuthUserDeleteBatchInput = GenAuthAdminTokenOverrideInput & {
+    userIds: string[];
+};
+declare function createGenAuthNamespace(transport: QoniTransport, options?: {
+    adminTokenFor?: GenAuthAdminTokenProvider;
+}): {
+    userInfo: <T = unknown>(input: GenAuthAccessTokenInput) => Promise<QoniResponse<T>>;
+    jwks: <T = unknown>() => Promise<QoniResponse<T>>;
+    discovery: <T = unknown>() => Promise<QoniResponse<T>>;
+    introspectDelegationToken: <T = unknown>(input: GenAuthDelegationIntrospectionInput) => Promise<QoniResponse<T>>;
+    users: {
+        list: <T = unknown>(input?: GenAuthUserListInput) => Promise<QoniResponse<T>>;
+        get: <T = unknown>(input: GenAuthUserGetInput) => Promise<QoniResponse<T>>;
+        getBatch: <T = unknown>(input: GenAuthUserGetBatchInput) => Promise<QoniResponse<T>>;
+        create: <T = unknown>(input: GenAuthUserCreateInput) => Promise<QoniResponse<T>>;
+        createBatch: <T = unknown>(input: GenAuthUserCreateBatchInput) => Promise<QoniResponse<T>>;
+        update: <T = unknown>(input: GenAuthUserUpdateInput) => Promise<QoniResponse<T>>;
+        deleteBatch: <T = unknown>(input: GenAuthUserDeleteBatchInput) => Promise<QoniResponse<T>>;
+    };
+};
+
+interface GumemCreateSessionInput extends RuntimeTokenInput {
+    userId?: string;
+    sessionId?: string;
+    /** @deprecated Use userId. */
+    user_id?: string;
+    /** @deprecated Use sessionId. */
+    session_id?: string;
+    title?: string;
+    metadata?: JsonObject;
+}
+interface GumemAddMessagesInput extends RuntimeTokenInput {
+    sessionId: string;
+    messages: JsonObject[];
+    sync?: boolean;
+    userId?: string;
+    /** @deprecated Use userId. */
+    user_id?: string;
+}
+interface GumemRecallInput extends RuntimeTokenInput {
+    sessionId?: string;
+    query?: string;
+    details?: boolean;
+    recallConfig?: JsonObject;
+    metadataFilters?: JsonObject;
+    /** @deprecated Use recallConfig. */
+    recall_config?: JsonObject;
+    /** @deprecated Use metadataFilters. */
+    metadata_filters?: JsonObject;
+}
+interface GumemUploadResourceInput extends RuntimeTokenInput {
+    userId?: string;
+    sessionId?: string;
+    /** @deprecated Use userId. */
+    user_id?: string;
+    /** @deprecated Use sessionId. */
+    session_id?: string;
+    file: Blob | File;
+    filename?: string;
+    contentType?: string;
+}
+declare function createGumemNamespace(transport: QoniTransport): {
+    createSession: <T = unknown>(input: GumemCreateSessionInput) => Promise<QoniResponse<T>>;
+    addMessages: <T = unknown>(input: GumemAddMessagesInput) => Promise<QoniResponse<T>>;
+    recall: <T = unknown>(input: GumemRecallInput) => Promise<QoniResponse<T>>;
+    uploadResource: <T = unknown>(input: GumemUploadResourceInput) => Promise<QoniResponse<T>>;
+    actions: {
+        record: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+        recall: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+        stream: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+    };
+};
+
+interface TrackCreateOptions {
+    /** Delegation token — passed once here; the returned handle holds it. */
+    token: string;
+    /** Natural-language description of what to monitor. */
+    prompt: string;
+    /** Rest of the monitor definition (url, schedule, …) — camelCase keys. */
+    [key: string]: unknown;
+}
+interface TrackAttachOptions {
+    token: string;
+}
+interface MonitorEventsOptions {
+    lastEventId?: string;
+    signal?: AbortSignal;
+}
+interface MonitorRunsOptions {
+    limit?: number;
+    offset?: number;
+}
+/** A monitor's check cadence. */
+type MonitorSchedule = {
+    kind: "cron";
+    expr: string;
+} | {
+    kind: "interval";
+    intervalSeconds: number;
+};
+/**
+ * Fields to change on a monitor via {@link MonitorHandle.refine}. Pass any
+ * subset; at least one is required. The monitor's natural-language `intent`
+ * is NOT refinable — it drives URL/schema/DSL generation, so changing it means
+ * creating a new monitor.
+ */
+interface MonitorRefinePatch {
+    schedule?: MonitorSchedule;
+    targetUrls?: string[];
+    extractionSchema?: JsonObject;
+    triggerDsl?: JsonObject;
+    stopConditionDsl?: JsonObject;
+    notifyChannel?: JsonObject | null;
+    [key: string]: unknown;
+}
+interface MonitorWireOps {
+    get(): Promise<JsonObject>;
+    update(input: JsonObject): Promise<JsonObject>;
+    runNow(): Promise<JsonObject>;
+    streamEvents(opts: MonitorEventsOptions): AsyncIterable<QoniEvent<unknown>>;
+    postAction(action: Action, body: JsonObject | undefined): Promise<void>;
+    listRuns(opts: MonitorRunsOptions): Promise<JsonObject>;
+    getRun(runId: string): Promise<JsonObject>;
+    delete(): Promise<void>;
+}
+/**
+ * Handle to a Track monitor — a resident resource (unlike a one-shot run).
+ * Holds the delegation token and monitor id internally; no method takes a
+ * token or an id.
+ */
+declare class MonitorHandle {
+    private readonly ops;
+    readonly id: string;
+    constructor(ops: MonitorWireOps, id: string);
+    /** Refresh and return the monitor (normalized camelCase fields). */
+    get(): Promise<JsonObject>;
+    /**
+     * Pause the monitor — stops scheduled ticks until {@link resume}. The
+     * monitor stays addressable; this is the way to "stop monitoring" without
+     * deleting.
+     */
+    pause(): Promise<JsonObject>;
+    /** Resume a paused monitor. */
+    resume(): Promise<JsonObject>;
+    /**
+     * Change the monitor definition. Pass any subset of fields (at least one);
+     * `schedule` is `{ kind: "cron", expr }` or `{ kind: "interval", intervalSeconds }`.
+     * The backend re-validates the trigger DSL against the schema, so a bad
+     * change is rejected, not applied. The natural-language intent is not
+     * refinable — create a new monitor to change it.
+     */
+    refine(patch: MonitorRefinePatch): Promise<JsonObject>;
+    /** Trigger an immediate tick outside the schedule. */
+    runNow(): Promise<JsonObject>;
+    /**
+     * Stream semantic monitor events. Monitors are resident, so the stream has
+     * no terminal event — it ends only when closed by the caller or the server.
+     */
+    events(opts?: MonitorEventsOptions): AsyncIterable<MonitorEvent>;
+    /**
+     * Wrap an {@link Interaction} (from `event.data` of an `interaction` event on
+     * the monitor stream — e.g. a `site_login` to unlock a `needs_reauth` park)
+     * in a typed {@link InteractionHandle}. The handle's action methods post to
+     * the endpoint the backend declared for that action.
+     */
+    interactionHandle(interaction: Interaction): InteractionHandle;
+    /**
+     * Read-only list of the runs the monitor's ticks produced. Tick runs are
+     * owned by the scheduler — to stop monitoring use `pause()` / `delete()`.
+     */
+    runs(opts?: MonitorRunsOptions): Promise<JsonObject[]>;
+    /** Read-only detail of a single tick run. */
+    run(runId: string): Promise<JsonObject>;
+    /** Delete the monitor. */
+    delete(): Promise<void>;
+}
+declare function createTrackNamespace(transport: QoniTransport): {
+    /** Create a monitor. Returns a handle — see `MonitorHandle`. */
+    create: (input: TrackCreateOptions) => Promise<MonitorHandle>;
+    /** Reconnect to an existing monitor. Verifies it exists before returning. */
+    attach: (monitorId: string, opts: TrackAttachOptions) => Promise<MonitorHandle>;
+    api: {
+        createMonitor: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+        getMonitor: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+        }) => Promise<QoniResponse<T>>;
+        runNow: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+        }) => Promise<QoniResponse<T>>;
+        events: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+            lastEventId?: string;
+            signal?: AbortSignal;
+        }) => AsyncIterable<QoniEvent<T>>;
+        intervene: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+        } & JsonObject) => Promise<QoniResponse<T>>;
+        listRuns: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<QoniResponse<T>>;
+        getRun: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+            runId: string;
+        }) => Promise<QoniResponse<T>>;
+        updateMonitor: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+        } & JsonObject) => Promise<QoniResponse<T>>;
+        deleteMonitor: <T = unknown>(input: RuntimeTokenInput & {
+            monitorId: string;
+        }) => Promise<QoniResponse<T>>;
+    };
+};
+
+interface WebSearchRunOptions {
+    /** Delegation token — passed once here; the returned handle holds it. */
+    token: string;
+    /** What to search for — one query, or several for a multi-query search. */
+    prompt: string | string[];
+    capture?: CaptureOptions;
+    /** Not supported by webSearch yet — passing it throws locally. */
+    limits?: RunLimits;
+    /** Not supported by webSearch — searches don't run in reusable sessions. */
+    session?: SessionRef;
+    maxResultsPerQuery?: number;
+    siteWhitelist?: string[];
+    siteBlacklist?: string[];
+    [key: string]: unknown;
+}
+interface WebSearchAttachOptions {
+    token: string;
+    capture?: CaptureOptions;
+}
+declare function createWebSearchNamespace(transport: QoniTransport): {
+    /** Start a search run. Returns a handle — see `RunHandle` for the run lifecycle. */
+    run: (input: WebSearchRunOptions) => Promise<RunHandle<WebSearchEvent>>;
+    /** Reconnect to an existing run. Verifies the run exists before returning. */
+    attach: (runId: string, opts: WebSearchAttachOptions) => Promise<RunHandle<WebSearchEvent>>;
+    api: {
+        run: <T = unknown>(input: RuntimeTokenInput & JsonObject) => Promise<QoniResponse<T>>;
+        get: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+        }) => Promise<QoniResponse<T>>;
+        events: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+            lastEventId?: string;
+            signal?: AbortSignal;
+            onReconnect?: (info: {
+                attempt: number;
+                lastEventId?: string;
+                error: unknown;
+            }) => void;
+        }) => AsyncIterable<QoniEvent<T>>;
+        cancel: <T = unknown>(input: RuntimeTokenInput & {
+            runId: string;
+            reason?: string;
+        }) => Promise<QoniResponse<T>>;
+    };
+};
+
+declare class QoniAgentKit {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly sseMaxRetries;
+    private readonly accessKey;
+    private readonly secretKey;
+    private readonly host;
+    private runtimeConfigPromise?;
+    private readonly productTokenCache;
+    private genAuthAdminTokenCache?;
+    readonly gumem: ReturnType<typeof createGumemNamespace>;
+    readonly genauth: ReturnType<typeof createGenAuthNamespace>;
+    readonly qoni: ReturnType<typeof createQoniNamespace>;
+    readonly webSearch: ReturnType<typeof createWebSearchNamespace>;
+    readonly doAnything: ReturnType<typeof createDoAnythingNamespace>;
+    readonly track: ReturnType<typeof createTrackNamespace>;
+    readonly deepResearch: ReturnType<typeof createDeepResearchNamespace>;
+    constructor(options: QoniOptions);
+    delegateToken(input: DelegateTokenInteractiveInput): Promise<QoniResponse<InteractiveDelegationResponse>>;
+    delegateToken(input: DelegateTokenSilentInput): Promise<QoniResponse<DelegateTokenSilentResponse>>;
+    delegateToken(input: DelegateTokenInput): Promise<QoniResponse<DelegateAgentResponse>>;
+    /** @deprecated Use delegateToken. */
+    delegateAgent(input: DelegateAgentInput): Promise<QoniResponse<DelegateAgentResponse>>;
+    completeDelegateToken(input: CompleteDelegateTokenInput): Promise<QoniResponse<DelegateTokenResponse>>;
+    /** @deprecated Use completeDelegateToken. */
+    completeDelegateAgent(input: CompleteDelegateAgentInput): Promise<QoniResponse<DelegateTokenResponse>>;
+    currentUser<T = unknown>(input: GenAuthAccessTokenInput): Promise<QoniResponse<T>>;
+    /**
+     * Resolve a real GenAuth user id from the userpool bound to this AK/SK, by
+     * listing users and returning the first one. Convenience for demos / smoke
+     * tests so `delegateToken` has a valid `userId` without hardcoding one. In
+     * application code, resolve the actual logged-in user via `currentUser`
+     * instead of picking an arbitrary userpool member.
+     */
+    resolveAnyBoundUser(): Promise<string>;
+    request<T = unknown>(input: RawRequestInput): Promise<QoniResponse<T>>;
+    unstableRequest<T = unknown>(input: RawRequestInput): Promise<QoniResponse<T>>;
+    private qoniJson;
+    private genauthJson;
+    private gumemJson;
+    private gumemSSE;
+    private webAgentJson;
+    private webAgentBytes;
+    private webAgentSSE;
+    private signedPost;
+    private jsonRequest;
+    private sseRequest;
+    private sseConnectOnce;
+    private fetchWithTimeout;
+    private baseUrlFor;
+    private explicitBaseUrlFor;
+    private runtimeConfig;
+    private fetchRuntimeConfig;
+    private webAgentPath;
+    private productTokenFor;
+    private genauthAdminTokenFor;
+}
+
+/**
+ * Known `QoniError.code` values. The SDK assigns the `*.*` codes; the `eak.*`
+ * codes are backend apiCodes surfaced verbatim. The trailing `(string & {})`
+ * keeps `code` assignable from any string (the backend may add new codes)
+ * while still giving literal autocomplete and letting you write an exhaustive
+ * `switch (err.code)` over the known set.
+ */
+type QoniErrorCode = "qoni_error" | "auth.failed" | "delegation.required" | "permission_denied" | "token.expired" | "validation.failed" | "rate_limit.exceeded" | "upstream.failed" | "timeout" | "not_found" | "conflict" | "eak.delegation.user_not_bound" | "eak.genauth.userpool_binding_missing" | "eak.genauth.userpool_owner_missing" | "eak.genauth.no_bound_users" | "eak.token_exchange.upstream_failed" | (string & {});
+interface QoniErrorOptions {
+    code?: QoniErrorCode;
+    status?: number;
+    requestId?: string;
+    traceId?: string;
+    auditId?: string;
+    retryable?: boolean;
+    body?: unknown;
+    cause?: unknown;
+}
+declare class QoniError extends Error {
+    readonly code: QoniErrorCode;
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly traceId?: string;
+    readonly auditId?: string;
+    readonly retryable: boolean;
+    readonly body?: unknown;
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniAuthError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniDelegationRequiredError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniPermissionDeniedError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniTokenExpiredError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniValidationError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniRateLimitError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniUpstreamError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+declare class QoniTimeoutError extends QoniError {
+    constructor(message: string, options?: QoniErrorOptions);
+}
+
+declare const QoniScopes: {
+    readonly GUMEM_SESSION_CREATE: "gumem.session:create";
+    readonly GUMEM_MESSAGE_WRITE: "gumem.message:write";
+    readonly GUMEM_MEMORY_READ: "gumem.memory:read";
+    readonly GUMEM_MEMORY_WRITE: "gumem.memory:write";
+    readonly GUMEM_MEMORY_DELETE: "gumem.memory:delete";
+    readonly GUMEM_SEARCH_RUN: "gumem.search:run";
+    readonly GUMEM_ADMIN_MANAGE: "gumem.admin:manage";
+    readonly GUMEM_RESOURCE_WRITE: "gumem.resource:write";
+    readonly GUMEM_ACTION_WRITE: "gumem.action:write";
+    readonly GUMEM_ACTION_READ: "gumem.action:read";
+    readonly GUMEM_PROFILE_READ: "gumem.profile:read";
+    readonly DO_ANYTHING_READ: "webagent.do_anything:read";
+    readonly DO_ANYTHING_MANAGE: "webagent.do_anything:manage";
+    readonly WEB_SEARCH_READ: "webagent.web_search:read";
+    readonly WEB_SEARCH_MANAGE: "webagent.web_search:manage";
+    readonly DEEP_RESEARCH_READ: "webagent.deep_research:read";
+    readonly DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage";
+    readonly TRACK_READ: "webagent.track:read";
+    readonly TRACK_MANAGE: "webagent.track:manage";
+};
+type QoniScope = (typeof QoniScopes)[keyof typeof QoniScopes];
+/** Product names accepted by `delegateToken({ products })`. */
+type QoniProduct = "doAnything" | "webSearch" | "deepResearch" | "track";
+/**
+ * Scope sets granted by the `delegateToken({ products })` sugar — each
+ * product expands to its full verb pair: `read` + `manage`.
+ */
+declare const QoniProductScopes: Record<QoniProduct, readonly QoniScope[]>;
+declare const QoniScopeBundles: {
+    readonly GUMEM_READONLY: readonly ["gumem.memory:read", "gumem.profile:read"];
+    readonly GUMEM_SESSION_RECALL: readonly ["gumem.memory:read", "gumem.memory:write", "gumem.message:write"];
+    readonly GUMEM_WRITE: readonly ["gumem.session:create", "gumem.message:write", "gumem.action:write"];
+    readonly DO_ANYTHING: readonly ["webagent.do_anything:read", "webagent.do_anything:manage"];
+    readonly WEB_SEARCH: readonly ["webagent.web_search:read", "webagent.web_search:manage"];
+    readonly DEEP_RESEARCH: readonly ["webagent.deep_research:read", "webagent.deep_research:manage"];
+    readonly TRACK: readonly ["webagent.track:read", "webagent.track:manage"];
+};
+
+export { type Action, type ActionKind, ActionKinds, type Artifact, type CaptureOptions, type ClarificationPayload, type CompleteDelegateAgentInput, type CompleteDelegateTokenInput, type ConfirmationPayload, type CoreRunEvent, type DeepResearchAttachOptions, type DeepResearchEvent, type DeepResearchRunOptions, type DelegateAgentInput, type DelegateAgentResponse, type DelegateAgentTokenResponse, type DelegateTokenInput, type DelegateTokenInteractiveInput, type DelegateTokenResponse, type DelegateTokenResult, type DelegateTokenSilentInput, type DelegateTokenSilentResponse, type DelegationMode, type DelegationTokenResponse, type DoAnythingAttachOptions, type DoAnythingEvent, type DoAnythingRunOptions, type DoAnythingSnapshot, type GenAuthAccessTokenInput, type GenAuthAdminToken, type GenAuthAdminTokenOverrideInput, type GenAuthDelegationIntrospectionInput, type GenAuthUserCreateBatchInput, type GenAuthUserCreateInput, type GenAuthUserDeleteBatchInput, type GenAuthUserGetBatchInput, type GenAuthUserGetInput, type GenAuthUserListInput, type GenAuthUserUpdateInput, type Interaction, type InteractionEvidence, InteractionHandle, type InteractionPayloadByType, type InteractionSite, type InteractionStatus, InteractionStatuses, type InteractionType, InteractionTypes, type InteractiveDelegationResponse, type JsonObject, type MonitorEvent, type MonitorEventsOptions, MonitorHandle, type MonitorRunsOptions, QoniAgentKit as Qoni, QoniAgentKit, QoniAuthError, QoniDelegationRequiredError, QoniError, type QoniErrorCode, type QoniErrorOptions, type QoniEvent, type QoniEventType, QoniEventTypes, type QoniMeta, type QoniOptions, QoniPermissionDeniedError, type QoniProduct, type QoniProductName, QoniProductScopes, QoniRateLimitError, type QoniResponse, type QoniRuntimeConfig, type QoniSSEEvent, QoniScopeBundles, QoniScopes, QoniTimeoutError, QoniTokenExpiredError, QoniUpstreamError, QoniValidationError, type RawRequestInput, type RunDoneData, type RunEvent, type RunEventsOptions, RunHandle, type RunImage, type RunLimits, type RunMessageData, type RunReconnectInfo, type RunResult, type RunScreenshotData, type RunStatus, type RunWaitOptions, type RuntimeTokenInput, type SessionRef, type SiteLoginPayload, type SnapshotAction, type SnapshotImage, type TakeControlPayload, type TokenInput, type TrackAttachOptions, type TrackCreateOptions, type WaitKind, type WaitPayload, type WebSearchAttachOptions, type WebSearchEvent, type WebSearchRunOptions, buildAuthorization, buildSignature, buildStringToSign };