Primary area
Cross-cutting / multiple
Related issue or feature request
Summary
TaskEvents today mix typed lifecycle events (task_created, session_started, pr_created) with free-form agent_milestone strings (step:implement:start, clone_complete). This RFC proposes a canonical event catalog with lowercase dot-notation names (e.g. step.started, agent.tool.completed), a stable JSON envelope for event-specific fields, and a documented boundary between product-facing events (durable, user-visible) and tracing logs (developer diagnostics).
Use case and motivation
Operators debugging long-running tasks need to filter, aggregate, and export events without parsing ad hoc milestone strings. CLI bgagent watch, notification dispatchers, and future eval pipelines all consume TaskEvents; inconsistent naming makes cross-run queries fragile.
Proposal
Event naming
Adopt lowercase dot notation. Initial catalog (illustrative): task.created, task.completed, step.started, step.completed, step.failed, agent.tool.started, agent.tool.completed, session.started.
Migration
- Phase 1: Document catalog; dual-emit legacy
event_type + new event field for one release.
- Phase 2: Update
watch.ts, fan-out dispatchers, and docs to prefer dot notation.
- Phase 3: Deprecate free-form milestone strings for step boundaries.
Tracing boundary
Document in OBSERVABILITY.md: CloudWatch/OTEL traces are for developers; TaskEvents are the operator audit trail.
Out of scope
- Replacing X-Ray / OTEL span names
- Changing DDB table keys or TTL
- Breaking CLI output in a single release without deprecation period
Potential challenges
- Tool-level events may increase DDB write rate; may need sampling or opt-in
--trace mode.
watch.ts and Slack templates need a mapping layer during migration.
Dependencies and integrations
agent/src/progress_writer.py, agent/src/workflow/runner.py, agent/src/hooks.pycli/src/commands/watch.ts, cdk/src/handlers/- Optional: JSON Schema in
contracts/task-events/
Note: Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.
Primary area
Cross-cutting / multiple
Related issue or feature request
step:<name>:start)Summary
TaskEvents today mix typed lifecycle events (
task_created,session_started,pr_created) with free-formagent_milestonestrings (step:implement:start,clone_complete). This RFC proposes a canonical event catalog with lowercase dot-notation names (e.g.step.started,agent.tool.completed), a stable JSON envelope for event-specific fields, and a documented boundary between product-facing events (durable, user-visible) and tracing logs (developer diagnostics).Use case and motivation
Operators debugging long-running tasks need to filter, aggregate, and export events without parsing ad hoc milestone strings. CLI
bgagent watch, notification dispatchers, and future eval pipelines all consume TaskEvents; inconsistent naming makes cross-run queries fragile.Proposal
Event naming
Adopt lowercase dot notation. Initial catalog (illustrative):
task.created,task.completed,step.started,step.completed,step.failed,agent.tool.started,agent.tool.completed,session.started.Migration
event_type+ neweventfield for one release.watch.ts, fan-out dispatchers, and docs to prefer dot notation.Tracing boundary
Document in OBSERVABILITY.md: CloudWatch/OTEL traces are for developers; TaskEvents are the operator audit trail.
Out of scope
Potential challenges
--tracemode.watch.tsand Slack templates need a mapping layer during migration.Dependencies and integrations
agent/src/progress_writer.py,agent/src/workflow/runner.py,agent/src/hooks.pycli/src/commands/watch.ts,cdk/src/handlers/contracts/task-events/Note: Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.