@agentwhy/cli 0.0.0-dev

package/dist/adapter/claude-code/discovery/claude-code-session-catalogue.js

@@ -0,0 +1,100 @@
+import { join } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { LAYOUT, parseSubagentFileName } from '../contract/layout.js';
+import { PROJECTS_DIRECTORY, matchesProject, projectDirectoryName } from '../contract/projects.js';
+/**
+ * Lists the sessions Claude Code has kept for a project, so that using the tool does not require typing a path
+ * that looks like `~/.claude/projects/-Users-someone-Projects-app/<uuid>`.
+ *
+ * Nothing inside a session is read here: only names, modification times and how many index files each has.
+ */
+export class ClaudeCodeSessionCatalogue {
+    #directories;
+    #home;
+    constructor(directories, home) {
+        this.#directories = directories;
+        this.#home = home;
+    }
+    async list(workingDirectory) {
+        const root = join(this.#home, ...PROJECTS_DIRECTORY);
+        const directory = await this.#directoryFor(root, workingDirectory);
+        let entries;
+        try {
+            entries = await this.#directories.list(directory);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            // Not found is an answer, not a failure: this project may simply never have been worked on here.
+            return { directory, found: false, searched: [{ provider: 'claude-code', directory, found: false }], sessions: [] };
+        }
+        const sessions = await Promise.all(entries
+            .filter((entry) => entry.kind === 'file' && entry.name.endsWith(LAYOUT.transcriptSuffix))
+            .map((entry) => this.#summarise(directory, entry.name)));
+        return {
+            directory,
+            found: true,
+            searched: [{ provider: 'claude-code', directory, found: true }],
+            sessions: sessions.sort((a, b) => b.modifiedAt - a.modifiedAt),
+        };
+    }
+    /**
+     * The encoded name first, because it costs nothing when it is right. When it is not - and the rule is
+     * inferred from examples, so it will not always be - the stored directories are compared against the working
+     * directory instead of trusting the guess.
+     */
+    async #directoryFor(root, workingDirectory) {
+        const derived = join(root, projectDirectoryName(workingDirectory));
+        try {
+            if ((await this.#directories.kindOf(derived)) === 'directory')
+                return derived;
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+        }
+        try {
+            const stored = await this.#directories.list(root);
+            const match = stored.find((entry) => entry.kind === 'directory' && matchesProject(entry.name, workingDirectory));
+            return match === undefined ? derived : join(root, match.name);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return derived;
+        }
+    }
+    async #summarise(directory, fileName) {
+        const id = fileName.slice(0, -LAYOUT.transcriptSuffix.length);
+        const path = join(directory, id);
+        return {
+            id,
+            path,
+            modifiedAt: await this.#modifiedAt(join(directory, fileName)),
+            delegations: await this.#delegations(join(path, LAYOUT.subagentsDir)),
+            provider: 'claude-code',
+        };
+    }
+    async #modifiedAt(path) {
+        try {
+            return await this.#directories.modifiedAt(path);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return 0;
+        }
+    }
+    /** Counted from the index files, which is the one thing that says a session delegated at all. */
+    async #delegations(subagents) {
+        try {
+            const entries = await this.#directories.list(subagents);
+            return entries.filter((entry) => parseSubagentFileName(entry.name)?.kind === 'meta').length;
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return 0;
+        }
+    }
+}

package/dist/adapter/claude-code/discovery/claude-code-session-discovery.js

@@ -0,0 +1,61 @@
+import { basename, join, resolve } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { byString } from '../../../shared/compare.js';
+import { LAYOUT } from '../contract/layout.js';
+import { CONTRACT_VERSION } from '../contract/version.js';
+import { pairSubagentFiles, splitToolResults } from './session-entries.js';
+export class ClaudeCodeSessionDiscovery {
+    #directories;
+    constructor(directories) {
+        this.#directories = directories;
+    }
+    async discover(input) {
+        const target = resolve(input);
+        const sessionDir = target.endsWith(LAYOUT.transcriptSuffix)
+            ? target.slice(0, -LAYOUT.transcriptSuffix.length)
+            : target;
+        const [mainTranscript, subagentsListing, toolResultsListing] = await Promise.all([
+            this.#presence(sessionDir + LAYOUT.transcriptSuffix, 'file'),
+            this.#list(join(sessionDir, LAYOUT.subagentsDir)),
+            this.#list(join(sessionDir, LAYOUT.toolResultsDir)),
+        ]);
+        const subagents = pairSubagentFiles(subagentsListing);
+        const toolResults = splitToolResults(toolResultsListing);
+        return {
+            contractVersion: CONTRACT_VERSION,
+            sessionId: basename(sessionDir),
+            mainTranscript,
+            subagentsDir: subagentsListing.presence,
+            subagents: subagents.sources,
+            toolResultsDir: toolResultsListing.presence,
+            toolResultFiles: toolResults.files,
+            unrecognised: [...subagents.unrecognised, ...toolResults.unrecognised].sort(byString),
+        };
+    }
+    async #presence(path, expected) {
+        try {
+            const kind = await this.#directories.kindOf(path);
+            return kind === expected ? { present: true, path } : { present: false, path, reason: 'wrong-kind' };
+        }
+        catch (error) {
+            if (error instanceof FileAccessError)
+                return { present: false, path, reason: error.failure };
+            throw error;
+        }
+    }
+    // A directory counts as present only once it has been listed: it can exist and still refuse to be read.
+    async #list(path) {
+        const found = await this.#presence(path, 'directory');
+        if (!found.present)
+            return { presence: found, entries: [] };
+        try {
+            return { presence: found, entries: await this.#directories.list(path) };
+        }
+        catch (error) {
+            if (error instanceof FileAccessError) {
+                return { presence: { present: false, path, reason: error.failure }, entries: [] };
+            }
+            throw error;
+        }
+    }
+}

