Add agent session index handoff

Author: renezander030

README.md

@@ -47,6 +47,7 @@ Andrej Karpathy's [LLM Wiki](https://www.mindstudio.ai/blog/andrej-karpathy-llm-
 - **Execution context.** `ats intent` captures outcome/why/done-when; `ats lifecycle` keeps stale context from steering current work; `ats security` scopes actions and audits allow/deny; `ats ledger` records what an agent did and whether the task advanced; `ats promote` turns exploration into a committed goal; `ats hierarchy evaluate` checks local work still supports its parent.
 - **Bounded events.** `ats events watch --json` emits deterministic `task.created/updated/completed/...` NDJSON, spooled `0600` with pending/ack recovery and stable dedup IDs. ATS only emits observations — a consumer still evaluates intent, validity, and security before acting.
 - **Task graph for agents.** Tasks become structured nodes with proof, writeback, review, lifecycle, and link edges instead of free-form memory text; see [`docs/task-graph-for-agents.md`](docs/task-graph-for-agents.md).
+- **Session-index handoff.** Coding-agent session browsers can keep raw transcript analytics while ATS stores the durable task-linked summary; see [`docs/agent-session-index.md`](docs/agent-session-index.md).
 - **Curated at write time.** Every item is hung on a "trunk" (a theme like `writing`, `client-work`) the moment it's captured, so retrieval has structure to grab.
 
 Metadata lives in flat YAML frontmatter on the task body, typed links in `## Related`, consulted sources in `## References`. Writes are **add-only** — ATS never drops a row or link a human added. [`npm run prove:intent`](examples/intent-layer/) runs a deterministic synthetic proof of the full path.

docs/agent-session-index.md

@@ -0,0 +1,45 @@
+# Agent session indexes
+
+Session browsers and analytics tools are good at answering "what happened in
+this coding-agent run?" ATS answers a different question: "what durable context
+should future agents retrieve from the task system?"
+
+The split is intentional:
+
+- session-index tools own raw transcript search, token charts, timeline views,
+  and per-run debugging
+- ATS owns durable task-linked memory, lifecycle validity, provenance, retrieval,
+  and writeback
+
+`@reneza/ats-core/session-index` provides the handoff schema between those layers.
+An agentsview-style tool can summarize a run and attach it to the task graph
+without asking ATS to become a transcript database.
+
+```js
+import { normalizeSessionIndexEntry, sessionIndexTaskBody } from '@reneza/ats-core/session-index';
+
+const session = normalizeSessionIndexEntry({
+  id: 'codex-2026-07-04-trivy-gate',
+  source: 'agentsview',
+  title: 'Build Trivy gate for skillgate',
+  repo: 'renezander030/skillgate',
+  cwd: '/work/github-repos/skillgate',
+  startedAt: '2026-07-04T08:00:00Z',
+  endedAt: '2026-07-04T08:40:00Z',
+  models: ['gpt-5'],
+  tools: ['shell', 'apply_patch'],
+  files: ['src/core.ts', 'src/spec.ts', 'test/core.test.ts'],
+  tasks: [{ projectId: 'github-oss', taskId: 'skillgate-trivy', role: 'source' }],
+  tokenStats: { input: 42000, output: 9000 },
+  outcome: 'tests-pass',
+  summary: 'Added a Trivy-backed gate for secrets, critical CVEs, and SBOM generation.',
+});
+
+const body = sessionIndexTaskBody(session);
+```
+
+The normalized entry is stable JSON: timestamps are ISO strings, arrays are
+deduplicated and sorted, token totals are explicit, and task references are kept
+as `{ projectId, taskId, role }` edges. Store the raw transcript wherever the
+session tool prefers; store the durable summary in ATS where retrieval can join
+it to work, decisions, blockers, and follow-up tasks.

packages/core/index.d.ts

