@smoothcodes/agent-client 0.0.0-stage → 0.1.1

package/dist/types/sdk/ts/core-live/src/edge.d.ts

@@ -0,0 +1,73 @@
+import type { LiveDeps } from './deps.js';
+export type Env = [now: number, online: boolean, visible: boolean, rand: number];
+/** As entradas que todo núcleo (LiveSession, LiveWatch) aceita; cada uma devolve os efeitos em JSON. */
+export interface CoreLike {
+    tick(...e: Env): string;
+    on_open(...a: [...Env, number]): string;
+    on_message(...a: [...Env, number, string]): string;
+    on_error(...a: [...Env, number]): string;
+    on_close(...a: [...Env, number, number, string]): string;
+    on_open_failed(...a: [...Env, number]): string;
+    on_token(...a: [...Env, number, boolean, string]): string;
+    on_probe(...a: [...Env, number, boolean, string]): string;
+    on_range(...a: [...Env, number, boolean, string, number, number]): string;
+    on_snapshot(...a: [...Env, number, boolean, string]): string;
+    next_deadline(): number;
+}
+export type IoFx = {
+    k: 'token' | 'probe' | 'snapshot';
+    req: number;
+} | {
+    k: 'invalidateToken';
+} | {
+    k: 'range';
+    req: number;
+    from: number;
+    to: number;
+} | {
+    k: 'open';
+    conn: number;
+    via: string;
+    url: string;
+    protocols: string[];
+} | {
+    k: 'send';
+    conn: number;
+    text: string;
+} | {
+    k: 'close';
+    conn: number;
+    code: number;
+    reason: string;
+};
+/** Um efeito que não é IO (cada casca trata os seus). */
+export type OtherFx = {
+    k: string;
+    [x: string]: unknown;
+};
+export declare class Edge<C extends CoreLike> {
+    private readonly d;
+    private readonly chatId;
+    private readonly random;
+    private readonly handle;
+    private readonly sockets;
+    private timer;
+    private stopped;
+    /** O núcleo desta casca; `null` até o wasm carregar (as entradas esperam em `pending`, em ordem). */
+    core: C | null;
+    private pending;
+    constructor(make: () => C, d: LiveDeps, chatId: string, random: () => number, handle: (f: OtherFx) => void);
+    /** Roda `fn` com o núcleo: na hora se já carregou, senão na ordem em que foi pedido, quando carregar. */
+    when(fn: (c: C) => void): void;
+    env(): Env;
+    /** Uma entrada pro núcleo; executa os efeitos devolvidos, em ordem; re-arma o timer. */
+    run(input: (c: C, e: Env) => string): void;
+    /** Executa uma lista de efeitos já devolvida (quando quem chamou precisou do JSON antes). */
+    exec(fx: Array<IoFx | OtherFx>): void;
+    /** Para tudo (depois do close do núcleo): sem timer, sem novas entradas. */
+    stop(): void;
+    private arm;
+    private disarm;
+    private one;
+    private open;
+}

package/dist/types/sdk/ts/core-live/src/feed.d.ts

@@ -0,0 +1,66 @@
+import type { Clock, LiveEnv, OpenSocket } from './deps.js';
+import type { BoxPresence } from './types.js';
+export interface ChatRow {
+    chatId: string;
+    agentId: string;
+    title?: string;
+    state: string;
+    waiting?: 'approval' | 'question' | 'input';
+    box?: BoxPresence;
+    lastEventSeq: number;
+    updatedAt: string;
+    lastReadSeq: number;
+    unreadCount: number;
+}
+export type FeedFrame = {
+    t: 'feed';
+    version: number;
+    rows: ChatRow[];
+} | {
+    t: 'row';
+    version: number;
+    row: ChatRow;
+} | {
+    t: 'removed';
+    version: number;
+    chatId: string;
+} | {
+    t: 'hello';
+    tokenExpiresAt?: number;
+} | {
+    t: 'bye';
+    reason: string;
+    reconnect: string;
+} | {
+    t: 'pong';
+};
+export type FeedStatus = 'connecting' | 'live' | 'reconnecting' | 'offline' | 'auth_failed' | 'forbidden' | 'closed';
+export interface FeedState {
+    version: number;
+    /** Ordenadas por `updatedAt` (mais recente primeiro), já filtradas por agente se pedido. */
+    rows: ChatRow[];
+    status: FeedStatus;
+}
+export interface FeedDeps {
+    url: string;
+    openSocket: OpenSocket;
+    token(): Promise<string>;
+    invalidateToken?(): void;
+    clock: Clock;
+    env: LiveEnv;
+}
+/** CASCA FINA sobre o núcleo Rust (`Feed`): a borda comum executa o IO; o estado chega pronto. */
+export declare class ChatListLive {
+    private readonly d;
+    private readonly edge;
+    private state;
+    private readonly listeners;
+    private readonly unWake;
+    private closed;
+    constructor(d: FeedDeps, filter?: {
+        agentId?: string;
+    });
+    getState: () => FeedState;
+    subscribe: (cb: (s: FeedState) => void) => (() => void);
+    close(): void;
+}

