neatlogs 1.0.8 → 1.0.9

package/dist/opencode-plugin.d.ts

@@ -4,34 +4,35 @@
  * opencode loads plugins from its config (`opencode.json` → `"plugin": [...]`)
  * or from local `.opencode/plugin/*.ts` files. A plugin is an async factory that
  * receives an app context and returns lifecycle hooks. This plugin instruments
- * opencode automatically — no per-call wiring — translating opencode's run into
+ * opencode automatically — no per-call wiring — turning an opencode session into
  * a neatlogs span tree:
  *
- *   LLM   assistant turn        (from `message.updated` completion events)
- *   TOOL  tool execution        (tool.execute.before → tool.execute.after)
+ *   AGENT  opencode.session       (one per user turn; parents that turn's spans)
+ *     ↳ LLM   assistant turn      (per completed assistant message)
+ *     ↳ TOOL  tool execution      (tool.execute.before → tool.execute.after)
  *
  * Every span carries `neatlogs.conversation.id` = the opencode session ID.
  *
+ * Export model (mirrors @raindrop-ai/opencode-plugin and neatlogs-claude-code):
+ * opencode loads the plugin in-process but `opencode run` is short-lived. Rather
+ * than the OpenTelemetry BatchSpanProcessor (whose async, scheduled-delay export
+ * + `beforeExit` shutdown races the teardown and drops spans), this plugin builds
+ * spans directly and ships them via AWAITED `fetch(POST /v1/traces)` — and it
+ * flushes after every completed assistant turn (incremental persistence) plus a
+ * final flush on `session.idle`. A `neatlogs.trace.complete` marker is sent so
+ * the backend enqueues the trace for finalization (simplification → UI).
+ *
  * Setup — either:
- *   • npm package, in opencode.json: `{ "plugin": ["neatlogs"] }`, OR
- *   • local file `.opencode/plugin/neatlogs.ts` (project) or
- *     `~/.config/opencode/plugin/neatlogs.ts` (global):
+ *   • npm package, in opencode.json: `{ "plugin": ["neatlogs/opencode"] }`, OR
+ *   • local file `.opencode/plugin/neatlogs.ts`:
  *       export { NeatlogsOpencodePlugin as default } from 'neatlogs/opencode';
  *
- * Then set NEATLOGS_API_KEY in the environment. The plugin bootstraps neatlogs
- * tracing on load (it runs inside opencode's own process, so it initializes the
- * SDK itself rather than relying on a user `init()` call).
- *
- * Optional env:
+ * Env:
  *   NEATLOGS_API_KEY            required to export
+ *   NEATLOGS_ENDPOINT           backend base URL (default https://staging-cloud.neatlogs.com)
  *   NEATLOGS_WORKFLOW_NAME      logical grouping (default: "opencode")
  *   NEATLOGS_CAPTURE_SYSTEM_PROMPT=true  capture system prompt text (default off)
  */
-/**
- * opencode Plugin factory. opencode calls this with its app context and uses the
- * returned hook object. Typed loosely to avoid a hard dependency on
- * `@opencode-ai/plugin`.
- */
 declare const NeatlogsOpencodePlugin: (_ctx: any) => Promise<Record<string, any>>;
 declare const neatlogsOpencodePlugin: (_ctx: any) => Promise<Record<string, any>>;