microsoft / microsoft/amplifier
[app-cli] Document events.jsonl (`amplifier.log` schema) as a stable, versioned integration surface
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 3.1k
- Forks
- 261
- Avg merge
- 3h 28m
- Merged PRs (30d)
- 13
Description
Context. Each session's events.jsonl (written by the hooks-logging module) is the best available signal for external tools to track session lifecycle: every record carries {"schema": {"name": "amplifier.log", "ver": "1.0.0"}, "event", "session_id", "ts", "data"}, and the lifecycle events (session:start, session:config, prompt:submit, execution:start/end, prompt:complete, session:resume, session:end) are exactly what a supervisor needs for busy/idle state and turn-completion notifications. We now drive a terminal-manager integration entirely from this file (danshapiro/freshell#514) — it's dramatically more reliable than inferring turn state from terminal output timing.
Ask.
- Document the
amplifier.logrecord shape and the lifecycle event vocabulary as a supported integration surface (even with an "additive changes within major version 1" caveat). - Commit to major-version discipline: bump
schema.vermajor on breaking changes so consumers can gate safely. - Note event-ordering caveats in the docs (we observed records near shutdown appearing out of timestamp order, and background session-naming
llm:request/provider:retryrecords afterprompt:complete— both fine, but worth documenting).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the hooks-logging module and the events.jsonl records described in the issue, focusing on the amplifier.log schema and listed lifecycle events. Document the record shape, additive version-1 policy, major-version rule, and observed ordering caveats; done means external consumers can understand and safely gate the integration.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100