@softprobe/opencode-plugin 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# Softprobe OpenCode plugin
+
+OpenCode plugin that maps coding-agent sessions to Softprobe OTLP observations
+(`agent` → `generation` → `tool`) using [`@softprobe/tracing`](../tracing).
+
+Full message and tool payloads are always captured so sessions can be evaluated
+and used to improve agents.
+
+## Install
+
+Enable OpenTelemetry and add the plugin in `opencode.json` / `opencode.jsonc`:
+
+```json
+{
+  "experimental": {
+    "openTelemetry": true
+  },
+  "plugin": ["@softprobe/opencode-plugin@latest"]
+}
+```
+
+Restart OpenCode after changing the config.
+
+## Credentials
+
+Create `opencode-softprobe.json` in the OpenCode / spcode global config directory:
+
+- spcode: `$XDG_CONFIG_HOME/spcode` (or `~/.config/spcode`)
+- OpenCode: `$XDG_CONFIG_HOME/opencode` (or `~/.config/opencode`)
+- Override directory with `OPENCODE_CONFIG_DIR`
+
+```json
+{
+  "publicKey": "<softprobe-bearer-token>",
+  "baseUrl": "https://thelake.softprobe.ai",
+  "otlpEndpoint": "https://thelake.softprobe.ai/v1/traces",
+  "environment": "production",
+  "userId": "your-user-id"
+}
+```
+
+`publicKey` and `baseUrl` are required. `otlpEndpoint` defaults to
+`{baseUrl}/v1/traces`. Credential parsing and validation use shared helpers from
+`@softprobe/tracing` (`resolveSoftprobeConfigFromEnv`, etc.); this package only
+adds the OpenCode config file path and soft-disable behavior when credentials are
+missing. When both `spcode` and `opencode` credential files exist, **spcode wins**.
+
+Or set environment variables (env wins when both key and base URL are set):
+
+```bash
+export SOFTPROBE_PUBLIC_KEY="..."
+export SOFTPROBE_BASE_URL="https://thelake.softprobe.ai"
+export SOFTPROBE_OTLP_ENDPOINT="https://thelake.softprobe.ai/v1/traces"
+export SOFTPROBE_ENVIRONMENT="production"
+export SOFTPROBE_USER_ID="your-user-id"
+```
+
+Softprobe **spcode** product builds auto-inject this plugin and default thelake
+credentials when `SPCODE_MODE` is on (see softprobe-code
+`softprobe-llm-defaults.ts`).
+
+## What is traced
+
+- User turns (`opencode.turn` / `agent`) with prompt text
+- Model generations with completions, usage, and cost
+- Tool executions with arguments and results (`gen_ai.tool.*` / `sp.tool.*`)
+- Retries, reasoning, compaction events
+- Failed steps and session errors / aborts
+
+See [Coding agents](../../docs/integrations/coding-agents.md).

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+import { MissingSoftprobeCredentialsError, type ResolvedSoftprobeConfig } from "@softprobe/tracing";
+export type SoftprobePluginCredentials = ResolvedSoftprobeConfig;
+export { MissingSoftprobeCredentialsError };
+/**
+ * OpenCode / spcode global config directory (XDG Base Directory).
+ * Matches OpenCode: `$OPENCODE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/<app>`,
+ * else `~/.config/<app>`. Softprobe spcode uses `spcode`; upstream OpenCode
+ * uses `opencode`.
+ * @see https://opencode.ai/docs/config/
+ */
+export declare function defaultConfigDir(app?: string): string;
+export declare function defaultConfigPath(): string;
+/** Credential file candidates: env dir, then spcode, then opencode. */
+export declare function candidateConfigPaths(): string[];
+/**
+ * Resolve Softprobe credentials for the OpenCode plugin.
+ * Env vars win when both `SOFTPROBE_PUBLIC_KEY` and `SOFTPROBE_BASE_URL` are set.
+ */
+export declare function loadSoftprobeCredentials(configPath?: string): Promise<SoftprobePluginCredentials>;

