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

package/README.md

@@ -0,0 +1,167 @@
+<!--
+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:58.176Z
+-->
+
+# @molecule/api-agent-transcript-markdown-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.
+
+Generic Markdown chat reader for `@molecule/api-agent-transcript`.
+
+The reader of last resort: a plain Markdown or text chat whose turns start
+with a speaker marker — a heading (`## User` / `## Assistant`), a bold
+label (`**User:** …`) or a plain label (`User: …`). Use it for chats saved
+by hand, copied out of a chat web app, or written by a harness that has no
+reader of its own.
+
+## Quick Start
+
+```typescript
+import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+import { provider } from '@molecule/api-agent-transcript-markdown-chat'
+
+setProvider(provider)
+const session = readTranscript({
+  text: '**User:** Add a README.\n\n**Assistant:** Added README.md with a short overview.',
+  fileName: 'chat.md',
+})
+// session.turns → [{ role: 'user', … }, { role: 'assistant', … }]
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-agent-transcript-markdown-chat @molecule/api-agent-transcript
+```
+
+## API
+
+### Functions
+
+#### `chatStyleOf(text)`
+
+The marker style a text uses: the style of its first marker, provided the
+text has at least one user and one assistant marker in that style.
+
+```typescript
+function chatStyleOf(text: string): Style | null
+```
+
+- `text` — The text.
+
+**Returns:** The style, or `null` when the text is not a chat.
+
+#### `looksLikeMarkdownChat(text)`
+
+Whether a text is a Markdown / plain-text chat.
+
+```typescript
+function looksLikeMarkdownChat(text: string): boolean
+```
+
+- `text` — The file's text.
+
+**Returns:** True when it has user and assistant markers in one style.
+
+#### `readMarkdownChat(text)`
+
+Read a Markdown / plain-text chat.
+
+```typescript
+function readMarkdownChat(text: string): AgentSession
+```
+
+- `text` — The chat's text.
+
+**Returns:** The normalized session.
+
+### Constants
+
+#### `ASSISTANT_NAMES`
+
+Names that mark the assistant.
+
+```typescript
+const ASSISTANT_NAMES: readonly [
+  'assistant',
+  'ai',
+  'bot',
+  'model',
+  'agent',
+  'claude',
+  'chatgpt',
+  'gpt',
+  'gemini',
+  'copilot',
+  'cursor',
+]
+```
+
+#### `provider`
+
+Reads a plain Markdown or text chat with User / Assistant speaker markers.
+Compose it LAST: every harness-specific reader should get the first look.
+
+```typescript
+const provider: AgentTranscriptReader
+```
+
+#### `USER_NAMES`
+
+Names that mark the person.
+
+```typescript
+const USER_NAMES: readonly ['user', 'human', 'you', 'me']
+```
+
+## 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-markdown-chat'
+
+export function setupAgentTranscriptMarkdownChat(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-agent-transcript` ^1.0.0
+
+### Runtime Dependencies
+
+- `@molecule/api-agent-transcript`
+
+- **Compose it last.** `@molecule/api-agent-transcript-autodetect` tries
+  every harness reader first; this one only sees files none of them claimed.
+- It still refuses anything without at least one user marker AND one
+  assistant marker, so a document that merely mentions "User:" is not a chat.
+- User names: User, Human, You, Me. Assistant names: Assistant, AI, Bot,
+  Model, Agent, Claude, ChatGPT, GPT, Gemini, Copilot, Cursor. Case does not
+  matter; a trailing colon is optional for headings.
+- Only the style of the file's first marker splits turns, and markers
+  inside fenced code blocks are ignored — so a `Model:` line in a reply
+  does not break a chat written with `##` headings.
+- A chat names no model, no times and no file writes; those fields stay
+  empty. `harness` is `Markdown chat`.

package/dist/chat.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A plain Markdown or text chat: turns introduced by a speaker marker in one
+ * of three styles — a heading (`## User`), a bold label (`**User:**`, text
+ * may follow on the same line) or a plain label at the start of a line
+ * (`User: …`).
+ *
+ * This is the reader of last resort, for chats saved by hand, by a harness
+ * with no reader of its own, or by a chat web app's copy button. It never
+ * guesses at a format: the file must hold at least one user marker AND one
+ * assistant marker, and only the style of the file's first marker splits
+ * turns, so a `Model:` line or `## Assistant notes` heading inside a reply
+ * cannot start a new turn in a file that uses another style. Markers inside
+ * fenced code blocks are ignored.
+ *
+ * @module
+ */
+import type { AgentSession } from '@molecule/api-agent-transcript';
+/** Names that mark the person. */
+export declare const USER_NAMES: readonly ["user", "human", "you", "me"];
+/** Names that mark the assistant. */
+export declare const ASSISTANT_NAMES: readonly ["assistant", "ai", "bot", "model", "agent", "claude", "chatgpt", "gpt", "gemini", "copilot", "cursor"];
+type Style = 'heading' | 'bold' | 'plain';
+/**
+ * The marker style a text uses: the style of its first marker, provided the
+ * text has at least one user and one assistant marker in that style.
+ *
+ * @param text - The text.
+ * @returns The style, or `null` when the text is not a chat.
+ */
+export declare function chatStyleOf(text: string): Style | null;
+/**
+ * Whether a text is a Markdown / plain-text chat.
+ *
+ * @param text - The file's text.
+ * @returns True when it has user and assistant markers in one style.
+ */
+export declare function looksLikeMarkdownChat(text: string): boolean;
+/**
+ * Read a Markdown / plain-text chat.
+ *
+ * @param text - The chat's text.
+ * @returns The normalized session.
+ * @throws {Error} When the text is not a chat.
+ */
+export declare function readMarkdownChat(text: string): AgentSession;
+export {};
+//# sourceMappingURL=chat.d.ts.map

package/dist/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAA4B,MAAM,gCAAgC,CAAA;AAE5F,kCAAkC;AAClC,eAAO,MAAM,UAAU,yCAA0C,CAAA;AAEjE,qCAAqC;AACrC,eAAO,MAAM,eAAe,kHAYlB,CAAA;AAEV,KAAK,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;AA2DzC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAMtD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA4B3D"}

package/dist/chat.js

@@ -0,0 +1,148 @@
+/**
+ * A plain Markdown or text chat: turns introduced by a speaker marker in one
+ * of three styles — a heading (`## User`), a bold label (`**User:**`, text
+ * may follow on the same line) or a plain label at the start of a line
+ * (`User: …`).
+ *
+ * This is the reader of last resort, for chats saved by hand, by a harness
+ * with no reader of its own, or by a chat web app's copy button. It never
+ * guesses at a format: the file must hold at least one user marker AND one
+ * assistant marker, and only the style of the file's first marker splits
+ * turns, so a `Model:` line or `## Assistant notes` heading inside a reply
+ * cannot start a new turn in a file that uses another style. Markers inside
+ * fenced code blocks are ignored.
+ *
+ * @module
+ */
+/** Names that mark the person. */
+export const USER_NAMES = ['user', 'human', 'you', 'me'];
+/** Names that mark the assistant. */
+export const ASSISTANT_NAMES = [
+    'assistant',
+    'ai',
+    'bot',
+    'model',
+    'agent',
+    'claude',
+    'chatgpt',
+    'gpt',
+    'gemini',
+    'copilot',
+    'cursor',
+];
+const NAME = `(${[...USER_NAMES, ...ASSISTANT_NAMES].join('|')})`;
+const PATTERNS = {
+    heading: new RegExp(`^#{1,4}\\s+${NAME}\\s*:?\\s*$`, 'i'),
+    bold: new RegExp(`^\\*\\*${NAME}(?::\\*\\*|\\*\\*:?)\\s*(.*)$`, 'i'),
+    plain: new RegExp(`^${NAME}:\\s*(.*)$`, 'i'),
+};
+const STYLES = ['heading', 'bold', 'plain'];
+/**
+ * The speaker marker on a line, if any.
+ *
+ * @param line - The line.
+ * @param only - Only this style counts, when given.
+ * @returns The marker, or `null`.
+ */
+function markerOf(line, only) {
+    for (const style of only ? [only] : STYLES) {
+        const m = PATTERNS[style].exec(line);
+        if (!m)
+            continue;
+        const name = m[1].toLowerCase();
+        const role = USER_NAMES.includes(name)
+            ? 'user'
+            : 'assistant';
+        return { style, role, rest: (m[2] ?? '').trim() };
+    }
+    return null;
+}
+/**
+ * The lines outside fenced code blocks, with their fence state.
+ *
+ * @param text - The text.
+ * @returns Each line and whether it is inside a fence.
+ */
+function withFences(text) {
+    let fence = null;
+    return text
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => {
+        const f = /^\s*(`{3,}|~{3,})/.exec(line);
+        const wasFenced = fence !== null;
+        if (f) {
+            if (fence === null)
+                fence = f[1][0];
+            else if (f[1][0] === fence)
+                fence = null;
+        }
+        return { line, fenced: wasFenced || !!f };
+    });
+}
+/**
+ * The marker style a text uses: the style of its first marker, provided the
+ * text has at least one user and one assistant marker in that style.
+ *
+ * @param text - The text.
+ * @returns The style, or `null` when the text is not a chat.
+ */
+export function chatStyleOf(text) {
+    const lines = withFences(text).filter((l) => !l.fenced);
+    const first = lines.map((l) => markerOf(l.line)).find(Boolean);
+    if (!first)
+        return null;
+    const roles = new Set(lines.map((l) => markerOf(l.line, first.style)?.role).filter(Boolean));
+    return roles.has('user') && roles.has('assistant') ? first.style : null;
+}
+/**
+ * Whether a text is a Markdown / plain-text chat.
+ *
+ * @param text - The file's text.
+ * @returns True when it has user and assistant markers in one style.
+ */
+export function looksLikeMarkdownChat(text) {
+    return chatStyleOf(text) !== null;
+}
+/**
+ * Read a Markdown / plain-text chat.
+ *
+ * @param text - The chat's text.
+ * @returns The normalized session.
+ * @throws {Error} When the text is not a chat.
+ */
+export function readMarkdownChat(text) {
+    const style = chatStyleOf(text);
+    if (!style)
+        throw new Error('Not a Markdown chat: no user and assistant speaker markers.');
+    const turns = [];
+    let current = null;
+    const close = () => {
+        if (!current)
+            return;
+        const body = current.body.join('\n').trim();
+        if (body) {
+            const last = turns[turns.length - 1];
+            if (last && last.role === current.role)
+                last.text = `${last.text}\n\n${body}`;
+            else
+                turns.push({ role: current.role, text: body, files: [] });
+        }
+        current = null;
+    };
+    for (const { line, fenced } of withFences(text)) {
+        const m = fenced ? null : markerOf(line, style);
+        if (m) {
+            close();
+            current = { role: m.role, body: m.rest ? [m.rest] : [] };
+        }
+        else if (current) {
+            current.body.push(line);
+        }
+    }
+    close();
+    // A `---` rule between turns belongs to the file's layout, not the message.
+    for (const t of turns)
+        t.text = t.text.replace(/\n+-{3,}\s*$/, '').trim();
+    return { format: 'markdown-chat', harness: 'Markdown chat', turns };
+}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generic Markdown chat reader for `@molecule/api-agent-transcript`.
+ *
+ * The reader of last resort: a plain Markdown or text chat whose turns start
+ * with a speaker marker — a heading (`## User` / `## Assistant`), a bold
+ * label (`**User:** …`) or a plain label (`User: …`). Use it for chats saved
+ * by hand, copied out of a chat web app, or written by a harness that has no
+ * reader of its own.
+ *
+ * @example
+ * ```typescript
+ * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+ * import { provider } from '@molecule/api-agent-transcript-markdown-chat'
+ *
+ * setProvider(provider)
+ * const session = readTranscript({
+ *   text: '**User:** Add a README.\n\n**Assistant:** Added README.md with a short overview.',
+ *   fileName: 'chat.md',
+ * })
+ * // session.turns → [{ role: 'user', … }, { role: 'assistant', … }]
+ * ```
+ *
+ * @remarks
+ * - **Compose it last.** `@molecule/api-agent-transcript-autodetect` tries
+ *   every harness reader first; this one only sees files none of them claimed.
+ * - It still refuses anything without at least one user marker AND one
+ *   assistant marker, so a document that merely mentions "User:" is not a chat.
+ * - User names: User, Human, You, Me. Assistant names: Assistant, AI, Bot,
+ *   Model, Agent, Claude, ChatGPT, GPT, Gemini, Copilot, Cursor. Case does not
+ *   matter; a trailing colon is optional for headings.
+ * - Only the style of the file's first marker splits turns, and markers
+ *   inside fenced code blocks are ignored — so a `Model:` line in a reply
+ *   does not break a chat written with `##` headings.
+ * - A chat names no model, no times and no file writes; those fields stay
+ *   empty. `harness` is `Markdown chat`.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './chat.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,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * Generic Markdown chat reader for `@molecule/api-agent-transcript`.
+ *
+ * The reader of last resort: a plain Markdown or text chat whose turns start
+ * with a speaker marker — a heading (`## User` / `## Assistant`), a bold
+ * label (`**User:** …`) or a plain label (`User: …`). Use it for chats saved
+ * by hand, copied out of a chat web app, or written by a harness that has no
+ * reader of its own.
+ *
+ * @example
+ * ```typescript
+ * import { readTranscript, setProvider } from '@molecule/api-agent-transcript'
+ * import { provider } from '@molecule/api-agent-transcript-markdown-chat'
+ *
+ * setProvider(provider)
+ * const session = readTranscript({
+ *   text: '**User:** Add a README.\n\n**Assistant:** Added README.md with a short overview.',
+ *   fileName: 'chat.md',
+ * })
+ * // session.turns → [{ role: 'user', … }, { role: 'assistant', … }]
+ * ```
+ *
+ * @remarks
+ * - **Compose it last.** `@molecule/api-agent-transcript-autodetect` tries
+ *   every harness reader first; this one only sees files none of them claimed.
+ * - It still refuses anything without at least one user marker AND one
+ *   assistant marker, so a document that merely mentions "User:" is not a chat.
+ * - User names: User, Human, You, Me. Assistant names: Assistant, AI, Bot,
+ *   Model, Agent, Claude, ChatGPT, GPT, Gemini, Copilot, Cursor. Case does not
+ *   matter; a trailing colon is optional for headings.
+ * - Only the style of the file's first marker splits turns, and markers
+ *   inside fenced code blocks are ignored — so a `Model:` line in a reply
+ *   does not break a chat written with `##` headings.
+ * - A chat names no model, no times and no file writes; those fields stay
+ *   empty. `harness` is `Markdown chat`.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './chat.js';
+export * from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The generic Markdown / plain-text chat reader.
+ *
+ * @module
+ */
+import type { AgentTranscriptReader } from '@molecule/api-agent-transcript';
+/**
+ * Reads a plain Markdown or text chat with User / Assistant speaker markers.
+ * Compose it LAST: every harness-specific reader should get the first look.
+ */
+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;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,qBActB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,23 @@
+/**
+ * The generic Markdown / plain-text chat reader.
+ *
+ * @module
+ */
+import { looksLikeMarkdownChat, readMarkdownChat } from './chat.js';
+/**
+ * Reads a plain Markdown or text chat with User / Assistant speaker markers.
+ * Compose it LAST: every harness-specific reader should get the first look.
+ */
+export const provider = {
+    format: 'markdown-chat',
+    label: 'Markdown chat',
+    detect(input) {
+        return looksLikeMarkdownChat(input.text);
+    },
+    read(input) {
+        if (!looksLikeMarkdownChat(input.text)) {
+            throw new Error(`Not a Markdown chat${input.fileName ? ` (${input.fileName})` : ''}: expected User and Assistant speaker markers (\`## User\`, \`**User:**\` or \`User:\`).`);
+        }
+        return readMarkdownChat(input.text);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-agent-transcript-markdown-chat",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A last-resort transcript reader for plain Markdown or text chats with clear User / Assistant speaker markers",
   "type": "module",
   "main": "dist/index.js",