@molecule/api-agent-transcript-claude-code 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,152 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-09-24T06:06:46.914Z
+-->
+
+# @molecule/api-agent-transcript-claude-code
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Claude Code transcript reader for `@molecule/api-agent-transcript`.
+
+Reads both forms of a Claude Code session into a normalized `AgentSession`:
+the session log Claude Code keeps at
+`~/.claude/projects/<project>/<session-id>.jsonl` (full fidelity: the
+assistant's markdown as written, per-message model and timestamps, and the
+complete text of every `Write` / `Edit` / `MultiEdit`), and the plain text
+`/export` writes (the terminal rendering: user `❯`, assistant `●`, tool
+calls such as `Write(path)` with the lines they wrote).
+
+## Quick Start
+
+```typescript
+import { readFileSync } from 'node:fs'
+import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+import { provider } from '@molecule/api-agent-transcript-claude-code'
+
+setProvider(provider)
+const session = readTranscript({
+  text: readFileSync('session.jsonl', 'utf8'),
+  fileName: 'session.jsonl',
+})
+// session.turns: [{ role: 'user', text: '…as typed…' }, { role: 'assistant', model: 'claude-…', text, files }]
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-agent-transcript-claude-code @molecule/api-agent-transcript
+```
+
+## API
+
+### Functions
+
+#### `looksLikeExportText(text)`
+
+Whether a text looks like a Claude Code `/export`.
+
+```typescript
+function looksLikeExportText(text: string): boolean
+```
+
+- `text` — The file's text.
+
+**Returns:** True when it carries the export's header or both of its speaker markers.
+
+#### `looksLikeSessionJsonl(text)`
+
+Whether a text looks like a Claude Code session log.
+
+```typescript
+function looksLikeSessionJsonl(text: string): boolean
+```
+
+- `text` — The file's text.
+
+**Returns:** True when the first parseable lines are Claude Code log records.
+
+#### `readExportText(text)`
+
+Read a Claude Code `/export` text.
+
+```typescript
+function readExportText(text: string): AgentSession
+```
+
+- `text` — The export's text.
+
+**Returns:** The normalized session.
+
+#### `readSessionJsonl(text)`
+
+Read a Claude Code session log.
+
+```typescript
+function readSessionJsonl(text: string): AgentSession
+```
+
+- `text` — The `.jsonl` text.
+
+**Returns:** The normalized session.
+
+### Constants
+
+#### `provider`
+
+Reads Claude Code sessions: the session log (`.jsonl`) and the `/export` text.
+
+```typescript
+const provider: AgentTranscriptReader
+```
+
+## Core Interface
+
+Implements `@molecule/api-agent-transcript` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/api-agent-transcript'
+import { provider } from '@molecule/api-agent-transcript-claude-code'
+
+export function setupAgentTranscriptClaudeCode(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-agent-transcript` ^1.0.0
+
+### Runtime Dependencies
+
+- `@molecule/api-agent-transcript`
+
+- **Prefer the `.jsonl` when you have it.** The `/export` text is a rendering:
+  markdown is already applied (a `## heading` arrives as `heading`, `**bold**`
+  as `bold`), paragraphs are re-joined from terminal wrapping, and the model
+  is only the display name in the header (`Haiku 4.5`). Edits the terminal
+  showed collapsed ("Made 1 edit") carry no text, and a truncated preview
+  (`… +N lines`) is marked `complete: false`.
+- Dropped from user turns: slash-command echoes (`<command-name>` …), their
+  output, `<system-reminder>` text, tool results, and lines Claude Code marks
+  `isMeta`. A subagent's own messages (`isSidechain`) are not part of the
+  session.
+- Verified against Claude Code 2.1.281's own files; the older `>` / `⏺`
+  markers are accepted too.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-agent-transcript-claude-code` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-agent-transcript-claude-code is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/export-text.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Claude Code's `/export` file: the terminal rendering of the conversation as
+ * plain text (verified against Claude Code 2.1.281).
+ *
+ * ```text
+ *  ▐▛███▛█   Claude Code v2.1.281
+ * ▝▜██████▀  Haiku 4.5 · Claude Max
+ *
+ * ❯ The user's message, wrapped at the terminal width and padded with spaces
+ *   to it.
+ *
+ * ● The assistant's reply, markdown already rendered (a heading loses its
+ *   `#`), wrapped at the terminal width.
+ *
+ * ● Write(notes.md)
+ *   ⎿  Wrote 3 lines to notes.md
+ *       1 # Notes
+ *       2
+ *       3 A line that runs past the width is broken mid-wo
+ *         rd.
+ *
+ * ✻ Cooked for 5s · done 8:43 AM
+ * ```
+ *
+ * Older versions used `>` for the user and `⏺` for the assistant; both are accepted.
+ *
+ * @module
+ */
+import type { AgentSession } from '@molecule/api-agent-transcript';
+/**
+ * Whether a text looks like a Claude Code `/export`.
+ *
+ * @param text - The file's text.
+ * @returns True when it carries the export's header or both of its speaker markers.
+ */
+export declare function looksLikeExportText(text: string): boolean;
+/**
+ * Read a Claude Code `/export` text.
+ *
+ * @param text - The export's text.
+ * @returns The normalized session.
+ */
+export declare function readExportText(text: string): AgentSession;
+//# sourceMappingURL=export-text.d.ts.map

package/dist/export-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-text.d.ts","sourceRoot":"","sources":["../src/export-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAa,MAAM,gCAAgC,CAAA;AAU7F;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIzD;AA0FD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAuEzD"}

package/dist/export-text.js

@@ -0,0 +1,226 @@
+/**
+ * Claude Code's `/export` file: the terminal rendering of the conversation as
+ * plain text (verified against Claude Code 2.1.281).
+ *
+ * ```text
+ *  ▐▛███▛█   Claude Code v2.1.281
+ * ▝▜██████▀  Haiku 4.5 · Claude Max
+ *
+ * ❯ The user's message, wrapped at the terminal width and padded with spaces
+ *   to it.
+ *
+ * ● The assistant's reply, markdown already rendered (a heading loses its
+ *   `#`), wrapped at the terminal width.
+ *
+ * ● Write(notes.md)
+ *   ⎿  Wrote 3 lines to notes.md
+ *       1 # Notes
+ *       2
+ *       3 A line that runs past the width is broken mid-wo
+ *         rd.
+ *
+ * ✻ Cooked for 5s · done 8:43 AM
+ * ```
+ *
+ * Older versions used `>` for the user and `⏺` for the assistant; both are accepted.
+ *
+ * @module
+ */
+const USER = /^(?:❯|>) ?(.*)$/;
+const ASSISTANT = /^(?:●|⏺) ?(.*)$/;
+const STATUS = /^✻ /;
+const TOOL_CALL = /^([A-Z][A-Za-z]*)\((.*)\)\s*$/;
+const RESULT = /^\s*⎿\s*(.*)$/;
+const NUMBERED = /^\s{2,}(\d+) ?(.*)$/;
+const MORE = /…\s*\+?\d+ lines?|ctrl\+o to expand/;
+/**
+ * Whether a text looks like a Claude Code `/export`.
+ *
+ * @param text - The file's text.
+ * @returns True when it carries the export's header or both of its speaker markers.
+ */
+export function looksLikeExportText(text) {
+    if (/^\s*[▐▛█▜▝▘▀▄▌ ]*Claude Code v\d/m.test(text.slice(0, 600)))
+        return true;
+    const lines = text.split('\n');
+    return lines.some((l) => /^(?:❯|>) \S/.test(l)) && lines.some((l) => /^(?:●|⏺) \S/.test(l));
+}
+/**
+ * Re-join text the terminal wrapped: consecutive lines of one paragraph become
+ * one line; a blank line ends a paragraph; list items keep their own lines.
+ *
+ * @param lines - The block's lines, already de-indented.
+ * @returns The prose.
+ */
+function unwrap(lines) {
+    const out = [];
+    let para = [];
+    let inList = false;
+    const flush = () => {
+        if (para.length)
+            out.push(para.join(inList ? '\n' : ' '));
+        para = [];
+        inList = false;
+    };
+    for (const raw of lines) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line.trim()) {
+            flush();
+            continue;
+        }
+        const item = /^(?:[-*•]|\d+\.) /.test(line);
+        if (item) {
+            if (!inList)
+                flush();
+            inList = true;
+            para.push(line);
+        }
+        else if (inList && /^\s+\S/.test(line)) {
+            para[para.length - 1] += ` ${line.trim()}`;
+        }
+        else {
+            if (inList)
+                flush();
+            para.push(line.trim());
+        }
+    }
+    flush();
+    return out.join('\n\n');
+}
+/**
+ * Read the file content a `Write` / `Update` result shows.
+ *
+ * @param name - The tool name.
+ * @param arg - The call's argument (the path).
+ * @param body - The lines under the call.
+ * @returns The write, or null for tools that do not write.
+ */
+function writeFrom(name, arg, body) {
+    const kind = name === 'Write'
+        ? 'create'
+        : name === 'Update' || name === 'Edit' || name === 'MultiEdit'
+            ? 'edit'
+            : null;
+    if (!kind)
+        return null;
+    const out = [];
+    let complete = true;
+    let last = 'dropped';
+    for (const raw of body) {
+        if (MORE.test(raw)) {
+            complete = false;
+            continue;
+        }
+        if (RESULT.test(raw))
+            continue;
+        const m = NUMBERED.exec(raw);
+        if (m) {
+            let text = m[2].replace(/\s+$/, '');
+            if (/No newline at end of file/.test(text)) {
+                last = 'dropped';
+                continue;
+            }
+            if (kind === 'edit') {
+                // Diff rows: "+added", "-removed", " context". Only what the edit put in counts.
+                if (!text.startsWith('+')) {
+                    last = 'dropped';
+                    continue;
+                }
+                text = text.slice(1);
+            }
+            out.push(text);
+            last = 'kept';
+        }
+        else if (raw.trim() && last === 'kept') {
+            // A content line broken at the terminal width continues mid-word.
+            out[out.length - 1] += raw.trim();
+        }
+    }
+    return { path: arg.trim(), kind, text: out.join('\n'), complete: complete && out.length > 0 };
+}
+/**
+ * Read a Claude Code `/export` text.
+ *
+ * @param text - The export's text.
+ * @returns The normalized session.
+ */
+export function readExportText(text) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const header = lines.slice(0, 8).join('\n');
+    const version = /Claude Code v([\d.]+)/.exec(header)?.[1];
+    const modelLine = lines
+        .slice(0, 6)
+        .map((l) => l.replace(/^[\s▐▛█▜▝▘▀▄▌▗▖]+/, ''))
+        .find((l) => / · /.test(l) && !/Claude Code v/.test(l));
+    const model = modelLine?.split(' · ')[0]?.trim() || undefined;
+    const turns = [];
+    let assistant = null;
+    // The block being read: its kind, first line and the lines under it.
+    let block = null;
+    const closeBlock = () => {
+        if (!block)
+            return;
+        if (block.kind === 'user') {
+            const body = [];
+            for (const l of block.body) {
+                // A user message is one contiguous run; the first blank line ends it (what follows, indented, is
+                // the harness's collapsed activity: "Made 1 edit", "Read 3 files").
+                if (!l.trim())
+                    break;
+                body.push(l.replace(/^ {2}/, ''));
+            }
+            turns.push({
+                role: 'user',
+                text: unwrap([block.first, ...body])
+                    .replace(/\n\n/g, ' ')
+                    .trim(),
+                files: [],
+            });
+            assistant = null;
+        }
+        else {
+            if (!assistant) {
+                assistant = { role: 'assistant', text: '', model, files: [] };
+                turns.push(assistant);
+            }
+            if (block.kind === 'tool') {
+                const call = TOOL_CALL.exec(block.first);
+                const w = call ? writeFrom(call[1], call[2], block.body) : null;
+                if (w)
+                    assistant.files.push(w);
+            }
+            else {
+                const prose = unwrap([block.first, ...block.body.map((l) => l.replace(/^ {2}/, ''))]);
+                if (prose)
+                    assistant.text = assistant.text ? `${assistant.text}\n\n${prose}` : prose;
+            }
+        }
+        block = null;
+    };
+    for (const line of lines) {
+        const u = USER.exec(line);
+        const a = u ? null : ASSISTANT.exec(line);
+        if (u && !/^\s/.test(line)) {
+            closeBlock();
+            block = { kind: 'user', first: u[1], body: [] };
+        }
+        else if (a && !/^\s/.test(line)) {
+            closeBlock();
+            block = { kind: TOOL_CALL.test(a[1]) ? 'tool' : 'text', first: a[1], body: [] };
+        }
+        else if (STATUS.test(line)) {
+            closeBlock();
+        }
+        else if (block) {
+            block.body.push(line);
+        }
+    }
+    closeBlock();
+    return {
+        format: 'claude-code',
+        harness: 'Claude Code',
+        harnessVersion: version,
+        model,
+        turns: turns.filter((t) => t.role === 'user' || t.text || t.files.length),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Claude Code transcript reader for `@molecule/api-agent-transcript`.
+ *
+ * Reads both forms of a Claude Code session into a normalized `AgentSession`:
+ * the session log Claude Code keeps at
+ * `~/.claude/projects/<project>/<session-id>.jsonl` (full fidelity: the
+ * assistant's markdown as written, per-message model and timestamps, and the
+ * complete text of every `Write` / `Edit` / `MultiEdit`), and the plain text
+ * `/export` writes (the terminal rendering: user `❯`, assistant `●`, tool
+ * calls such as `Write(path)` with the lines they wrote).
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'node:fs'
+ * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+ * import { provider } from '@molecule/api-agent-transcript-claude-code'
+ *
+ * setProvider(provider)
+ * const session = readTranscript({ text: readFileSync('session.jsonl', 'utf8'), fileName: 'session.jsonl' })
+ * // session.turns: [{ role: 'user', text: '…as typed…' }, { role: 'assistant', model: 'claude-…', text, files }]
+ * ```
+ *
+ * @remarks
+ * - **Prefer the `.jsonl` when you have it.** The `/export` text is a rendering:
+ *   markdown is already applied (a `## heading` arrives as `heading`, `**bold**`
+ *   as `bold`), paragraphs are re-joined from terminal wrapping, and the model
+ *   is only the display name in the header (`Haiku 4.5`). Edits the terminal
+ *   showed collapsed ("Made 1 edit") carry no text, and a truncated preview
+ *   (`… +N lines`) is marked `complete: false`.
+ * - Dropped from user turns: slash-command echoes (`<command-name>` …), their
+ *   output, `<system-reminder>` text, tool results, and lines Claude Code marks
+ *   `isMeta`. A subagent's own messages (`isSidechain`) are not part of the
+ *   session.
+ * - Verified against Claude Code 2.1.281's own files; the older `>` / `⏺`
+ *   markers are accepted too.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './export-text.js';
+export * from './jsonl.js';
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * Claude Code transcript reader for `@molecule/api-agent-transcript`.
+ *
+ * Reads both forms of a Claude Code session into a normalized `AgentSession`:
+ * the session log Claude Code keeps at
+ * `~/.claude/projects/<project>/<session-id>.jsonl` (full fidelity: the
+ * assistant's markdown as written, per-message model and timestamps, and the
+ * complete text of every `Write` / `Edit` / `MultiEdit`), and the plain text
+ * `/export` writes (the terminal rendering: user `❯`, assistant `●`, tool
+ * calls such as `Write(path)` with the lines they wrote).
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'node:fs'
+ * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+ * import { provider } from '@molecule/api-agent-transcript-claude-code'
+ *
+ * setProvider(provider)
+ * const session = readTranscript({ text: readFileSync('session.jsonl', 'utf8'), fileName: 'session.jsonl' })
+ * // session.turns: [{ role: 'user', text: '…as typed…' }, { role: 'assistant', model: 'claude-…', text, files }]
+ * ```
+ *
+ * @remarks
+ * - **Prefer the `.jsonl` when you have it.** The `/export` text is a rendering:
+ *   markdown is already applied (a `## heading` arrives as `heading`, `**bold**`
+ *   as `bold`), paragraphs are re-joined from terminal wrapping, and the model
+ *   is only the display name in the header (`Haiku 4.5`). Edits the terminal
+ *   showed collapsed ("Made 1 edit") carry no text, and a truncated preview
+ *   (`… +N lines`) is marked `complete: false`.
+ * - Dropped from user turns: slash-command echoes (`<command-name>` …), their
+ *   output, `<system-reminder>` text, tool results, and lines Claude Code marks
+ *   `isMeta`. A subagent's own messages (`isSidechain`) are not part of the
+ *   session.
+ * - Verified against Claude Code 2.1.281's own files; the older `>` / `⏺`
+ *   markers are accepted too.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './export-text.js';
+export * from './jsonl.js';
+export * from './provider.js';

