@molecule/api-agent-transcript-copilot-chat 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,126 @@
+<!--
+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-29T16:49:57.282Z
+-->
+
+# @molecule/api-agent-transcript-copilot-chat
+
+> **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.
+
+GitHub Copilot Chat transcript reader for `@molecule/api-agent-transcript`.
+
+Reads the `chat.json` VS Code saves from "Chat: Export Chat…" (Command
+Palette, or the chat view's ⋯ menu) into a normalized `AgentSession`: each
+request as you typed it, each response's markdown, the model that answered,
+and the files the response edited.
+
+## Quick Start
+
+```typescript
+import { readFileSync } from 'node:fs'
+import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+import { provider } from '@molecule/api-agent-transcript-copilot-chat'
+
+setProvider(provider)
+const file = 'chat.json'
+const session = readTranscript({ text: readFileSync(file, 'utf8'), fileName: file })
+console.log(session.harness, session.model) // 'GitHub Copilot Chat', 'copilot/…'
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-agent-transcript-copilot-chat @molecule/api-agent-transcript
+```
+
+## API
+
+### Functions
+
+#### `looksLikeChatExport(text)`
+
+Whether a text is a VS Code chat export.
+
+```typescript
+function looksLikeChatExport(text: string): boolean
+```
+
+- `text` — The file's text.
+
+**Returns:** True on a positive match.
+
+#### `readChatExport(text)`
+
+Read a VS Code chat export.
+
+```typescript
+function readChatExport(text: string): AgentSession
+```
+
+- `text` — The export's text.
+
+**Returns:** The normalized session.
+
+### Constants
+
+#### `provider`
+
+Reads the JSON VS Code's "Chat: Export Chat…" saves.
+
+```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-copilot-chat'
+
+export function setupAgentTranscriptCopilotChat(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-agent-transcript` ^1.0.0
+
+### Runtime Dependencies
+
+- `@molecule/api-agent-transcript`
+
+- **The export is VS Code's, not Copilot's**, so any chat participant's
+  export reads the same way. `harness` is `GitHub Copilot Chat` when the
+  responder is Copilot, otherwise `VS Code Chat (<responder>)`.
+- `model` on each reply is the request's `modelId` as VS Code records it
+  (e.g. `copilot/gpt-5.3`); the session's `model` is set when every reply
+  used the same one.
+- Reply text is the response's markdown with inline file references
+  written as `` `name` ``; thinking, tool-invocation and progress parts are
+  not prose.
+- Files: each `textEditGroup` part is an edit, its text the inserted text
+  of every edit in the group. Requests VS Code started itself
+  (`isSystemInitiated`) contribute their reply but no user turn; requests
+  hidden from the transcript are skipped.
+- Format verified 2026-09-29 against the VS Code source
+  (`chatImportExport.ts`, `chatModel.ts` `toExport()`).

package/dist/export.d.ts

@@ -0,0 +1,53 @@
+/**
+ * VS Code's chat export — the JSON "Chat: Export Chat…" saves
+ * (`chat.json`) from GitHub Copilot Chat or any other chat participant.
+ * Verified 2026-09-29 against microsoft/vscode `main`:
+ * `src/vs/workbench/contrib/chat/browser/actions/chatImportExport.ts`
+ * (writes `JSON.stringify(model.toExport())`) and
+ * `src/vs/workbench/contrib/chat/common/model/chatModel.ts`
+ * (`IExportableChatData`, `ISerializableChatRequestData`, `toExport()`).
+ *
+ * ```json
+ * {
+ *   "initialLocation": "panel",
+ *   "responderUsername": "GitHub Copilot",
+ *   "requests": [
+ *     {
+ *       "requestId": "request_…",
+ *       "message": { "text": "the message as typed", "parts": [ … ] },
+ *       "timestamp": 1790582400000,
+ *       "modelId": "copilot/gpt-5.3",
+ *       "response": [
+ *         { "value": "markdown…" },
+ *         { "kind": "inlineReference", "inlineReference": { "path": "/src/app.ts", … }, "name"?: "…" },
+ *         { "kind": "textEditGroup", "uri": { "path": "/src/app.ts", … }, "edits": [[{ "range": …, "text": "…" }]] },
+ *         { "kind": "toolInvocationSerialized", … }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * A response is a list of parts: markdown is written as a bare
+ * `IMarkdownString` (`{ value }`, no `kind`), everything else keeps its
+ * `kind`. Older exports stored `message` as a plain string.
+ *
+ * @module
+ */
+import type { AgentSession } from '@molecule/api-agent-transcript';
+/**
+ * Whether a text is a VS Code chat export.
+ *
+ * @param text - The file's text.
+ * @returns True on a positive match.
+ */
+export declare function looksLikeChatExport(text: string): boolean;
+/**
+ * Read a VS Code chat export.
+ *
+ * @param text - The export's text.
+ * @returns The normalized session.
+ * @throws {Error} When the text is not an export.
+ */
+export declare function readChatExport(text: string): AgentSession;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAa,MAAM,gCAAgC,CAAA;AAoD7F;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AA0DD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAuCzD"}

package/dist/export.js

@@ -0,0 +1,173 @@
+/**
+ * VS Code's chat export — the JSON "Chat: Export Chat…" saves
+ * (`chat.json`) from GitHub Copilot Chat or any other chat participant.
+ * Verified 2026-09-29 against microsoft/vscode `main`:
+ * `src/vs/workbench/contrib/chat/browser/actions/chatImportExport.ts`
+ * (writes `JSON.stringify(model.toExport())`) and
+ * `src/vs/workbench/contrib/chat/common/model/chatModel.ts`
+ * (`IExportableChatData`, `ISerializableChatRequestData`, `toExport()`).
+ *
+ * ```json
+ * {
+ *   "initialLocation": "panel",
+ *   "responderUsername": "GitHub Copilot",
+ *   "requests": [
+ *     {
+ *       "requestId": "request_…",
+ *       "message": { "text": "the message as typed", "parts": [ … ] },
+ *       "timestamp": 1790582400000,
+ *       "modelId": "copilot/gpt-5.3",
+ *       "response": [
+ *         { "value": "markdown…" },
+ *         { "kind": "inlineReference", "inlineReference": { "path": "/src/app.ts", … }, "name"?: "…" },
+ *         { "kind": "textEditGroup", "uri": { "path": "/src/app.ts", … }, "edits": [[{ "range": …, "text": "…" }]] },
+ *         { "kind": "toolInvocationSerialized", … }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * A response is a list of parts: markdown is written as a bare
+ * `IMarkdownString` (`{ value }`, no `kind`), everything else keeps its
+ * `kind`. Older exports stored `message` as a plain string.
+ *
+ * @module
+ */
+/**
+ * The export, when the text is one.
+ *
+ * @param text - The file's text.
+ * @returns The export, or `null`.
+ */
+function parse(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{'))
+        return null;
+    let v;
+    try {
+        v = JSON.parse(trimmed);
+    }
+    catch (_error) {
+        // Not JSON: not an export.
+        return null;
+    }
+    const e = v;
+    if (!e || typeof e.responderUsername !== 'string' || !Array.isArray(e.requests))
+        return null;
+    const ok = e.requests.every((r) => r &&
+        typeof r === 'object' &&
+        (typeof r.message === 'string' || (typeof r.message === 'object' && r.message !== null)) &&
+        (r.response === undefined || r.response === null || Array.isArray(r.response)));
+    return ok ? e : null;
+}
+/**
+ * Whether a text is a VS Code chat export.
+ *
+ * @param text - The file's text.
+ * @returns True on a positive match.
+ */
+export function looksLikeChatExport(text) {
+    return parse(text) !== null;
+}
+/**
+ * The path a serialized URI (or location) points at.
+ *
+ * @param v - The URI, or a `{ uri, range }` location.
+ * @returns The path, or ''.
+ */
+function pathOf(v) {
+    const u = v;
+    if (!u || typeof u !== 'object')
+        return '';
+    if (u.uri)
+        return pathOf(u.uri);
+    return u.fsPath ?? u.path ?? '';
+}
+/**
+ * The prose and files of one response.
+ *
+ * @param parts - The response parts.
+ * @returns The reply's text and writes.
+ */
+function readResponse(parts) {
+    let text = '';
+    const files = [];
+    for (const raw of parts) {
+        const p = raw;
+        if (!p || typeof p !== 'object')
+            continue;
+        if (p.kind === undefined && typeof p.value === 'string') {
+            text += p.value;
+        }
+        else if (p.kind === 'inlineReference') {
+            const path = pathOf(p.inlineReference);
+            const label = p.name ?? path.split('/').pop() ?? '';
+            if (label)
+                text += `\`${label}\``;
+        }
+        else if (p.kind === 'textEditGroup') {
+            const path = pathOf(p.uri);
+            const groups = Array.isArray(p.edits) ? p.edits : [];
+            const inserted = groups
+                .flatMap((g) => (Array.isArray(g) ? g : []))
+                .map((e) => e && typeof e.text === 'string'
+                ? e.text
+                : '')
+                .filter(Boolean);
+            if (path && inserted.length)
+                files.push({ path, kind: 'edit', text: inserted.join('\n'), complete: true });
+        }
+    }
+    return { text: text.trim(), files };
+}
+/**
+ * Read a VS Code chat export.
+ *
+ * @param text - The export's text.
+ * @returns The normalized session.
+ * @throws {Error} When the text is not an export.
+ */
+export function readChatExport(text) {
+    const e = parse(text);
+    if (!e)
+        throw new Error('Not a VS Code chat export.');
+    const turns = [];
+    const iso = (ms) => typeof ms === 'number' ? new Date(ms).toISOString() : undefined;
+    for (const r of e.requests) {
+        if (r.hiddenFromTranscript)
+            continue;
+        const said = (typeof r.message === 'string' ? r.message : (r.message?.text ?? '')).trim();
+        if (said && !r.isSystemInitiated) {
+            turns.push({ role: 'user', text: said, timestamp: iso(r.timestamp), files: [] });
+        }
+        const { text: reply, files } = readResponse(r.response ?? []);
+        if (reply || files.length) {
+            const last = turns[turns.length - 1];
+            if (last && last.role === 'assistant') {
+                last.text = [last.text, reply].filter(Boolean).join('\n\n');
+                last.files.push(...files);
+            }
+            else {
+                turns.push({
+                    role: 'assistant',
+                    text: reply,
+                    timestamp: iso(r.timestamp),
+                    model: r.modelId,
+                    files,
+                });
+            }
+        }
+    }
+    const copilot = /copilot/i.test(e.responderUsername);
+    const session = {
+        format: 'copilot-chat',
+        harness: copilot ? 'GitHub Copilot Chat' : `VS Code Chat (${e.responderUsername})`,
+        startedAt: turns[0]?.timestamp,
+        turns,
+    };
+    const models = new Set(turns.map((t) => t.model).filter(Boolean));
+    if (models.size === 1)
+        session.model = [...models][0];
+    return session;
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * GitHub Copilot Chat transcript reader for `@molecule/api-agent-transcript`.
+ *
+ * Reads the `chat.json` VS Code saves from "Chat: Export Chat…" (Command
+ * Palette, or the chat view's ⋯ menu) into a normalized `AgentSession`: each
+ * request as you typed it, each response's markdown, the model that answered,
+ * and the files the response edited.
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'node:fs'
+ * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+ * import { provider } from '@molecule/api-agent-transcript-copilot-chat'
+ *
+ * setProvider(provider)
+ * const file = 'chat.json'
+ * const session = readTranscript({ text: readFileSync(file, 'utf8'), fileName: file })
+ * console.log(session.harness, session.model) // 'GitHub Copilot Chat', 'copilot/…'
+ * ```
+ *
+ * @remarks
+ * - **The export is VS Code's, not Copilot's**, so any chat participant's
+ *   export reads the same way. `harness` is `GitHub Copilot Chat` when the
+ *   responder is Copilot, otherwise `VS Code Chat (<responder>)`.
+ * - `model` on each reply is the request's `modelId` as VS Code records it
+ *   (e.g. `copilot/gpt-5.3`); the session's `model` is set when every reply
+ *   used the same one.
+ * - Reply text is the response's markdown with inline file references
+ *   written as `` `name` ``; thinking, tool-invocation and progress parts are
+ *   not prose.
+ * - Files: each `textEditGroup` part is an edit, its text the inserted text
+ *   of every edit in the group. Requests VS Code started itself
+ *   (`isSystemInitiated`) contribute their reply but no user turn; requests
+ *   hidden from the transcript are skipped.
+ * - Format verified 2026-09-29 against the VS Code source
+ *   (`chatImportExport.ts`, `chatModel.ts` `toExport()`).
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './export.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * GitHub Copilot Chat transcript reader for `@molecule/api-agent-transcript`.
+ *
+ * Reads the `chat.json` VS Code saves from "Chat: Export Chat…" (Command
+ * Palette, or the chat view's ⋯ menu) into a normalized `AgentSession`: each
+ * request as you typed it, each response's markdown, the model that answered,
+ * and the files the response edited.
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'node:fs'
+ * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+ * import { provider } from '@molecule/api-agent-transcript-copilot-chat'
+ *
+ * setProvider(provider)
+ * const file = 'chat.json'
+ * const session = readTranscript({ text: readFileSync(file, 'utf8'), fileName: file })
+ * console.log(session.harness, session.model) // 'GitHub Copilot Chat', 'copilot/…'
+ * ```
+ *
+ * @remarks
+ * - **The export is VS Code's, not Copilot's**, so any chat participant's
+ *   export reads the same way. `harness` is `GitHub Copilot Chat` when the
+ *   responder is Copilot, otherwise `VS Code Chat (<responder>)`.
+ * - `model` on each reply is the request's `modelId` as VS Code records it
+ *   (e.g. `copilot/gpt-5.3`); the session's `model` is set when every reply
+ *   used the same one.
+ * - Reply text is the response's markdown with inline file references
+ *   written as `` `name` ``; thinking, tool-invocation and progress parts are
+ *   not prose.
+ * - Files: each `textEditGroup` part is an edit, its text the inserted text
+ *   of every edit in the group. Requests VS Code started itself
+ *   (`isSystemInitiated`) contribute their reply but no user turn; requests
+ *   hidden from the transcript are skipped.
+ * - Format verified 2026-09-29 against the VS Code source
+ *   (`chatImportExport.ts`, `chatModel.ts` `toExport()`).
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './export.js';
+export * from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The GitHub Copilot Chat (VS Code chat export) transcript reader.
+ *
+ * @module
+ */
+import type { AgentTranscriptReader } from '@molecule/api-agent-transcript';
+/**
+ * Reads the JSON VS Code's "Chat: Export Chat…" saves.
+ */
+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;AAIvC;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,qBActB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,22 @@
+/**
+ * The GitHub Copilot Chat (VS Code chat export) transcript reader.
+ *
+ * @module
+ */
+import { looksLikeChatExport, readChatExport } from './export.js';
+/**
+ * Reads the JSON VS Code's "Chat: Export Chat…" saves.
+ */
+export const provider = {
+    format: 'copilot-chat',
+    label: 'GitHub Copilot Chat',
+    detect(input) {
+        return looksLikeChatExport(input.text);
+    },
+    read(input) {
+        if (!looksLikeChatExport(input.text)) {
+            throw new Error(`Not a GitHub Copilot Chat transcript${input.fileName ? ` (${input.fileName})` : ''}: expected the chat.json VS Code's "Export Chat…" saves.`);
+        }
+        return readChatExport(input.text);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-agent-transcript-copilot-chat",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Reads VS Code GitHub Copilot Chat exports (Chat: Export Chat…) into a normalized agent session",
   "type": "module",
   "main": "dist/index.js",