imbue-mngr-opencode-usage 0.1.0__py3-none-any.whl

imbue/mngr_opencode_usage/plugin.py

@@ -0,0 +1,90 @@
+"""OpenCode usage data provider for `mngr usage`.
+
+Single responsibility: install a second in-process TypeScript plugin into each
+OpenCode agent's config dir (alongside mngr_opencode's lifecycle plugin) that
+appends one ``cost_snapshot`` event per assistant message to
+``$MNGR_AGENT_STATE_DIR/events/opencode/usage/events.jsonl``. The ``mngr usage``
+CLI walks those events files itself (see ``imbue-mngr-usage``).
+
+Provisioning runs from an ``on_after_provisioning`` hookimpl so the per-agent
+OpenCode config dir (and its ``plugin/`` subdir) already exists when we drop our
+writer in. All file I/O goes through ``host.write_text_file`` so it works for
+local and remote agents uniformly. The reader side is an
+``aggregate_usage_source`` hookimpl that claims the ``opencode`` source and
+aggregates it with the session-incremental strategy (OpenCode reports cost/tokens
+per message, not cumulatively).
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+from imbue.mngr import hookimpl
+from imbue.mngr.config.data_types import MngrContext
+from imbue.mngr.hosts.host import get_agent_state_dir_path
+from imbue.mngr.interfaces.agent import AgentInterface
+from imbue.mngr.interfaces.host import OnlineHostInterface
+from imbue.mngr_opencode.opencode_config import get_opencode_config_dir
+from imbue.mngr_opencode.opencode_config import get_opencode_plugin_path
+from imbue.mngr_opencode.plugin import OpenCodeAgent
+from imbue.mngr_opencode_usage import resources as _resources
+from imbue.mngr_usage.api import aggregate_session_incremental
+from imbue.mngr_usage.data_types import UsageEvent
+from imbue.mngr_usage.data_types import UsageSnapshot
+
+# The usage writer plugin dropped alongside mngr_opencode's lifecycle plugin in
+# the per-agent ``<config dir>/plugin/`` (OpenCode auto-loads every plugin/*.ts).
+_USAGE_PLUGIN_FILENAME = "mngr_opencode_usage_plugin.ts"
+
+# Source name the writer emits under ($STATE_DIR/events/opencode/usage/...);
+# the reader strips "/usage", so this hookimpl claims exactly "opencode".
+_OPENCODE_USAGE_SOURCE_NAME = "opencode"
+
+
+def _load_resource(filename: str) -> str:
+    """Load a resource file's text from the mngr_opencode_usage resources package."""
+    return importlib.resources.files(_resources).joinpath(filename).read_text()
+
+
+def _provision_usage_writer_plugin(host: OnlineHostInterface, agent_state_dir: Path) -> None:
+    """Install the usage writer plugin into the agent's OpenCode ``plugin/`` dir.
+
+    Idempotent: re-provisioning overwrites the file in place. The destination is
+    the same ``plugin/`` dir OpenCode auto-loads, next to mngr_opencode's
+    lifecycle plugin.
+    """
+    config_dir = get_opencode_config_dir(agent_state_dir)
+    plugin_dir = get_opencode_plugin_path(config_dir).parent
+    host.write_text_file(plugin_dir / _USAGE_PLUGIN_FILENAME, _load_resource(_USAGE_PLUGIN_FILENAME))
+
+
+@hookimpl
+def on_after_provisioning(agent: AgentInterface, host: OnlineHostInterface, mngr_ctx: MngrContext) -> None:
+    """Install the OpenCode usage writer plugin for OpenCode agents on any host.
+
+    Skips non-OpenCode agents. Runs after the harness has provisioned the config
+    dir, so the ``plugin/`` dir exists; the writer then loads automatically on the
+    next ``opencode serve``.
+    """
+    if not isinstance(agent, OpenCodeAgent):
+        return
+    _provision_usage_writer_plugin(host, get_agent_state_dir_path(host.host_dir, agent.id))
+
+
+@hookimpl
+def aggregate_usage_source(
+    source_name: str,
+    agents_events: dict[str, list[UsageEvent]],
+    since_seconds: int,
+    now: int,
+) -> UsageSnapshot | None:
+    """Aggregate the OpenCode usage source; decline every other source.
+
+    OpenCode reports each assistant message's own cost/tokens (not a cumulative
+    total), so this is the session-incremental strategy. Returning None for
+    non-OpenCode sources lets the firstresult hook fall through.
+    """
+    if source_name != _OPENCODE_USAGE_SOURCE_NAME:
+        return None
+    return aggregate_session_incremental(source_name, agents_events, since_seconds=since_seconds, now=now)