package/dist/jsonl.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Claude Code's session log (`~/.claude/projects/<project>/<session>.jsonl`):
+ * one JSON object per line; `type: 'user' | 'assistant'` lines carry an
+ * Anthropic Messages API `message`.
+ *
+ * @module
+ */
+import type { AgentSession } from '@molecule/api-agent-transcript';
+/**
+ * Whether a text looks like a Claude Code session log.
+ *
+ * @param text - The file's text.
+ * @returns True when the first parseable lines are Claude Code log records.
+ */
+export declare function looksLikeSessionJsonl(text: string): boolean;
+/**
+ * Read a Claude Code session log.
+ *
+ * @param text - The `.jsonl` text.
+ * @returns The normalized session.
+ */
+export declare function readSessionJsonl(text: string): AgentSession;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../src/jsonl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAa,MAAM,gCAAgC,CAAA;AAwB7F;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkB3D;AA+BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAsE3D"}

package/dist/jsonl.js

@@ -0,0 +1,145 @@
+/**
+ * Claude Code's session log (`~/.claude/projects/<project>/<session>.jsonl`):
+ * one JSON object per line; `type: 'user' | 'assistant'` lines carry an
+ * Anthropic Messages API `message`.
+ *
+ * @module
+ */
+/** User text Claude Code writes on the user's behalf: slash-command echoes, their output, caveats. */
+const INJECTED_USER_TEXT = /^\s*<(command-name|command-message|command-args|local-command-stdout|local-command-stderr|local-command-caveat|system-reminder|bash-input|bash-stdout|bash-stderr)>/;
+/**
+ * Whether a text looks like a Claude Code session log.
+ *
+ * @param text - The file's text.
+ * @returns True when the first parseable lines are Claude Code log records.
+ */
+export function looksLikeSessionJsonl(text) {
+    let seen = 0;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (!line.startsWith('{'))
+            return false;
+        let o;
+        try {
+            o = JSON.parse(line);
+        }
+        catch (_error) {
+            // A line that is not JSON means this is not a .jsonl log.
+            return false;
+        }
+        if ((o.type === 'user' || o.type === 'assistant') && o.message && (o.sessionId || o.uuid))
+            return true;
+        if (++seen > 20)
+            return false;
+    }
+    return false;
+}
+/**
+ * A file write or edit from a tool call, or null when the tool does not write.
+ *
+ * @param block - The `tool_use` block.
+ * @returns The writes it made.
+ */
+function writesOf(block) {
+    const input = block.input ?? {};
+    const path = typeof input.file_path === 'string'
+        ? input.file_path
+        : typeof input.path === 'string'
+            ? input.path
+            : '';
+    if (!path)
+        return [];
+    if (block.name === 'Write' && typeof input.content === 'string') {
+        return [{ path, kind: 'create', text: input.content, complete: true }];
+    }
+    if (block.name === 'Edit' && typeof input.new_string === 'string') {
+        return [{ path, kind: 'edit', text: input.new_string, complete: true }];
+    }
+    if (block.name === 'MultiEdit' && Array.isArray(input.edits)) {
+        return input.edits
+            .filter((e) => typeof e.new_string === 'string')
+            .map((e) => ({ path, kind: 'edit', text: e.new_string, complete: true }));
+    }
+    return [];
+}
+/**
+ * Read a Claude Code session log.
+ *
+ * @param text - The `.jsonl` text.
+ * @returns The normalized session.
+ */
+export function readSessionJsonl(text) {
+    const turns = [];
+    let version;
+    let startedAt;
+    let current = null;
+    const models = new Set();
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('{'))
+            continue;
+        let o;
+        try {
+            o = JSON.parse(line);
+        }
+        catch (_error) {
+            // A torn final line (a log still being written) carries nothing to read.
+            continue;
+        }
+        if (o.type !== 'user' && o.type !== 'assistant')
+            continue;
+        // A subagent's own conversation, and lines Claude Code marks as meta, are not the session.
+        if (o.isSidechain || o.isMeta)
+            continue;
+        version ??= o.version;
+        startedAt ??= o.timestamp;
+        const content = o.message?.content;
+        const blocks = typeof content === 'string' ? [{ type: 'text', text: content }] : (content ?? []);
+        if (o.type === 'user') {
+            // Tool results arrive as user lines; they belong to the assistant turn in progress.
+            const typed = blocks
+                .filter((b) => b.type === 'text' && typeof b.text === 'string' && !INJECTED_USER_TEXT.test(b.text))
+                .map((b) => b.text);
+            if (typed.length === 0)
+                continue;
+            current = null;
+            turns.push({
+                role: 'user',
+                text: typed.join('\n\n').trim(),
+                timestamp: o.timestamp,
+                files: [],
+            });
+            continue;
+        }
+        if (!current) {
+            current = {
+                role: 'assistant',
+                text: '',
+                timestamp: o.timestamp,
+                files: [],
+            };
+            turns.push(current);
+        }
+        // `<synthetic>` marks a message Claude Code made itself (an interruption notice), not a model.
+        if (o.message?.model && !o.message.model.startsWith('<')) {
+            current.model ??= o.message.model;
+            models.add(o.message.model);
+        }
+        for (const b of blocks) {
+            if (b.type === 'text' && b.text?.trim())
+                current.text = current.text ? `${current.text}\n\n${b.text.trim()}` : b.text.trim();
+            else if (b.type === 'tool_use')
+                current.files.push(...writesOf(b));
+        }
+    }
+    return {
+        format: 'claude-code',
+        harness: 'Claude Code',
+        harnessVersion: version,
+        model: models.size === 1 ? [...models][0] : undefined,
+        startedAt,
+        turns: turns.filter((t) => t.role === 'user' || t.text || t.files.length),
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Claude Code transcript reader.
+ *
+ * @module
+ */
+import type { AgentTranscriptReader } from '@molecule/api-agent-transcript';
+/**
+ * Reads Claude Code sessions: the session log (`.jsonl`) and the `/export` text.
+ */
+export declare const provider: AgentTranscriptReader;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EAEtB,MAAM,gCAAgC,CAAA;AAKvC;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,qBAatB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,24 @@
+/**
+ * The Claude Code transcript reader.
+ *
+ * @module
+ */
+import { looksLikeExportText, readExportText } from './export-text.js';
+import { looksLikeSessionJsonl, readSessionJsonl } from './jsonl.js';
+/**
+ * Reads Claude Code sessions: the session log (`.jsonl`) and the `/export` text.
+ */
+export const provider = {
+    format: 'claude-code',
+    label: 'Claude Code',
+    detect(input) {
+        return looksLikeSessionJsonl(input.text) || looksLikeExportText(input.text);
+    },
+    read(input) {
+        if (looksLikeSessionJsonl(input.text))
+            return readSessionJsonl(input.text);
+        if (looksLikeExportText(input.text))
+            return readExportText(input.text);
+        throw new Error(`Not a Claude Code transcript${input.fileName ? ` (${input.fileName})` : ''}: expected a session .jsonl or a /export text.`);
+    },
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@molecule/api-agent-transcript-claude-code",
+  "version": "1.0.0",
+  "description": "Reads Claude Code sessions — the /export text and the session .jsonl — into a normalized agent session",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "agent",
+    "transcript",
+    "claude-code",
+    "export",
+    "jsonl"
+  ],
+  "license": "Apache-2.0",
+  "author": "Molecule Dev, Inc. (https://molecule.dev)",
+  "peerDependencies": {
+    "@molecule/api-agent-transcript": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-agent-transcript": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/agent-transcript/claude-code"
+  },
+  "homepage": "https://www.molecule.dev/packages/api-agent-transcript-claude-code",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}