Lena AgentOps OpenCode Plugin

This package captures OpenCode session telemetry and sends it to the Lena AgentOps event ingestion API.

The plugin is intentionally non-blocking: send failures are logged locally and queued for retry.

Configuration

Environment variables take priority over OpenCode settings.

export LENA_AGENTOPS_API_URL="https://localhost:5001"
export LENA_AGENTOPS_API_KEY="loa_xxx"

OpenCode plugin options can provide the same values in opencode.json.

{
  "plugin": [
    [
      "@lenasoftware/opencode-plugin",
      {
        "apiUrl": "https://localhost:5001",
        "apiKey": "loa_xxx"
      }
    ]
  ]
}

OpenCode Plugin

For reusable OpenCode installation across projects, publish or install this package as an OpenCode npm plugin and reference it from each project's opencode.json:

{
  "plugin": ["@lenasoftware/opencode-plugin"]
}

OpenCode installs npm plugins automatically with Bun at startup. Build the package before publishing or packing it:

cd plugins/opencode
npm install
npm run build

To test before publishing, create a tarball:

cd plugins/opencode
npm pack

Then reference the tarball from another project's opencode.json:

{
  "plugin": [
    [
      "file:/Users/burhancetinkaya/Development/lena-agentops/plugins/opencode/lenasoftware-opencode-plugin-0.1.2.tgz",
      {
        "apiUrl": "http://localhost:5172",
        "apiKey": "loa_xxx"
      }
    ]
  ]
}

After publishing, configure the plugin from each project's opencode.json:

{
  "plugin": [
    [
      "@lenasoftware/opencode-plugin",
      {
        "apiUrl": "http://localhost:5172",
        "apiKey": "loa_xxx"
      }
    ]
  ]
}

Updating the npm plugin

OpenCode caches the first version resolved by @latest under ~/.cache/opencode/packages/@lenasoftware/opencode-plugin@latest. If OpenCode still loads an older release after a new version is published, close OpenCode and run:

npm exec --yes --prefer-online --package=@lenasoftware/opencode-plugin@latest -- lena-agentops-opencode refresh

The refresh command compares the latest published plugin version with OpenCode's cached version. It moves only a stale @latest cache to a timestamped backup, so OpenCode resolves the current release on its next start.

To check for stale plugin versions before every OpenCode launch:

npm exec --yes --prefer-online --package=@lenasoftware/opencode-plugin@latest -- lena-agentops-opencode refresh && opencode

For deterministic environments, pin an exact plugin version in opencode.json and update the version explicitly during upgrades. Changing the exact version creates a new OpenCode cache key.

The exported OpenCode plugin reads settings from the second tuple item in plugin and forwards OpenCode session, compaction, tool, message, idle, and error events to the Lena AgentOps ingestion API. Skills are detected automatically when OpenCode loads them through the native skill tool.

Defaults:

• apiUrl: https://localhost:5001
• queue path: ~/.lena-agentops/opencode-queue.jsonl
• log path: ~/.lena-agentops/opencode-plugin.log
• timeout: 3 seconds
• retry attempts: 3
• max queued events: 1000

Usage

import { createLenaAgentOpsPlugin } from "@lenasoftware/opencode-plugin";

const plugin = createLenaAgentOpsPlugin({
  lenaAgentOps: {
    apiUrl: "https://localhost:5001",
    apiKey: "loa_xxx"
  }
});

await plugin.sessionStarted({
  sessionId: "session-123",
  agent: {
    model: "anthropic/claude-sonnet-4.6"
  }
});

await plugin.toolExecuted({
  sessionId: "session-123",
  metadata: {
    toolName: "bash",
    success: true
  },
  metrics: {
    durationMs: 350,
    toolCallCount: 1
  }
});

The generic sendEvent method accepts all supported event types:

• SessionStarted
• TurnCompleted
• ToolExecuted
• SessionCompacted
• HumanMessageSent
• AgentMessageReceived
• SessionFinished
• SessionFailed

Metadata Safety

The plugin sends git metadata, skill metadata, agent metadata, metrics, and small safe metadata fields.

It does not send source file contents, environment variables, prompt text, message contents, API keys, authorization headers, passwords, tokens, or secrets. Sensitive metadata keys are removed before events are sent or queued.

Local Retry Queue

If the backend is unavailable or the API key is missing, events are written as JSONL to the local queue. The next successful send attempt flushes queued events before sending the current event. When the queue exceeds the configured max size, the oldest events are dropped.

Development

npm install
npm run build
npm test