package/dist/types/sdk/ts/core-live/src/ids.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `messageId` gerado no cliente: `msg_` + UUIDv7 (contrato control: `^msg_[A-Za-z0-9_-]{8,64}$`).
+ * É a idempotência e o dedupe do log; o prefixo separa mensagem de número de evento no `history?around=`.
+ */
+export declare function newMessageId(nowMs?: number): string;
+/** UUIDv7 (ordenável no tempo). */
+export declare function uuidv7(nowMs?: number): string;

package/dist/types/sdk/ts/core-live/src/index.d.ts

@@ -0,0 +1,11 @@
+export { LiveClient, type LiveClientOptions } from './client.js';
+export { LiveChat, newMessageId, uuidv7, type HistoryPage, type HistoryQuery, type HistoryWindow, type LocalSend, type Reducer, type WatchDeps, type SwitchTo, type WatchOptions, type WatchState } from './watch.js';
+export { RunHandle, PromptRejectedError, type RunEvent, type RunOutcome, type RunResult } from './prompt.js';
+export { ChatStream, ERROR_CODES, ERROR_CODE_HTTP, errorCode, type ErrorCode, type DebugEvent, type LiveStatus, type StreamListener, type StreamOptions, type Via, type Violation } from './stream.js';
+export { TokenSource, authedFetch, jwtExpiresAt, SmoothAgentAuthError, type AuthErrorReason } from './auth.js';
+export { DEFAULT_BACKOFF, type BackoffPolicy } from './backoff.js';
+export { ChatListLive, type ChatRow, type FeedState, type FeedStatus } from './feed.js';
+export { PING, PONG, PROTOCOL, serverEnv, systemClock, type Clock, type LiveDeps, type LiveEnv, type OpenSocket, type SocketLike } from './deps.js';
+export type * from './types.js';
+export { toContentParts } from './types.js';
+export { loadCore } from './native.js';

package/dist/types/sdk/ts/core-live/src/native.d.ts

@@ -0,0 +1,7 @@
+import * as live from './wasm/live.js';
+/** Carrega o núcleo (uma vez). A camada ao vivo chama sozinha; chamar antes só adianta o download. */
+export declare function loadCore(): Promise<typeof live>;
+/** O núcleo, se já carregou (senão `null`: quem usa enfileira até `loadCore()` resolver). */
+export declare function coreIfReady(): typeof live | null;
+/** O núcleo já carregado; antes disso é erro (use `loadCore()`). */
+export declare function core(): typeof live;

package/dist/types/sdk/ts/core-live/src/prompt.d.ts