@@ -31,6 +31,9 @@ export {
 
 export { record as logUsage } from './usage-log.js';
 
+export { SESSION_INDEX_VERSION, normalizeSessionIndexEntry, normalizeSessionIndex, sessionIndexTaskBody } from './session-index.js';
+export type { SessionTaskRef, SessionTokenStats, SessionIndexInput, SessionIndexEntry } from './session-index.js';
+
 export { runConformance, formatConformance } from './conformance.js';
 export type {
   ConformanceStatus,

packages/core/index.js

@@ -7,6 +7,7 @@ export {
   clear as clearCorpus,
 } from './corpus-cache.js';
 export { record as logUsage } from './usage-log.js';
+export { SESSION_INDEX_VERSION, normalizeSessionIndexEntry, normalizeSessionIndex, sessionIndexTaskBody } from './session-index.js';
 export { runConformance, formatConformance } from './conformance.js';
 export {
   TASK_CONTEXT_VERSION,

packages/core/package.json

@@ -30,6 +30,10 @@
       "types": "./usage-log.d.ts",
       "default": "./usage-log.js"
     },
+    "./session-index": {
+      "types": "./session-index.d.ts",
+      "default": "./session-index.js"
+    },
     "./task-context": {
       "types": "./task-context.d.ts",
       "default": "./task-context.js"

packages/core/session-index.d.ts

@@ -0,0 +1,56 @@
+export const SESSION_INDEX_VERSION: 1;
+
+export interface SessionTaskRef {
+  projectId: string;
+  taskId: string;
+  role?: string;
+}
+
+export interface SessionTokenStats {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+}
+
+export interface SessionIndexInput {
+  id: string;
+  source?: string;
+  title?: string;
+  cwd?: string;
+  repo?: string;
+  branch?: string;
+  startedAt: string;
+  endedAt?: string;
+  models?: string[];
+  tools?: string[];
+  files?: string[];
+  tasks?: SessionTaskRef[];
+  tokenStats?: Partial<SessionTokenStats>;
+  outcome?: string;
+  summary?: string;
+}
+
+export interface SessionIndexEntry {
+  version: 1;
+  id: string;
+  source: string;
+  title: string;
+  cwd: string | null;
+  repo: string | null;
+  branch: string | null;
+  startedAt: string;
+  endedAt: string | null;
+  models: string[];
+  tools: string[];
+  files: string[];
+  taskRefs: Array<Required<SessionTaskRef>>;
+  tokenStats: SessionTokenStats;
+  outcome: string | null;
+  summary: string | null;
+}
+
+export function normalizeSessionIndexEntry(entry: SessionIndexInput): SessionIndexEntry;
+export function normalizeSessionIndex(entries: SessionIndexInput[]): SessionIndexEntry[];
+export function sessionIndexTaskBody(entry: SessionIndexInput): string;

packages/core/session-index.js

@@ -0,0 +1,98 @@
+export const SESSION_INDEX_VERSION = 1;
+
+const TOKEN_FIELDS = ['input', 'output', 'cacheRead', 'cacheWrite', 'total'];
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function stringList(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map(cleanString).filter(Boolean))].sort();
+}
+
+function tokenStats(value = {}) {
+  const out = {};
+  for (const field of TOKEN_FIELDS) {
+    const n = Number(value[field] ?? 0);
+    out[field] = Number.isFinite(n) && n >= 0 ? n : 0;
+  }
+  if (!out.total) {
+    out.total = out.input + out.output + out.cacheRead + out.cacheWrite;
+  }
+  return out;
+}
+
+function iso(value, fallback = null) {
+  const text = cleanString(value);
+  if (!text) return fallback;
+  const d = new Date(text);
+  return Number.isNaN(d.getTime()) ? fallback : d.toISOString();
+}
+
+/**
+ * Normalize an agent-session summary into the stable ATS handoff schema.
+ * UI/indexing tools can own raw transcript search; ATS stores the durable
+ * task-linked facts an agent should retrieve across sessions.
+ */
+export function normalizeSessionIndexEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('session index entry must be an object');
+  }
+  const id = cleanString(entry.id);
+  if (!id) throw new Error('session index entry requires id');
+  const startedAt = iso(entry.startedAt);
+  if (!startedAt) throw new Error('session index entry requires valid startedAt');
+
+  const tasks = Array.isArray(entry.tasks) ? entry.tasks : [];
+  return {
+    version: SESSION_INDEX_VERSION,
+    id,
+    source: cleanString(entry.source) || 'agent-session',
+    title: cleanString(entry.title) || id,
+    cwd: cleanString(entry.cwd),
+    repo: cleanString(entry.repo),
+    branch: cleanString(entry.branch),
+    startedAt,
+    endedAt: iso(entry.endedAt),
+    models: stringList(entry.models),
+    tools: stringList(entry.tools),
+    files: stringList(entry.files),
+    taskRefs: tasks
+      .map((task) => ({
+        projectId: cleanString(task?.projectId),
+        taskId: cleanString(task?.taskId),
+        role: cleanString(task?.role) || 'related',
+      }))
+      .filter((task) => task.projectId && task.taskId),
+    tokenStats: tokenStats(entry.tokenStats),
+    outcome: cleanString(entry.outcome),
+    summary: cleanString(entry.summary),
+  };
+}
+
+export function normalizeSessionIndex(entries) {
+  if (!Array.isArray(entries)) throw new Error('session index must be an array');
+  return entries.map(normalizeSessionIndexEntry).sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.id.localeCompare(b.id));
+}
+
+export function sessionIndexTaskBody(entry) {
+  const s = normalizeSessionIndexEntry(entry);
+  const lines = [
+    `Agent session: ${s.title}`,
+    '',
+    `Source: ${s.source}`,
+    `Started: ${s.startedAt}`,
+  ];
+  if (s.endedAt) lines.push(`Ended: ${s.endedAt}`);
+  if (s.repo) lines.push(`Repo: ${s.repo}`);
+  if (s.cwd) lines.push(`CWD: ${s.cwd}`);
+  if (s.branch) lines.push(`Branch: ${s.branch}`);
+  if (s.models.length) lines.push(`Models: ${s.models.join(', ')}`);
+  if (s.tools.length) lines.push(`Tools: ${s.tools.join(', ')}`);
+  if (s.files.length) lines.push(`Files: ${s.files.join(', ')}`);
+  lines.push(`Tokens: ${s.tokenStats.total}`);
+  if (s.outcome) lines.push(`Outcome: ${s.outcome}`);
+  if (s.summary) lines.push('', s.summary);
+  return lines.join('\n');
+}