package/dist/adapter/claude-code/discovery/claude-code-session-titles.js

@@ -0,0 +1,28 @@
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { LAYOUT } from '../contract/layout.js';
+import { SESSION_TITLE } from '../contract/session-title.js';
+import { recognitionIn } from './transcript-tail.js';
+/**
+ * Reads what a person recognises a session by from the end of its transcript, in one read: the title Claude Code gave
+ * it, handed over only once it has passed the redactor, and which way into Claude Code it was held
+ * (`.ai/specs/2026-09-27-which-project.md` V4). Nothing else in the transcript is looked at, and nothing is kept.
+ */
+export class ClaudeCodeSessionTitles {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async recognise(session) {
+        const { transcripts, redactor } = this.#dependencies;
+        let tail;
+        try {
+            tail = await transcripts.readTail(session.path + LAYOUT.transcriptSuffix, SESSION_TITLE.tailBytes);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return {};
+        }
+        return recognitionIn(tail, redactor);
+    }
+}

package/dist/adapter/claude-code/discovery/discovered-session.js

@@ -0,0 +1 @@
+export {};

package/dist/adapter/claude-code/discovery/session-entries.js

@@ -0,0 +1,41 @@
+import { join } from 'node:path';
+import { byString } from '../../../shared/compare.js';
+import { LAYOUT, isToolResultFileName, parseSubagentFileName, subagentFileName } from '../contract/layout.js';
+export function pairSubagentFiles(listing) {
+    const found = new Map();
+    const unrecognised = [];
+    for (const entry of listing.entries) {
+        const parsed = entry.kind === 'file' ? parseSubagentFileName(entry.name) : undefined;
+        if (parsed === undefined) {
+            unrecognised.push(join(LAYOUT.subagentsDir, entry.name));
+            continue;
+        }
+        const seen = found.get(parsed.fileId) ?? { transcript: false, meta: false };
+        seen[parsed.kind] = true;
+        found.set(parsed.fileId, seen);
+    }
+    const dir = listing.presence.path;
+    const sources = [...found]
+        .sort(([a], [b]) => byString(a, b))
+        .map(([fileId, seen]) => ({
+        fileId,
+        transcript: listed(dir, subagentFileName(fileId, 'transcript'), seen.transcript),
+        meta: listed(dir, subagentFileName(fileId, 'meta'), seen.meta),
+    }));
+    return { sources, unrecognised };
+}
+export function splitToolResults(listing) {
+    const files = [];
+    const unrecognised = [];
+    for (const entry of listing.entries) {
+        if (entry.kind === 'file' && isToolResultFileName(entry.name))
+            files.push(entry.name);
+        else
+            unrecognised.push(join(LAYOUT.toolResultsDir, entry.name));
+    }
+    return { files: files.sort(byString), unrecognised };
+}
+function listed(dir, name, isPresent) {
+    const path = join(dir, name);
+    return isPresent ? { present: true, path } : { present: false, path, reason: 'not-found' };
+}