@@ -0,0 +1,80 @@
+import type { ContentPart, Envelope, SendMode } from './types.js';
+import type { LiveChat } from './watch.js';
+export type RunOutcome = 'completed' | 'stopped' | 'failed' | 'not_delivered' | 'cancelled';
+export interface RunResult {
+    status: RunOutcome;
+    messageId: string;
+    runId?: string;
+    text: string;
+    /** Itens fechados deste run (o `data.item` dos item.completed). */
+    items: unknown[];
+    usage?: unknown;
+    error?: unknown;
+    /** Só em `not_delivered`: `not_consumed` = a box dormiu várias vezes sem o provedor ler; ausente = STOP antes do turno. */
+    notDeliveredReason?: string;
+}
+export type RunEvent = {
+    type: 'queued';
+} | {
+    type: 'started';
+    runId: string;
+} | {
+    type: 'text';
+    delta: string;
+    text: string;
+} | {
+    type: 'item';
+    item: unknown;
+} | {
+    type: 'event';
+    event: Envelope;
+} | {
+    type: 'done';
+    result: RunResult;
+};
+export declare class PromptRejectedError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class RunHandle implements AsyncIterable<RunEvent> {
+    private readonly live;
+    private readonly onSettled?;
+    readonly result: Promise<RunResult>;
+    state: 'sending' | 'queued' | 'running' | 'done';
+    messageId: string;
+    runId: string | undefined;
+    private resolve;
+    private reject;
+    private readonly handlers;
+    private readonly buffer;
+    private wakeIterators;
+    private text;
+    private readonly items;
+    private readonly untap;
+    private unselect;
+    constructor(live: LiveChat<unknown, unknown>, content: string | ContentPart[], opts?: {
+        mode?: SendMode;
+        attachments?: string[];
+        messageId?: string;
+    }, onSettled?: (() => void) | undefined);
+    on<K extends RunEvent['type']>(type: K, cb: (e: Extract<RunEvent, {
+        type: K;
+    }>) => void): this;
+    /** STOP do chat (o run é dele). O `result` resolve com `stopped` quando o run fechar. */
+    stop(): Promise<unknown>;
+    /** Para de ouvir; o agente segue. O `result` resolve com `cancelled`. */
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<RunEvent>;
+    private watchQueue;
+    private onEvent;
+    /**
+     * O texto do run = os itens `text` fechados. Um steer no Codex CORTA a resposta em andamento
+     * (`steerBoundary: 'model_call'`): o parcial fecha `interrupted` e outra resposta começa já com o
+     * steer — a resposta final é a que completou; o parcial cortado só entra se não houver outra.
+     */
+    private finalText;
+    private settle;
+    private fail;
+    private cleanup;
+    private emit;
+}

package/dist/types/sdk/ts/core-live/src/providers.d.ts

