feat(api): session export endpoint — download transcript as JSONL/Markdown (#3114)

OneStepAt4time · OneStepAt4time · commit 128dfa303d5e · 2026-05-10T17:49:59.000+02:00
Adds GET /v1/sessions/:id/export?format=jsonl|markdown:
- JSONL: NDJSON stream with proper content-disposition header
- Markdown: readable export with section headers, thinking blocks,
  tool calls in collapsible &lt;details&gt;, permission requests, errors
- 400 for unsupported formats
- 404 for non-existent sessions or sessions with no transcript data
- Auth/ownership checks via withOwnership middleware
- 9 tests covering all cases
diff --git a/src/__tests__/session-export-3114.test.ts b/src/__tests__/session-export-3114.test.ts
@@ -0,0 +1,190 @@
+/**
+ * Issue #3114: Session export API — download full transcript as JSONL/Markdown.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import Fastify from 'fastify';
+import { registerSessionDataRoutes } from '../routes/session-data.js';
+import type { RouteContext } from '../routes/context.js';
+import type { SessionInfo } from '../session.js';
+import type { ParsedEntry } from '../transcript.js';
+
+const SESSION_ID = 'export-test-session';
+const AUTH_TOKEN = 'test-token';
+
+function makeSession(): SessionInfo {
+  return {
+    id: SESSION_ID,
+    windowId: '',
+    displayName: 'export-test',
+    workDir: '/tmp',
+    byteOffset: 0,
+    monitorOffset: 0,
+    status: 'idle',
+    createdAt: Date.now(),
+    lastActivity: Date.now(),
+    stallThresholdMs: 30_000,
+    permissionStallMs: 60_000,
+    permissionMode: 'default',
+  };
+}
+
+const sampleEntries: ParsedEntry[] = [
+  { role: 'user', contentType: 'text', text: 'Hello, how are you?' },
+  { role: 'assistant', contentType: 'thinking', text: 'Let me think about this...' },
+  { role: 'assistant', contentType: 'text', text: 'I am doing well, thanks!' },
+  { role: 'assistant', contentType: 'tool_use', text: 'ReadFile', toolName: 'ReadFile', toolUseId: 'tc-1' },
+  { role: 'assistant', contentType: 'tool_result', text: 'file contents here', toolUseId: 'tc-1' },
+  { role: 'assistant', contentType: 'tool_error', text: 'Permission denied', toolUseId: 'tc-2' },
+  { role: 'system', contentType: 'permission_request', text: 'Allow write to foo.txt' },
+];
+
+function buildApp(withData = false): { app: ReturnType<typeof Fastify>; sessions: Record<string, unknown> } {
+  const app = Fastify({ logger: false });
+  app.addHook('onRequest', async (req) => {
+    req.authKeyId = null;
+    req.tenantId = 'system';
+  });
+
+  const session = makeSession();
+  const sessions = {
+    getSession: vi.fn((id: string) => id === SESSION_ID ? session : undefined),
+    readTranscript: vi.fn(async () => ({
+      messages: withData ? sampleEntries : [],
+      total: withData ? sampleEntries.length : 0,
+      page: 1,
+      limit: 100_000,
+      hasMore: false,
+    })),
+  };
+
+  const ctx = {
+    sessions,
+    auth: { authEnabled: false },
+    config: {},
+    metrics: { getSessionMetrics: vi.fn() },
+    monitor: {},
+    eventBus: { subscribe: vi.fn() },
+    channels: {},
+    toolRegistry: { processEntries: vi.fn(), getSessionTools: vi.fn(() => []), getToolDefinitions: vi.fn(() => []) },
+    sseLimiter: { acquire: vi.fn(() => ({ allowed: false, reason: 'test' })) },
+  } as unknown as RouteContext;
+
+  registerSessionDataRoutes(app, ctx);
+  return { app, sessions };
+}
+
+describe('Issue #3114: Session export API', () => {
+  it('returns 400 for unsupported format', async () => {
+    const { app } = buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export?format=csv`,
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toEqual({ error: expect.stringContaining('Invalid format') });
+    await app.close();
+  });
+
+  it('returns 404 for non-existent session', async () => {
+    const { app } = buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/v1/sessions/nonexistent/export?format=jsonl',
+    });
+    expect(res.statusCode).toBe(404);
+    await app.close();
+  });
+
+  it('returns 404 for session with no transcript data', async () => {
+    const { app } = buildApp(false); // no data
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export?format=jsonl`,
+    });
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({ error: expect.stringContaining('No transcript data') });
+    await app.close();
+  });
+
+  it('returns NDJSON for jsonl format with data', async () => {
+    const { app } = buildApp(true); // with data
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export?format=jsonl`,
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toContain('application/x-ndjson');
+    expect(res.headers['content-disposition']).toContain(`session-${SESSION_ID}.jsonl`);
+    
+    const lines = res.body.split('\n').filter(Boolean);
+    expect(lines.length).toBe(sampleEntries.length);
+    for (const line of lines) {
+      const parsed = JSON.parse(line);
+      expect(parsed).toHaveProperty('role');
+      expect(parsed).toHaveProperty('contentType');
+    }
+    await app.close();
+  });
+
+  it('returns markdown for markdown format with data', async () => {
+    const { app } = buildApp(true);
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export?format=markdown`,
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toContain('text/markdown');
+    expect(res.headers['content-disposition']).toContain(`session-${SESSION_ID}.md`);
+    expect(res.body).toContain('# Session Export');
+    expect(res.body).toContain('export-test');
+    expect(res.body).toContain('Hello, how are you?');
+    expect(res.body).toContain('Let me think about this');
+    expect(res.body).toContain('🔧 Tool: ReadFile');
+    expect(res.body).toContain('<details>');
+    await app.close();
+  });
+
+  it('defaults to jsonl format when no format specified', async () => {
+    const { app } = buildApp(true);
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export`,
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toContain('application/x-ndjson');
+    await app.close();
+  });
+
+  it('markdown includes thinking blocks', async () => {
+    const { app } = buildApp(true);
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export?format=markdown`,
+    });
+    expect(res.body).toContain('💭 Thinking');
+    expect(res.body).toContain('Let me think about this...');
+    await app.close();
+  });
+
+  it('markdown includes permission request', async () => {
+    const { app } = buildApp(true);
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export?format=markdown`,
+    });
+    expect(res.body).toContain('🔐 Permission Request');
+    expect(res.body).toContain('Allow write to foo.txt');
+    await app.close();
+  });
+
+  it('markdown includes tool error with warning', async () => {
+    const { app } = buildApp(true);
+    const res = await app.inject({
+      method: 'GET',
+      url: `/v1/sessions/${SESSION_ID}/export?format=markdown`,
+    });
+    expect(res.body).toContain('⚠️ Tool error');
+    expect(res.body).toContain('Permission denied');
+    await app.close();
+  });
+});
diff --git a/src/routes/session-data.ts b/src/routes/session-data.ts
@@ -233,6 +233,96 @@ export function registerSessionDataRoutes(app: FastifyInstance, ctx: RouteContex
   // Issue #2461: /stream alias for /events SSE
   registerWithLegacy(app, 'get', '/v1/sessions/:id/stream', sessionEventsHandler);
 
+
+  // Issue #3114: Session export — download full transcript as JSONL or Markdown
+  registerWithLegacy(app, 'get', '/v1/sessions/:id/export', withOwnership(sessions, async (req: FastifyRequest, reply: FastifyReply, session) => {
+    const query = req.query as { format?: string };
+    const format = query.format ?? 'jsonl';
+
+    if (format !== 'jsonl' && format !== 'markdown') {
+      return reply.status(400).send({ error: `Invalid format: ${format}. Supported: jsonl, markdown` });
+    }
+
+    // Read full transcript
+    const sessionId = (req.params as { id: string }).id;
+    const transcript = await sessions.readTranscript(sessionId, 1, 100_000);
+    const entries = transcript.messages;
+
+    if (entries.length === 0) {
+      return reply.status(404).send({ error: 'No transcript data available for this session' });
+    }
+
+    if (format === 'jsonl') {
+      // NDJSON — one JSON object per line
+      const lines = entries.map(e => JSON.stringify({
+        role: e.role,
+        contentType: e.contentType,
+        text: e.text,
+        ...(e.toolName ? { toolName: e.toolName } : {}),
+        ...(e.toolUseId ? { toolUseId: e.toolUseId } : {}),
+        ...(e.timestamp ? { timestamp: e.timestamp } : {}),
+      }));
+      return reply
+        .header('Content-Type', 'application/x-ndjson')
+        .header('Content-Disposition', `attachment; filename="session-${session.id}.jsonl"`)
+        .send(lines.join('\n'));
+    }
+
+    // Markdown format
+    const mdParts: string[] = [
+      `# Session Export: ${session.displayName || session.id}`,
+      ``,
+      `> Exported: ${new Date().toISOString()}`,
+      `> Session ID: ${session.id}`,
+      `> Status: ${session.status}`,
+      ``,
+      `---`,
+      ``,
+    ];
+
+    for (const entry of entries) {
+      if (entry.contentType === 'tool_use') {
+        mdParts.push(`### 🔧 Tool: ${entry.toolName || 'unknown'}`);
+        mdParts.push('');
+        mdParts.push(`<details>`);
+        mdParts.push(`<summary>${entry.text || entry.toolName || 'Tool call'}</summary>`);
+        mdParts.push('');
+      } else if (entry.contentType === 'tool_result' || entry.contentType === 'tool_error') {
+        const isError = entry.contentType === 'tool_error';
+        if (isError) {
+          mdParts.push(`> ⚠️ Tool error: ${entry.text?.slice(0, 200) || 'unknown error'}`);
+        } else {
+          mdParts.push(entry.text?.slice(0, 2000) || '');
+        }
+        mdParts.push('');
+        mdParts.push(`</details>`);
+        mdParts.push('');
+      } else if (entry.contentType === 'thinking') {
+        mdParts.push(`### 💭 Thinking`);
+        mdParts.push('');
+        mdParts.push(entry.text || '');
+        mdParts.push('');
+      } else if (entry.contentType === 'permission_request') {
+        mdParts.push(`### 🔐 Permission Request`);
+        mdParts.push('');
+        mdParts.push(`> ${entry.text || 'Permission requested'}`);
+        mdParts.push('');
+      } else {
+        // Regular text message
+        const roleLabel = entry.role === 'user' ? '👤 User' : entry.role === 'system' ? '⚙️ System' : '🤖 Assistant';
+        mdParts.push(`### ${roleLabel}`);
+        mdParts.push('');
+        mdParts.push(entry.text || '');
+        mdParts.push('');
+      }
+    }
+
+    return reply
+      .header('Content-Type', 'text/markdown; charset=utf-8')
+      .header('Content-Disposition', `attachment; filename="session-${session.id}.md"`)
+      .send(mdParts.join('\n'));
+  }));
+
   // ── Claude Code Hook Endpoints (Issue #161) ─────────────────────
   // Permission hook — validates body with withValidation, looks up session manually
   // (Claude Code calls this directly, not through API user auth)