package/dist/config.js

@@ -0,0 +1,70 @@
+import { access, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { MissingSoftprobeCredentialsError, resolveSoftprobeConfigFromEnv, resolveSoftprobeConfigFromObject, } from "@softprobe/tracing";
+export { MissingSoftprobeCredentialsError };
+/**
+ * OpenCode / spcode global config directory (XDG Base Directory).
+ * Matches OpenCode: `$OPENCODE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/<app>`,
+ * else `~/.config/<app>`. Softprobe spcode uses `spcode`; upstream OpenCode
+ * uses `opencode`.
+ * @see https://opencode.ai/docs/config/
+ */
+export function defaultConfigDir(app = "opencode") {
+    const custom = process.env.OPENCODE_CONFIG_DIR?.trim();
+    if (custom)
+        return custom;
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    const configHome = xdg || join(homedir(), ".config");
+    return join(configHome, app);
+}
+export function defaultConfigPath() {
+    return join(defaultConfigDir("opencode"), "opencode-softprobe.json");
+}
+/** Credential file candidates: env dir, then spcode, then opencode. */
+export function candidateConfigPaths() {
+    const custom = process.env.OPENCODE_CONFIG_DIR?.trim();
+    if (custom)
+        return [join(custom, "opencode-softprobe.json")];
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    const configHome = xdg || join(homedir(), ".config");
+    return [
+        join(configHome, "spcode", "opencode-softprobe.json"),
+        join(configHome, "opencode", "opencode-softprobe.json"),
+    ];
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve Softprobe credentials for the OpenCode plugin.
+ * Env vars win when both `SOFTPROBE_PUBLIC_KEY` and `SOFTPROBE_BASE_URL` are set.
+ */
+export async function loadSoftprobeCredentials(configPath) {
+    const envCreds = resolveSoftprobeConfigFromEnv();
+    if (envCreds)
+        return envCreds;
+    const paths = configPath ? [configPath] : candidateConfigPaths();
+    const tried = [];
+    for (const path of paths) {
+        tried.push(path);
+        if (!(await fileExists(path)))
+            continue;
+        try {
+            const text = await readFile(path, "utf8");
+            return resolveSoftprobeConfigFromObject(JSON.parse(text));
+        }
+        catch (error) {
+            if (error instanceof MissingSoftprobeCredentialsError)
+                throw error;
+            throw new MissingSoftprobeCredentialsError(`Invalid Softprobe credentials in ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new MissingSoftprobeCredentialsError(`Missing Softprobe credentials (set SOFTPROBE_PUBLIC_KEY + SOFTPROBE_BASE_URL or create one of: ${tried.join(", ")})`);
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { Hooks, Plugin } from "@opencode-ai/plugin";
+import { SoftprobeSessionTracer } from "./softprobe.js";
+/** Build OpenCode hooks from an existing tracer (used by the plugin and tests). */
+export declare function createHooksFromTracer(tracer: SoftprobeSessionTracer): Hooks;
+export declare const SoftprobePlugin: Plugin;
+/**
+ * OpenCode V1 plugin shape (`{ id, server }`).
+ * Required so file:// installs do not fall through to legacy export scanning,
+ * which would invoke every exported function/class (including Error subclasses).
+ */
+declare const _default: {
+    id: string;
+    server: Plugin;
+};
+export default _default;
+export { SoftprobeSessionTracer, createSoftprobeSessionTracer, } from "./softprobe.js";
+export { loadSoftprobeCredentials, MissingSoftprobeCredentialsError, defaultConfigDir, defaultConfigPath, type SoftprobePluginCredentials, } from "./config.js";
+export { inferToolKind } from "./tool-kind.js";

package/dist/index.js

@@ -0,0 +1,235 @@
+import { loadSoftprobeCredentials, MissingSoftprobeCredentialsError, } from "./config.js";
+import { createSoftprobeSessionTracer, } from "./softprobe.js";
+function log(level, message) {
+    const line = `[softprobe-opencode] ${message}`;
+    if (level === "error")
+        console.error(line);
+    else if (level === "warn")
+        console.warn(line);
+    else
+        console.info(line);
+}
+function formatHookError(error) {
+    if (error instanceof Error)
+        return error.stack ?? error.message;
+    if (Array.isArray(error)) {
+        return error.map((item) => formatHookError(item)).join("; ") || "[]";
+    }
+    try {
+        const json = JSON.stringify(error);
+        if (json && json !== "{}" && json !== "[{}]")
+            return json;
+    }
+    catch {
+        // fall through
+    }
+    return String(error);
+}
+function createShutdownOnce(tracer) {
+    let shutdownPromise;
+    return () => {
+        if (!shutdownPromise) {
+            shutdownPromise = tracer.shutdown().catch((error) => {
+                log("error", `shutdown failed: ${formatHookError(error)}`);
+            });
+        }
+        return shutdownPromise;
+    };
+}
+async function handleEvent(tracer, event, shutdown) {
+    if (event.type === "session.idle") {
+        log("info", "Flushing spans");
+        tracer.finalizeSessionTracing();
+        await tracer.forceFlush();
+    }
+    if (event.type === "server.instance.disposed") {
+        tracer.finalizeSessionTracing();
+        if (shutdown)
+            await shutdown();
+    }
+    if (event.type === "session.error" && "properties" in event) {
+        const props = event.properties;
+        if (props.sessionID) {
+            tracer.traceSessionError({
+                sessionID: props.sessionID,
+                error: props.error,
+            });
+        }
+    }
+    if (event.type === "message.part.updated" && "properties" in event) {
+        const part = event.properties.part;
+        tracer.rememberAssistantPart(part);
+        tracer.traceReasoningPart(part);
+        tracer.traceToolPart(part);
+    }
+    if (event.type === "session.next.step.started") {
+        tracer.startActiveGenerationStep({
+            sessionID: event.properties.sessionID,
+            agent: event.properties.agent,
+            model: event.properties.model,
+            started: event.properties.timestamp,
+            snapshot: event.properties.snapshot,
+        });
+    }
+    if (event.type === "session.next.step.failed") {
+        tracer.traceFailedGenerationStep({
+            id: event.id,
+            sessionID: event.properties.sessionID,
+            completed: event.properties.timestamp,
+            error: event.properties.error,
+        });
+    }
+    if (event.type === "session.next.retried") {
+        tracer.traceEvent({
+            id: event.id,
+            sessionID: event.properties.sessionID,
+            name: "opencode.generation.retry",
+            timestamp: event.properties.timestamp,
+            output: event.properties.error,
+            metadata: { attempt: event.properties.attempt },
+        });
+    }
+    if (event.type === "session.next.reasoning.ended") {
+        tracer.traceReasoning({
+            reasoningID: event.properties.reasoningID,
+            sessionID: event.properties.sessionID,
+            timestamp: event.properties.timestamp,
+            text: event.properties.text,
+            messageID: event.properties.assistantMessageID,
+            source: "session.next.reasoning.ended",
+        });
+    }
+    if (event.type === "session.next.compaction.ended") {
+        tracer.traceEvent({
+            id: event.id,
+            sessionID: event.properties.sessionID,
+            name: "opencode.generation.compaction",
+            timestamp: event.properties.timestamp,
+            output: { text: event.properties.text },
+            metadata: {
+                include: event.properties.include ?? null,
+            },
+        });
+    }
+    if (event.type === "message.updated" && "properties" in event) {
+        const message = event.properties.info;
+        if (message.role !== "assistant" || !message.time.completed) {
+            return;
+        }
+        tracer.traceGeneration({
+            sessionID: message.sessionID,
+            messageID: message.id,
+            parentID: message.parentID,
+            modelID: message.modelID,
+            providerID: message.providerID,
+            agent: message.mode,
+            mode: message.mode,
+            created: message.time.created,
+            completed: message.time.completed,
+            finish: message.finish,
+            cost: message.cost,
+            tokens: message.tokens,
+        });
+    }
+}
+function safeRun(hookName, fn) {
+    return Promise.resolve()
+        .then(fn)
+        .catch((error) => {
+        log("error", `hook "${hookName}" failed: ${formatHookError(error)}`);
+    });
+}
+/** Build OpenCode hooks from an existing tracer (used by the plugin and tests). */
+export function createHooksFromTracer(tracer) {
+    const shutdownOnce = createShutdownOnce(tracer);
+    return {
+        dispose: () => safeRun("dispose", async () => {
+            tracer.finalizeSessionTracing();
+            await shutdownOnce();
+        }),
+        config: (config) => safeRun("config", () => {
+            if (!config.experimental?.openTelemetry) {
+                log("warn", "[Tracing disabled] Enable `experimental.openTelemetry` in opencode.json to use the Softprobe plugin");
+            }
+        }),
+        event: ({ event }) => safeRun("event", async () => {
+            try {
+                await handleEvent(tracer, event, shutdownOnce);
+            }
+            catch (error) {
+                // forceFlush often rejects with [Error] when thelake is slow;
+                // spans may already have been accepted via BatchSpanProcessor.
+                // Log and continue so session lifecycle is not blocked on OTLP.
+                if (event.type === "session.idle" &&
+                    (Array.isArray(error) ||
+                        (error instanceof Error && /timed out/i.test(error.message)))) {
+                    log("warn", `flush after session.idle: ${formatHookError(error)}`);
+                    return;
+                }
+                throw error;
+            }
+        }),
+        "chat.message": (input, output) => safeRun("chat.message", () => {
+            tracer.traceUserMessage({
+                sessionID: input.sessionID,
+                messageID: input.messageID,
+                agent: input.agent,
+                model: input.model,
+                parts: output.parts,
+            });
+        }),
+        "tool.execute.before": (input, output) => safeRun("tool.execute.before", () => {
+            tracer.traceToolStart({
+                sessionID: input.sessionID,
+                callID: input.callID,
+                tool: input.tool,
+                args: output.args,
+            });
+        }),
+        "tool.execute.after": (input, output) => safeRun("tool.execute.after", () => {
+            tracer.traceToolEnd({
+                sessionID: input.sessionID,
+                callID: input.callID,
+                tool: input.tool,
+                args: input.args,
+                title: output.title,
+                output: output.output,
+            });
+        }),
+    };
+}
+export const SoftprobePlugin = async () => {
+    let tracer;
+    try {
+        const credentials = await loadSoftprobeCredentials();
+        tracer = createSoftprobeSessionTracer({
+            publicKey: credentials.publicKey,
+            baseUrl: credentials.baseUrl,
+            otlpEndpoint: credentials.otlpEndpoint,
+            environment: credentials.environment,
+            userId: credentials.userId,
+            serviceName: credentials.serviceName ?? "opencode",
+        });
+        log("info", `OTLP tracing initialized → ${credentials.otlpEndpoint}`);
+    }
+    catch (error) {
+        if (error instanceof MissingSoftprobeCredentialsError) {
+            log("warn", `[Tracing disabled] ${error.message}`);
+            return {};
+        }
+        throw error;
+    }
+    return createHooksFromTracer(tracer);
+};
+/**
+ * OpenCode V1 plugin shape (`{ id, server }`).
+ * Required so file:// installs do not fall through to legacy export scanning,
+ * which would invoke every exported function/class (including Error subclasses).
+ */
+export default {
+    id: "softprobe-opencode",
+    server: SoftprobePlugin,
+};
+export { SoftprobeSessionTracer, createSoftprobeSessionTracer, } from "./softprobe.js";
+export { loadSoftprobeCredentials, MissingSoftprobeCredentialsError, defaultConfigDir, defaultConfigPath, } from "./config.js";
+export { inferToolKind } from "./tool-kind.js";

package/dist/softprobe.d.ts

@@ -0,0 +1,119 @@
+import { SoftprobeClient, type Generation, type JsonValue, type Observation, type SoftprobeClientOptions } from "@softprobe/tracing";
+import type { AssistantGenerationInput, MessagePart, SessionErrorInfo, UserMessageInput } from "./types.js";
+export type SoftprobeSessionTracerOptions = SoftprobeClientOptions;
+/**
+ * Maps OpenCode session hooks to Softprobe Part A observations.
+ * Construct with an injected SoftprobeClient (tests) or via {@link createSoftprobeSessionTracer}.
+ */
+export declare class SoftprobeSessionTracer {
+    readonly client: SoftprobeClient;
+    private readonly userId?;
+    private readonly abortedSessions;
+    private readonly tracedMessageIds;
+    private readonly tracedGenerationIds;
+    private readonly tracedEventIds;
+    private readonly tracedReasoningIds;
+    private readonly tracedToolCallIds;
+    private readonly pendingReasoningByMessageId;
+    private readonly assistantParts;
+    private readonly generationByMessageId;
+    private readonly turnByMessageId;
+    private readonly latestTurnBySession;
+    private readonly activeTools;
+    private readonly activeGenerations;
+    private readonly generationParents;
+    constructor(client: SoftprobeClient, options?: {
+        userId?: string;
+    });
+    clearTraceState(): void;
+    endActiveToolObservations(sessionID?: string, error?: SessionErrorInfo): void;
+    endActiveGenerationSteps(sessionID?: string, error?: SessionErrorInfo): void;
+    endActiveTurnObservations(): void;
+    finalizeSessionTracing(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private getTurn;
+    private generationParent;
+    private sessionAttrs;
+    traceUserMessage(input: UserMessageInput): void;
+    startActiveGenerationStep(input: {
+        sessionID: string;
+        agent: string;
+        model: {
+            providerID: string;
+            id: string;
+            variant?: string;
+        };
+        started: number;
+        snapshot?: string;
+    }): void;
+    rememberAssistantPart(part: MessagePart): void;
+    private getAssistantText;
+    private getAssistantToolCalls;
+    private flushPendingReasoning;
+    traceGeneration(input: AssistantGenerationInput): void;
+    traceFailedGenerationStep(input: {
+        id: string;
+        sessionID: string;
+        completed: number;
+        error: {
+            message: string;
+        };
+    }): void;
+    traceEvent(input: {
+        id: string;
+        sessionID: string;
+        name: string;
+        timestamp: number;
+        input?: unknown;
+        output?: unknown;
+        metadata?: Record<string, JsonValue>;
+        parent?: Observation | Generation;
+    }): void;
+    traceReasoning(input: {
+        reasoningID: string;
+        sessionID: string;
+        timestamp: number;
+        text: string;
+        messageID?: string;
+        source: string;
+        parent?: Generation;
+    }): void;
+    traceReasoningPart(part: MessagePart): void;
+    /** Fallback when tools arrive before session.next.step.started. */
+    private ensureGenerationParent;
+    /**
+     * Prefer an active/synthetic generation under the agent turn
+     * (`agent → generation → tool`). Creates a generation when the turn exists
+     * but session.next.step.started never fired.
+     */
+    private toolParent;
+    /**
+     * Capture tool observations from message.part.updated when tool.execute.*
+     * hooks are missed (or spans from those hooks were dropped on export).
+     */
+    traceToolPart(part: MessagePart): void;
+    traceToolStart(input: {
+        sessionID: string;
+        callID: string;
+        tool: string;
+        args: unknown;
+        started?: number;
+    }): void;
+    traceToolEnd(input: {
+        sessionID: string;
+        callID: string;
+        tool: string;
+        args: unknown;
+        title: string;
+        output: string;
+        completed?: number;
+        started?: number;
+        status?: "ok" | "error" | "cancelled";
+    }): void;
+    traceSessionError(input: {
+        sessionID: string;
+        error?: SessionErrorInfo;
+    }): void;
+}
+export declare function createSoftprobeSessionTracer(options: SoftprobeSessionTracerOptions): SoftprobeSessionTracer;