packages/core/test/session-index.test.js

@@ -0,0 +1,73 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  SESSION_INDEX_VERSION,
+  normalizeSessionIndex,
+  normalizeSessionIndexEntry,
+  sessionIndexTaskBody,
+} from '../session-index.js';
+
+test('normalizeSessionIndexEntry produces stable durable session summaries', () => {
+  const entry = normalizeSessionIndexEntry({
+    id: '  codex-123  ',
+    source: 'agentsview',
+    title: 'Build trivy gate',
+    cwd: '/repo/skillgate',
+    repo: 'renezander030/skillgate',
+    branch: 'main',
+    startedAt: '2026-07-04T10:00:00+02:00',
+    endedAt: '2026-07-04T10:20:00+02:00',
+    models: ['gpt-5', 'gpt-5', ''],
+    tools: ['shell', 'apply_patch'],
+    files: ['src/core.ts', 'src/core.ts', 'README.md'],
+    tasks: [
+      { projectId: 'p1', taskId: 't1', role: 'source' },
+      { projectId: '', taskId: 'missing' },
+    ],
+    tokenStats: { input: 100, output: 50 },
+    outcome: 'merged',
+    summary: 'Added a Trivy-backed finish-line gate.',
+  });
+
+  assert.equal(entry.version, SESSION_INDEX_VERSION);
+  assert.equal(entry.id, 'codex-123');
+  assert.equal(entry.startedAt, '2026-07-04T08:00:00.000Z');
+  assert.deepEqual(entry.models, ['gpt-5']);
+  assert.deepEqual(entry.files, ['README.md', 'src/core.ts']);
+  assert.deepEqual(entry.taskRefs, [{ projectId: 'p1', taskId: 't1', role: 'source' }]);
+  assert.deepEqual(entry.tokenStats, { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, total: 150 });
+});
+
+test('normalizeSessionIndex sorts sessions by start time then id', () => {
+  const entries = normalizeSessionIndex([
+    { id: 'b', startedAt: '2026-07-04T10:00:00Z' },
+    { id: 'a', startedAt: '2026-07-04T10:00:00Z' },
+    { id: 'c', startedAt: '2026-07-04T09:00:00Z' },
+  ]);
+  assert.deepEqual(entries.map((entry) => entry.id), ['c', 'a', 'b']);
+});
+
+test('sessionIndexTaskBody renders a compact ATS note body', () => {
+  const body = sessionIndexTaskBody({
+    id: 'session-1',
+    source: 'agentsview',
+    title: 'Debug retrieval',
+    startedAt: '2026-07-04T09:00:00Z',
+    repo: 'renezander030/agentic-task-system',
+    files: ['packages/core/retrieval.js'],
+    tokenStats: { total: 1200 },
+    summary: 'Found the stale ranking assumption.',
+  });
+
+  assert.match(body, /Agent session: Debug retrieval/);
+  assert.match(body, /Source: agentsview/);
+  assert.match(body, /Repo: renezander030\/agentic-task-system/);
+  assert.match(body, /Files: packages\/core\/retrieval\.js/);
+  assert.match(body, /Tokens: 1200/);
+  assert.match(body, /Found the stale ranking assumption/);
+});
+
+test('normalizeSessionIndexEntry rejects missing id or invalid startedAt', () => {
+  assert.throws(() => normalizeSessionIndexEntry({ startedAt: '2026-07-04T10:00:00Z' }), /requires id/);
+  assert.throws(() => normalizeSessionIndexEntry({ id: 'x', startedAt: 'not-a-date' }), /valid startedAt/);
+});