@volund-ia/sdk 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,356 @@
+//#region src/protocol/events.d.ts
+/**
+ * ⚠️  ARQUIVO VENDORADO — NÃO EDITE À MÃO ABAIXO DO SENTINEL.
+ *
+ * Cópia fiel de `lib/agent/connectors/api/events.ts` do repo `volund-os`
+ * (a FONTE ÚNICA do contrato VolundEvent v1). O servidor emite estes eventos;
+ * este pacote os entrega tipados. Manter os dois em sincronia é invariante do
+ * projeto — o CI roda `scripts/check-protocol-drift.mjs`, que falha se o
+ * conteúdo abaixo do sentinel divergir do upstream.
+ *
+ * Para atualizar: rode `npm run sync:protocol` (copia do volund-os) — nunca
+ * edite o corpo manualmente. Promover para um pacote `@volund/protocol`
+ * publicado no futuro é trivial: este diretório não importa nada do SDK.
+ */
+/**
+ * Contrato público de eventos do Volund OS SDK — VERSÃO 1.
+ *
+ * Fonte única (graduada de `docs/prototypes/sse-adapter/events.ts`). É o que o
+ * servidor (Parte A) emite via SSE e o que o SDK (Parte B) entregará como
+ * AsyncIterable<VolundEvent>. Clientes externos dependem disso por anos —
+ * NÃO altere os tipos públicos sem bump de SCHEMA_VERSION.
+ *
+ * DECISÕES DESTA VERSÃO (aprovadas pelo time em 22/06):
+ *  [D1] Naming = snake_case no wire. Consistente com a API pública que JÁ
+ *       existe (GET /api/v1/runs/{id} e webhook) E com o padrão do ecossistema:
+ *       Anthropic é 100% snake_case no fio; Cursor espelha em snake_case os
+ *       campos estilo Claude Code. camelCase fica reservado p/ ergonomia futura
+ *       na borda da linguagem (mapeado no SDK), não no contrato.
+ *  [D2] Status reusa o vocabulário do GET /runs: "completed" | "failed".
+ *       Pausa (HITL) = UM evento genérico `awaiting_input { kind }`. Na V1 o
+ *       único `kind` é "vault": runs via API rodam com
+ *       `--permission-mode bypassPermissions` (lib/agent/v2/run.ts), então NÃO
+ *       pausam por aprovação de ferramenta. "approval" foi descopado da V1
+ *       (decisão do time, 22/06) — reintroduzir quando/se a API suportar.
+ *  [D3] tool_result.is_error CONFIRMADO real no nível stream-json: vem como
+ *       `is_error: true` dentro do tool_result (no evento cru `user`). O
+ *       types.ts da Volund não o tipa → o adapter lê do cru via cast. Mantido
+ *       opcional (só presente/true em erro de ferramenta).
+ *  [D4] Versionamento (modelo combinado): campo `protocol` no run_started
+ *       (portátil p/ HTTP e CLI) p/ MAJOR; minor/patch via política
+ *       "ignore unknown fields" (clientes ignoram campos desconhecidos).
+ *  [D5] SSE `id:` por evento é emitido pelo ADAPTER (não é campo de payload),
+ *       RESERVADO p/ reconexão futura (V2). A V1 NÃO promete retomada.
+ *
+ * ROTEAMENTO DE ERROS (por `type`, nunca por posição):
+ *  - erro de ferramenta  → tool_result.is_error (este arquivo, ToolResultEvent)
+ *  - falha do run inteiro → run_finished status:"failed" + error
+ *  - erro de transporte   → cru `system/api_retry`: NÃO exposto na V1 (interno;
+ *                           retries são tratados dentro da nuvem).
+ *
+ * REGRAS DE OURO:
+ *  1. NÃO vazar interno: nada de session_id, sandbox, scratchDir, nome do
+ *     executor (claude-code/cursor), api_retry, nem formatos do AI SDK.
+ *  2. Versionar (SCHEMA_VERSION). Mudança incompatível => bump MAJOR.
+ *  3. input/output são `unknown` mas DEVEM ser JSON-serializáveis.
+ *  4. Fonte única: servidor importa daqui; o pacote @volund/sdk publica daqui.
+ *
+ * INVARIANTES DO ADAPTER (blindagem contra inconsistências):
+ *  I1. tool_call.input é emitido COMPLETO. O input chega vazio no 1º snapshot e
+ *      completo depois. O adapter acumula input_json_delta e só emite no
+ *      content_block_stop — nunca um input meio-vazio.
+ *  I2. tool_result.output é NORMALIZADO: bloco MCP [{type:"text",text}] vira
+ *      string; imagem `data:image/...` vira placeholder (não trafega binário);
+ *      tamanho limitado. Saída sempre JSON-serializável e enxuta.
+ *  I3. Sentinel de vault (__vault_request_pending__:<id>) NUNCA vaza como
+ *      tool_result — o adapter detecta e emite awaiting_input{kind:"vault"},
+ *      suprimindo o sentinel e o run_finished subsequente.
+ *  I4. Texto duplicado: o adapter faz diff entre partials e snapshot cumulativo
+ *      (gate hasSeenPartials), nunca reemite texto já enviado.
+ *  I5. Stream drenado por inteiro (dispara persister + hooks via o tap em
+ *      runAgentV2); abort do cliente → kill(). RESSALVA HITL: no vault o run
+ *      termina sozinho (emite `result`); o adapter NÃO dá kill — só suprime a
+ *      saída ao cliente e continua drenando até o `result` natural, pra o
+ *      persister flipar a thread pra `awaiting_vault` e `handle.finished`
+ *      resolver. Ver sse-adapter.ts.
+ *  I6. V1 achata turnos: um único stream ordenado de deltas, sem id de bloco/
+ *      turno no payload.
+ */
+/** Versão do schema. Bump em qualquer mudança incompatível. */
+declare const SCHEMA_VERSION: "v1";
+/**
+ * Primeiro evento do stream. run_id === thread_id (detalhe opaco p/ o cliente).
+ * Carrega `protocol` p/ o cliente validar a versão do contrato logo no começo
+ * (modelo Anthropic system/init), sem depender de inspecionar headers. [D4]
+ */
+interface RunStartedEvent {
+  type: "run_started";
+  protocol: typeof SCHEMA_VERSION;
+  run_id: string;
+  agent_id: string;
+}
+/** Raciocínio do agente, em streaming (origem: partials stream_event). */
+interface ThinkingDeltaEvent {
+  type: "thinking_delta";
+  delta: string;
+}
+/** Resposta do agente, em streaming token a token (origem: partials stream_event). */
+interface AssistantTextDeltaEvent {
+  type: "assistant_text_delta";
+  delta: string;
+}
+/** O agente chamou uma ferramenta (origem: assistant → content[].tool_use). */
+interface ToolCallEvent {
+  type: "tool_call";
+  tool_call_id: string;
+  tool_name: string;
+  /** JSON-serializável e COMPLETO (invariante I1). */
+  input: unknown;
+}
+/** Uma ferramenta retornou (origem: user → content[].tool_result). */
+interface ToolResultEvent {
+  type: "tool_result";
+  tool_call_id: string;
+  /** JSON-serializável e NORMALIZADO (invariante I2): texto desembrulhado,
+   *  imagem vira placeholder, tamanho limitado. */
+  output: unknown;
+  /** [D3] Presente (true) quando a ferramenta falhou. Vem do `is_error` dentro
+   *  do tool_result cru (evento `user`), que o types.ts da Volund não tipa. */
+  is_error?: boolean;
+}
+/**
+ * HITL: o run pausou esperando ação humana. Na V1 o único caso é "vault"
+ * (preencher uma credencial no cofre) — o servidor emite este evento, SUPRIME o
+ * resto do stream e o cliente retoma pelos endpoints existentes. [D2] Modelo
+ * genérico (decisão do time, 22/06): `kind` fica como união pra ser extensível.
+ *
+ * "approval" foi descopado da V1: runs via API usam
+ * `--permission-mode bypassPermissions` (lib/agent/v2/run.ts), logo não pausam
+ * por aprovação de ferramenta. Reintroduzir `kind:"approval"` quando/se a API
+ * passar a suportar aprovação (provável na V2).
+ */
+interface AwaitingInputEvent {
+  type: "awaiting_input";
+  request_id: string;
+  kind: "vault";
+}
+/** Último evento de um stream que termina normalmente (origem: result). */
+interface RunFinishedEvent {
+  type: "run_finished";
+  /** [D2] Mesmo vocabulário do GET /runs e do webhook. */
+  status: "completed" | "failed";
+  /** Texto final (origem: result.result). Pode ser null. */
+  output: string | null;
+  /** Origem: result.usage (snake_case já usado na API). Pode ser null. */
+  usage: {
+    input_tokens?: number;
+    output_tokens?: number;
+  } | null;
+  /** Preenchido quando status === "failed". */
+  error?: string;
+}
+/** União discriminada pública. Faça narrowing por `event.type`. */
+type VolundEvent = RunStartedEvent | ThinkingDeltaEvent | AssistantTextDeltaEvent | ToolCallEvent | ToolResultEvent | AwaitingInputEvent | RunFinishedEvent;
+/** Todos os literais de `type` (útil p/ exhaustiveness/validação). */
+type VolundEventType = VolundEvent["type"];
+/** Mesmo shape do { url } | { data } que a API atual aceita. */
+type VolundFileInput = {
+  url: string;
+  name?: string;
+} | {
+  data: string;
+  name?: string;
+  mime?: string;
+};
+/**
+ * Gancho p/ V2 (inferência na nuvem + execução local). Na V1 só "cloud"
+ * existe; o tipo já antecipa a V2 sem fechar a porta. NÃO implementar "local".
+ */
+type ExecutionMode = "cloud" | {
+  local: {
+    cwd: string;
+  };
+};
+interface RunInput {
+  agentId: string;
+  input: string;
+  files?: VolundFileInput[];
+  execution?: ExecutionMode;
+}
+interface ContinueInput {
+  runId: string;
+  input: string;
+  files?: VolundFileInput[];
+  execution?: ExecutionMode;
+}
+type VolundErrorCode = "missing_api_key" | "invalid_api_key" | "forbidden" | "agent_not_found" | "run_not_found" | "run_busy" | "internal_error";
+//#endregion
+//#region src/http.d.ts
+interface HttpConfig {
+  apiKey: string;
+  baseUrl: string;
+  fetch: typeof fetch;
+  /** Headers extra em toda requisição (ex.: bypass de proteção da Vercel). */
+  defaultHeaders?: Record<string, string>;
+  /** Timeout (ms) p/ receber a resposta. Default 60s. 0 desliga. */
+  timeoutMs?: number;
+  /** Tentativas extras em erro de rede/5xx. Default 2. 0 desliga. */
+  maxRetries?: number;
+  /** Sleep injetável (testes). Default: setTimeout real. */
+  sleep?: (ms: number) => Promise<void>;
+}
+//#endregion
+//#region src/run.d.ts
+interface RunResult {
+  /** Texto final do agente. */
+  output: string;
+  usage: {
+    input_tokens?: number;
+    output_tokens?: number;
+  } | null;
+}
+declare class Run {
+  #private;
+  constructor(response: Response, id: string, abort: AbortController);
+  /**
+   * `run_id` (== `thread_id` no Volund OS). Use em `agents.continue`.
+   * Para um run NOVO, só fica disponível depois que o primeiro evento
+   * (`run_started`) é consumido via `stream()`/`result()` — antes disso é "".
+   * Em `agents.continue`, já vem preenchido (você passou o `runId`).
+   */
+  get id(): string;
+  /**
+   * Itera os `VolundEvent` conforme chegam. ⚠️ Consumível UMA vez (é um stream
+   * de rede) — não chame `stream()` e `result()` no mesmo `Run`.
+   *
+   * Se você ABANDONAR o stream no meio (um `break`/`throw` antes de um evento
+   * terminal), a conexão é fechada automaticamente — o servidor mata o sandbox e
+   * não vaza recurso (§3.6/§4.2 da proposta). Já em `run_finished`/`awaiting_input`
+   * o servidor encerra sozinho, então NÃO abortamos (abortar no `awaiting_input`
+   * mataria um run parqueado p/ vault e quebraria o resume — §3.5).
+   */
+  stream(): AsyncIterable<VolundEvent>;
+  /**
+   * Espera o run terminar e devolve o texto final + uso de tokens.
+   * Lança `VolundRunFailedError` se o run falhar e `VolundAwaitingInputError`
+   * se ele pausar para HITL (vault). Para esses casos, prefira `stream()`.
+   */
+  result(): Promise<RunResult>;
+  /** Cancela o run: aborta a conexão → o servidor mata a sandbox. */
+  cancel(): void;
+}
+//#endregion
+//#region src/agents.d.ts
+/** Opções de `agents.run`. Estende o contrato do wire com `signal` (runtime). */
+type RunOptions = RunInput & {
+  signal?: AbortSignal;
+};
+/** Opções de `agents.continue`. */
+type ContinueOptions = ContinueInput & {
+  signal?: AbortSignal;
+};
+declare class Agents {
+  #private;
+  constructor(http: HttpConfig);
+  /** Dispara um run novo (cria uma thread) e devolve um `Run` em streaming. */
+  run(options: RunOptions): Promise<Run>;
+  /** Continua uma conversa existente (mesma thread). */
+  continue(options: ContinueOptions): Promise<Run>;
+}
+//#endregion
+//#region src/client.d.ts
+interface VolundOSConfig {
+  /** Chave de API "vos_live_...". Obrigatória. */
+  apiKey: string;
+  /** Sobrescreve a URL base (staging/local). Default: produção. */
+  baseUrl?: string;
+  /** Injeta um `fetch` (testes ou runtimes sem fetch global). */
+  fetch?: typeof fetch;
+  /**
+   * Headers extra em toda requisição. Útil p/ o Protection Bypass da Vercel ao
+   * testar contra um preview deployment:
+   * `{ "x-vercel-protection-bypass": process.env.VERCEL_BYPASS! }`.
+   * Os headers obrigatórios (Authorization/Content-Type/Accept) não podem ser
+   * sobrescritos.
+   */
+  defaultHeaders?: Record<string, string>;
+  /**
+   * Timeout (ms) p/ RECEBER a resposta (headers). NÃO limita a duração do stream
+   * — um run pode durar minutos. Default: 60000. Use 0 para desligar.
+   */
+  timeoutMs?: number;
+  /**
+   * Tentativas extras em erro de rede/5xx (só na fase pré-stream). **Default: 0
+   * (sem retry).** ⚠️ `run`/`continue` não são idempotentes — um 5xx ou queda de
+   * conexão pode ter criado o run mesmo assim, então retentar pode DUPLICAR runs.
+   * Só aumente se a duplicidade for aceitável no seu caso de uso.
+   */
+  maxRetries?: number;
+}
+declare class VolundOS {
+  /** Disparo e continuação de runs de agente. */
+  readonly agents: Agents;
+  constructor(config: VolundOSConfig);
+}
+//#endregion
+//#region src/sse.d.ts
+/**
+ * Transforma o corpo de uma resposta `text/event-stream` numa sequência de
+ * `VolundEvent`. Web-standard: roda em Node ≥18, Deno, Bun, Workers e browser.
+ */
+declare function parseVolundSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<VolundEvent>;
+//#endregion
+//#region src/errors.d.ts
+/** Códigos locais do SDK que não vêm do servidor. */
+type VolundClientErrorCode = "network_error" | "timeout" | "stream_error" | "run_failed" | "awaiting_input" | "unsupported";
+type AnyVolundErrorCode = VolundErrorCode | VolundClientErrorCode;
+interface VolundErrorOptions {
+  code: AnyVolundErrorCode;
+  /** Status HTTP, quando o erro veio de uma resposta da API. */
+  status?: number;
+  cause?: unknown;
+}
+/** Erro base de todo o SDK. */
+declare class VolundError extends Error {
+  readonly code: AnyVolundErrorCode;
+  readonly status?: number;
+  constructor(message: string, opts: VolundErrorOptions);
+}
+/** 401 — chave ausente ou inválida. */
+declare class VolundAuthError extends VolundError {
+  constructor(message: string, code?: VolundErrorCode, cause?: unknown);
+}
+/** 403 — a chave não tem acesso a este agente/run. */
+declare class VolundForbiddenError extends VolundError {
+  constructor(message: string, cause?: unknown);
+}
+/** 404 — agente ou run inexistente. */
+declare class VolundNotFoundError extends VolundError {
+  constructor(message: string, code?: VolundErrorCode, cause?: unknown);
+}
+/** 409 — já existe um run ativo na thread (só na continuação). */
+declare class VolundRunBusyError extends VolundError {
+  constructor(message: string, cause?: unknown);
+}
+/** O run terminou com `status: "failed"`. Lançado por `run.result()`. */
+declare class VolundRunFailedError extends VolundError {
+  constructor(message: string, cause?: unknown);
+}
+/**
+ * O run pausou esperando ação humana (HITL — na V1, preenchimento de cofre).
+ * `run.result()` lança isto porque o stream termina sem `run_finished`. Quem
+ * usa `run.stream()` recebe o evento `awaiting_input` normalmente, sem exceção.
+ */
+declare class VolundAwaitingInputError extends VolundError {
+  readonly requestId: string;
+  readonly kind: "vault";
+  constructor(requestId: string, kind: "vault");
+}
+/** Constrói a subclasse certa a partir de uma resposta de erro da API. */
+declare function errorFromApiResponse(status: number, body: {
+  error?: string;
+  message?: string;
+}): VolundError;
+//#endregion
+export { Agents, type AnyVolundErrorCode, type AssistantTextDeltaEvent, type AwaitingInputEvent, type ContinueInput, type ContinueOptions, type ExecutionMode, Run, type RunFinishedEvent, type RunInput, type RunOptions, type RunResult, type RunStartedEvent, SCHEMA_VERSION, type ThinkingDeltaEvent, type ToolCallEvent, type ToolResultEvent, VolundAuthError, VolundAwaitingInputError, type VolundClientErrorCode, VolundError, type VolundErrorCode, type VolundEvent, type VolundEventType, type VolundFileInput, VolundForbiddenError, VolundNotFoundError, VolundOS, type VolundOSConfig, VolundRunBusyError, VolundRunFailedError, errorFromApiResponse, parseVolundSSE };
+//# sourceMappingURL=index.d.mts.map