@@ -0,0 +1,187 @@
+import type { Clock } from './deps.js';
+/** Um provedor como a API devolve (`/me/providers` ou dentro de uma conexão). */
+export interface ProviderRow {
+    provider: string;
+    connected: boolean;
+    via: string[];
+    expiresAt?: string | null;
+    /** ok | expiring (renova sozinho no próximo uso) | dead (reconectar) | disconnected. */
+    status: 'ok' | 'expiring' | 'dead' | 'disconnected';
+    message?: string;
+    models: {
+        id: string;
+        name?: string;
+    }[];
+    connect: string[];
+    /** `/me/providers`: algum agente do usuário roda neste provedor. Ausente nas conexões do workspace. */
+    needed?: boolean;
+}
+/** O início de um login, como a API devolve (`connect`). */
+export type LoginStart = {
+    kind: 'oauth';
+    loginId: string;
+    url: string;
+    expiresAt: string;
+} | {
+    kind: 'device';
+    loginId: string;
+    url: string;
+    userCode: string;
+    expiresAt: string;
+};
+/** As rotas de UM dono. A cola (client/server) monta isto com o REST gerado. */
+export interface ProviderEndpoints {
+    list(): Promise<ProviderRow[]>;
+    connect(provider: string): Promise<LoginStart>;
+    complete(loginId: string, code: string): Promise<unknown>;
+    loginStatus(loginId: string): Promise<{
+        status: string;
+        error?: {
+            code?: string;
+            message?: string;
+        };
+    }>;
+    setKey(provider: string, key: string): Promise<unknown>;
+    disconnect(provider: string, via?: 'subscription' | 'key'): Promise<unknown>;
+}
+/** O estado de um fluxo de conectar. `error` no pending = falha que dá pra tentar de novo (código errado, rede). */
+export type ConnectState = {
+    status: 'starting';
+    provider: string;
+} | {
+    status: 'pending';
+    provider: string;
+    kind: 'oauth';
+    url: string;
+    expiresAt: string;
+    submitting: boolean;
+    error?: string;
+} | {
+    status: 'pending';
+    provider: string;
+    kind: 'device';
+    userCode: string;
+    verificationUrl: string;
+    expiresAt: string;
+    error?: string;
+} | {
+    status: 'connected';
+    provider: string;
+} | {
+    status: 'expired';
+    provider: string;
+} | {
+    status: 'failed';
+    provider: string;
+    message: string;
+    code?: string;
+} | {
+    status: 'cancelled';
+    provider: string;
+};
+export type ConnectStatus = ConnectState['status'];
+/** Um login em andamento. `subscribe`/`getState` servem o `useSyncExternalStore`. */
+export interface ConnectFlow {
+    readonly provider: string;
+    getState(): ConnectState;
+    subscribe(fn: (s: ConnectState) => void): () => void;
+    /** Só OAuth: o código que o site mostrou. Código errado = continua `pending` com `error` (cole de novo). */
+    complete(code: string): Promise<ConnectState>;
+    /** Para de esperar (o login no servidor vence sozinho). */
+    cancel(): void;
+    /** Resolve no estado final: connected | expired | failed | cancelled. Nunca rejeita. */
+    readonly done: Promise<ConnectState>;
+}
+/** Um provedor na tela: a linha da API + o fluxo de conectar dele + a ação de chave/desconectar em curso. */
+export interface ProviderEntry extends ProviderRow {
+    /** Em que seção desenhar (ver `sortProviders`). */
+    group: ProviderGroup;
+    /** O login aberto (ou o último que falhou/venceu, até o próximo `connect`/`dismiss`). */
+    flow: ConnectState | null;
+    /** `setKey`/`disconnect` em curso. */
+    busy: 'key' | 'disconnect' | null;
+    /** O erro da última `setKey`/`disconnect` (limpo na próxima ação). */
+    error: string | null;
+}
+export interface ProvidersState {
+    /** Ordenada: os que algum agente do usuário usa (`needed`) primeiro, depois os outros, na ordem da API. */
+    rows: ProviderEntry[];
+    loading: boolean;
+    /** Falha ao carregar a lista. */
+    error: string | null;
+}
+export interface ProviderSetOptions {
+    clock: Clock;
+    /** Os provedores do agente/chat aberto (ex.: `agent.needs` ou `[agent.provider]`): vêm primeiro. Troque com `setPrimary`. */
+    primary?: readonly string[];
+    /** Intervalo do poll do device (padrão 2 s). */
+    pollMs?: number;
+    /** Folga sobre o `expiresAt` do servidor antes de dar `expired` localmente (relógio do aparelho torto; padrão 30 s). */
+    graceMs?: number;
+}
+export declare const PROVIDER_POLL_MS = 2000;
+/** O grupo da linha na tela: os do agente/chat (`primary`), os que algum agente do usuário usa (`needed`), o resto. */
+export type ProviderGroup = 'primary' | 'needed' | 'other';
+export declare const groupOf: (r: {
+    provider: string;
+    needed?: boolean;
+}, primary?: readonly string[]) => ProviderGroup;
+/** Ordena: `primary` (na ordem dada) → `needed` → o resto; estável. A lista nunca é filtrada. */
+export declare function sortProviders<R extends {
+    provider: string;
+    needed?: boolean;
+}>(rows: readonly R[], primary?: readonly string[]): R[];
+/** Texto curto de um erro do REST pra tela (sem nada do pedido). */
+export declare function errorMessage(e: unknown): string;
+/** Só http(s): URL de login com outro esquema (javascript:, data:) não chega na tela. */
+export declare function safeLoginUrl(url: unknown): string | null;
+/**
+ * Os provedores de UM dono, prontos pra tela: lista ordenada, conectar (OAuth/device, com o poll aqui dentro), chave,
+ * desconectar. Recarrega a lista sozinho depois de cada mudança. `release()` quando a tela desmontar.
+ */
+export declare class ProviderSet {
+    private readonly ep;
+    private state;
+    private raw;
+    private flows;
+    private last;
+    private busy;
+    private errors;
+    private subs;
+    private loadSeq;
+    private released;
+    private readonly o;
+    private primary;
+    constructor(ep: ProviderEndpoints, o: ProviderSetOptions);
+    getState: () => ProvidersState;
+    subscribe: (fn: (s: ProvidersState) => void) => (() => void);
+    /** Busca a lista de novo (a resposta mais nova vence). */
+    reload: () => Promise<void>;
+    /** Abre o login: Claude → `oauth` (abra `url`, cole o código em `complete`); Codex → `device` (mostre `userCode`). */
+    connect: (provider: string) => ConnectFlow;
+    /** O login aberto deste provedor, se houver. */
+    flow(provider: string): ConnectFlow | null;
+    /** Troca os provedores que vêm primeiro (o chat mudou de agente). Não busca de novo. */
+    setPrimary: (primary: readonly string[] | undefined) => void;
+    /** Some com o erro/expirado que ficou na linha. */
+    dismiss: (provider: string) => void;
+    /** Chave própria. Rejeita com o erro da API (e o deixa na linha); a chave nunca fica guardada. */
+    setKey: (provider: string, key: string) => Promise<void>;
+    disconnect: (provider: string, via?: "subscription" | "key") => Promise<void>;
+    /** Cancela os logins abertos e para de avisar. */
+    release: () => void;
+    private act;
+    private emit;
+}
+type Method = (req: never, opts?: never) => PromiseLike<unknown>;
+/** O que a SDK gerada tem pra `/me/providers` (o mesmo no client e no server). */
+export type GeneratedMyProviders = Record<'myProvidersList' | 'myProvidersConnect' | 'myProvidersComplete' | 'myProvidersLoginStatus' | 'myProvidersSetKey' | 'myProvidersDisconnect', Method>;
+/** O que a SDK gerada (server) tem pra `/connections`. */
+export type GeneratedConnections = Record<'get' | 'connect' | 'complete' | 'loginStatus' | 'setKey' | 'disconnect', Method>;
+/** As rotas do usuário (`/me/providers`), com a gerada. */
+export declare function myProviderEndpoints(g: GeneratedMyProviders): ProviderEndpoints;
+/** As rotas de uma conexão do workspace (`/connections/{id}`), com a gerada: a mesma forma do usuário. */
+export declare function connectionProviderEndpoints(g: GeneratedConnections, id: string): ProviderEndpoints;
+/** A gerada + métodos a mais (os da gerada continuam presos a ela). */
+export declare function withExtra<G extends object, E extends object>(gen: G, extra: E): G & E;
+export {};

