GitHub UAS companion - Agent Session Record

Companion draft, separately versioned. Version: draft 0.1, for ASR format version 0.1 and the GitHub Unified Agent Session Specification v2.5.0 (serialization format version 1). Not part of core conformance.

GitHub’s Unified Agent Session Specification (UAS) normalizes the logs of the agent engines that GitHub Agentic Workflows runs (Claude, Copilot, Codex, Gemini, Pi and others) into a canonical trace. It also assembles a unified artifact with runtime evidence from one workflow run. ASR and UAS share several normalization rules; this companion maps between them. UAS persists its canonical trace in a file named agent-session.jsonl. Despite the name, that file is a UAS trace, not an ASR stream.

Shared normalization rules

UAS rule	ASR requirement
T-UAS-005: missing values do not mean zero; never invent IDs, timestamps, models, outcomes, durations, costs or token counts	ASR-500 to ASR-502
T-UAS-006: unknown events survive in order	ASR-113, ASR-615
T-UAS-016: continue parsing past malformed lines	ASR-009
T-UAS-019: array position determines order rather than timestamps	ASR-014
T-UAS-020, T-UAS-021: exact text; deltas joined by concatenation	ASR-211
T-UAS-022 to T-UAS-024: pair by exact ID; dangling starts (no matching completion) stay dangling; orphans (completions with no start) are kept	ASR-262 to ASR-266
T-UAS-030 to T-UAS-034: usage names, reasoning as a subset, explicit cache inclusion, no summing of snapshots	ASR-304 to ASR-311, ASR-319

Import (UAS to ASR)

producer.method: "import", producer.source: {"format": "gh-aw-uas", "formatVersion": "1"}. One ASR stream per agent session in the trace.

UAS event	ASR
`session.init`	The header (agent and model from its data; the model as a `config_change` when it is a selection rather than a served model).
`user.message`	`message`, `role: user`. `author` only when the engine’s data says who wrote it.
`assistant.message`	`message`, `role: assistant`, text parts.
`assistant.reasoning`	A reasoning-only `message`; `visibility` only when the data states it.
`assistant.refusal`	A `message` with a `refusal` part.
`tool.execution_start`	`tool_call` (`callId` from the event’s tool call ID, `callIdSource: native`).
`tool.execution_complete`	`tool_result` with `linkage: exact`; status from the event’s outcome.
`session.result`	`state` `ended`, and a `usage_summary` (`scope: session`) for its totals.
`subagent.started`, `subagent.completed`, `subagent.failed`	`subagent` records in the parent; separate child streams when the child’s events are separable (for example by parent tool use ID and agent ID, as for Claude SDK nested sessions, which share the root session ID).
Any other event (`mcp.rpc.`, `firewall.`, `model.`, `skill.`, `safe_output.`, `grader.result`, `eval.result`, `workflow.info`, `otel.`, …)	An audit-only vendor record of type `com.github.gh-aw/<event type>`, with the event in `native.record`.

Records are written in trace order; seq follows array position.
Event id values become record IDs where they fit the pattern (ASR-018), and are otherwise kept in native; parentId is preserved in native and not interpreted, as in UAS.
Per-record provenance goes in _meta["com.github.gh-aw/provenance"].
Token fields map to ASR usage. input_tokens_include_cache true, false or absent maps to includesCache true, false or null. Per-turn reports that accumulate become cumulative usage_summary records (ASR-319).
UAS has no file-edit or commit events: declare file_change as lost, unless the importer reads edits from tool inputs under the coding profile’s precision rules.
The compact unified session profile is a lossy view and SHOULD NOT be imported when the full trace is available.

Export (ASR to UAS)

An exporter writes a UAS canonical trace (layer 1) from a stream’s records in seq order:

ASR	UAS event
header	`session.init`
`message` user	`user.message`
`message` assistant (text parts)	`assistant.message`
reasoning parts and reasoning-only messages	`assistant.reasoning` (text only; opaque content and signatures never)
refusal parts	`assistant.refusal`
`tool_call`	`tool.execution_start` (calls with `requestedBy` other than `model` are flagged in the event’s data)
`tool_result`	`tool.execution_complete` (dangling calls get none)
`state` `ended` with the latest session `usage_summary`	`session.result`
`subagent`	`subagent.started` (and `subagent.completed` from the child’s end, when known)

Records with no UAS equivalent (file_change, vcs, compaction, rewind, permission, input_request, memory_change, delivery, plan, hook, terminal, gap, tombstone and others) are exported as namespaced events of type agent_session.<record type> containing the record. UAS allows these additional event types and preserves their order. The exporter omits these records on request. Branches are flattened to the primary head’s active path; the exporter declares this.

​Shared normalization rules

​Import (UAS to ASR)

​Export (ASR to UAS)

Shared normalization rules

Import (UAS to ASR)

Export (ASR to UAS)