@adecore/agents 0.0.1 → 0.17.0-beta.2

package/src/chat/claude-title.ts

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { usageRoots } from '../usage/roots.ts';
+import { cleanTitle, readLines } from '../title-file.ts';
+
+interface Progress {
+    offset: number;
+    aiTitle: string | null;
+    customTitle: string | null;
+}
+
+// The two records carry these words; a line without them is never parsed.
+const MARKERS = ['"ai-title"', '"custom-title"'];
+
+/*
+ * The name Claude Code gave a session, out of its own transcript. It writes an `ai-title` record a
+ * few seconds after the first prompt, anywhere in the file and more than once, and a `custom-title`
+ * when a person ran /rename in the CLI, which wins because a person chose it. A transcript only ever
+ * grows, so each path is read from where the previous read stopped: a file of many megabytes costs
+ * its full read once, and every read after that only the lines added since.
+ */
+export class ClaudeTitleReader {
+    private readonly progress = new Map<string, Progress>();
+    private readonly found = new Map<string, string>();
+    private readonly projectsDir: string;
+    private readonly chunkBytes: number;
+
+    constructor(projectsDir: string = usageRoots().find((root) => root.provider === 'claude')?.path ?? '', chunkBytes = 4 * 1024 * 1024) {
+        this.projectsDir = projectsDir;
+        this.chunkBytes = chunkBytes;
+    }
+
+    /* The title of a session found by its id, for a chat, which knows no transcript path; in the projects of its account. */
+    async forSession(agentSessionId: string, projectsDir: string = this.projectsDir): Promise<string | null> {
+        const path = await this.locate(agentSessionId, projectsDir);
+        return path === null ? null : await this.forTranscript(path);
+    }
+
+    async forTranscript(path: string): Promise<string | null> {
+        let size: number;
+        try {
+            size = (await stat(path)).size;
+        } catch {
+            return null;
+        }
+        let progress = this.progress.get(path);
+        // Smaller than where we were is a file that was replaced, not one that grew.
+        if (!progress || size < progress.offset) {
+            progress = { offset: 0, aiTitle: null, customTitle: null };
+            this.progress.set(path, progress);
+        }
+        if (size > progress.offset) {
+            const current = progress;
+            current.offset = await readLines(path, current.offset, size, this.chunkBytes, (line) => this.take(line, current));
+        }
+        return progress.customTitle ?? progress.aiTitle;
+    }
+
+    private take(line: string, progress: Progress): void {
+        if (!MARKERS.some((marker) => line.includes(marker))) {
+            return;
+        }
+        let record: unknown;
+        try {
+            record = JSON.parse(line);
+        } catch {
+            return;
+        }
+        if (typeof record !== 'object' || record === null) {
+            return;
+        }
+        const entry = record as Record<string, unknown>;
+        if (entry.type === 'ai-title') {
+            progress.aiTitle = cleanTitle(entry.aiTitle) ?? progress.aiTitle;
+        } else if (entry.type === 'custom-title') {
+            progress.customTitle = cleanTitle(entry.customTitle) ?? progress.customTitle;
+        }
+    }
+
+    /* The folder a transcript sits in is named after the working directory, so the file name is the only key a session id gives. */
+    private async locate(agentSessionId: string, projectsDir: string): Promise<string | null> {
+        const known = this.found.get(agentSessionId);
+        if (known !== undefined && existsSync(known)) {
+            return known;
+        }
+        if (projectsDir === '' || agentSessionId.includes('/')) {
+            return null;
+        }
+        let dirs: string[];
+        try {
+            dirs = await readdir(projectsDir);
+        } catch {
+            return null;
+        }
+        const file = `${agentSessionId}.jsonl`;
+        for (const dir of dirs) {
+            const path = join(projectsDir, dir, file);
+            if (existsSync(path)) {
+                this.found.set(agentSessionId, path);
+                return path;
+            }
+        }
+        return null;
+    }
+}

package/src/chat/claude-transcript.ts

