feat(handlers): add agent usage metrics and sub-agent tracking

[digitalfiz]

Summary

• Agent attribution on existing metrics — opencode.token.usage, opencode.cost.usage, opencode.cache.count, opencode.message.count, and opencode.model.usage now carry an agent attribute, enabling per-agent cost/token breakdowns in dashboards. The agent name is sourced from SessionTotals (populated by the chat.message hook on each user prompt) and defaults to "unknown" when absent. The api_request and api_error log records are also tagged.

• Sub-agent invocation counter — new opencode.subtask.count counter fires on every SubtaskPart event (when opencode spawns a sub-agent), with agent, session.id, and project.id attributes. A subtask_invoked log record is always emitted alongside it (respects OPENCODE_DISABLE_METRICS=subtask.count).

• Session-level sub-agent tagging — opencode.session.count and the session.created log record now include is_subagent (boolean), derived from the presence of Session.parentID, making it straightforward to distinguish root sessions from sub-agent child sessions.

Changes

File	What changed
src/types.ts	Added subtaskCounter to Instruments; added agent field to SessionTotals
src/otel.ts	Registered opencode.subtask.count counter instrument
src/util.ts	Preserved agent field when accumulating session totals
src/handlers/message.ts	Added agent attr to all 5 counters and both log records; added SubtaskPart handling
src/handlers/session.ts	Added is_subagent attr to session counter and log record; seeded agent: "unknown" in SessionTotals
src/index.ts	chat.message hook now writes agent into sessionTotals for the session
tests/	34 new tests covering all new behaviour; 151 total, all passing

Testing

bun run typecheck  # clean
bun test           # 151 pass, 0 fail

Summary by CodeRabbit

Release Notes

• New Features

  • Added sub-agent invocation tracking with new subtask metrics for better visibility.
  • Enhanced telemetry with agent attribution across all metrics and logs.
  • Improved session tracking to distinguish between main agents and sub-agents.

• Tests

  • Added comprehensive test coverage for subtask metrics and agent attribution functionality.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Changes add subtask invocation tracking via a new metric counter and propagate an agent identifier through session state into all telemetry emissions. Session creation now detects subagent relationships via parentID and initializes agent tracking consistently.

Changes

Cohort / File(s)	Summary
Type & Instrument Definitions src/types.ts, src/otel.ts	Extended Instruments type with subtaskCounter and updated createInstruments to instantiate the new counter with unit {subtask}. Extended SessionTotals type to include agent: string field.
Message & Part Handling src/handlers/message.ts	Added subtask part-type recognition to handleMessagePartUpdated with telemetry emission and counter increment; refactored handleMessageUpdated to derive agent from session totals and inject it into all token, cost, cache, message, model-usage, and log attributes.
Session Creation & State src/handlers/session.ts, src/util.ts, src/index.ts	Updated handleSessionCreated to derive is_subagent from parentID and include it in metrics; modified session totals initialization to include agent: "unknown". Updated accumulateSessionTotals to preserve agent field. Modified "chat.message" handler to derive and persist agent into per-session totals.
Test Helpers & Infrastructure tests/helpers.ts	Extended MockContext to include subtaskCounter spy and updated makeCtx() to instantiate it alongside other counter mocks.
Handler & Feature Tests tests/handlers/message.test.ts, tests/handlers/session.test.ts, tests/handlers/disabled-metrics.test.ts	Added test helpers and suites validating agent propagation into all metric/log attributes, subtask counter behavior with agent/session attributes, is_subagent detection in session creation, and disabled-metrics compliance for subtask.count.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• feat(observability): add debug logging and enhanced metrics (v0.3.0) #8 — Directly modifies sessionTotals state management, OpenTelemetry instruments, and handlers (session.ts, index.ts, types.ts) that this PR extends with agent propagation.
• feat(ci): add release workflow and clean up plugin packaging #1 — Introduces createInstruments and Instruments type definitions that this PR extends with subtaskCounter.
• feat(config): add OPENCODE_DISABLE_METRICS to suppress individual metrics #11 — Implements disabled-metrics gating logic that this PR's tests explicitly verify for the new subtask.count metric.

Poem

🐰 Hops through telemetry fields so bright,
Agent pathways now in sight!
Subtasks counted, sessions flow,
Subagents' parentage we know,
Metrics bloom with propagation's light! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding agent usage metrics and sub-agent tracking across the codebase.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agent-usage-metrics

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

CodeRabbit can approve the review once all CodeRabbit's comments are resolved.

Enable the reviews.request_changes_workflow setting to automatically approve the review once all CodeRabbit's comments are resolved.