validate-session-schemas

name	validate-session-schemas
description	Loop over recent local AI-coding session log files for every supported file-based platform (Copilot Chat, Copilot CLI, JetBrains, Claude Code, Gemini CLI, Antigravity, OpenCode) and validate they still match the documented schema, while surfacing newly-discovered fields we could start using. Use after an editor/CLI update, when adding a parser, or on a schedule to catch schema drift early.

Validate Session Schemas Skill

Validates that recent session log files on the current machine still match the schema our parsers expect, per supported platform, and surfaces new fields that appeared on disk but aren't documented/used yet.

It answers two questions in one pass:

1. Did anything break? — Drift detection against a small set of fields our parsers actually depend on ("contracts"). A missing required field on an observed record type is a DRIFT failure.
2. Is there new information to use? — Any field observed on disk that is not in the known baseline ("knownFields") is reported as a new field. These are candidates for new features or better token attribution (e.g. real token counts, new model metadata, new event types).

Why this skill exists

The pre-existing copilot-log-analysis skill (analyze-session-schema.ps1) only covered VS Code Copilot Chat JSON + Copilot CLI JSONL + OpenCode, with crude substring-based "new field" detection. It did not loop per supported platform, had no recency window, and didn't cover JetBrains, Claude Code, Gemini CLI, or Antigravity. This skill closes that gap.

Platforms covered

The source of truth for supported platforms is src/adapters/adapterRegistry.ts. This skill validates the file-based JSON/JSONL ecosystems that have schema docs under docs/logFilesSchema/:

Platform id	Editor / tool	Format	Discovery root
copilot-chat	VS Code Copilot Chat	json / jsonl	VS Code variants workspaceStorage/*/chatSessions, globalStorage
copilot-cli	Copilot CLI	jsonl	~/.copilot/session-state/
jetbrains	JetBrains Copilot	jsonl	~/.copilot/jb/{uuid}/partition-*.jsonl
claude-code	Claude Code	jsonl	~/.claude/projects/{hash}/*.jsonl
gemini-cli	Gemini CLI	jsonl	~/.gemini/tmp/*/chats/session-*.jsonl
antigravity	Antigravity	jsonl	~/.gemini/antigravity/brain/*/.system_generated/logs/transcript.jsonl
opencode	OpenCode	json / jsonl	<xdg-data>/opencode/storage/session/**/ses_*.json; also opencode.db (SQLite, via node:sqlite)

Not validated by this skill (DB / binary formats that need the adapters' own parsers, so a generic JSON walker can't read them): crush (SQLite), visual-studio (MessagePack), continue, mistral-vibe, claude-desktop. They are listed in the report under "Not validated" so coverage is never silently overstated. If you add a new file-based adapter, add a discovery function + a schema-baselines.json entry here too.

Usage

# Validate every platform's recent sessions (last 30 days, 5 files each)
node .github/skills/validate-session-schemas/validate-session-schemas.js

# Widen the window and look at more files
node .github/skills/validate-session-schemas/validate-session-schemas.js --days 60 --max 10

# One platform only
node .github/skills/validate-session-schemas/validate-session-schemas.js --platform claude-code

# Machine-readable output (for CI / further processing)
node .github/skills/validate-session-schemas/validate-session-schemas.js --json

# Refresh the "known fields" snapshot from what's on disk (does NOT touch contracts)
node .github/skills/validate-session-schemas/validate-session-schemas.js --update-baseline

# Include truncated example values (may contain user content — off by default)
node .github/skills/validate-session-schemas/validate-session-schemas.js --include-examples

Options

Flag	Meaning
--days N	Only consider files modified within the last N days (default 30; 0 = no limit)
--max N	Analyze at most N most-recent files per platform (default 5)
--platform <id>	Validate a single platform
--update-baseline	Rewrite knownFields from observed fields; never modifies contracts
--include-examples	Capture truncated example values per field
--fail-on-new-fields	Exit non-zero when new fields are discovered
--json	Emit JSON only
--help	Usage

Exit codes

• 0 — all observed contracts pass (new fields alone do not fail unless --fail-on-new-fields)
• 1 — contract drift or an unparseable file
• 2 — configuration / environment error (bad args, missing baseline)

Per-platform statuses

PASS, DRIFT, NO_FILES (editor not installed / no sessions), NO_RECENT_FILES (sessions exist but none in the window), INCONCLUSIVE (recent files existed but no parseable records).

How drift and new-field detection work

schema-baselines.json holds two independent things per platform:

• contracts — hand-maintained list of the fields our parsers depend on, optionally scoped by format (json/jsonl) and a discriminator (the JSONL event type / kind). A contract is only evaluated when matching records are actually observed, so a union format never produces false drift for an event type that simply wasn't present. --update-baseline never changes contracts — edit them by hand when the parser's real dependencies change.
• knownFields — the last-known set of observed field paths. New = observed − known. Refresh with --update-baseline once you've reviewed and accepted the new fields.

Field-path notation: a.b nested, arr[] array items, arr[].c a field inside array items.

Acting on results

• DRIFT → a required field disappeared. Open the platform's doc under docs/logFilesSchema/ and the matching adapter under src/adapters/, confirm the change, and update both the parser and the contract.
• New fields → review them. If useful (e.g. real token counts, new model metadata, a new event type), document them in docs/logFilesSchema/, consider wiring them into the adapter/parser, then run --update-baseline to clear them from future reports.

Periodic run (optional)

This script is dependency-free Node and CI-friendly via its exit codes:

- name: Validate recent session schemas
  run: node .github/skills/validate-session-schemas/validate-session-schemas.js --json

(On CI the runner usually has no local session files, so most platforms report NO_FILES and the job passes — it's most useful run on a developer machine or a self-hosted runner that has real session data.)

Related

• docs/logFilesSchema/ — per-platform schema documentation (the human source of truth)
• .github/skills/copilot-log-analysis/ — deeper Copilot-only schema field dump (analyze-session-schema.ps1)
• .github/skills/validate-app-db-schema/ — validates the unrelated ~/.copilot/data.db hierarchy schema
• src/adapters/adapterRegistry.ts — canonical list of supported ecosystems