@@ -0,0 +1,233 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { ChatHistoryResult, ChatItem } from '@adecore/agent-contracts';
+import { readLines } from '../title-file.ts';
+import { ClaudeProtocol } from './claude-protocol.ts';
+import { readingThread, settledReading } from './subagent-projection.ts';
+import type { ChatThread } from './thread.ts';
+import type { ThreadProjector } from './projector.ts';
+
+const CHUNK_BYTES = 4 * 1024 * 1024;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function str(value: unknown): string | null {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+
+/* The words of a user line that somebody said, or null for a line that carries tool results. */
+function spokenText(content: unknown): string | null {
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (!Array.isArray(content) || content.some((block) => isRecord(block) && block.type === 'tool_result')) {
+        return null;
+    }
+    const texts = content.filter((block) => isRecord(block) && block.type === 'text').map((block) => String((block as { text?: unknown }).text ?? ''));
+    return texts.length === 0 ? null : texts.join('\n');
+}
+
+/* What Claude Code writes beside a subagent's transcript. Pinned on 2.1.273, where only the agent's own id is always there. */
+export interface SubagentMeta {
+    agentId: string;
+    toolUseId: string | null;
+    // Set for an agent a subagent opened, which gets a file of its own in the same folder.
+    parentAgentId: string | null;
+    description: string | null;
+    transcript: string;
+}
+
+/* The folder name Claude Code gives a working directory: every character that is not a letter or a digit becomes a dash. */
+export function claudeProjectSlug(cwd: string): string {
+    return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/*
+ * Where the subagents of a session keep their transcripts. The folder of the chat's own directory
+ * first; a slug the CLI wrote differently (or a session resumed from somewhere else) is found by the
+ * session id alone, which is unique across every project.
+ */
+export async function findSubagentsDir(projectsDir: string, cwd: string, sessionId: string): Promise<string | null> {
+    if (projectsDir === '' || sessionId.includes('/') || sessionId.includes('..')) {
+        return null;
+    }
+    const own = join(projectsDir, claudeProjectSlug(cwd), sessionId, 'subagents');
+    if (existsSync(own)) {
+        return own;
+    }
+    let dirs: string[];
+    try {
+        dirs = await readdir(projectsDir);
+    } catch {
+        return null;
+    }
+    for (const dir of dirs) {
+        const candidate = join(projectsDir, dir, sessionId, 'subagents');
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+
+/* Every meta file in a subagents folder that says which agent it is about; one that does not parse is left out. */
+export async function readSubagentMetas(dir: string): Promise<SubagentMeta[]> {
+    let names: string[];
+    try {
+        names = await readdir(dir);
+    } catch {
+        return [];
+    }
+    const metas: SubagentMeta[] = [];
+    for (const name of names) {
+        const match = /^agent-(.+)\.meta\.json$/.exec(name);
+        if (!match) {
+            continue;
+        }
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(await readFile(join(dir, name), 'utf8'));
+        } catch {
+            continue;
+        }
+        if (!isRecord(parsed)) {
+            continue;
+        }
+        const agentId = match[1]!;
+        metas.push({
+            agentId,
+            toolUseId: str(parsed.toolUseId),
+            parentAgentId: str(parsed.parentAgentId),
+            description: str(parsed.description),
+            transcript: join(dir, `agent-${agentId}.jsonl`)
+        });
+    }
+    return metas;
+}
+
+/*
+ * The transcript of one agent a workflow started. Claude Code 2.1.282 keeps a folder per run under
+ * `workflows` in the subagents folder, and nothing but the agent id ties an agent to its run.
+ */
+export async function findWorkflowAgent(subagentsDir: string, agentId: string): Promise<SubagentMeta | null> {
+    if (!/^[\w-]+$/.test(agentId)) {
+        return null;
+    }
+    const workflowsDir = join(subagentsDir, 'workflows');
+    let runs: string[];
+    try {
+        runs = await readdir(workflowsDir);
+    } catch {
+        return null;
+    }
+    for (const run of runs) {
+        const dir = join(workflowsDir, run);
+        const transcript = join(dir, `agent-${agentId}.jsonl`);
+        if (existsSync(transcript)) {
+            return { agentId, toolUseId: null, parentAgentId: null, description: null, transcript };
+        }
+    }
+    return null;
+}
+
+/*
+ * One subagent transcript as thread items, read on from where the last read stopped: a transcript only
+ * grows, and a panel that follows a working agent asks again every time a line lands. The lines have
+ * the envelope of the main transcript, so an assistant or a tool result goes through the same mapping
+ * the live stream does. A file that shrank or was rewritten is read again from the start under a new
+ * thread, whose cursors then no longer match, so a client holding one is told the history expired.
+ */
+export class TranscriptProjection {
+    readonly path: string;
+    private thread!: ChatThread;
+    private projector!: ThreadProjector;
+    private protocol!: ClaudeProtocol;
+    private offset = 0;
+    private size = 0;
+    private mtimeMs = 0;
+    private lineTime = 0;
+
+    constructor(path: string) {
+        this.path = path;
+        this.reset();
+    }
+
+    /* Reads what was added since the last call; false when the file is not there. */
+    async refresh(): Promise<boolean> {
+        let info: { size: number; mtimeMs: number };
+        try {
+            info = await stat(this.path);
+        } catch {
+            return false;
+        }
+        if (info.size < this.size || info.mtimeMs < this.mtimeMs) {
+            this.reset();
+        }
+        this.size = info.size;
+        this.mtimeMs = info.mtimeMs;
+        if (info.size > this.offset) {
+            this.offset = await readLines(this.path, this.offset, info.size, CHUNK_BYTES, (line) => this.take(line));
+        }
+        return true;
+    }
+
+    items(): ChatItem[] {
+        return this.thread.list().map(settledReading);
+    }
+
+    /* The page before `cursor`, or the newest page without one; the cursors are the thread's own. */
+    page(limit: number, cursor?: string): ChatHistoryResult {
+        const page = this.thread.history(limit, cursor);
+        return { items: page.items.map(settledReading), history: page.history };
+    }
+
+    private reset(): void {
+        const reading = readingThread('Claude', () => this.lineTime);
+        this.thread = reading.thread;
+        this.projector = reading.projector;
+        this.protocol = new ClaudeProtocol();
+        this.offset = 0;
+        this.size = 0;
+        this.mtimeMs = 0;
+    }
+
+    private take(line: string): void {
+        if (line.trim() === '') {
+            return;
+        }
+        let entry: unknown;
+        try {
+            entry = JSON.parse(line);
+        } catch {
+            return;
+        }
+        if (!isRecord(entry) || (entry.type !== 'user' && entry.type !== 'assistant')) {
+            return;
+        }
+        const time = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN;
+        if (Number.isFinite(time)) {
+            this.lineTime = time;
+        }
+        const message = isRecord(entry.message) ? entry.message : {};
+        const said = entry.type === 'user' ? spokenText(message.content) : null;
+        if (said !== null) {
+            // The prompt it was given, or a message sent to it later; a reminder the CLI slipped in is not somebody talking.
+            if (entry.isMeta !== true && said.trim() !== '') {
+                this.thread.upsert({
+                    id: `user-${str(entry.uuid) ?? this.thread.list().length}`,
+                    kind: 'user',
+                    createdAt: this.lineTime,
+                    turnId: null,
+                    text: said
+                });
+            }
+            return;
+        }
+        for (const event of this.protocol.handle({ type: entry.type, message })) {
+            this.projector.project(0, event);
+        }
+    }
+}