@timefly/opencode-plugin 0.2.1 → 0.2.3

package/README.md

@@ -180,7 +180,7 @@ OpenCode hooks → @timefly/opencode-plugin → @timefly/ai-sdk
   → POST /ai/sync (gzip JSON, Bearer token)
   → Gateway auth + Supporter check
   → Ingest queue (Redis)
-  → Worker (every 5s) → ClickHouse ai_usage_events
+  → Worker (every 5s) → ClickHouse activity_events (ai.* activities)
   → Dashboard GET /analytics/ai-usage
 ```
 
@@ -230,10 +230,76 @@ OpenCode installs npm plugins automatically at startup via Bun.
 
 ## Events captured
 
+Based on OpenCode source (`packages/opencode`, `@opencode-ai/plugin` hooks, and `@opencode-ai/sdk` event types). We only emit metadata — never prompts, tool args, or file contents.
+
+### Plugin hooks we use
+
+| Hook | When it fires (OpenCode source) | TimeFly event |
+|------|----------------------------------|---------------|
+| `event` | Bus events forwarded from `EventV2Bridge` to all plugins | see bus table below |
+| `chat.params` | Before every LLM call (`LLMRequestPrep.prepare`) | `llm_request` |
+| `tool.execute.before` | Before built-in, MCP, and registry tools run (`SessionTools.resolve`) | `tool_call` |
+| `tool.execute.after` | After tool completes (same path) | `tool_result` |
+| `experimental.session.compacting` | Before compaction LLM call (`SessionCompaction.process`) | `compaction` |
+
+### Bus events we handle (`event` hook)
+
+| OpenCode event | Status | TimeFly event | Data captured |
+|----------------|--------|---------------|---------------|
+| `session.created` | Active | `session_start` | title, project, directory |
+| `session.status` (`type: idle`) | Preferred | `session_end` | session token/tool/request totals |
+| `session.idle` | Deprecated alias | `session_end` | same as above |
+| `message.updated` (assistant, completed) | Active | `turn_complete` + `llm_response` | tokens, cost, duration, finish reason |
+| `message.updated` (user) | Active | `llm_request` | model, agent (metadata only) |
+| `message.part.updated` (`step-finish`) | Active | `llm_response` | per-step tokens, cost |
+| `message.part.updated` (`retry`) | Active | `error` | retry attempt |
+| `message.part.updated` (`compaction`) | Active | `compaction` | auto/manual flag |
+| `session.compacted` | Active | `compaction` | session id |
+| `session.error` | Active | `error` | error name/message |
+| `command.executed` | Active | `tool_call` | command name (as `command:*`) |
+
+### Bus events we intentionally skip
+
+| OpenCode event | Why not tracked |
+|----------------|-----------------|
+| `message.part.updated` (`text`, `reasoning`, `tool`, …) | Would expose prompt/response/tool args |
+| `message.removed`, `message.part.removed` | Deletion only — no usage signal |
+| `session.updated`, `session.deleted`, `session.diff` | Metadata or file diffs — not AI usage |
+| `file.edited`, `file.watcher.updated` | File paths/content |
+| `permission.asked`, `permission.replied` | No token/model signal |
+| `todo.updated` | Task list text |
+| `lsp.*`, `pty.*`, `tui.*`, `installation.*`, `server.*` | IDE/infra — not LLM usage |
+
+### Hooks we do not use (available in OpenCode, not needed for usage telemetry)
+
+| Hook | Reason |
+|------|--------|
+| `chat.message` | Full user message + parts — privacy |
+| `chat.headers` | Auth headers — security |
+| `shell.env` | Environment variables — secrets risk |
+| `permission.ask` | Could track denials; not implemented yet |
+| `command.execute.before` | Parts contain prompt fragments |
+| `experimental.chat.messages.transform` | Full message history |
+| `experimental.compaction.autocontinue` | No extra telemetry beyond compaction events |
+| `tool` (custom tools) | Execution still flows through `tool.execute.*` |
+
+### Known limitations
+
+| Topic | Detail |
+|-------|--------|
+| **Custom providers** (e.g. `nan`) | OpenCode runtime passes flat `Provider.Info` (`provider.id`) via `LLMRequestPrep.prepare` — not `provider.info.id`. Plugin reads both runtime and typed `ProviderContext` shapes. |
+| **Token counts** | Require provider to report usage. If `message.updated` lacks token fields, turn events are skipped (no crash). |
+| **Provider-side tools** | Tools executed inside the provider (`providerExecuted`) may not hit `tool.execute.*` — no tool events for those. |
+| **Multi-step turns** | `step-finish` parts can emit extra `llm_response` events; message-level `turn_complete` deduplicates by message id. |
+| **`session.idle` vs `session.status`** | OpenCode marks `session.idle` deprecated; we handle both. |
+| **v2 event system** | OpenCode is migrating to `session.next.*` internally; plugins still receive v1 bus types above via the bridge. |
+
+### Quick reference (captured signals)
+
 | OpenCode signal | TimeFly `eventType` | Data |
 |-----------------|---------------------|------|
 | `session.created` | `session_start` | title, project, directory |
-| `session.idle` | `session_end` | session token/tool/request totals |
+| `session.status` / `session.idle` | `session_end` | session token/tool/request totals |
 | `chat.params` | `llm_request` | model, provider, agent, temperature |
 | `message.updated` (assistant, completed) | `turn_complete` + `llm_response` | tokens, duration, tokens/s, cost |
 | `message.part.updated` (step-finish) | `llm_response` | per-step tokens |

package/dist/event-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-handlers.d.ts","sourceRoot":"","sources":["../src/event-handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAiBvD,OAAO,EASN,KAAK,gBAAgB,EACrB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAG/D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,SAAS,CAAC,CAAA;AAKxE,eAAO,MAAM,oBAAoB,GAAI,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,cAAc,KAAG,OAAO,CAAC,IAAI,CAapH,CAAA;AAED,eAAO,MAAM,iBAAiB,GAC7B,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAad,CAAA;AAED,eAAO,MAAM,oBAAoB,GAChC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAwCd,CAAA;AAED,eAAO,MAAM,wBAAwB,GACpC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAiCd,CAAA;AAED,eAAO,MAAM,sBAAsB,GAClC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAQd,CAAA;AAED,eAAO,MAAM,kBAAkB,GAC9B,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAmBd,CAAA;AAED,eAAO,MAAM,qBAAqB,GACjC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAad,CAAA;AAED,eAAO,MAAM,cAAc,GAC1B,OAAO,gBAAgB,EACvB,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAyBd,CAAA"}
+{"version":3,"file":"event-handlers.d.ts","sourceRoot":"","sources":["../src/event-handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAiBvD,OAAO,EASN,KAAK,gBAAgB,EACrB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAG/D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,SAAS,CAAC,CAAA;AAKxE,eAAO,MAAM,oBAAoB,GAAI,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,cAAc,KAAG,OAAO,CAAC,IAAI,CAapH,CAAA;AAED,eAAO,MAAM,iBAAiB,GAC7B,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAad,CAAA;AAED,eAAO,MAAM,oBAAoB,GAChC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAwCd,CAAA;AAED,eAAO,MAAM,wBAAwB,GACpC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAiCd,CAAA;AAED,eAAO,MAAM,sBAAsB,GAClC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAQd,CAAA;AAED,eAAO,MAAM,kBAAkB,GAC9B,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAmBd,CAAA;AAED,eAAO,MAAM,qBAAqB,GACjC,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAad,CAAA;AAED,eAAO,MAAM,cAAc,GAC1B,OAAO,gBAAgB,EACvB,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAC9C,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAkCd,CAAA"}

package/dist/event-handlers.js

@@ -127,6 +127,13 @@ export const handleBusEvent = (event, tracker, publish) => {
     switch (event.type) {
         case 'session.created':
             return handleSessionCreated(eventProperties, publish);
+        case 'session.status': {
+            const statusRecord = isRecord(eventProperties.status) ? eventProperties.status : undefined;
+            if (statusRecord?.type !== 'idle') {
+                return Promise.resolve();
+            }
+            return handleSessionIdle(eventProperties, tracker, publish);
+        }
         case 'session.idle':
             return handleSessionIdle(eventProperties, tracker, publish);
         case 'message.updated':

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAUjD,eAAO,MAAM,qBAAqB,EAAE,MA0CnC,CAAA;AAED,eAAe,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAgBjD,eAAO,MAAM,qBAAqB,EAAE,MA+DnC,CAAA;AAED,eAAe,qBAAqB,CAAA"}

package/dist/index.js

@@ -2,33 +2,49 @@ import { createEventTracker } from './event-tracker.js';
 import { handleBusEvent } from './event-handlers.js';
 import { mapCompactionInput, mapLlmRequestInput, mapToolCallInput, mapToolResultInput } from './map-opencode-event.js';
 import { createEventPublisher } from './publish-events.js';
+import { resolveChatParams } from './read-chat-params.js';
 import packageJson from '../package.json' with { type: 'json' };
 const PLUGIN_VERSION = packageJson.version;
+const runHookSafely = (run) => Promise.resolve()
+    .then(run)
+    .catch(() => undefined);
 export const timeflyOpenCodePlugin = ({ client }) => {
     const tracker = createEventTracker();
     const publisher = createEventPublisher(client, PLUGIN_VERSION);
-    return Promise.resolve({
-        event: (input) => handleBusEvent(input.event, tracker, publisher.publish),
-        'chat.params': (input, output) => {
+    return client.app
+        .log({
+        body: {
+            service: 'timefly-opencode-plugin',
+            level: 'info',
+            message: `TimeFly telemetry active (v${PLUGIN_VERSION})`,
+            extra: { source: 'opencode' }
+        }
+    })
+        .then(() => undefined)
+        .catch(() => undefined)
+        .then(() => Promise.resolve({
+        event: (input) => runHookSafely(() => handleBusEvent(input.event, tracker, publisher.publish)),
+        'chat.params': (input, output) => runHookSafely(() => {
             tracker.recordSessionStats(input.sessionID, { requestCount: 1 });
+            const resolvedParams = resolveChatParams(input, output);
             return publisher.publish([
                 mapLlmRequestInput({
-                    sessionID: input.sessionID,
-                    agent: input.agent,
-                    providerId: input.provider.info.id,
-                    modelId: input.model.id,
-                    providerSource: input.provider.source,
-                    temperature: output.temperature,
-                    topP: output.topP,
-                    maxOutputTokens: output.maxOutputTokens
+                    sessionID: resolvedParams.sessionID,
+                    agent: resolvedParams.agent,
+                    providerId: resolvedParams.providerId,
+                    modelId: resolvedParams.modelId,
+                    providerSource: resolvedParams.providerSource,
+                    temperature: resolvedParams.temperature,
+                    topP: resolvedParams.topP,
+                    maxOutputTokens: resolvedParams.maxOutputTokens
                 })
             ]);
-        },
-        'tool.execute.before': (input) => {
+        }),
+        'tool.execute.before': (input) => runHookSafely(() => {
             tracker.recordSessionStats(input.sessionID, { toolCallCount: 1 });
             return publisher.publish([mapToolCallInput(input)]);
-        },
-        'tool.execute.after': (input, output) => publisher.publish([
+        }),
+        'tool.execute.after': (input, output) => runHookSafely(() => publisher.publish([
             mapToolResultInput({
                 sessionID: input.sessionID,
                 tool: input.tool,
@@ -36,8 +52,8 @@ export const timeflyOpenCodePlugin = ({ client }) => {
                 hasOutput: Boolean(output.output),
                 outputLength: output.output.length
             })
-        ]),
-        'experimental.session.compacting': (input) => publisher.publish([mapCompactionInput(input.sessionID)])
-    });
+        ])),
+        'experimental.session.compacting': (input) => runHookSafely(() => publisher.publish([mapCompactionInput(input.sessionID)]))
+    }));
 };
 export default timeflyOpenCodePlugin;

package/dist/read-chat-params.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OpenCode runtime passes flat `Provider.Info` to `chat.params`:
+ * `packages/opencode/src/session/llm/request.ts` → `provider: input.provider`
+ *
+ * Shape: `{ id, name, source, env, options, models }` — id is at the top level.
+ *
+ * `@opencode-ai/plugin` types document `ProviderContext` (`{ source, info, options }`)
+ * which does not match current runtime (anomalyco/opencode#20562). We accept both.
+ *
+ * Model shape: `Provider.Model` → `{ id, providerID, … }`.
+ */
+export type OpenCodeProviderInfo = {
+    id: string;
+    name?: string;
+    source?: 'env' | 'config' | 'custom' | 'api' | string;
+    options?: Record<string, unknown>;
+};
+export type OpenCodeProviderContext = {
+    source?: 'env' | 'config' | 'custom' | 'api' | string;
+    info?: {
+        id?: string;
+        name?: string;
+    };
+    options?: Record<string, unknown>;
+};
+export type OpenCodeModel = {
+    id: string;
+    providerID: string;
+};
+export type ChatParamsInput = {
+    sessionID: string;
+    agent: string;
+    model?: OpenCodeModel;
+    provider?: OpenCodeProviderInfo | OpenCodeProviderContext;
+};
+export type ChatParamsOutput = {
+    temperature: number;
+    topP: number;
+    maxOutputTokens?: number;
+};
+export type ResolvedChatParams = {
+    sessionID: string;
+    agent: string;
+    providerId: string;
+    modelId: string;
+    providerSource: string;
+    temperature: number;
+    topP: number;
+    maxOutputTokens?: number;
+};
+export declare const resolveChatParams: (input: ChatParamsInput, output: ChatParamsOutput) => ResolvedChatParams;
+//# sourceMappingURL=read-chat-params.d.ts.map

package/dist/read-chat-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-chat-params.d.ts","sourceRoot":"","sources":["../src/read-chat-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACrC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;IACrD,IAAI,CAAC,EAAE;QACN,EAAE,CAAC,EAAE,MAAM,CAAA;QACX,IAAI,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;IACD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,QAAQ,CAAC,EAAE,oBAAoB,GAAG,uBAAuB,CAAA;CACzD,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAiBD,eAAO,MAAM,iBAAiB,GAAI,OAAO,eAAe,EAAE,QAAQ,gBAAgB,KAAG,kBASnF,CAAA"}

package/dist/read-chat-params.js

@@ -0,0 +1,21 @@
+const readProviderId = (provider, model) => {
+    if (provider && 'id' in provider && typeof provider.id === 'string' && provider.id.length > 0) {
+        return provider.id;
+    }
+    const nestedProviderId = provider && 'info' in provider ? provider.info?.id : undefined;
+    if (typeof nestedProviderId === 'string' && nestedProviderId.length > 0) {
+        return nestedProviderId;
+    }
+    return model?.providerID ?? 'unknown';
+};
+const readProviderSource = (provider) => provider?.source ?? 'unknown';
+export const resolveChatParams = (input, output) => ({
+    sessionID: input.sessionID,
+    agent: input.agent,
+    providerId: readProviderId(input.provider, input.model),
+    modelId: input.model?.id ?? 'unknown',
+    providerSource: readProviderSource(input.provider),
+    temperature: output.temperature,
+    topP: output.topP,
+    maxOutputTokens: output.maxOutputTokens
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@timefly/opencode-plugin",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"description": "TimeFly telemetry plugin for OpenCode — sessions, tokens, models, and tools",
 	"type": "module",
 	"bin": "./dist/cli.js",