bridge: emit context-window stats in inbox pull meta

[benvinegar]

Summary

Add context-window and session token usage stats to broker pull telemetry metadata.

This builds on the merged inbox pull meta support and extends baudbot to emit context pressure metrics that the broker can ingest into Analytics Engine.

What changed

• pi/extensions/context.ts

  • Persist best-effort snapshot file at ~/.pi/agent/context-usage.json.
  • Snapshot is written atomically on:
    • session_start
    • turn_end
    • tool_result
  • Snapshot fields include:
    • context_window_used_tokens
    • context_window_limit_tokens
    • context_window_used_pct
    • session_total_tokens
    • session_total_cost_usd

• slack-bridge/broker-bridge.mjs

  • Reads ~/.pi/agent/context-usage.json (best effort).
  • Merges available values into POST /api/inbox/pull meta:
    • context_window_used_tokens
    • context_window_limit_tokens
    • context_window_used_pct
    • session_total_tokens
    • session_total_cost_usd

• test/broker-bridge.integration.test.mjs

  • Extends inbox pull test to validate the context usage fields are emitted in meta when snapshot file is present.

• CONFIGURATION.md

  • Documents that broker-mode pull meta includes context usage from ~/.pi/agent/context-usage.json.

Validation

• npm test -- test/broker-bridge.integration.test.mjs
• npm run typecheck

Follow-up

Broker-side mapping in modem-dev/baudbot-services is still required to store/query these fields in Analytics Engine.

[greptile-apps]

Greptile Summary

Extends broker pull telemetry by persisting context-window stats from the agent and emitting them to the broker for analytics. The implementation uses atomic file writes and best-effort reads to avoid disrupting runtime.

• Added snapshot persistence in context.ts with atomic writes on session_start, turn_end, and tool_result events
• Broker bridge reads and validates the snapshot, merging 5 telemetry fields into pull meta
• Test coverage validates all telemetry fields are correctly emitted when snapshot exists
• Documentation updated to describe the new telemetry behavior

Minor inconsistency found: tool_result handler uses fire-and-forget async pattern while other event handlers await the snapshot write.

Confidence Score: 4/5

• Safe to merge with minor async handling inconsistency
• The implementation is solid with atomic writes, proper error handling, comprehensive test coverage, and follows best practices. The only issue is a minor style inconsistency in async handling patterns that doesn't affect correctness
• Consider reviewing pi/extensions/context.ts:523 for async handling consistency

Important Files Changed

Filename	Overview
pi/extensions/context.ts	Added context-window snapshot persistence to file system with atomic writes on session_start, turn_end, and tool_result events
slack-bridge/broker-bridge.mjs	Reads context-usage.json snapshot and merges valid telemetry fields into broker pull meta with proper validation
test/broker-bridge.integration.test.mjs	Added test coverage for context usage telemetry fields in broker pull meta with temporary HOME directory override
CONFIGURATION.md	Documents that broker-mode pull meta includes context usage telemetry from snapshot file

Sequence Diagram

sequenceDiagram
    participant Agent as Pi Agent Extension
    participant FS as File System
    participant Bridge as Broker Bridge
    participant Broker as Remote Broker

    Note over Agent: Event triggers (session_start, turn_end, tool_result)
    Agent->>Agent: buildContextUsageSnapshot()
    Agent->>Agent: Calculate tokens, costs, percentages
    Agent->>FS: Write to ~/.pi/agent/context-usage.json.tmp
    Agent->>FS: Atomic rename to context-usage.json
    Note over FS: Snapshot persisted (best-effort)

    Note over Bridge: Broker pull interval
    Bridge->>FS: Read ~/.pi/agent/context-usage.json
    Bridge->>Bridge: Parse and validate numeric fields
    Bridge->>Bridge: Merge into buildPullMeta()
    Bridge->>Broker: POST /api/inbox/pull with meta
    Note over Broker: Analytics Engine ingestion

Loading

_{Last reviewed commit: e3f9415}

[greptile-apps]

_{4 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Inconsistent async handling - tool_result uses void (fire-and-forget) while turn_end and session_start use await

Suggested change

	void persistSnapshotFromContext(ctx);
	await persistSnapshotFromContext(ctx);

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: pi/extensions/context.ts
Line: 523

Comment:
Inconsistent async handling - `tool_result` uses `void` (fire-and-forget) while `turn_end` and `session_start` use `await`

```suggestion
		await persistSnapshotFromContext(ctx);
```

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.