@vymalo/opencode-core-otel 0.14.1

package/dist/recorder.d.ts

@@ -0,0 +1,166 @@
+import { type Context } from "@opentelemetry/api";
+import type { Hooks } from "@opencode-ai/plugin";
+import type { Logger } from "./logging.js";
+import type { TelemetryProviders } from "./providers.js";
+import type { ResolvedOtelConfig } from "./types.js";
+type OpencodeEvent = Parameters<NonNullable<Hooks["event"]>>[0]["event"];
+type ChatMessageInput = Parameters<NonNullable<Hooks["chat.message"]>>[0];
+type ChatMessageOutput = Parameters<NonNullable<Hooks["chat.message"]>>[1];
+type ToolBeforeInput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[0];
+type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
+type ChatParamsInput = Parameters<NonNullable<Hooks["chat.params"]>>[0];
+type ChatParamsOutput = Parameters<NonNullable<Hooks["chat.params"]>>[1];
+type TextCompleteInput = Parameters<NonNullable<Hooks["experimental.text.complete"]>>[0];
+type PermissionAskInput = Parameters<NonNullable<Hooks["permission.ask"]>>[0];
+type CompactionInput = Parameters<NonNullable<Hooks["experimental.compaction.autocontinue"]>>[0];
+export interface RecorderDeps {
+	providers: TelemetryProviders;
+	config: ResolvedOtelConfig;
+	logger: Logger;
+	/** Injectable clock; defaults to `Date.now`. */
+	now?: () => number;
+	/**
+	* Sinks for the two resource attributes OpenCode only reveals through
+	* events (`installation.updated`, `vcs.branch.updated`). Without these the
+	* recorder has nowhere to put them: a `Resource` is fixed at provider
+	* construction, which happens before any event arrives.
+	*/
+	resourceSinks?: {
+		version?: (value: string) => void;
+		branch?: (value: string) => void;
+	};
+}
+/**
+* Translates the OpenCode event stream and hook callbacks into OTel signals.
+*
+* Deliberately holds no content: lengths, counts, durations and outcomes only.
+* See `plans/otel.md` → "No content capture in v1".
+*/
+export declare class TelemetryRecorder {
+	private readonly deps;
+	private readonly instruments?;
+	private readonly now;
+	private readonly sessions;
+	private readonly chats;
+	/**
+	* Chats opened by `chat.params` but not yet matched to an assistant message.
+	* `chat.params` fires *before* the provider request goes out, so without this
+	* the very first request of a turn has no span to propagate trace context
+	* from. Keyed by session; adopted by the next assistant message.
+	*/
+	private readonly pendingChats;
+	private readonly tools;
+	/** Completed assistant text length per message, from `experimental.text.complete`. */
+	private readonly responseLengths;
+	/** Permissions already counted at `permission.ask` time, so a later reply cannot double-count. */
+	private readonly autoDecided;
+	/**
+	* Terminal tool outcomes already recorded, so the hook and the part update
+	* cannot double-count. Keyed by call id, valued by session so the entry can
+	* be pruned when that session ends.
+	*/
+	private readonly finishedTools;
+	/**
+	* Assistant messages already finalized — `message.updated` fires repeatedly
+	* with cumulative totals. Valued by session, for pruning.
+	*/
+	private readonly finalizedMessages;
+	/** Pending permission prompts, so `permission.replied` can name the tool it resolved. */
+	private readonly permissions;
+	/**
+	* Last-seen cumulative diff per `sessionID\0file`. `session.diff` reports the
+	* session's whole diff each time, so only the delta may be counted.
+	*/
+	private readonly diffs;
+	constructor(deps: RecorderDeps);
+	/**
+	* Session id as a *metric* attribute — omitted unless `includeSessionId`,
+	* because it is unbounded cardinality and metric backends bill per series.
+	* Logs and spans always carry it.
+	*/
+	private metricSession;
+	private emit;
+	private session;
+	onEvent(event: OpencodeEvent): void;
+	private dispatch;
+	private onSessionCreated;
+	private onSessionStatus;
+	private settleActiveTime;
+	private onSessionIdle;
+	private onCompacted;
+	private onSessionError;
+	private onSessionDiff;
+	private onMessageUpdated;
+	private finalizeMessage;
+	private onPartUpdated;
+	private onPermissionReplied;
+	private recordDecision;
+	/**
+	* Drop every per-session entry. Without this the bookkeeping sets grow for
+	* the life of the process — fine for a CLI invocation, a slow leak in a
+	* long-running OpenCode server.
+	*/
+	private forgetSession;
+	/**
+	* Drop the dedupe bookkeeping for a session's finished messages and tool
+	* calls. Safe to run at every idle — those ids are never reused, so nothing
+	* can be double-counted afterwards. Deliberately does **not** touch `diffs`:
+	* `session.diff` is cumulative, so forgetting the last-seen totals for a
+	* session that later resumes would re-count its whole diff.
+	*/
+	private pruneCompleted;
+	private onCommandExecuted;
+	private onTodoUpdated;
+	onChatMessage(input: ChatMessageInput, output: ChatMessageOutput): void;
+	/**
+	* `chat.params` runs immediately before the provider request. Opening the
+	* `chat` span here rather than at the first `message.updated` is what makes
+	* trace-context propagation work at all for the first request of a turn —
+	* otherwise the fetch happens while no chat span exists.
+	*/
+	onChatParams(input: ChatParamsInput, output: ChatParamsOutput): void;
+	/** Assistant text finished streaming — record its size, never its content. */
+	onTextComplete(input: TextCompleteInput, output: {
+		text?: string;
+	}): void;
+	/**
+	* Every permission evaluation passes through here, including the ones config
+	* auto-resolves. Only an already-decided prompt is counted now — an `ask`
+	* waits for `permission.replied`, so the two paths never double-count. Without
+	* this hook, auto-allowed permissions were invisible and the decision counter
+	* silently undercounted.
+	*/
+	onPermissionAsk(input: PermissionAskInput, output: {
+		status?: string;
+	}): void;
+	/** Compaction finished — `overflow` says whether the context forced it. */
+	onCompactionAutocontinue(input: CompactionInput, output: {
+		enabled?: boolean;
+	}): void;
+	onToolBefore(input: ToolBeforeInput): void;
+	onToolAfter(input: ToolAfterInput, output: {
+		output?: string;
+	}): void;
+	/**
+	* Record a tool's terminal outcome exactly once. Both `tool.execute.after`
+	* and the tool part reaching a terminal state report it, and which arrives
+	* depends on whether the tool succeeded — first writer wins, so a failing
+	* tool (no `after` hook) is still counted.
+	*/
+	private finishTool;
+	/**
+	* The context of the single in-flight chat, or `undefined` when zero or more
+	* than one is running. Ambiguity yields no trace context rather than a wrong
+	* parent — a missing link is recoverable, a fabricated one is not.
+	*/
+	currentChatContext(): Context | undefined;
+	/**
+	* Sizes of the in-memory bookkeeping. Exposed because these maps are the only
+	* unbounded thing the plugin holds — a long-running OpenCode server that
+	* never emitted `session.deleted` is exactly where a leak would show up, and
+	* "how big is it" should be answerable without a heap dump.
+	*/
+	pendingStateSize(): Record<string, number>;
+	shutdown(): Promise<void>;
+}
+export {};