package/dist/types/sdk/ts/core-live/src/reducers/contract.d.ts

@@ -0,0 +1,16 @@
+import type { ChatState } from '../types.js';
+import type { Reducer } from '../watch.js';
+/**
+ * O `ChatState` GERADO do contrato (contract/events, auditoria H23), com os itens vistos pela lente solta
+ * `ContractItem` (o app lê campos do item sem estreitar a união `Item` por `kind`).
+ */
+export type ContractChatState = Omit<ChatState, 'items'> & {
+    items: Record<string, ContractItem>;
+};
+export interface ContractItem {
+    id: string;
+    kind: string;
+    status?: string;
+    [k: string]: unknown;
+}
+export declare const contractReducer: Reducer<ContractChatState, ContractItem>;

package/dist/types/sdk/ts/core-live/src/rest.d.ts

@@ -0,0 +1,48 @@
+import type { Clock } from './deps.js';
+import type { ErrorCode } from './types.js';
+/** Cabeçalho padrão do cliente gerado: uma chave nova por chamada (a mesma em todas as tentativas dela). */
+export declare function idempotencyHeaders(): Record<string, () => string>;
+/** Tentativas do `send` além do retry do gerador (que não cobre queda de rede): ~1+2+4+8+16 s. */
+export declare const SEND_ATTEMPTS = 6;
+/**
+ * Falha passageira: rede caiu (sem status), timeout, 408/429/5xx, ou 409 `retryable` (a mesma chave ainda em
+ * andamento) — a menos que o corpo diga `retryable:false`.
+ */
+export declare function transient(e: unknown, errors: {
+    api: abstract new (...a: never[]) => unknown;
+    timeout: abstract new (...a: never[]) => unknown;
+}): boolean;
+/** O corpo de erro do contrato (`{ error: ErrorBody }`, §6). */
+export interface ApiErrorBody {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    /** o campo culpado em `invalid_request` */
+    param?: string;
+    requestId?: string;
+    /** dados do código: `reason`, `resetsAt`, `scope`… */
+    details?: Record<string, unknown>;
+}
+/**
+ * O corpo tipado de um erro do REST (`SmoothAgentApiError`), ou `undefined` se não for um (rede, timeout,
+ * outro erro). Código fora da lista do §6 vira `internal` (versão nova do servidor não quebra a tela).
+ */
+export declare function apiErrorBody(e: unknown): ApiErrorBody | undefined;
+/**
+ * Faz o `send` até gravar: o `clientMessageId` é gerado UMA vez (antes do 1º envio) e vira também a
+ * Idempotency-Key; na falha passageira repete o MESMO pedido com espera. O log responde `duplicate`/a mesma
+ * resposta se o primeiro já tinha gravado.
+ */
+export declare function sendBody<R extends {
+    clientMessageId?: string;
+    'Idempotency-Key'?: string;
+}>(req: R): R & {
+    clientMessageId: string;
+    'Idempotency-Key': string;
+};
+export declare function untilStored<T>(call: () => Promise<T>, o: {
+    clock: Clock;
+    abortSignal?: AbortSignal;
+    isTransient(e: unknown): boolean;
+    attempts?: number;
+}): Promise<T>;

