@snack-ai/opencode 1.0.0 → 1.0.2

package/README.md

@@ -3,13 +3,9 @@
 Live metadata capture for [SNACK](https://github.com/Duck1201/snack) — an OpenCode plugin that
 records what happened to each prompt, and never what was in it.
 
-[English](#english) · [Português](#português)
+Em português: [README.pt-BR.md](./README.pt-BR.md).
 
----
-
-## English
-
-### The friendly version
+## The friendly version
 
 OpenCode already writes down what you did. This plugin watches it happen instead of reading about it
 afterwards.
@@ -22,7 +18,7 @@ It is deliberately tiny. It appends one line of JSON per event to a private file
 way. It never opens a database, never imports the SNACK CLI, never phones anywhere, and never —
 under any failure — gets between you and your prompt.
 
-### You do not install this yourself
+## You do not install this yourself
 
 The SNACK CLI registers it in OpenCode's own configuration for you:
 
@@ -38,7 +34,7 @@ you confirm. `snack doctor` afterwards tells you whether the registration is one
 default. The plugin is the upgrade: outcomes observed live, including the refusals that leave no
 trace, and optional prompt-size features that are computed in memory and thrown away.
 
-### What it writes
+## What it writes
 
 One line of JSON per event, appended to a private spool directory that setup configured, under a
 versioned schema (`spool-event-v1`) that both packages ship a byte-identical copy of. Every field is
@@ -56,7 +52,7 @@ With `--enable-prospective-analysis`, each prompt additionally carries a few non
 features: an estimated token count, a bucketed line count, a bucketed count of fenced code blocks,
 and how many files were attached. They are derived in memory from text the plugin never writes down.
 
-### What it will not do
+## What it will not do
 
 **It will not break OpenCode.** Capture failures are swallowed, never thrown into the host, and
 never allowed to block a prompt. If the spool cannot be written, the plugin warns at most once a
@@ -73,7 +69,7 @@ would carry an invented meaning downstream for as long as it lived.
 
 ---
 
-### Under the hood
+## Under the hood
 
 #### The spool
 
@@ -110,7 +106,7 @@ The provider's own error **code** is stored on purpose — it is what distinguis
 a timeout, and classifying that difference correctly is the entire reason SNACK does not treat your
 flaky Wi-Fi as a quota event. The error _message_ is not stored.
 
-### Compatibility
+## Compatibility
 
 Requires Node.js 24 and a `@snack-ai/cli` that accepts `spool-event-v1`. Event `schema_version` is
 `1` and has been stable since the plugin's first release, so a current CLI reads any published
@@ -119,122 +115,3 @@ rather than incompatible, and re-running `snack setup opencode --install-plugin`
 
 Apache-2.0. Security reports go through the private channel in
 [SECURITY.md](https://github.com/Duck1201/snack/blob/main/SECURITY.md).
-
----
-
-## Português
-
-### A versão amigável
-
-O OpenCode já anota o que você fez. Este plugin assiste isso acontecer, em vez de ler sobre depois.
-
-Essa diferença importa mais do que parece. Algumas coisas simplesmente não sobrevivem até o disco —
-um prompt que o provedor recusa de cara pode não deixar rastro durável no banco do próprio OpenCode,
-e uma recusa que o SNACK não enxerga é uma recusa com a qual ele não aprende. O plugin pega essas no
-ato.
-
-Ele é propositalmente minúsculo. Acrescenta uma linha de JSON por evento num arquivo privado e sai
-da frente. Nunca abre banco, nunca importa a CLI do SNACK, nunca liga para lugar nenhum, e nunca —
-sob falha alguma — entra entre você e o seu prompt.
-
-### Você não instala isto por conta própria
-
-A CLI do SNACK registra o plugin na configuração do próprio OpenCode para você:
-
-```bash
-npm install -g @snack-ai/cli
-snack setup opencode --install-plugin
-```
-
-O setup mostra a mudança exata de configuração antes de fazê-la, guarda um backup, e não faz nada
-até você confirmar. Depois, `snack doctor` diz se o registro é um que o SNACK consegue ler.
-
-**O SNACK funciona bem sem ele.** A CLI lê o banco do OpenCode diretamente, e esse é o padrão. O
-plugin é o upgrade: desfechos observados ao vivo, incluindo as recusas que não deixam rastro, e
-features opcionais de tamanho de prompt calculadas em memória e descartadas.
-
-### O que ele escreve
-
-Uma linha de JSON por evento, acrescentada a um diretório de spool privado que o setup configurou,
-sob um schema versionado (`spool-event-v1`) do qual os dois pacotes carregam uma cópia
-byte-idêntica. Todo campo é metadado:
-
-- a qual prompt e sessão pertence, por identificador;
-- o provedor e o modelo, e quando aconteceu;
-- como terminou: completado, cancelado, um erro operacional, ou uma restrição observada e sua
-  classe;
-- contagens de tokens e custo, como o provedor reportou.
-
-Não existe campo para texto de prompt nem de resposta, e o schema recusa campos desconhecidos de
-forma categórica.
-
-Com `--enable-prospective-analysis`, cada prompt carrega também algumas features não semânticas de
-formato: contagem estimada de tokens, contagem de linhas em faixas, contagem de blocos de código em
-faixas, e quantos arquivos foram anexados. São derivadas em memória de um texto que o plugin nunca
-escreve.
-
-### O que ele não vai fazer
-
-**Não vai quebrar o OpenCode.** Falhas de captura são engolidas, nunca lançadas para dentro do host,
-e nunca podem bloquear um prompt. Se o spool não puder ser escrito, o plugin avisa no máximo uma vez
-por minuto e o OpenCode segue exatamente como se ele não estivesse instalado. Isso não é gentileza
-de melhor-esforço; é a primeira restrição de projeto do plugin, e é testada injetando falha no
-caminho de escrita e verificando que o host nunca vê exceção.
-
-**Não vai ler o que não precisa.** Nunca abre SQLite, nunca importa a CLI do SNACK, nunca toca nas
-credenciais do OpenCode. Escreve no seu próprio diretório de spool e em nenhum outro lugar.
-
-**Não vai chutar.** Um evento que não valida contra o schema publicado é descartado em vez de
-interpretado pela metade, porque um registro canônico construído a partir de um formato que o SNACK
-não reconhece carregaria um significado inventado rio abaixo por todo o tempo em que existisse.
-
----
-
-### Por dentro
-
-#### O spool
-
-Eventos são acrescentados como NDJSON em arquivos de segmento com permissão `0600` num diretório
-`0700`. Acrescentar é a única operação de escrita; nada é reescrito no lugar, e é isso que torna uma
-queda no meio da escrita recuperável em vez de corruptora.
-
-Uma linha cortada por uma queda é exatamente o que a recuperação de truncamento espera: o leitor
-valida cada linha, descarta a incompleta com um diagnóstico sanitizado, e mantém tudo que veio
-antes. A contagem de registros recusados aparece no `snack sync` como `rejected_invalid` em vez de
-sumir.
-
-Segmentos só são removidos depois que **toda fonte configurada commitou além deles**. Um cursor que
-avançasse sem sua transação commitar descartaria histórico em silêncio, então cursores só se movem
-dentro da transação que commita.
-
-#### Reconciliação com o backfill
-
-O plugin e o leitor de banco vão ver a maioria dos prompts. Esse é o arranjo pretendido, não um bug
-a evitar, e o SNACK reconcilia os dois num único registro canônico por identidade estável, domínio
-de revisão e finalidade — nunca confiando em quem chegou primeiro.
-
-Restrições são unidas entre os dois caminhos: uma recusa vista por qualquer observador conta.
-Revisões finais conflitantes que não podem ser ordenadas são excluídas em vez de resolvidas no
-chute. Testes de propriedade garantem convergência sob duplicatas, reordenação e lacunas, porque
-"eventualmente consistente" sem prova é só esperança.
-
-#### Livre de conteúdo por construção
-
-O schema não tem campo capaz de carregar texto de prompt ou resposta, então vazamento é violação de
-schema, não falha de política. As strings-canário de privacidade são compartilhadas byte a byte
-entre os dois pacotes e empurradas pelo caminho de captura nos testes; um canário chegando a
-qualquer byte escrito quebra o build.
-
-O **código** de erro do provedor é armazenado de propósito — é o que distingue um rate limit de um
-timeout, e classificar essa diferença corretamente é a razão inteira de o SNACK não tratar o seu
-Wi-Fi instável como evento de quota. A _mensagem_ de erro não é armazenada.
-
-### Compatibilidade
-
-Requer Node.js 24 e uma `@snack-ai/cli` que aceite `spool-event-v1`. O `schema_version` do evento é
-`1` e está estável desde a primeira release do plugin, então uma CLI atual lê qualquer versão
-publicada dele. O `snack doctor` reporta um registro fixado numa versão antiga como desatualizado, e
-não como incompatível; rodar `snack setup opencode --install-plugin` de novo atualiza o pin.
-
-Apache-2.0. Relatos de segurança vão pelo canal privado descrito em
-[SECURITY.md](https://github.com/Duck1201/snack/blob/main/SECURITY.md).

package/README.pt-BR.md

@@ -0,0 +1,121 @@
+# @snack-ai/opencode
+
+Captura de metadados ao vivo para o [SNACK](https://github.com/Duck1201/snack) — um plugin do
+OpenCode que registra o que aconteceu com cada prompt, e nunca o que havia nele.
+
+In English: [README.md](./README.md).
+
+## A versão amigável
+
+O OpenCode já anota o que você fez. Este plugin assiste isso acontecer, em vez de ler sobre depois.
+
+Essa diferença importa mais do que parece. Algumas coisas simplesmente não sobrevivem até o disco —
+um prompt que o provedor recusa de cara pode não deixar rastro durável no banco do próprio OpenCode,
+e uma recusa que o SNACK não enxerga é uma recusa com a qual ele não aprende. O plugin pega essas no
+ato.
+
+Ele é propositalmente minúsculo. Acrescenta uma linha de JSON por evento num arquivo privado e sai
+da frente. Nunca abre banco, nunca importa a CLI do SNACK, nunca liga para lugar nenhum, e nunca —
+sob falha alguma — entra entre você e o seu prompt.
+
+## Você não instala isto por conta própria
+
+A CLI do SNACK registra o plugin na configuração do próprio OpenCode para você:
+
+```bash
+npm install -g @snack-ai/cli
+snack setup opencode --install-plugin
+```
+
+O setup mostra a mudança exata de configuração antes de fazê-la, guarda um backup, e não faz nada
+até você confirmar. Depois, `snack doctor` diz se o registro é um que o SNACK consegue ler.
+
+**O SNACK funciona bem sem ele.** A CLI lê o banco do OpenCode diretamente, e esse é o padrão. O
+plugin é o upgrade: desfechos observados ao vivo, incluindo as recusas que não deixam rastro, e
+features opcionais de tamanho de prompt calculadas em memória e descartadas.
+
+## O que ele escreve
+
+Uma linha de JSON por evento, acrescentada a um diretório de spool privado que o setup configurou,
+sob um schema versionado (`spool-event-v1`) do qual os dois pacotes carregam uma cópia
+byte-idêntica. Todo campo é metadado:
+
+- a qual prompt e sessão pertence, por identificador;
+- o provedor e o modelo, e quando aconteceu;
+- como terminou: completado, cancelado, um erro operacional, ou uma restrição observada e sua
+  classe;
+- contagens de tokens e custo, como o provedor reportou.
+
+Não existe campo para texto de prompt nem de resposta, e o schema recusa campos desconhecidos de
+forma categórica.
+
+Com `--enable-prospective-analysis`, cada prompt carrega também algumas features não semânticas de
+formato: contagem estimada de tokens, contagem de linhas em faixas, contagem de blocos de código em
+faixas, e quantos arquivos foram anexados. São derivadas em memória de um texto que o plugin nunca
+escreve.
+
+## O que ele não vai fazer
+
+**Não vai quebrar o OpenCode.** Falhas de captura são engolidas, nunca lançadas para dentro do host,
+e nunca podem bloquear um prompt. Se o spool não puder ser escrito, o plugin avisa no máximo uma vez
+por minuto e o OpenCode segue exatamente como se ele não estivesse instalado. Isso não é gentileza
+de melhor-esforço; é a primeira restrição de projeto do plugin, e é testada injetando falha no
+caminho de escrita e verificando que o host nunca vê exceção.
+
+**Não vai ler o que não precisa.** Nunca abre SQLite, nunca importa a CLI do SNACK, nunca toca nas
+credenciais do OpenCode. Escreve no seu próprio diretório de spool e em nenhum outro lugar.
+
+**Não vai chutar.** Um evento que não valida contra o schema publicado é descartado em vez de
+interpretado pela metade, porque um registro canônico construído a partir de um formato que o SNACK
+não reconhece carregaria um significado inventado rio abaixo por todo o tempo em que existisse.
+
+---
+
+## Por dentro
+
+#### O spool
+
+Eventos são acrescentados como NDJSON em arquivos de segmento com permissão `0600` num diretório
+`0700`. Acrescentar é a única operação de escrita; nada é reescrito no lugar, e é isso que torna uma
+queda no meio da escrita recuperável em vez de corruptora.
+
+Uma linha cortada por uma queda é exatamente o que a recuperação de truncamento espera: o leitor
+valida cada linha, descarta a incompleta com um diagnóstico sanitizado, e mantém tudo que veio
+antes. A contagem de registros recusados aparece no `snack sync` como `rejected_invalid` em vez de
+sumir.
+
+Segmentos só são removidos depois que **toda fonte configurada commitou além deles**. Um cursor que
+avançasse sem sua transação commitar descartaria histórico em silêncio, então cursores só se movem
+dentro da transação que commita.
+
+#### Reconciliação com o backfill
+
+O plugin e o leitor de banco vão ver a maioria dos prompts. Esse é o arranjo pretendido, não um bug
+a evitar, e o SNACK reconcilia os dois num único registro canônico por identidade estável, domínio
+de revisão e finalidade — nunca confiando em quem chegou primeiro.
+
+Restrições são unidas entre os dois caminhos: uma recusa vista por qualquer observador conta.
+Revisões finais conflitantes que não podem ser ordenadas são excluídas em vez de resolvidas no
+chute. Testes de propriedade garantem convergência sob duplicatas, reordenação e lacunas, porque
+"eventualmente consistente" sem prova é só esperança.
+
+#### Livre de conteúdo por construção
+
+O schema não tem campo capaz de carregar texto de prompt ou resposta, então vazamento é violação de
+schema, não falha de política. As strings-canário de privacidade são compartilhadas byte a byte
+entre os dois pacotes e empurradas pelo caminho de captura nos testes; um canário chegando a
+qualquer byte escrito quebra o build.
+
+O **código** de erro do provedor é armazenado de propósito — é o que distingue um rate limit de um
+timeout, e classificar essa diferença corretamente é a razão inteira de o SNACK não tratar o seu
+Wi-Fi instável como evento de quota. A _mensagem_ de erro não é armazenada.
+
+## Compatibilidade
+
+Requer Node.js 24 e uma `@snack-ai/cli` que aceite `spool-event-v1`. O `schema_version` do evento é
+`1` e está estável desde a primeira release do plugin, então uma CLI atual lê qualquer versão
+publicada dele. O `snack doctor` reporta um registro fixado numa versão antiga como desatualizado, e
+não como incompatível; rodar `snack setup opencode --install-plugin` de novo atualiza o pin.
+
+Apache-2.0. Relatos de segurança vão pelo canal privado descrito em
+[SECURITY.md](https://github.com/Duck1201/snack/blob/main/SECURITY.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snack-ai/opencode",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Fail-open OpenCode metadata capture for SNACK",
   "license": "Apache-2.0",
   "repository": {
@@ -17,7 +17,8 @@
     "src",
     "LICENSE",
     "NOTICE",
-    "README.md"
+    "README.md",
+    "README.pt-BR.md"
   ],
   "engines": {
     "node": ">=24 <25"

package/src/plugin.js

@@ -19,7 +19,7 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
   const spoolDirectory = stringOrNull(options.spool_directory);
   const captureFeatures = options.prospective_analysis === true;
   const sourceBindings = bindingMap(options.source_bindings);
-  /** @type {Map<string, {promptId: string, provider: string | null, model: string | null, spoolDirectory: string}>} */
+  /** @type {Map<string, {promptId: string, provider: string | null, model: string | null, spoolDirectory: string, buffered: Record<string, unknown>[]}>} */
   const prompts = new Map();
   let writes = Promise.resolve();
   let pendingWrites = 0;
@@ -56,10 +56,44 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
       });
   };
 
+  /**
+   * Route a session's spool directory once its provider is known.
+   *
+   * OpenCode declares `model` optional on `chat.message` and does not send it on `1.18.10`, so the
+   * routing decision cannot be taken there. An event written to `_pending` is never attributed and
+   * never revisited, so a prompt whose provider is still unknown is held rather than misfiled, and
+   * released as soon as `chat.params` names one. A prompt whose provider never arrives is released
+   * to `_pending` at the terminal event, which is where it would have gone anyway.
+   *
+   * @param {{provider: string | null, model: string | null, spoolDirectory: string, buffered: Record<string, unknown>[]}} prompt
+   */
+  const release = (prompt) => {
+    for (const event of prompt.buffered.splice(0)) {
+      append(prompt.spoolDirectory, { ...event, provider: prompt.provider, model: prompt.model });
+    }
+  };
+
   return {
     async dispose() {
+      for (const prompt of prompts.values()) release(prompt);
       await writes;
     },
+    async "chat.params"(/** @type {Record<string, unknown>} */ input) {
+      try {
+        const sessionId = stringOrNull(input.sessionID);
+        const prompt = sessionId ? prompts.get(sessionId) : undefined;
+        if (!prompt || prompt.provider || !spoolDirectory) return;
+        const model = recordOrNull(input.model);
+        const provider = stringOrNull(model?.providerID);
+        if (!provider) return;
+        prompt.provider = provider;
+        prompt.model = stringOrNull(model?.modelID);
+        prompt.spoolDirectory = sourceBindings.get(provider) ?? join(spoolDirectory, "_pending");
+        release(prompt);
+      } catch {
+        // Capture must never change OpenCode prompt behavior.
+      }
+    },
     async "chat.message"(
       /** @type {Record<string, unknown>} */ input,
       /** @type {unknown} */ output,
@@ -76,14 +110,16 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
           ? (sourceBindings.get(provider) ?? join(spoolDirectory, "_pending"))
           : join(spoolDirectory, "_pending");
         if (!targetDirectory) return;
-        prompts.set(sessionId, {
+        const prompt = {
           promptId,
           provider,
           model: modelId,
           spoolDirectory: targetDirectory,
-        });
+          /** @type {Record<string, unknown>[]} */ buffered: [],
+        };
+        prompts.set(sessionId, prompt);
         const occurredAt = new Date().toISOString();
-        append(targetDirectory, {
+        const started = {
           schema_version: 1,
           event_id: `chat.message:${sessionId}:${promptId}:${occurredAt}`,
           installation_id: installationId,
@@ -101,7 +137,9 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
           usage_slices: [],
           restrictions: [],
           ...(captureFeatures ? { input_features: analyzePrompt(output) } : {}),
-        });
+        };
+        if (provider) append(targetDirectory, started);
+        else prompt.buffered.push(started);
       } catch {
         // Capture must never change OpenCode prompt behavior.
       }
@@ -118,6 +156,7 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
         const occurredAt = timestampOrNow(properties.time);
         const error = recordOrNull(properties.error);
         const restricted = type === "session.error" && isExplicitRateLimit(error);
+        release(prompt);
         append(prompt.spoolDirectory, {
           schema_version: 1,
           event_id: `${type}:${sessionId}:${prompt.promptId}:${occurredAt}`,