package/dist/adapter/claude-code/discovery/transcript-tail.js

@@ -0,0 +1,81 @@
+import { parseJsonObject } from '../../../shared/json.js';
+import { oneLine } from '../../../shared/printable.js';
+import { ENTRY_POINT_VALUES } from '../contract/entry-points.js';
+import { FIELDS } from '../contract/fields.js';
+import { SESSION_TITLE } from '../contract/session-title.js';
+/*
+ * What the end of a transcript says about the session, read from the text `FileTailReader` hands over. The rules are
+ * the same for every part: a record ends at `\n` alone (lesson L010); the first line of a tail is usually cut and the
+ * last may still be being written (L008), so a line that does not parse is not a record; and a field counts only on the
+ * record itself, never as text quoted inside another record - a prompt that pastes one (L009). A megabyte of tool
+ * results is not parsed line by line: a line is parsed only where it names the field it is searched for.
+ */
+/**
+ * What a person recognises the session by (`which-project.md` V4): its latest title, only once it has passed the
+ * redactor, and which way into Claude Code it was held.
+ */
+export function recognitionIn(tail, redactor) {
+    const title = lastTitleIn(tail);
+    const entryPoint = lastEntryPointIn(tail);
+    return {
+        ...(title === undefined ? {} : { title: redactor.scan(title) }),
+        ...(entryPoint === undefined ? {} : { entryPoint }),
+    };
+}
+/** The session's latest title, as one line of plain words: its last `ai-title` record. */
+export function lastTitleIn(tail) {
+    for (const record of recordsFromTheEnd(tail, SESSION_TITLE.lineType)) {
+        if (record[FIELDS.lineType] !== SESSION_TITLE.lineType)
+            continue;
+        const title = record[SESSION_TITLE.field];
+        if (typeof title !== 'string')
+            continue;
+        const shown = oneLine(title);
+        if (shown !== '')
+            return shown;
+    }
+    return undefined;
+}
+/**
+ * Which way into Claude Code the session was started by, from the last record that says so (`entry-points.ts`). A
+ * value the contract does not list is `unknown`; a tail with no such record says nothing.
+ */
+export function lastEntryPointIn(tail) {
+    for (const record of recordsFromTheEnd(tail, keyOf(FIELDS.entryPoint))) {
+        const value = record[FIELDS.entryPoint];
+        if (typeof value !== 'string')
+            continue;
+        const known = Object.keys(ENTRY_POINT_VALUES).find((kind) => ENTRY_POINT_VALUES[kind] === value);
+        return known ?? 'unknown';
+    }
+    return undefined;
+}
+/**
+ * The latest working directory the tail's records carry that `accept` takes. One session can carry more than one
+ * (contract v12, 14 of 244 tails): which of them names the project is the caller's to decide by the project's directory,
+ * so the latest is never taken on its own. The search stops at the first taken, since nearly every record carries one.
+ */
+export function workingDirectoryIn(tail, accept) {
+    for (const record of recordsFromTheEnd(tail, keyOf(FIELDS.workingDirectory))) {
+        const value = record[FIELDS.workingDirectory];
+        if (typeof value === 'string' && value !== '' && accept(value))
+            return value;
+    }
+    return undefined;
+}
+/** The tail's whole records, the last first, among the lines holding `mark` - a cheap filter before any parse. */
+function* recordsFromTheEnd(tail, mark) {
+    const lines = tail.split('\n');
+    for (let at = lines.length - 1; at >= 0; at -= 1) {
+        const line = lines[at] ?? '';
+        if (!line.includes(mark))
+            continue;
+        const record = parseJsonObject(line);
+        if (record !== undefined)
+            yield record;
+    }
+}
+/** A field's name as a record writes it, quoted: `"cwd"`, which a path or a word in the text rarely is. */
+function keyOf(field) {
+    return `"${field}"`;
+}

package/dist/adapter/claude-code/events/claude-code-session-source.js

