@smoothbuilder/smoothagent-agent-server 0.0.0-stage → 0.4.0

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>;

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

@@ -0,0 +1,55 @@
+import type { CFSend, ContentPart as ContractContentPart, ErrorCode, Origin, Provider, RawFrame, SnapshotPayload, SubmitAccepted, SubmitConflict, SubmitDuplicate, Timestamp } from '../../../../contract/events/ts/src/gen/events.js';
+export type { AgentSelection, ChatMessage, EffectiveSelection, QueueItem, QueueState, PendingSwitch, BoxPresence, ChatState, ClientFrame, ErrorCode, Event, InboxEntry, InboxState, Origin, QueueOp, RawFrame, ScheduledSwitch, ServerFrame, FeedFrame, } from '../../../../contract/events/ts/src/gen/events.js';
+/**
+ * Um evento da timeline com `type`/`data` soltos (o app lê campos sem estreitar a união). É o envelope do
+ * contrato (`Event`) sem a amarração por tipo; pra estreitar por `type`, use `Event`.
+ */
+export interface Envelope {
+    /** = String(seq) */
+    id: string;
+    seq: number;
+    /** fencing: a concessão que numerou */
+    epoch?: number;
+    chatId: string;
+    ts: string;
+    type: string;
+    runId?: string;
+    itemId?: string;
+    parentItemId?: string;
+    origin?: Origin;
+    /** só com `includeRaw` */
+    raw?: RawFrame[];
+    data?: Record<string, unknown>;
+}
+export type SendMode = CFSend['mode'];
+/**
+ * "Conecte sua conta": o usuário roda com a PRÓPRIA credencial do provedor e ela falta ou venceu. Derivado no
+ * núcleo (o snapshot/F5 reproduz): fila parada por `auth`, último run falhado por `provider_not_connected`/
+ * `provider_auth_expired`, ou send/resend recusado com esses códigos. Some no `run.started` seguinte.
+ */
+export interface NeedsProvider {
+    provider: Provider;
+    reason: 'not_connected' | 'auth_expired';
+    /** desde quando a fila está parada (o `held.since`) */
+    since?: Timestamp;
+}
+/** Pedaço do conteúdo de uma mensagem — o tipo GERADO do contrato. No fio do WS o conteúdo é SEMPRE lista. */
+export type ContentPart = ContractContentPart;
+/**
+ * Texto solto vira `[{type:'text', text}]` (o realtime recusa string no `send` e no `edit`); anexos
+ * (`fileId` do upload) entram como partes `file` — o frame não tem campo `attachments`.
+ */
+export declare function toContentParts(content: string | ContentPart[], attachments?: string[]): ContentPart[];
+/**
+ * A resposta de um comando, só depois de gravado no log. O `rejected` da SDK traz sempre um código do §6
+ * (`ErrorCode`): código fora da lista vira `internal` (e `bad_ack` no modo estrito).
+ */
+export type SubmitResult = SubmitAccepted | SubmitDuplicate | SubmitConflict | {
+    status: 'rejected';
+    code: ErrorCode;
+    message: string;
+};
+/** O snapshot que o servidor manda (o estado já reduzido no `seq`, a inbox, a presença e os recentes). */
+export type ChatSnapshot = SnapshotPayload;
+/** @deprecated o nome antigo; é o `InboxState` do contrato. */
+export type { InboxState as Inbox } from '../../../../contract/events/ts/src/gen/events.js';