microsoft / microsoft/amplifier

[app-cli] Document events.jsonl (`amplifier.log` schema) as a stable, versioned integration surface

Open
#315 0 comments 0 reactions 0 assignees View on GitHub

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.

  1. Document the amplifier.log record shape and the lifecycle event vocabulary as a supported integration surface (even with an "additive changes within major version 1" caveat).
  2. Commit to major-version discipline: bump schema.ver major on breaking changes so consumers can gate safely.
  3. Note event-ordering caveats in the docs (we observed records near shutdown appearing out of timestamp order, and background session-naming llm:request/provider:retry records after prompt:complete — both fine, but worth documenting).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.