@@ -0,0 +1,197 @@
+import { MAIN_AGENT_TYPE } from '../../../core/agent.js';
+import { correlate } from '../../../core/correlation/correlate.js';
+import { agentSource, mainSource } from '../../../core/evidence.js';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { parseJsonObject } from '../../../shared/json.js';
+import { FIELDS } from '../contract/fields.js';
+import { readDelegationIndex } from './delegation-index.js';
+import { callsIn, delegationTextIn, deliveriesIn, handbackIn, isDelegation, messagesIn, resultsIn } from './transcript-scan.js';
+/**
+ * Reads a Claude Code session into the core's model. Everything format-specific stops here: what a record holds
+ * comes from the contract, and what belongs with what comes from `correlate`.
+ */
+export class ClaudeCodeSessionSource {
+    #discovery;
+    #files;
+    constructor(dependencies) {
+        this.#discovery = dependencies.discovery;
+        this.#files = dependencies.files;
+    }
+    async read(input) {
+        return correlate(await this.#collect(await this.#discovery.discover(input)));
+    }
+    async #collect(session) {
+        const collected = {
+            agents: [{ id: session.sessionId, type: MAIN_AGENT_TYPE, depth: 0 }],
+            calls: [],
+            results: [],
+            delegations: [],
+            delegationIndex: [],
+            messages: [],
+            deliveredReports: [],
+            gaps: [],
+            workingDirectories: new Set(),
+            spilledFiles: new Set(session.toolResultFiles),
+            // Absent is normal - a session that spilled nothing has no such directory. Present but unusable is not.
+            spilledFilesKnown: session.toolResultsDir.present || session.toolResultsDir.reason === 'not-found',
+        };
+        if (!collected.spilledFilesKnown)
+            collected.gaps.push({ kind: 'source-missing' });
+        if (session.mainTranscript.present) {
+            await this.#scan(session.mainTranscript.path, session.sessionId, mainSource(), collected);
+        }
+        else {
+            // Not just a missing source: without the main transcript there is no session to report on.
+            collected.gaps.push({ kind: 'session-missing' });
+        }
+        for (const subagent of session.subagents) {
+            await this.#collectSubagent(subagent, collected);
+        }
+        return {
+            sessionId: session.sessionId,
+            provider: 'claude-code',
+            agents: collected.agents,
+            calls: collected.calls,
+            results: collected.results,
+            delegations: collected.delegations,
+            delegationIndex: collected.delegationIndex,
+            messages: collected.messages,
+            deliveredReports: collected.deliveredReports,
+            workingDirectories: [...collected.workingDirectories],
+            // Claude Code records none of these apart from what is above: said as none, never left out
+            // (`2026-09-27-what-codex-wrote.md` §4.G). Its capabilities are those its contract measured, not declared per file.
+            agentReports: [],
+            followUps: [],
+            followUpIndex: [],
+            turns: [],
+            reviews: [],
+            contexts: [],
+            deliveries: [],
+            capabilities: [],
+            gaps: collected.gaps,
+        };
+    }
+    async #collectSubagent(subagent, collected) {
+        const agentId = subagent.fileId;
+        const entry = subagent.meta.present ? await this.#readIndexEntry(subagent.meta.path, agentId, collected) : undefined;
+        if (!subagent.meta.present)
+            collected.gaps.push({ kind: 'source-missing', agentId });
+        collected.agents.push({
+            id: agentId,
+            ...(entry?.requestedType === undefined ? {} : { type: entry.requestedType }),
+            ...(entry?.depth === undefined ? {} : { depth: entry.depth }),
+            ...(entry?.callId === undefined ? {} : { startedBy: entry.callId }),
+        });
+        if (entry?.callId !== undefined) {
+            collected.delegationIndex.push({
+                callId: entry.callId,
+                agentId,
+                ...(entry.requestedType === undefined ? {} : { requestedType: entry.requestedType }),
+                ...(entry.depth === undefined ? {} : { depth: entry.depth }),
+            });
+        }
+        if (subagent.transcript.present) {
+            await this.#scan(subagent.transcript.path, agentId, agentSource(agentId), collected, entry?.callId);
+        }
+        else {
+            // The delegation still happened; only its actions are unknown. Saying "no actions" beats dropping it.
+            collected.gaps.push({ kind: 'source-missing', agentId });
+        }
+    }
+    async #readIndexEntry(path, agentId, collected) {
+        let text;
+        try {
+            text = await this.#files.readText(path);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            collected.gaps.push({ kind: 'source-missing', agentId });
+            return undefined;
+        }
+        const entry = readDelegationIndex(text);
+        if (entry === undefined)
+            collected.gaps.push({ kind: 'record-damaged', agentId });
+        return entry;
+    }
+    /**
+     * `answers` is the delegation this transcript belongs to, when it is a subagent's. A report handed back through
+     * a call names no delegation of its own (D9), so this is the join: the words answer the call that started the
+     * agent whose transcript they are on.
+     */
+    async #scan(path, agentId, source, collected, answers) {
+        let record = 0;
+        let sequence = 0;
+        try {
+            for await (const raw of this.#files.readLines(path)) {
+                if (raw.trim() === '')
+                    continue;
+                record += 1;
+                const json = parseJsonObject(raw);
+                if (json === undefined) {
+                    collected.gaps.push({ kind: 'record-damaged', agentId });
+                    continue;
+                }
+                const workingDirectory = json[FIELDS.workingDirectory];
+                if (typeof workingDirectory === 'string')
+                    collected.workingDirectories.add(workingDirectory);
+                // When the line was written, for display only: a value that does not parse is no time, never a guessed one.
+                const stamp = json[FIELDS.recordedAt];
+                const at = typeof stamp === 'string' ? Date.parse(stamp) : Number.NaN;
+                const evidence = { source, record, ...(Number.isFinite(at) ? { at } : {}) };
+                for (const call of callsIn(json)) {
+                    sequence += 1;
+                    collected.calls.push({
+                        id: call.id,
+                        agentId,
+                        sequence,
+                        toolName: call.toolName,
+                        input: call.input,
+                        targets: call.targets,
+                        commands: call.commands,
+                        resultShape: call.resultShape,
+                        toolKnown: call.toolKnown,
+                        ...(call.written === undefined ? {} : { written: call.written }),
+                        ...(call.printsMatches === true ? { printsMatches: true } : {}),
+                        evidence,
+                    });
+                    if (isDelegation(call)) {
+                        collected.delegations.push({ callId: call.id, parentAgentId: agentId, ...delegationTextIn(call), evidence });
+                    }
+                    const handback = handbackIn(call);
+                    if (handback !== undefined && answers !== undefined) {
+                        collected.deliveredReports.push({ callId: answers, content: handback, evidence });
+                    }
+                }
+                // A text or reasoning block is read whole: nothing of it is held back by the record.
+                for (const message of messagesIn(json))
+                    collected.messages.push({ agentId, ...message, completeness: 'complete', evidence });
+                for (const delivery of deliveriesIn(json)) {
+                    collected.deliveredReports.push({ callId: delivery.callId, content: delivery.text, evidence });
+                }
+                const scanned = resultsIn(json);
+                for (const result of scanned.results) {
+                    const missing = collected.spilledFilesKnown && result.spilledFiles.some((name) => !collected.spilledFiles.has(name));
+                    collected.results.push({
+                        callId: result.callId,
+                        ...(result.content === undefined ? {} : { content: result.content }),
+                        ...(result.denial === undefined ? {} : { denial: result.denial }),
+                        ...(missing ? { spilledResultMissing: true } : {}),
+                        ...(scanned.denialUnattributed ? { attributionAmbiguous: true } : {}),
+                        ...(result.launchNotice === true ? { launchNotice: true } : {}),
+                        // A tool_result is the message the calling agent's model was handed, so it is that stage, whole as recorded. A
+                        // spilled result keeps its own notice and gap, as before.
+                        stage: 'model',
+                        completeness: 'complete',
+                        evidence,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            collected.gaps.push({ kind: 'source-missing', agentId });
+        }
+    }
+}

package/dist/adapter/claude-code/events/delegation-index.js

@@ -0,0 +1,15 @@
+import { parseJsonObject } from '../../../shared/json.js';
+import { META_FIELD } from '../contract/fields.js';
+export function readDelegationIndex(text) {
+    const meta = parseJsonObject(text);
+    if (meta === undefined)
+        return undefined;
+    const callId = meta[META_FIELD.toolUseId];
+    const requestedType = meta[META_FIELD.agentType];
+    const depth = meta[META_FIELD.spawnDepth];
+    return {
+        ...(typeof callId === 'string' ? { callId } : {}),
+        ...(typeof requestedType === 'string' ? { requestedType } : {}),
+        ...(typeof depth === 'number' ? { depth } : {}),
+    };
+}