@volund-ia/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @volund-ia/sdk
+
+Cliente TypeScript para rodar agentes do **Volund OS** pelo seu próprio código e
+receber, em tempo real (streaming), tudo que o agente faz — raciocínio, chamadas
+de ferramenta e a resposta token a token.
+
+```bash
+npm install @volund-ia/sdk
+```
+
+> Requer Node ≥ 18 (usa o `fetch` nativo). Funciona também em Deno, Bun, Workers
+> e no browser (parser SSE 100% web-standard).
+
+## Quickstart
+
+```ts
+import { VolundOS } from "@volund-ia/sdk";
+
+const volund = new VolundOS({ apiKey: process.env.VOLUND_API_KEY! });
+
+const run = await volund.agents.run({
+  agentId: "agt_123",
+  input: "Pesquise os 3 maiores concorrentes da empresa X e resuma.",
+});
+
+// Passo a passo conforme acontece:
+for await (const event of run.stream()) {
+  if (event.type === "assistant_text_delta") process.stdout.write(event.delta);
+  if (event.type === "tool_call") console.log("→ usou:", event.tool_name);
+}
+
+// Ou só o resultado final:
+const run2 = await volund.agents.run({ agentId: "agt_123", input: "Oi" });
+const { output, usage } = await run2.result();
+```
+
+Continuar uma conversa (mesma thread):
+
+```ts
+const next = await volund.agents.continue({ runId: run.id, input: "E o 4º?" });
+```
+
+## A DX
+
+Espelha o Cursor SDK (`Agent.create()` → `agent.send()` → `run.stream()`):
+`new VolundOS()` → `agents.run()` → `run.stream()` / `run.result()` /
+`run.cancel()`.
+
+## Eventos (`VolundEvent`)
+
+Stream tipado por união discriminada — faça narrowing por `event.type`:
+
+| `type`                  | Campos                                            |
+| ----------------------- | ------------------------------------------------- |
+| `run_started`           | `protocol`, `run_id`, `agent_id`                  |
+| `thinking_delta`        | `delta` (raciocínio, streaming)                   |
+| `assistant_text_delta`  | `delta` (resposta, streaming)                     |
+| `tool_call`             | `tool_call_id`, `tool_name`, `input`              |
+| `tool_result`           | `tool_call_id`, `output`, `is_error?`             |
+| `awaiting_input`        | `request_id`, `kind: "vault"` (HITL — fecha o stream) |
+| `run_finished`          | `status`, `output`, `usage`, `error?`             |
+
+O contrato é **snake_case no fio** (consistente com a API v1 e o ecossistema
+Anthropic/Cursor) e versionado por `SCHEMA_VERSION` (`protocol` no `run_started`).
+
+## Erros
+
+Todos herdam de `VolundError` (tem `.code` e `.status`). Roteie por `instanceof`:
+
+| Classe                      | Quando                                  |
+| --------------------------- | --------------------------------------- |
+| `VolundAuthError`           | 401 — chave ausente/inválida            |
+| `VolundForbiddenError`      | 403 — sem acesso ao agente              |
+| `VolundNotFoundError`       | 404 — agente/run inexistente            |
+| `VolundRunBusyError`        | 409 — já há run ativo na thread         |
+| `VolundRunFailedError`      | `run.result()` quando o run falha       |
+| `VolundAwaitingInputError`  | `run.result()` quando pausa p/ vault    |
+
+## Notas
+
+- **`stream()` é consumível uma única vez** (é um stream de rede). Não combine
+  `stream()` e `result()` no mesmo `Run`.
+- `run.cancel()` aborta a conexão — o servidor encerra a sandbox.
+- `execution: "local"` (rodar no `cwd` do dev, estilo Cursor) chega na **V2**; o
+  tipo já existe, mas a V1 só roda na nuvem.
+
+## Testar contra um preview da Vercel (modo intermediário)
+
+Antes do endpoint de produção, dá pra apontar o SDK pro deployment de preview do
+PR:
+
+```bash
+VOLUND_API_KEY=vos_live_... \
+VOLUND_AGENT_ID=agt_... \
+VOLUND_BASE_URL=https://seu-preview.vercel.app \
+npm run example
+```
+
+Se o preview estiver com **Deployment Protection** ligada, passe o token de
+*Protection Bypass for Automation* — ele vira um header via `defaultHeaders`:
+
+```bash
+VERCEL_BYPASS=<secret> ...demais envs... npm run example
+```
+
+```ts
+new VolundOS({
+  apiKey,
+  baseUrl: "https://seu-preview.vercel.app",
+  defaultHeaders: { "x-vercel-protection-bypass": process.env.VERCEL_BYPASS! },
+});
+```
+
+## Instalar antes da publicação no NPM (beta)
+
+Enquanto `@volund-ia/sdk` não está publicado:
+
+```bash
+npm install anaraque-l/volund-sdk   # do GitHub (builda no install via `prepare`)
+# ou um tarball:
+npm pack && npm install ./volund-sdk-0.2.0.tgz
+```
+
+## Desenvolvimento
+
+```bash
+npm install
+npm test              # testes do parser SSE (vitest)
+npm run typecheck
+npm run build         # tsdown → ESM + CJS + .d.ts
+npm run check:protocol  # garante o contrato em sincronia com o volund-os
+```
+
+O contrato de eventos é **vendorado** de `volund-os` em `src/protocol/events.ts`
+— ver [`src/protocol/README.md`](src/protocol/README.md). Atualize só via
+`npm run sync:protocol`.
+
+## Licença
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,537 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let eventsource_parser = require("eventsource-parser");
+//#region src/errors.ts
+/** Erro base de todo o SDK. */
+var VolundError = class extends Error {
+	code;
+	status;
+	constructor(message, opts) {
+		super(message, { cause: opts.cause });
+		this.name = "VolundError";
+		this.code = opts.code;
+		this.status = opts.status;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/** 401 — chave ausente ou inválida. */
+var VolundAuthError = class extends VolundError {
+	constructor(message, code = "invalid_api_key", cause) {
+		super(message, {
+			code,
+			status: 401,
+			cause
+		});
+		this.name = "VolundAuthError";
+	}
+};
+/** 403 — a chave não tem acesso a este agente/run. */
+var VolundForbiddenError = class extends VolundError {
+	constructor(message, cause) {
+		super(message, {
+			code: "forbidden",
+			status: 403,
+			cause
+		});
+		this.name = "VolundForbiddenError";
+	}
+};
+/** 404 — agente ou run inexistente. */
+var VolundNotFoundError = class extends VolundError {
+	constructor(message, code = "agent_not_found", cause) {
+		super(message, {
+			code,
+			status: 404,
+			cause
+		});
+		this.name = "VolundNotFoundError";
+	}
+};
+/** 409 — já existe um run ativo na thread (só na continuação). */
+var VolundRunBusyError = class extends VolundError {
+	constructor(message, cause) {
+		super(message, {
+			code: "run_busy",
+			status: 409,
+			cause
+		});
+		this.name = "VolundRunBusyError";
+	}
+};
+/** O run terminou com `status: "failed"`. Lançado por `run.result()`. */
+var VolundRunFailedError = class extends VolundError {
+	constructor(message, cause) {
+		super(message, {
+			code: "run_failed",
+			cause
+		});
+		this.name = "VolundRunFailedError";
+	}
+};
+/**
+* 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.
+*/
+var VolundAwaitingInputError = class extends VolundError {
+	requestId;
+	kind;
+	constructor(requestId, kind) {
+		super(`Run pausou aguardando entrada do tipo "${kind}" (request ${requestId}).`, { code: "awaiting_input" });
+		this.name = "VolundAwaitingInputError";
+		this.requestId = requestId;
+		this.kind = kind;
+	}
+};
+/** Constrói a subclasse certa a partir de uma resposta de erro da API. */
+function errorFromApiResponse(status, body) {
+	const code = body.error ?? "internal_error";
+	const message = body.message ?? `Requisição falhou (HTTP ${status}).`;
+	switch (code) {
+		case "missing_api_key":
+		case "invalid_api_key": return new VolundAuthError(message, code);
+		case "forbidden": return new VolundForbiddenError(message);
+		case "agent_not_found":
+		case "run_not_found": return new VolundNotFoundError(message, code);
+		case "run_busy": return new VolundRunBusyError(message);
+		default: return new VolundError(message, {
+			code,
+			status
+		});
+	}
+}
+/** Base do backoff exponencial (ms): 300, 600, 1200... */
+const RETRY_BASE_MS = 300;
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+* Combina o sinal externo (cancel do usuário) com um timeout. O fetch recebe o
+* sinal combinado. `clearTimer()` desarma o timeout (chame ao receber a resposta,
+* p/ o timer não abortar o stream em andamento); a ligação com o sinal externo
+* permanece, então `run.cancel()` segue funcionando durante todo o stream.
+*/
+function linkAbort(external, timeoutMs) {
+	const controller = new AbortController();
+	let timedOut = false;
+	const onExternalAbort = () => controller.abort();
+	if (external) if (external.aborted) controller.abort();
+	else external.addEventListener("abort", onExternalAbort, { once: true });
+	const timer = timeoutMs > 0 ? setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, timeoutMs) : void 0;
+	return {
+		signal: controller.signal,
+		/** Foi o timeout (e não o cancel do usuário) que abortou? */
+		timedOut: () => timedOut,
+		/** Desarma o timeout MANTENDO a ligação com o sinal externo. Use no sucesso,
+		*  p/ `run.cancel()` seguir abortando o stream em andamento. */
+		clearTimer: () => {
+			if (timer) clearTimeout(timer);
+		},
+		/** Desarma o timer E solta o listener do sinal externo. Use em tentativas
+		*  abandonadas (erro/retry) p/ não vazar listeners no signal do usuário. */
+		dispose: () => {
+			if (timer) clearTimeout(timer);
+			if (external) external.removeEventListener("abort", onExternalAbort);
+		}
+	};
+}
+/**
+* Faz POST num endpoint `/stream` e devolve a `Response` SSE crua. Lança a
+* subclasse de `VolundError` apropriada se a resposta for um erro. Aplica timeout
+* pré-stream e retry (rede/5xx) conforme a config.
+*/
+async function postStream(cfg, path, body, signal) {
+	const url = `${cfg.baseUrl.replace(/\/+$/, "")}${path}`;
+	const timeoutMs = cfg.timeoutMs ?? 6e4;
+	const maxRetries = cfg.maxRetries ?? 0;
+	const sleep = cfg.sleep ?? defaultSleep;
+	const payload = JSON.stringify(body);
+	let lastError;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		if (signal?.aborted) throw new VolundError(`Requisição a ${path} cancelada.`, {
+			code: "network_error",
+			cause: signal.reason
+		});
+		const link = linkAbort(signal, timeoutMs);
+		let res;
+		try {
+			res = await cfg.fetch(url, {
+				method: "POST",
+				headers: {
+					...cfg.defaultHeaders,
+					Authorization: `Bearer ${cfg.apiKey}`,
+					"Content-Type": "application/json",
+					Accept: "text/event-stream"
+				},
+				body: payload,
+				signal: link.signal
+			});
+		} catch (cause) {
+			link.dispose();
+			if (link.timedOut()) lastError = new VolundError(`Timeout (${timeoutMs}ms) esperando resposta de ${path}.`, {
+				code: "timeout",
+				cause
+			});
+			else if (signal?.aborted) throw new VolundError(`Requisição a ${path} cancelada.`, {
+				code: "network_error",
+				cause
+			});
+			else lastError = new VolundError(`Falha de rede ao chamar ${path}.`, {
+				code: "network_error",
+				cause
+			});
+			if (attempt < maxRetries) {
+				await sleep(RETRY_BASE_MS * 2 ** attempt);
+				continue;
+			}
+			throw lastError;
+		}
+		link.clearTimer();
+		const contentType = res.headers.get("content-type") ?? "";
+		if (res.ok && contentType.includes("text/event-stream")) return res;
+		link.dispose();
+		let errBody = {};
+		try {
+			errBody = await res.json();
+		} catch {
+			errBody = { message: `Resposta inesperada (HTTP ${res.status}).` };
+		}
+		const mapped = errorFromApiResponse(res.status, errBody);
+		if (res.status >= 500 && attempt < maxRetries) {
+			lastError = mapped;
+			await sleep(RETRY_BASE_MS * 2 ** attempt);
+			continue;
+		}
+		throw mapped;
+	}
+	throw lastError ?? new VolundError(`Falha ao chamar ${path}.`, { code: "network_error" });
+}
+//#endregion
+//#region src/sse.ts
+/**
+* Parser SSE → `VolundEvent`. Camada fina sobre `eventsource-parser`, o mesmo
+* parser usado pelo Vercel AI SDK e pelo SDK da OpenAI. Ele resolve, de graça,
+* as três armadilhas do wire do Volund OS (ver `sse-adapter.ts` no servidor):
+*
+*   1. Heartbeat `: ping\n\n` — linhas de comentário são ignoradas pelo parser.
+*   2. Campo `id: <n>` por frame — exposto como `event.id` (reservado p/
+*      reconexão na V2); a V1 não o usa.
+*   3. `data:` multi-linha / partido entre chunks — o parser bufferiza e
+*      concatena conforme a spec SSE.
+*
+* Cada `event.data` é um JSON de um único `VolundEvent`. JSON inválido ou tipo
+* desconhecido é IGNORADO (regra de ouro [D4]: clientes ignoram o que não
+* conhecem — permite minor bumps sem quebrar).
+*
+* Usamos a API de callback (`createParser`) + um reader manual em vez do
+* `EventSourceParserStream` para evitar o atrito de variância de tipos entre
+* `TextDecoderStream` e `ReadableStream<Uint8Array>` no `lib.dom`.
+*/
+const KNOWN_TYPES = /* @__PURE__ */ new Set([
+	"run_started",
+	"thinking_delta",
+	"assistant_text_delta",
+	"tool_call",
+	"tool_result",
+	"awaiting_input",
+	"run_finished"
+]);
+function isVolundEvent(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string" && KNOWN_TYPES.has(value.type);
+}
+/**
+* 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.
+*/
+async function* parseVolundSSE(body) {
+	const queue = [];
+	const parser = (0, eventsource_parser.createParser)({ onEvent(event) {
+		if (!event.data) return;
+		let parsed;
+		try {
+			parsed = JSON.parse(event.data);
+		} catch {
+			return;
+		}
+		if (isVolundEvent(parsed)) queue.push(parsed);
+	} });
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			parser.feed(decoder.decode(value, { stream: true }));
+			while (queue.length > 0) yield queue.shift();
+		}
+		const tail = decoder.decode();
+		if (tail) {
+			parser.feed(tail);
+			while (queue.length > 0) yield queue.shift();
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+//#endregion
+//#region src/run.ts
+/**
+* `Run` — uma execução de agente em andamento. Espelha o `run` do Cursor SDK:
+* `.stream()` (eventos ao vivo), `.result()` (atalho p/ o texto final) e
+* `.cancel()` (fecha a conexão; o servidor mata a sandbox).
+*/
+var Run = class {
+	#id;
+	#response;
+	#abort;
+	#consumed = false;
+	constructor(response, id, abort) {
+		this.#response = response;
+		this.#id = id;
+		this.#abort = abort;
+	}
+	/**
+	* `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() {
+		return this.#id;
+	}
+	/**
+	* 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).
+	*/
+	async *stream() {
+		if (this.#consumed) throw new VolundError("Este run já foi consumido (stream/result só uma vez).", { code: "stream_error" });
+		this.#consumed = true;
+		const body = this.#response.body;
+		if (!body) throw new VolundError("Resposta de streaming sem corpo legível.", { code: "stream_error" });
+		let serverClosing = false;
+		try {
+			for await (const event of parseVolundSSE(body)) {
+				if (event.type === "run_started" && event.run_id) this.#id = event.run_id;
+				if (event.type === "run_finished" || event.type === "awaiting_input") serverClosing = true;
+				yield event;
+			}
+		} catch (err) {
+			if (this.#abort.signal.aborted) return;
+			throw err;
+		} finally {
+			if (!serverClosing) this.#abort.abort();
+		}
+	}
+	/**
+	* 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()`.
+	*/
+	async result() {
+		let text = "";
+		for await (const event of this.stream()) switch (event.type) {
+			case "assistant_text_delta":
+				text += event.delta;
+				break;
+			case "awaiting_input": throw new VolundAwaitingInputError(event.request_id, event.kind);
+			case "run_finished":
+				if (event.status === "failed") throw new VolundRunFailedError(event.error ?? "Run falhou sem motivo informado.");
+				return {
+					output: event.output ?? text,
+					usage: event.usage
+				};
+		}
+		return {
+			output: text,
+			usage: null
+		};
+	}
+	/** Cancela o run: aborta a conexão → o servidor mata a sandbox. */
+	cancel() {
+		this.#abort.abort();
+	}
+};
+//#endregion
+//#region src/agents.ts
+/**
+* `volund.agents` — dispara (`run`) e continua (`continue`) execuções de agente.
+* DX espelha o Cursor SDK: `agents.run(...)` → `Run` com `.stream()/.result()`.
+*/
+/** Combina o sinal do usuário com o sinal interno de `run.cancel()`. */
+function linkSignals(controller, external) {
+	if (!external) return;
+	if (external.aborted) {
+		controller.abort();
+		return;
+	}
+	external.addEventListener("abort", () => controller.abort(), { once: true });
+}
+/** V1 só roda na nuvem; o gancho `execution` já existe p/ a V2 (local.cwd). */
+function assertCloud(execution) {
+	if (execution && execution !== "cloud") throw new VolundError("execution: \"local\" ainda não é suportado (chega na V2). Use \"cloud\" ou omita.", { code: "unsupported" });
+}
+var Agents = class {
+	#http;
+	constructor(http) {
+		this.#http = http;
+	}
+	/** Dispara um run novo (cria uma thread) e devolve um `Run` em streaming. */
+	async run(options) {
+		assertCloud(options.execution);
+		const controller = new AbortController();
+		linkSignals(controller, options.signal);
+		const body = { input: options.input };
+		if (options.files?.length) body.files = options.files;
+		const res = await postStream(this.#http, `/api/v1/agents/${encodeURIComponent(options.agentId)}/stream`, body, controller.signal);
+		return new Run(res, runIdFromResponse(res), controller);
+	}
+	/** Continua uma conversa existente (mesma thread). */
+	async continue(options) {
+		assertCloud(options.execution);
+		const controller = new AbortController();
+		linkSignals(controller, options.signal);
+		const body = { input: options.input };
+		if (options.files?.length) body.files = options.files;
+		return new Run(await postStream(this.#http, `/api/v1/runs/${encodeURIComponent(options.runId)}/stream`, body, controller.signal), options.runId, controller);
+	}
+};
+/**
+* Para um run NOVO o `run_id` só existe no primeiro evento (`run_started`) — o
+* servidor não o devolve em header. Então iniciamos o `Run` com "" e ele faz o
+* backfill do id ao consumir o `run_started` (ver `Run.stream`). Mantemos um
+* fast-path opcional por header caso o servidor passe a ecoá-lo no futuro.
+*/
+function runIdFromResponse(res) {
+	return res.headers.get("x-volund-run-id") ?? "";
+}
+//#endregion
+//#region src/client.ts
+/**
+* `VolundOS` — ponto de entrada do SDK. Configuração mínima: uma API key.
+*
+*   const volund = new VolundOS({ apiKey: process.env.VOLUND_API_KEY! });
+*   const run = await volund.agents.run({ agentId, input });
+*/
+/** Endpoint de produção do Volund OS (decisão de proposta §6). */
+const DEFAULT_BASE_URL = "https://os.volund.com.br";
+var VolundOS = class {
+	/** Disparo e continuação de runs de agente. */
+	agents;
+	constructor(config) {
+		if (!config?.apiKey || typeof config.apiKey !== "string") throw new VolundError("apiKey é obrigatória.", { code: "missing_api_key" });
+		const fetchImpl = config.fetch ?? globalThis.fetch;
+		if (typeof fetchImpl !== "function") throw new VolundError("fetch global indisponível. Use Node ≥18 ou injete `fetch` no config.", { code: "unsupported" });
+		const http = {
+			apiKey: config.apiKey,
+			baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+			fetch: (...args) => fetchImpl(...args),
+			...config.defaultHeaders ? { defaultHeaders: config.defaultHeaders } : {},
+			...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {},
+			...config.maxRetries !== void 0 ? { maxRetries: config.maxRetries } : {}
+		};
+		this.agents = new Agents(http);
+	}
+};
+//#endregion
+//#region src/protocol/events.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. */
+const SCHEMA_VERSION = "v1";
+//#endregion
+exports.Agents = Agents;
+exports.Run = Run;
+exports.SCHEMA_VERSION = SCHEMA_VERSION;
+exports.VolundAuthError = VolundAuthError;
+exports.VolundAwaitingInputError = VolundAwaitingInputError;
+exports.VolundError = VolundError;
+exports.VolundForbiddenError = VolundForbiddenError;
+exports.VolundNotFoundError = VolundNotFoundError;
+exports.VolundOS = VolundOS;
+exports.VolundRunBusyError = VolundRunBusyError;
+exports.VolundRunFailedError = VolundRunFailedError;
+exports.errorFromApiResponse = errorFromApiResponse;
+exports.parseVolundSSE = parseVolundSSE;
+
+//# sourceMappingURL=index.cjs.map