Skip to content

Add delegate observability + metering (#39 slice 6)#48

Merged
Jason-Vaughan merged 1 commit into
mainfrom
feat/delegate-observability
Jun 18, 2026
Merged

Add delegate observability + metering (#39 slice 6)#48
Jason-Vaughan merged 1 commit into
mainfrom
feat/delegate-observability

Conversation

@Jason-Vaughan

Copy link
Copy Markdown
Owner

What

The deferred non-local delegate metering, landed as orchestration-tree observability. Delegated sub-calls are now metered and broken down by backend — without corrupting the existing "spend avoided" headline.

  • measurement — records gain a kind field (task default / delegate; older records read as task). rollup keeps delegate records out of the headline (no double-count — the parent task already credits the whole job) and aggregates them separately into summary["delegates"] = {count, by_backend: {model: {count, in/out tokens}}, in/out tokens, cloud_equiv_usd}. format_rollup adds a "Delegated sub-tasks" section (omitted when there are none). A process-level lock serializes the log append (delegate_many fans out across threads).
  • delegaterun_delegate meters each sub-call as kind="delegate" at a single seam, so delegate_many inherits it for free. A metering error never breaks the delegation.
  • GUI — the stats card renders the delegate breakdown.

Why

Slice 6 of the scatter-gather roadmap (#39). Until now, delegated work was invisible to measurement — you could see the top-level task but not which backends did the offloaded sub-work. This makes the fan-out observable (which backend → how much) while keeping the spend-avoided number honest (delegations are informational, never double-credited). It's also the data source that would tell us whether a delegate_reduce tool (slice 4) ever earns code.

Scope

The per-parent-task tree (linking each delegation to its specific top-level task across processes) is deferred — it needs a task-id propagated through the orchestrator CLIs to the MCP child, which can't be verified hermetically. This slice delivers the robust by-backend aggregate.

Test plan

  • +13 hermetic tests: kind written (default/explicit); rollup excludes delegates from the headline (tasks/by_tier/tokens/spend_avoided unaffected) and into delegates; kindless record → task; by-backend aggregation; format_rollup shows/omits the section; 20-thread concurrent append → 20 well-formed lines (thread-safety); run_delegate meters kind="delegate"; a raising record_task doesn't break delegation; GUI view_stats carries delegates.
  • +1 gated live metering check (temp TANGLEBRAIN_STATE_DIR).
  • Test isolation verified: ran the full suite with no state-dir override — the real ~/.cache/tanglebrain/usage.jsonl was untouched (3 lines → 3 lines).
  • Full suite green under clean-roster conditions: 380 pass / 14 skipped; make lint OK.
  • Independent Critic review: SHIP (3 doc-parity fixes applied — stale "not metered" notes in docstrings + roster comment).

Part of #39 (slice 6; does not close the epic). Also promotes the pending slice-4 ### Internal entry into this release.

🤖 Generated with Claude Code

Meter delegated sub-calls and surface them, without corrupting the
spend-avoided headline. The deferred non-local delegate metering.

- measurement: records gain a `kind` field (task|delegate; old records
  read as task). `rollup` keeps delegate records OUT of the headline
  (no double-count — the parent task already credits the whole job) and
  aggregates them separately into `summary["delegates"]` (count, by
  backend, est tokens, informational cloud-equiv). `format_rollup` shows
  a "Delegated sub-tasks" section. Process-level lock serializes the
  log append (delegate_many fans out across threads).
- delegate: `run_delegate` meters each sub-call as kind="delegate" at a
  single seam (delegate_many inherits it); a metering error never breaks
  the delegation.
- GUI: stats card shows the delegate breakdown.
- README/ARCHITECTURE/CHANGELOG/roster comment + docstrings updated
  (the old "not metered" notes corrected). +13 hermetic tests (380 pass)
  + a gated live metering check. Independent Critic: SHIP (3 doc-parity
  fixes applied).

The per-parent-task cross-process tree is deferred.
@Jason-Vaughan Jason-Vaughan merged commit c029b98 into main Jun 18, 2026
3 checks passed
@Jason-Vaughan Jason-Vaughan deleted the feat/delegate-observability branch June 18, 2026 21:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant