Feature Request: Formalize events.jsonl as an official hook/integration API
- Ngôn ngữ chính
- Shell
- Star
- 11.2k
- Fork
- 1.9k
- Merge trung bình
- 14 giờ 16 phút
- Pull request đã merge (30 ngày)
- 6
Mô tả
## Summary
Copilot CLI already writes a rich, machine-readable event stream to `~/.copilot/session-state/{id}/events.jsonl` for every session. This file contains 20+ event types covering the full session lifecycle (task completion, user prompts, tool invocations, sub-agent activity, context compaction, model changes, etc.).
**This is effectively a zero-configuration hook system** — external tools can watch this file and react to events without any plugin API, registration, or modification to Copilot CLI itself.
## Proposal
Formalize `events.jsonl` as a **supported, documented external integration surface** with:
1. **Official documentation** of the event schema (types, data fields, guarantees)
2. **Stability contract** — which event types/fields are stable vs. internal/experimental
3. **Versioning** — a schema version field so consumers can handle format changes gracefully
4. **Best practices guide** for external consumers (file sharing mode, incremental reading, offset tracking)
## Why This Matters
Several community tools already consume this file for:
- **Toast notifications** when a task completes (the `session.task_complete` event even includes a natural-language summary)
- **Real-time activity indicators** (Working/Idle/NeedsInput/Problem states)
- **Session dashboards** and monitoring UIs
- **Webhook integration** (forward completion events to Slack, etc.)
- **Cost tracking** via `session.compaction_complete` token counts
Without documentation or stability guarantees, these integrations are fragile — any internal change to event formats could silently break them.
## Current Event Types (observed in v1.0.54)
| Event Type | Description |
|---|---|
| `session.start` | Session began (includes version, cwd, model) |
| `session.task_complete` | Agent finished work (**includes summary text**) |
| `session.shutdown` | Session ended permanently |
| `session.model_change` | Model switched |
| `session.mode_changed` | Mode changed (autopilot, etc.) |
| `session.plan_changed` | Implementation plan updated |
| `session.compaction_start/complete` | Context compaction (token counts) |
| `assistant.turn_start/end` | Agent reasoning turns |
| `assistant.message` | Agent output |
| `user.message` | User submitted prompt |
| `tool.execution_start/complete` | Tool invocations (includes tool name, args, success) |
| `subagent.started/completed` | Fleet agents |
| `skill.invoked` | Skill triggered |
| `hook.start/end` | Internal hooks |
| `abort` | User cancelled |
## Comparison to Claude Code Hooks
Claude Code requires explicit hook registration in `~/.claude/settings.json` and only fires 2 events (Stop, UserPromptSubmit). Copilot CLI's events.jsonl is **richer (20+ events), requires zero setup, and includes contextual data** like task summaries and token counts. The only tradeoff is ~1-2s detection latency vs. instant script invocation.
## Reference Implementation
I've documented the full pattern with code examples (PowerShell, C#, Node.js) and 10 use-case ideas:
https://gist.github.com/RockNoggin/8cc87f640ce5e3d284298a6db21f7523
## Ask
- Document the event schema officially
- Declare which events/fields are stable for external consumption
- Add a schema version to the JSON line format
- Consider adding a simple `session.idle` event (agent finished turn, no pending tool calls) to make done detection even easier for simple consumers
Hướng dẫn đóng góp
Hướng nghiên cứu
Start by reviewing the event stream at ~/.copilot/session-state/{id}/events.jsonl and the referenced integration examples in the linked gist. Define the documented schema, stability and versioning expectations, and consumer guidance; done means external consumers have an official, durable integration contract.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- json
- Lĩnh vực
- api, cli, documentation
- Loại issue
- Tính năng
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 35/100