imbue/mngr_opencode_usage/resources/mngr_opencode_usage_plugin.ts

@@ -0,0 +1,116 @@
+// mngr usage writer plugin for OpenCode agents.
+//
+// OpenCode auto-loads every `$OPENCODE_CONFIG_DIR/plugin/*.ts`, so this file
+// loads alongside mngr_opencode's lifecycle plugin without any config entry. Its
+// single job: on each assistant `message.updated`, append one `cost_snapshot`
+// event carrying that message's own cost + tokens to
+//   $MNGR_AGENT_STATE_DIR/events/opencode/usage/events.jsonl
+// which `mngr usage` reads (see imbue-mngr-usage).
+//
+// OpenCode reports cost/tokens PER MESSAGE (not cumulatively), so the reader uses
+// the session-incremental strategy: it sums each session's messages, keeping the
+// freshest event per `message_id` (so a streaming message's re-fires collapse to
+// its final reading). That makes this writer stateless and restart-proof -- each
+// event is self-contained and append-only; nothing is accumulated in memory.
+//
+// Like the lifecycle plugin, this only acts in the mngr-managed `opencode serve`
+// process (MNGR_OPENCODE_ROLE=server); the attach client loads it too but stays
+// inert, so usage events have exactly one writer. If MNGR_AGENT_STATE_DIR is
+// unset (opencode run outside an mngr agent) it is a no-op. Every fs touch is
+// wrapped so a transient error never disrupts OpenCode's loop.
+//
+// Reported cost is authoritative for OpenCode (provenance REPORTED); tokens are
+// emitted for auditability. The model is provider-qualified (`<providerID>/
+// <modelID>`) to match the canonical pricing-table key. cost_mode is API_KEY:
+// OpenCode bills against a real provider key, not an imputed subscription.
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { randomBytes } from "node:crypto"
+import { appendFileSync, mkdirSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+// Kept in sync with the reader's discovery convention (events/<source>/usage).
+const USAGE_EVENTS_RELATIVE_PATH = "events/opencode/usage/events.jsonl"
+const SOURCE = "opencode/usage"
+const ROLE_ENV_VAR = "MNGR_OPENCODE_ROLE"
+const SERVER_ROLE = "server"
+
+const _numberOrNull = (value: unknown): number | null => (typeof value === "number" ? value : null)
+
+export const MngrUsagePlugin: Plugin = async () => {
+  const stateDir = process.env.MNGR_AGENT_STATE_DIR
+  if (!stateDir || process.env[ROLE_ENV_VAR] !== SERVER_ROLE) {
+    return {}
+  }
+  const usagePath = join(stateDir, USAGE_EVENTS_RELATIVE_PATH)
+
+  let usageDirEnsured = false
+  const appendUsage = (line: string): void => {
+    try {
+      if (!usageDirEnsured) {
+        mkdirSync(dirname(usagePath), { recursive: true })
+        usageDirEnsured = true
+      }
+      appendFileSync(usagePath, line + "\n")
+    } catch {
+      // best-effort: a transient fs error must not break OpenCode's loop
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (event.type !== "message.updated") {
+        return
+      }
+      const message = (event.properties as any)?.info
+      if (!message || message.role !== "assistant") {
+        return
+      }
+      const sessionId = message.sessionID
+      if (typeof sessionId !== "string" || !sessionId) {
+        // session_id is contractually required by the reader; skip if absent.
+        return
+      }
+
+      const cost = _numberOrNull(message.cost)
+      const rawTokens = message.tokens
+      const hasTokens = rawTokens && typeof rawTokens === "object"
+      if (cost === null && !hasTokens) {
+        // Nothing to report yet (e.g. an assistant message before any usage lands).
+        return
+      }
+
+      // OpenCode token buckets are non-overlapping: input is non-cached, cache.read
+      // / cache.write are separate. Reasoning is folded into output (the wire
+      // convention: output includes reasoning, billed at the output rate). The
+      // reported cost is authoritative regardless of this bucketing.
+      const tokens = hasTokens
+        ? {
+            input: _numberOrNull(rawTokens.input),
+            output: (rawTokens.output ?? 0) + (rawTokens.reasoning ?? 0),
+            cache_read: _numberOrNull(rawTokens.cache?.read),
+            cache_creation: _numberOrNull(rawTokens.cache?.write),
+          }
+        : null
+
+      const model =
+        typeof message.providerID === "string" && typeof message.modelID === "string"
+          ? `${message.providerID}/${message.modelID}`
+          : null
+
+      const record = {
+        source: SOURCE,
+        type: "cost_snapshot",
+        event_id: "evt-" + randomBytes(16).toString("hex"),
+        timestamp: new Date().toISOString(),
+        session_id: sessionId,
+        message_id: typeof message.id === "string" ? message.id : null,
+        cost: cost === null ? null : { total_cost_usd: cost },
+        tokens,
+        model,
+        cost_mode: "API_KEY",
+      }
+      appendUsage(JSON.stringify(record))
+    },
+  }
+}

imbue_mngr_opencode_usage-0.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: imbue-mngr-opencode-usage
+Version: 0.1.0
+Summary: OpenCode usage data provider for `mngr usage` (per-agent in-process plugin that captures per-message cost + tokens)
+Requires-Python: >=3.12
+Requires-Dist: imbue-mngr-opencode==0.2.16
+Requires-Dist: imbue-mngr-usage==0.1.5
+Requires-Dist: imbue-mngr==0.2.16
+Description-Content-Type: text/markdown
+
+# imbue-mngr-opencode-usage
+
+OpenCode data provider for `mngr usage`. Single responsibility: install a second
+in-process TypeScript plugin into each OpenCode agent so each assistant message
+appends one event to `$MNGR_AGENT_STATE_DIR/events/opencode/usage/events.jsonl`.
+The `mngr usage` CLI walks those events files itself (see `imbue-mngr-usage`).
+
+## How the pieces fit
+
+```
+mngr_opencode_usage's on_after_provisioning hookimpl
+  └─→ installs <config_dir>/plugin/mngr_opencode_usage_plugin.ts
+        (alongside mngr_opencode's lifecycle plugin; OpenCode auto-loads plugin/*.ts)
+
+OpenCode serve process, on each assistant message.updated
+  └─→ mngr_opencode_usage_plugin.ts
+        └─→ events/opencode/usage/events.jsonl (append one cost_snapshot event)
+
+mngr usage
+  └─→ aggregate_usage_source hookimpl (claims the "opencode" source)
+        └─→ aggregate_session_incremental: sum each session's messages
+```
+
+All file I/O goes through `host.write_text_file`, so provisioning works for local
+**and** remote agents.
+
+## What gets captured
+
+OpenCode computes cost and tokens per message and exposes them on each assistant
+`message.updated` event. The writer emits, per message, a self-contained event
+carrying:
+
+- `cost.total_cost_usd` -- OpenCode's own per-message cost (provenance is
+  **REPORTED**; no estimation needed).
+- `tokens` -- `{input, output, cache_read, cache_creation}` (reasoning folded
+  into output), for auditability.
+- `model` -- the provider-qualified `<providerID>/<modelID>`.
+- `session_id` + `message_id` -- the reader sums per session, keeping the freshest
+  event per `message_id` so a streaming message's re-fires collapse to its final
+  reading.
+
+## Why session-incremental
+
+OpenCode reports each message's **own** cost, not a session running total. So the
+writer is stateless -- it appends one self-contained event per message and keeps
+nothing in memory. The reader (`aggregate_session_incremental`) recomputes each
+session's total from the append-only log, which makes it robust across
+`mngr stop`/`start` (a fresh serve process with empty memory loses no history).
+
+`cost_mode` is `API_KEY`: OpenCode bills against a real provider key, so the cost
+is real spend, never an imputed subscription value.

imbue_mngr_opencode_usage-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+imbue/mngr_opencode_usage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imbue/mngr_opencode_usage/plugin.py,sha256=v6ZJkjostwe19wGTSzP2MpZC05m6aaP_ghkZu2J_dqc,4097
+imbue/mngr_opencode_usage/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imbue/mngr_opencode_usage/resources/mngr_opencode_usage_plugin.ts,sha256=n5aH-KJhYQcP4cvHTbOecCy3hu_cY2icKFb5D6M5lD4,4769
+imbue_mngr_opencode_usage-0.1.0.dist-info/METADATA,sha256=vigvdvpDpH3OGZXFux23kqN87wrAL86CAgzsCuPQhgg,2639
+imbue_mngr_opencode_usage-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+imbue_mngr_opencode_usage-0.1.0.dist-info/entry_points.txt,sha256=s07aVwJ7EhFeoSJBLIvlBeGSRHTWWivttBgLNt9-ok0,57
+imbue_mngr_opencode_usage-0.1.0.dist-info/RECORD,,

imbue_mngr_opencode_usage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

imbue_mngr_opencode_usage-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mngr]
+opencode_usage = imbue.mngr_opencode_usage.plugin