package/dist/types/sdk/ts/core-live/src/stream.d.ts

@@ -0,0 +1,145 @@
+import type { ErrorCode as ContractErrorCode } from '../../../../contract/events/ts/src/gen/events.js';
+import { ERROR_CODE_HTTP } from '../../../../contract/events/ts/src/gen/known.js';
+import { type BackoffPolicy } from './backoff.js';
+import type { LiveDeps } from './deps.js';
+import type { BoxPresence, ChatSnapshot, ClientFrame, Envelope, InboxState, QueueState, ServerFrame, SubmitResult } from './types.js';
+/** auth_failed = token inválido/revogado (4401) · forbidden = sem grant no chat/agente (4403). Nenhum dos dois religa sozinho. */
+export type LiveStatus = 'connecting' | 'synchronizing' | 'live' | 'reconnecting' | 'offline' | 'auth_failed' | 'forbidden' | 'closed';
+export { PING, PONG } from './deps.js';
+/** Por onde a tela fala: sempre o conector do realtime (DESIGN §17.4 — ele repassa pra box quente). */
+export type Via = 'connector';
+export type DebugEvent = 
+/** `timeout` com `reason:'sync'` = a conexão não sincronizou no prazo (B-39): derrubada e assinada de novo */
+{
+    kind: 'transport';
+    via: Via;
+    what: 'connecting' | 'open' | 'close' | 'dead' | 'fail' | 'error' | 'timeout';
+    code?: number;
+    reason?: string;
+} | {
+    kind: 'switch';
+    from: Via | null;
+    to: Via;
+} | {
+    kind: 'dup_dropped' | 'gap_detected' | 'gap_closed' | 'compacted_skip';
+    from: number;
+    to: number;
+} | {
+    kind: 'resync';
+    reason: string;
+} | {
+    kind: 'cursor';
+    seq: number;
+} | {
+    kind: 'resend';
+    ref: string;
+    attempt?: number;
+}
+/** O servidor falhou de passagem (`retryable`): o mesmo comando sai de novo em `inMs`. */
+ | {
+    kind: 'retry';
+    ref: string;
+    code: string | null;
+    attempt: number;
+    inMs: number;
+};
+/**
+ * Modo estrito (pro `tests`): em vez de esconder o problema (resync), reporta.
+ *  - gap_timeout: buraco que não fechou no prazo (o estado fica parado no buraco);
+ *  - out_of_order: a camada ia aplicar um seq que não é o seguinte (não deveria acontecer nunca);
+ *  - snapshot_regressed: snapshot com seq menor que o já aplicado;
+ *  - bad_time_unit: epoch de frame que veio em segundos/µs (o contrato é ms) — converte, mas reporta;
+ *  - bad_ack: `ack` com status fora do SubmitResult (o app recebe `rejected`).
+ * Duplicado pelos dois transportes é normal (só `dup_dropped` no debug).
+ */
+export interface Violation {
+    kind: 'gap_timeout' | 'out_of_order' | 'snapshot_regressed' | 'bad_time_unit' | 'bad_ack';
+    from: number;
+    to: number;
+    cursor: number;
+    at: number;
+}
+export interface StreamListener {
+    snapshot?(s: ChatSnapshot): void;
+    events?(evs: Envelope[]): void;
+    /** @deprecated §17: use `queue`. */
+    inbox?(inbox: InboxState): void;
+    /** A fila (§17, `QueueState`), já pela maior versão. */
+    queue?(queue: QueueState): void;
+    box?(box: BoxPresence, via: Via): void;
+    status?(status: LiveStatus): void;
+    /** Frames que esta camada não trata (ex. `test.*`, extensões futuras). */
+    other?(frame: ServerFrame): void;
+    debug?(e: DebugEvent): void;
+    /** Só no modo estrito: o que a camada teria escondido (resync) vira violação visível. */
+    violation?(v: Violation): void;
+}
+export interface StreamOptions {
+    chatId: string;
+    /** Retomar de um cache: estado já aplicado até aqui (pula o snapshot). */
+    resumeFrom?: {
+        cursor: number;
+        inboxVersion: number;
+    };
+    includeRaw?: boolean;
+    backoff?: BackoffPolicy;
+    random?: () => number;
+    pingEveryMs?: number;
+    pongTimeoutMs?: number;
+    /** Troca dentro deste prazo não muda o status (o usuário não percebe). */
+    switchGraceMs?: number;
+    /** Conector que abre e não manda snapshot/replay neste prazo é tratado como morto (T3: 15 s). */
+    syncTimeoutMs?: number;
+    gapTimeoutMs?: number;
+    /** Voltar de background mais longo que isto troca o socket na hora em vez de sondar (T3). */
+    longAwayMs?: number;
+    /** Comando sem `ack` neste prazo (socket de pé, frame sumido) = reenvia o MESMO frame (padrão 10 s). */
+    ackTimeoutMs?: number;
+    /** B-45: com a aba visível, confere a fila (o snapshot do REST, só a fila) a cada tanto (padrão 5 min; 0 = nunca). */
+    queueCheckEveryMs?: number;
+    /** Foco/aba visível de novo também conferem a fila, no máximo uma vez neste intervalo (padrão 30 s). */
+    queueCheckMinMs?: number;
+    /** Modo estrito (testes): buraco vira violação em vez de resync. Ver `Violation`. */
+    strict?: boolean;
+}
+/** Epoch dos frames em ms (a regra mora no núcleo; ver `Violation.bad_time_unit`). */
+export declare function toMs(epoch: number, now?: number): number;
+/** Códigos fechados de erro (DESIGN §6) — a lista é a do contrato (@smoothagent/events/known). */
+export declare const ERROR_CODES: readonly ["unauthorized", "forbidden", "not_found", "invalid_request", "provider_not_connected", "provider_auth_expired", "provider_error", "usage_limit_reached", "plan_limit", "rate_limited", "box_unavailable", "conflict", "machine_offline", "request_expired", "no_run", "queue_full", "internal"];
+export type ErrorCode = ContractErrorCode;
+export { ERROR_CODE_HTTP };
+export declare const errorCode: (c: unknown) => ErrorCode;
+/**
+ * `ref` de comando ÚNICO entre interfaces (o realtime guarda o recibo por `ref` no chat: repetido, a 2ª tela
+ * receberia o recibo da 1ª e o comando dela sumiria calado — ORD-05). UUIDv7 = tempo + 74 bits aleatórios.
+ */
+export declare const newRef: () => string;
+export declare class ChatStream {
+    private readonly d;
+    private readonly opts;
+    private readonly l;
+    private readonly edge;
+    private readonly waiting;
+    private closed;
+    private readonly unWake;
+    constructor(d: LiveDeps, opts: StreamOptions, l: StreamListener);
+    get status(): LiveStatus;
+    get cursor(): number;
+    get via(): Via | null;
+    get box(): BoxPresence | null;
+    /**
+     * Manda um comando (send/queue/stop/respond/resend/reset). Resolve com o `ack` — que só vem depois de
+     * gravado no log. Cai o socket antes do ack: o núcleo reenvia o MESMO frame no próximo transporte; o
+     * servidor devolve `duplicate`. Nunca rejeita por transporte; só por close()/revogação.
+     */
+    command(frame: ClientFrame & {
+        ref: string;
+    }): Promise<SubmitResult>;
+    /** Token do usuário renovado: vai pelo socket do conector sem derrubar. */
+    tokenRenewed(token: string): void;
+    retry(): void;
+    close(): void;
+    private handle;
+}
+/** A configuração do núcleo a partir das opções do TS (a mesma pro ChatStream e pro LiveChat). */
+export declare function sessionConfig(d: LiveDeps, opts: StreamOptions): Record<string, unknown>;