Commit a9771f7

const fs = require("fs");

const { isSessionEvent } = require("./agent_session.cjs");

const { collectUnifiedSession, parseEngineSession } = require("./unified_session.cjs");

const { serializeSessionArtifact } = require("./session_artifact.cjs");

const { generateCopilotCliStyleSummary } = require("./log_parser_shared.cjs");

const { validateSessionFileHeader } = require("./unified_session_render.cjs");

function readSessionInput(inputPath) {

try {

return fs.readFileSync(inputPath, "utf8");

} catch (error) {

throw new Error(`Failed to read session input ${inputPath}`, { cause: error });

}

function sessionCLI(args) {

const [mode, inputPath, engine, customParser] = args;

if (!inputPath) throw new Error("A session input path is required");

if (mode === "reconstruct") {

const { events, maskedValues } = collectUnifiedSession({

rootDir: inputPath,

...(engine ? { engine } : {}),

warn: message => console.error(message),

});

if (!events.some(event => event.provenance?.component === "agent")) throw new Error("No recognizable agent session found in the agent artifact");

return serializeSessionArtifact(events, maskedValues);

}

if (mode === "markdown") {

const events = readSessionInput(inputPath)

.split(/\r?\n/)

.filter(line => line.trim())

.map((line, index) => {

let event;

try {

event = JSON.parse(line);

} catch (error) {

throw new Error(`Invalid session JSONL at record ${index + 1}`, { cause: error });

}

if (!isSessionEvent(event)) throw new Error(`Invalid session event at record ${index + 1}`);

return event;

});

validateSessionFileHeader(events);

return generateCopilotCliStyleSummary(events) + "\n";

}

if (mode === "agent-markdown") {

if (!engine) throw new Error("An engine is required to parse an agent log");

if (customParser) {

if (customParser !== "behavior_log_parser.cjs") throw new Error("Invalid custom log parser");

const parsed = require("./" + customParser).parseLog(readSessionInput(inputPath));

if (typeof parsed === "string") return parsed + "\n";

if (Array.isArray(parsed?.mcpFailures) && parsed.mcpFailures.length > 0) {

throw new Error(`MCP server(s) failed to launch: ${parsed.mcpFailures.join(", ")}`);

}

if (parsed?.maxTurnsHit) throw new Error("Agent execution stopped: max-turns limit reached");

if (Array.isArray(parsed?.logEntries) && parsed.logEntries.length > 0) {

return generateCopilotCliStyleSummary(parsed.logEntries) + "\n";

}

if (typeof parsed?.markdown === "string") return parsed.markdown + "\n";

return generateCopilotCliStyleSummary(parsed?.logEntries ?? []) + "\n";

}

return generateCopilotCliStyleSummary(parseEngineSession(readSessionInput(inputPath), engine)) + "\n";

}

throw new Error(`Unsupported session CLI mode: ${mode}`);

if (require.main === module) {

try {

process.stdout.write(sessionCLI(process.argv.slice(2)));

} catch (error) {

console.error(error instanceof Error ? error.message : String(error));

process.exitCode = 1;

}

module.exports = { sessionCLI };

import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import fs from "node:fs";

import os from "node:os";

import path from "node:path";

import { sessionCLI } from "./session_cli.cjs";

describe("Session CLI adapter", () => {

let root;

beforeEach(() => {

root = fs.mkdtempSync(path.join(os.tmpdir(), "gh-aw-session-cli-"));

});

afterEach(() => {

vi.restoreAllMocks();

fs.rmSync(root, { recursive: true, force: true });

});

function write(name, events) {

const file = path.join(root, name);

fs.mkdirSync(path.dirname(file), { recursive: true });

fs.writeFileSync(file, typeof events === "string" ? events : events.map(event => JSON.stringify(event)).join("\n") + "\n");

return file;

}

it("reconstructs compact unified JSONL with source provenance and no invented timestamps", () => {

write("agent-session.jsonl", [{ type: "assistant.message", id: "native-id", data: { content: " exact text\n" } }]);

const jsonl = sessionCLI(["reconstruct", root]);

const lines = jsonl.trimEnd().split("\n");

const events = lines.map(JSON.parse);

expect(events[0]).toMatchObject({ type: "session.format", data: { version: 1 } });

expect(events.find(event => event.type === "assistant.message")).toEqual({

type: "assistant.message",

id: "native-id",

data: { content: " exact text\n" },

provenance: { component: "agent", phase: "agent", path: "agent-session.jsonl", index: 0 },

});

expect(lines.every(line => JSON.stringify(JSON.parse(line)) === line)).toBe(true);

expect(jsonl.endsWith("\n")).toBe(true);

});

it("renders unified Markdown using the privacy-preserving shared summary", () => {

write("agent-session.jsonl", [

{ type: "user.message", data: { content: "private user prompt" } },

{ type: "assistant.message", data: { content: "Visible assistant response" } },

{ type: "tool.execution_start", data: { toolName: "bash", arguments: { command: "private shell command" } } },

]);

const file = write("usage/aw_session.jsonl", sessionCLI(["reconstruct", root]));

const markdown = sessionCLI(["markdown", file]);

expect(markdown).toContain("### Unified session");

expect(markdown).toContain("Visible assistant response");

expect(markdown).toContain("tool.execution_start");

expect(markdown).not.toContain("private user prompt");

expect(markdown).not.toContain("private shell command");

});

it("uses the engine parser for audit Markdown", () => {

const file = write("agent-stdio.log", '{"type":"item.completed","item":{"type":"agent_message","text":"Codex response"}}\n');

expect(sessionCLI(["agent-markdown", file, "codex"])).toContain("Codex response");

});

it("rejects unrecognized agent logs rather than returning a metadata-only session", () => {

write("agent-stdio.log", "unrecognized log text\n");

vi.spyOn(console, "error").mockImplementation(() => {});

expect(() => sessionCLI(["reconstruct", root, "claude"])).toThrow("No recognizable agent session");

});

it("rejects invalid session files and unsupported versions", () => {

expect(() => sessionCLI(["markdown", write("invalid.jsonl", "not JSON")])).toThrow();

expect(() => sessionCLI(["markdown", write("invalid-event.jsonl", [{ type: "assistant.message", data: [] }])])).toThrow("Invalid session event");

expect(() => sessionCLI(["markdown", write("missing-header.jsonl", [{ type: "assistant.message", data: {} }])])).toThrow("missing its leading");

expect(() => sessionCLI(["markdown", write("future.jsonl", [{ type: "session.format", data: { version: 2 }, provenance: { component: "collector" } }])])).toThrow("Unsupported unified session file-format version");

});

it("reports missing input, engine, and invalid modes", () => {

expect(() => sessionCLI([])).toThrow("input path is required");

expect(() => sessionCLI(["agent-markdown", root])).toThrow("engine is required");

expect(() => sessionCLI(["invalid", root])).toThrow("Unsupported session CLI mode");

});

package setup

import "embed"

var SessionParserSources embed.FS

mcpCmd, logsCmd, auditCmd, sessionsCmd, viewCmd, healthCmd, outcomesCmd, mcpServerCmd, prCmd, secretsCmd *cobra.Command

sessionsCmd: cli.NewSessionsCommand(),

cmds.sessionsCmd.GroupID = "analysis"

runCmd, removeCmd, cmds.statusCmd, cmds.listCmd, enableCmd, disableCmd, cmds.logsCmd, cmds.auditCmd, cmds.sessionsCmd, cmds.viewCmd,

**Date**: 2026-10-03

**Status**: Draft

**Deciders**: gh-aw maintainers (review pending)

This pull request adds a new `gh aw sessions download <run-id-or-url>` command so operators can export workflow sessions without generating a full audit report. Recent runs may already publish `usage/aw_session.jsonl`, but older runs often only contain agent artifacts, raw engine logs, or legacy metadata layouts. The implementation must preserve published JSONL byte-for-byte when it already exists, support historical artifact names and nested layouts, and provide both machine-readable JSONL and privacy-preserving Markdown output. The command also needs to work outside a source checkout, so the runtime parser sources used by Actions and audit summaries must be packaged for CLI reuse.

We will expose session export as a dedicated `gh aw sessions download` command that first prefers the published `usage/aw_session.jsonl` artifact and falls back to reconstructing the unified session from downloaded agent evidence when the published file is absent. We will reuse the same JavaScript session parsers and renderers already used by audit and workflow summaries by embedding their runtime sources in Go and executing them through a shared CLI adapter. We will validate unified session headers and records before returning output, support both `jsonl` and privacy-preserving `markdown` formats, and only reconstruct data from artifacts that are actually present instead of inventing missing evidence.

This would have been the simplest implementation because the CLI could just fetch the usage artifact and stream it to stdout. It was not chosen because the PR explicitly targets historical runs that predate unified session publication and therefore need reconstruction from agent artifacts, engine logs, and legacy metadata layouts.

A dedicated parser stack could have been tailored only for `sessions download` and avoided packaging the current audit parser sources for reuse outside a source checkout. It was not chosen because the PR intentionally shares the existing engine parsers, Markdown renderer, and validation path with audit and workflow summaries so session exports stay consistent across commands and do not fork parsing logic.

- Users can export a unified session directly from a workflow run without generating a full audit report.

- Historical runs remain usable because the command can reconstruct the current unified format from older artifact names, raw engine logs, and legacy directory layouts.

- Session parsing and Markdown rendering stay consistent with audit and workflow summaries because the same runtime sources are reused.

- The CLI now depends on packaging and executing embedded Node.js parser sources, which increases implementation complexity and introduces a runtime requirement for reconstruction and Markdown rendering.

- Session download logic must handle multiple artifact naming conventions, metadata sources, and flattening behaviors, which increases maintenance cost.

- Reconstruction can only report evidence that exists in downloaded artifacts, so older runs may still produce incomplete sessions when key artifacts are missing.

- Published `aw_session.jsonl` remains the preferred source of truth and is returned byte-for-byte when present.

- Markdown output is intentionally privacy-preserving and bounded, while JSONL remains the complete machine-readable format.

- The command is introduced as experimental, so its interface and output details can evolve as session export needs become clearer.

*ADR created by [adr-writer agent]. Review and finalize before changing status from Draft to Accepted.*

Experimental: download a unified agent session for an existing workflow run. The command writes

`usage/aw_session.jsonl` to standard output without changing its contents. If that

`agent-session.jsonl`: native Copilot events, Pi streams, and raw engine logs are

`--output/-o` (output file), `--repo/-r` (`[HOST/]owner/repo`; defaults to the