Text of github.github.com › gh-aw › specs › unified-agent-session-specification as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Unified Agent Session Specification | GitHub Agentic Workflows

Skip to main content Unified Agent Session Specification Version : 2.11.0 Status : Draft Publication Date : 2026-11-17 Editors : GitHub Agentic Workflows Team (GitHub) This Version : unified-agent-session-specification Latest Version : This document Abstract Section titled “Abstract” This specification defines the session traces used by GitHub Agentic Workflows: ordered arrays of Copilot-compatible event objects containing type , data , and optional native metadata.

It establishes a loss-preserving parser contract for Claude, Copilot, Codex, Gemini, Pi, and custom engines, including OpenCode and Goose sample integrations, and a conclusion-job projection of essential agent, MCP gateway (MCPG), agent workflow firewall (AWF), safe-output, experiment, grader, and eval payloads. The serialized usage/aw_session.jsonl begins with a numeric file-format version header, followed by timestamp-ordered evidence with source provenance; untimed observations remain available without invented timestamps.

Native evidence, canonical parser traces, and existing accounting artifacts remain available separately. TypeScript declarations generate machine-readable schemas for both representations. Status of This Document Section titled “Status of This Document” This is a GitHub Agentic Workflows project specification , written using W3C-inspired document conventions. It is not an official W3C standard , W3C publication, or W3C-endorsed recommendation.

Version 2.11.0 is a draft governed by the project’s normal review process. It may be updated, replaced, or superseded. The accompanying implementation and regression suites exercise this contract, including the sampled CI sessions identified in Section 9.4. This is not a blanket declaration of conformance for every engine version or source format. Section 10 records historical pre-implementation gaps, not current defects.

Approval and ongoing compliance testing remain project responsibilities. The specification version belongs to this document. The unified file’s leading session.format record carries an independent numeric serialization-format version; native trace records do not receive per-event specification versions. Table of Contents Section titled “Table of Contents” Introduction (Informative) Conformance (Normative) Trace Model (Normative) Core Event Vocabulary (Normative) Parsing and Normalization (Normative) Usage and Session Accounting (Normative) Engine Mappings (Normative) Renderers and Bootstrap Telemetry (Normative) Compliance Testing (Normative) Implementation Gap Matrix (Informative) References Appendices (Informative) Change Log (Informative) 1.

Introduction (Informative) Section titled “1. Introduction (Informative)” 1.1 Purpose and scope Section titled “1.1 Purpose and scope” The parsers in actions/setup/js/ translate different engine logs into a shared conversation model. log_parser_shared.cjs exposes convertLegacyLogEntriesToCopilotEvents and convertCopilotEventsToLegacyLogEntries ; the first establishes the canonical event representation, while the second supports existing legacy renderers.

This specification covers parsing supported input records, canonical conversion, usage aggregation, tool correlation, compatibility projections, bootstrap telemetry, and conclusion-job artifact merging. It does not generally specify engine execution, workflow frontmatter, model behavior, transport protocols, or a cross-language storage API; Section 7.6 additionally constrains ingestion and publication for opt-in protected declarative sessions.

JSON and JSON Lines are serialization forms, not different session models. Section 3.8 additionally defines a bounded, lossy compact unified-session profile for metadata delivery; it never replaces the full session artifact. 1.2 Data flow Section titled “1.2 Data flow” engine log / native event stream | tolerant parser | ordered canonical events / \ summary renderer session.result selection | | legacy display legacy telemetry projection projection for existing metric readers The parser’s existing return object can contain markdown , logEntries , mcpFailures , and maxTurnsHit .

The session trace is the logEntries array, not that return object. The agent artifact already contains native session evidence: Copilot session events.jsonl , Pi pi-streaming.jsonl , and other engine logs such as agent-stdio.log . The bootstrap additionally persists its redacted, normalized logEntries as agent-session.jsonl so conclusion can reuse canonical events without parsing the same native transcript again. After downloading agent, detection, safe-output, experiment, and eval evidence, the conclusion job merges these observations into usage/aw_session.jsonl .

Conclusion also downloads activation’s info artifact to collect runner-owned aw_info.json as workflow.info , including available engine, model, version, revision, and trigger metadata. Runtime model metadata, when captured, takes precedence over the activation snapshot. The agent artifact also carries the split activation aw-prompts/system.txt and aw-prompts/user.txt files; the merger records each available file as an untimed prompt.system or prompt.user event with its exact content and source path.

These prompt events are omitted from default summaries. Built-in graders compute from the redacted in-memory unified session in conclusion, after all sources are collected. Their manifest and result events are appended before the session is persisted; grader files are written into the usage artifact. Graders never reread the session or source files. Collection and upload run after conclusion handlers, before setup cleanup.

The existing usage JSON, JSONL accounting, activity summary, and result files remain available. 1.3 Terminology Section titled “1.3 Terminology” Term Meaning Canonical event An object with a dot-namespaced type , a data object, and any supplied native metadata. Core event One of the eight common agent event types in Sections 4.1–4.6. Runtime observations and file metadata have additional declared signatures. Native extension event A native event with another dot-namespaced type, such as session.shutdown or assistant.message_delta , retaining its original payload.

Legacy entry A supported pre-event record, such as system / init , assistant , user , or result . Raw engine record An engine-specific record that still needs mapping, such as Gemini tool_result or Codex item.completed . Partial trace A trace missing some source evidence, including a start, completion, final message, usage report, or terminal record. Dangling call A tool start with no matching observed completion. Orphan completion A tool completion with no matching observed start.

Per-turn report Accounting for one distinct model turn or response, not a session-total snapshot. Snapshot An accounting observation covering work already reported, rather than additional work. Projection A derived compatibility or presentation view, not a replacement for the canonical trace. 2. Conformance (Normative) Section titled “2. Conformance (Normative)” 2.1 Requirement levels Section titled “2.1 Requirement levels” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 .

T-UAS-001 — Conformance claims. An implementation claiming conformance MUST identify its conformance class and supported engines. It MUST satisfy every applicable MUST and MUST NOT requirement and report unsupported engine mappings rather than claiming full pipeline conformance. T-UAS-002 — Normative scope. Conformance assessment MUST use the explicitly normative sections and their identified requirements. Informative examples, implementation observations, and references to source code MUST NOT override the normative contract.

2.2 Conformance classes Section titled “2.2 C

The rest of this page is on the live site.