@agentwhy/cli 0.0.0-dev

package/dist/core/access/search-output.js

@@ -0,0 +1,34 @@
+import { listingPathCandidates } from './listing.js';
+const LINE_NUMBER = /^\d+[:-]/;
+const CONTEXT_LINE = /^(.+)-(\d+)-(.*)$/;
+export function hitLines(output, withContext) {
+    const lines = output.split('\n');
+    const found = [];
+    for (const line of lines) {
+        const colon = line.indexOf(':');
+        if (colon <= 0)
+            continue;
+        const path = line.slice(0, colon);
+        // The same rule a listing uses for the field before a hit's first colon: a path because of where it sits.
+        if (!listingPathCandidates(line).some(([first]) => first?.positional === true && first.text === path))
+            continue;
+        found.push({ path, kind: 'hit', text: line.slice(colon + 1).replace(LINE_NUMBER, '') });
+    }
+    if (!withContext || found.length === 0)
+        return found;
+    // A context line with a colon in its text - `.env-3-URL=https://…` - reads as a hit on a path no file has: where its
+    // "path" is another hit path's line number, it is that file's context line, and is taken below as one.
+    const around = (path) => found.some((other) => other.path !== path && path.startsWith(other.path + '-') && /^\d+-/.test(path.slice(other.path.length + 1)));
+    const hits = found.filter((hit) => !around(hit.path));
+    const hitPaths = new Set(hits.map((hit) => hit.path));
+    const context = lines.flatMap((line) => {
+        const match = CONTEXT_LINE.exec(line);
+        // The longest prefix that is a hit path: `my-file-2-x` is `my-file`'s line 2 where `my-file` had a hit.
+        if (match === null || line.indexOf(':') !== -1 && hitPaths.has(line.slice(0, line.indexOf(':'))))
+            return [];
+        const path = [...hitPaths].filter((candidate) => line.startsWith(candidate + '-') && /^\d+-/.test(line.slice(candidate.length + 1)))
+            .sort((one, other) => other.length - one.length)[0];
+        return path === undefined ? [] : [{ path, kind: 'context', text: line.slice(path.length + 1).replace(/^\d+-/, '') }];
+    });
+    return [...hits, ...context];
+}

package/dist/core/access/search-reach.js

@@ -0,0 +1,268 @@
+import { addressesNothing, simpleCommandsIn } from './command-line.js';
+const GREPS = new Set(['grep', 'egrep', 'fgrep']);
+/** A glob character the shell expands in an unquoted word. */
+const GLOB = /[*?[]/;
+export function hasGlob(word) {
+    return GLOB.test(word);
+}
+/**
+ * The searches a command line runs and the words its shell expands. The pattern a search looks for is neither: `grep
+ * "KEY.*" src` expands nothing, because the word is quoted and is a pattern. Only the words a program takes as files
+ * are offered as globs.
+ */
+export function reachOf(command) {
+    const searches = [];
+    const globs = [];
+    for (const { program, args } of simpleCommandsIn(command)) {
+        if (addressesNothing(program))
+            continue;
+        const search = GREPS.has(program) ? grepArguments(args) : program === 'rg' ? rgArguments(args) : undefined;
+        const files = search === undefined ? args.filter((word) => !word.startsWith('-')) : search.paths;
+        globs.push(...files.filter(hasGlob));
+        if (search?.recursive === true) {
+            const { includes, excludes, excludeDirs, hidden } = search;
+            searches.push({ roots: search.paths.length === 0 ? ['.'] : search.paths, includes, excludes, excludeDirs, hidden });
+        }
+    }
+    return { searches, globs };
+}
+/**
+ * Splits a program's words into its options and its positional words, the way `getopt_long` reads them: options may
+ * follow positional words, a cluster (`-rn`) holds several, and `--` ends them.
+ */
+export function readOptions(args, table) {
+    const options = [];
+    const positionals = [];
+    let parsing = true;
+    for (let at = 0; at < args.length; at += 1) {
+        const word = args[at] ?? '';
+        if (parsing && word === '--') {
+            parsing = false;
+        }
+        else if (parsing && word.startsWith('--')) {
+            const separator = word.indexOf('=');
+            const name = separator === -1 ? word : word.slice(0, separator);
+            if (separator !== -1)
+                options.push({ name, value: word.slice(separator + 1) });
+            else if (table.longWithValue.has(name))
+                options.push({ name, value: args[(at += 1)] ?? '' });
+            else
+                options.push({ name });
+        }
+        else if (parsing && word.startsWith('-') && word.length > 1) {
+            for (let index = 1; index < word.length; index += 1) {
+                const flag = word.charAt(index);
+                if (table.shortWithValue.has(flag)) {
+                    const value = index + 1 < word.length ? word.slice(index + 1) : (args[(at += 1)] ?? '');
+                    options.push({ name: `-${flag}`, value });
+                    break;
+                }
+                options.push({ name: `-${flag}` });
+            }
+        }
+        else {
+            positionals.push(word);
+        }
+    }
+    return { options, positionals };
+}
+const GREP_OPTIONS = {
+    shortWithValue: new Set(['e', 'f', 'm', 'A', 'B', 'C', 'd', 'D']),
+    longWithValue: new Set([
+        '--regexp', '--file', '--max-count', '--after-context', '--before-context', '--context', '--directories',
+        '--devices', '--include', '--exclude', '--exclude-dir', '--include-dir', '--exclude-from', '--label',
+        '--binary-files', '--group-separator',
+    ]),
+};
+/** GNU and BSD `grep`: `-r`, `-R`, `--recursive`, or `-d recurse`; the first positional word is the pattern unless `-e` or `-f` gave one. */
+function grepArguments(args) {
+    const { options, positionals } = readOptions(args, GREP_OPTIONS);
+    // grep matches `--include` and its kin against a file's base name, and minds case.
+    const valuesOf = (...names) => options.filter((option) => names.includes(option.name)).map((option) => ({ glob: option.value ?? '' }));
+    const recursive = options.some((option) => ['-r', '-R', '--recursive', '--dereference-recursive'].includes(option.name) ||
+        (['-d', '--directories'].includes(option.name) && option.value === 'recurse'));
+    const patternGiven = options.some((option) => ['-e', '-f', '--regexp', '--file'].includes(option.name));
+    return {
+        recursive,
+        paths: patternGiven ? positionals : positionals.slice(1),
+        includes: valuesOf('--include'),
+        excludes: valuesOf('--exclude'),
+        excludeDirs: valuesOf('--exclude-dir'),
+        hidden: true,
+    };
+}
+const RG_OPTIONS = {
+    // `-r` is `--replace` here, not "recursive": ripgrep always recurses.
+    shortWithValue: new Set(['e', 'f', 'g', 't', 'T', 'm', 'A', 'B', 'C', 'j', 'M', 'E', 'd', 'r']),
+    longWithValue: new Set([
+        '--regexp', '--file', '--glob', '--iglob', '--type', '--type-not', '--type-add', '--type-clear', '--max-count',
+        '--after-context', '--before-context', '--context', '--threads', '--max-columns', '--encoding', '--max-depth',
+        '--replace', '--pre', '--pre-glob', '--sort', '--sortr', '--colors', '--color', '--path-separator', '--max-filesize',
+        '--ignore-file', '--context-separator', '--field-match-separator', '--field-context-separator', '--engine',
+        '--dfa-size-limit', '--regex-size-limit', '--hyperlink-format', '--generate',
+    ]),
+};
+/**
+ * ripgrep. It skips hidden files unless `--hidden`, `-.` or `-uu` says otherwise; a `.env` is hidden. A glob of `-g`
+ * narrows it, and a `!` in front turns the glob into an exclusion, of files and directories alike. What `.gitignore`
+ * leaves out is not read here, so a search it would narrow is taken to reach everything.
+ */
+function rgArguments(args) {
+    const { options, positionals } = readOptions(args, RG_OPTIONS);
+    const names = options.map((option) => option.name);
+    // `--files` lists what would be searched and opens nothing; `--type-list` and friends search nothing at all.
+    if (names.some((name) => ['--files', '--type-list', '--help', '-h', '--version', '-V', '--generate'].includes(name)))
+        return undefined;
+    const unrestricted = names.filter((name) => name === '-u' || name === '--unrestricted').length;
+    // `--glob-case-insensitive` makes every `-g` an `--iglob`; the last of it and its `--no-` form wins.
+    const everyCaseless = names.lastIndexOf('--glob-case-insensitive') > names.lastIndexOf('--no-glob-case-insensitive');
+    const globs = options
+        .filter((option) => ['-g', '--glob', '--iglob'].includes(option.name))
+        .map((option) => ({ glob: option.value ?? '', caseless: everyCaseless || option.name === '--iglob' }));
+    const nameGlob = (glob, caseless) => (caseless ? { glob, caseless: true } : { glob });
+    const excluded = globs.filter(({ glob }) => glob.startsWith('!')).map(({ glob, caseless }) => nameGlob(atAnyDepth(glob.slice(1)), caseless));
+    const patternGiven = names.some((name) => ['-e', '-f', '--regexp', '--file'].includes(name));
+    return {
+        recursive: true,
+        paths: patternGiven ? positionals : positionals.slice(1),
+        includes: globs.filter(({ glob }) => !glob.startsWith('!')).map(({ glob, caseless }) => nameGlob(includedName(glob), caseless)),
+        excludes: excluded,
+        excludeDirs: excluded,
+        hidden: unrestricted >= 2 || names.includes('--hidden') || names.includes('-.'),
+    };
+}
+// ripgrep matches a glob as `.gitignore` does (measured, ripgrep 14.1.1): `**/` in front matches at any depth
+// (`**/.env` took every `.env` below the search), and a glob with any other `/` in it is matched against the path, not
+// the name (`config/.env` took nothing from a search of `.`, `app/config/.env` took that one file). The walk here meets
+// names, so the first is dropped, which is exact. The second is read so that it never leaves out a file ripgrep would
+// open: an include keeps its last part, and so takes every file of that name wherever it is; an exclusion keeps the
+// `/`, matches no name, and leaves nothing out.
+function atAnyDepth(glob) {
+    return glob.replace(/^(?:\*\*\/)+/, '');
+}
+function includedName(glob) {
+    const name = atAnyDepth(glob);
+    if (!name.includes('/'))
+        return name === '' ? '*' : name;
+    const last = name.slice(name.lastIndexOf('/') + 1);
+    // A `/` inside an alternative (`{.env,config/.env}`) cannot be cut at, and a glob that ends in one names directories;
+    // what either would include is not worked out here, so it includes every file.
+    return last === '' || /[{}]/.test(name) ? '*' : last;
+}
+/**
+ * Whether a file name matches a glob the way `fnmatch` and a shell match one: `*` and `?` within the name, `[...]`
+ * classes, and `{a,b}` alternatives, which a shell expands in an unquoted word before the program sees it.
+ *
+ * `period`: a shell does not let a wildcard match the dot that starts a hidden name, so `cat *` leaves `.env` out while
+ * `cat .env*` does not. A program matching its own `--include` has no such rule.
+ *
+ * `caseless`: `rg --iglob '*.ENV'` opens `.env`.
+ */
+export function matchesName(name, glob, options) {
+    if (options.period && name.startsWith('.') && !glob.startsWith('.'))
+        return false;
+    return nameGlobToRegExp(glob, options.caseless === true ? 'i' : '').test(name);
+}
+const SPECIAL = /[.+^$()|\\/]/g;
+function nameGlobToRegExp(glob, flags) {
+    let source = '';
+    let braces = 0;
+    for (let index = 0; index < glob.length; index += 1) {
+        const character = glob.charAt(index);
+        if (character === '*')
+            source += '.*';
+        else if (character === '?')
+            source += '.';
+        else if (character === '[') {
+            const close = glob.indexOf(']', index + 2);
+            if (close === -1) {
+                source += '\\[';
+            }
+            else {
+                const body = glob.slice(index + 1, close).replace(/^[!^]/, '^').replace(/\\/g, '\\\\');
+                source += `[${body}]`;
+                index = close;
+            }
+        }
+        else if (character === '{') {
+            braces += 1;
+            source += '(?:';
+        }
+        else if (character === '}' && braces > 0) {
+            braces -= 1;
+            source += ')';
+        }
+        else if (character === ',' && braces > 0)
+            source += '|';
+        else if (character === '}' || character === '{')
+            source += `\\${character}`;
+        else
+            source += character.replace(SPECIAL, '\\$&');
+    }
+    // An alternative left open is not one, and a class a regular expression cannot hold (`[z-a]`) is not a class a shell
+    // would expand either: both are read as the text they are. Any word may arrive here - a sed script, inline code - and
+    // a hook that threw over one would be a hook that failed on an ordinary command.
+    if (braces > 0)
+        return literally(glob, flags);
+    try {
+        return new RegExp(`^${source}$`, flags);
+    }
+    catch {
+        return literally(glob, flags);
+    }
+}
+function literally(text, flags) {
+    return new RegExp(`^${text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}$`, flags);
+}
+/**
+ * Whether a command line runs a search that prints the lines it matched (`search-hits-are-reads` H1), and how. Undefined
+ * where it runs no search, or only ones that print no text - names (`-l`, `-L`), counts (`-c`), nothing (`-q`), or the
+ * files it would search (`rg --files`). Several searches in one line (`grep -rn KEY . | grep -v test`) are bare only
+ * when all are: the first one's names are still on the lines the last one prints.
+ */
+export function printedSearch(command) {
+    let found;
+    for (const { program, args } of simpleCommandsIn(command)) {
+        const git = program === 'git' && args[0] === 'grep';
+        const searched = git || GREPS.has(program) ? GREP_PRINTS : program === 'ag' || program === 'ack' ? LISTER_PRINTS : program === 'rg' ? RG_PRINTS : undefined;
+        if (searched === undefined)
+            continue;
+        const { options, positionals } = readOptions(git ? args.slice(1) : args, searched.table);
+        const names = options.map((option) => option.name);
+        if (names.some((name) => searched.quiet.has(name)))
+            continue;
+        const operands = names.some((name) => PATTERN_GIVEN.has(name)) ? positionals.length : positionals.length - 1;
+        // grep recurses when asked to; ripgrep, ag and ack always do.
+        const recursive = searched !== GREP_PRINTS || options.some((option) => RECURSIVE.has(option.name) || ((option.name === '-d' || option.name === '--directories') && option.value === 'recurse'));
+        const said = names.some((name) => searched.unnamed.has(name)) ? 'never'
+            : git || names.some((name) => searched.named.has(name)) || operands > 1 ? 'always'
+                // With no file, grep reads what was piped to it, and a recursive search the directory it is in.
+                : operands === 0 ? (recursive ? 'always' : 'never')
+                    : recursive ? 'maybe' : 'never';
+        found = {
+            context: (found?.context ?? false) || names.some((name) => CONTEXT.has(name)),
+            names: found === undefined ? said : NAMES_RANK.indexOf(said) < NAMES_RANK.indexOf(found.names) ? said : found.names,
+            numbered: (found?.numbered ?? false) || names.includes('-n') || names.includes('--line-number'),
+        };
+    }
+    return found === undefined ? undefined
+        : { context: found.context, names: found.names, ...(found.numbered ? { numbered: true } : {}) };
+}
+/** In a pipeline, a name any search puts on the lines stays on them through the searches after it. */
+const NAMES_RANK = ['always', 'maybe', 'never'];
+const RECURSIVE = new Set(['-r', '-R', '--recursive', '--dereference-recursive']);
+const QUIET = ['-l', '-L', '--files-with-matches', '--files-without-match', '--files-without-matches', '--name-only', '-c', '--count', '-q', '--quiet', '--silent'];
+const GREP_PRINTS = {
+    table: GREP_OPTIONS, quiet: new Set(QUIET), named: new Set(['-H', '--with-filename']), unnamed: new Set(['-h', '--no-filename']),
+};
+/** ag and ack: `-g` and ack's `-f` list the files a search would read. */
+const LISTER_PRINTS = { ...GREP_PRINTS, quiet: new Set([...QUIET, '-g', '-f']), named: new Set(['-H', '--with-filename', '--filename']) };
+/** ripgrep: `-f` is a file of patterns, and `-I`, not `-h`, drops the name. */
+const RG_PRINTS = {
+    table: RG_OPTIONS,
+    quiet: new Set(['-l', '--files-with-matches', '--files-without-match', '-c', '--count', '--count-matches', '-q', '--quiet', '--files', '--type-list']),
+    named: new Set(['-H', '--with-filename']),
+    unnamed: new Set(['-I', '--no-filename']),
+};
+const PATTERN_GIVEN = new Set(['-e', '-f', '--regexp', '--file']);
+const CONTEXT = new Set(['-A', '-B', '-C', '--after-context', '--before-context', '--context']);

package/dist/core/access/uses.js

@@ -0,0 +1,143 @@
+import { commitsIn, programsIn } from './command-line.js';
+/** On one record, the more direct source is named: a protected read, then a return, then anything else. */
+const SOURCE_ORDER = ['read', 'returned', 'delivered', 'unprotected'];
+/**
+ * Every use of a traced value (R7, R8): a run of it in an agent's message or in the input of a call, with where it
+ * landed and the first thing earlier in that agent's own record stream that carried it. Order is a record's position
+ * within one agent's stream: a use is never placed against another agent's records, and never by time. The claim is
+ * sameness - the same value appears here - and nothing about how it travelled (R10).
+ */
+export function valueUses(model, accesses, traced) {
+    if (traced.values.length === 0)
+        return [];
+    const { values, trace } = traced;
+    const delegating = new Set(model.delegations.map((delegation) => delegation.id));
+    const protectedInputs = new Set(accesses.filter((access) => access.source === 'input').map((access) => access.eventId));
+    const sources = sourcesOf(model, accesses, traced);
+    const foundIn = (texts) => new Set(texts.flatMap((text) => [...trace.foundIn(text)]));
+    const uses = [];
+    const use = (agentId, evidence, found, landing) => {
+        if (found.size === 0)
+            return;
+        const files = new Set();
+        let uncertain = false;
+        for (const index of found) {
+            const value = values[index];
+            if (value === undefined)
+                continue;
+            for (const path of value.paths)
+                files.add(path);
+            if (value.paths.length > 1)
+                uncertain = true;
+        }
+        const [first] = (sources.get(agentId) ?? []).filter((source) => source.record < evidence.record && [...found].some((index) => source.found.has(index)));
+        uses.push({
+            agentId,
+            files: [...files].sort(),
+            ...(uncertain ? { fileUncertain: true } : {}),
+            ...landing,
+            source: first?.kind ?? 'none',
+            ...(first?.kind === 'unprotected' && first.targets.length > 0 ? { sourceTargets: first.targets } : {}),
+            ...(first === undefined ? {} : { sourceRecord: first.record }),
+            ...(first?.delegationId === undefined ? {} : { sourceDelegationId: first.delegationId }),
+            evidence,
+        });
+    };
+    for (const message of model.messages) {
+        use(message.agentId, message.evidence, trace.foundIn(message.text), { landed: message.kind });
+    }
+    // X17: later words to a helper hand a value to it as the first instruction does - once per instruction, where the
+    // sender wrote them.
+    for (const followUp of model.delegations.flatMap((delegation) => delegation.followUps)) {
+        use(followUp.senderAgentId, followUp.evidence, trace.foundIn(followUp.text), { landed: 'delegation' });
+    }
+    // Words an agent wrote that are no call of the model: code it handed its runtime (X14), and instructions that reached
+    // no helper by id (X17). Each says only that the agent put the value into what it sent, never that it ran or arrived.
+    for (const context of model.contexts) {
+        if (context.author !== 'agent' || context.agentId === undefined)
+            continue;
+        if (context.kind !== 'code' && context.kind !== 'unjoined-instruction')
+            continue;
+        use(context.agentId, context.evidence, trace.foundIn(context.text), { landed: 'call' });
+    }
+    for (const event of model.events) {
+        if (event.written !== undefined) {
+            // What a call puts into a file, never the text an edit takes out: a value only there was in the file already.
+            const landing = { landed: 'file', targets: event.targets, intoProtected: protectedInputs.has(event.id) };
+            use(event.agentId, event.evidence, foundIn(event.written), landing);
+            continue;
+        }
+        const found = foundIn(stringsIn(event.input));
+        if (delegating.has(event.id))
+            use(event.agentId, event.evidence, found, { landed: 'delegation' });
+        else if (event.commands.length > 0) {
+            const programs = [...new Set(event.commands.flatMap((command) => programsIn(command)))];
+            use(event.agentId, event.evidence, found, { landed: 'command', programs, commits: event.commands.some((command) => commitsIn(command)) });
+        }
+        else
+            use(event.agentId, event.evidence, found, { landed: 'call' });
+    }
+    const order = new Map(model.agents.map((agent, index) => [agent.id, index]));
+    const position = (agentId) => order.get(agentId) ?? order.size;
+    return uses.sort((first, second) => position(first.agentId) - position(second.agentId) || first.evidence.record - second.evidence.record);
+}
+/** The texts each agent received that carry a traced value, earliest first. */
+function sourcesOf(model, accesses, { trace }) {
+    const events = new Map(model.events.map((event) => [event.id, event]));
+    const delegating = new Set(model.delegations.map((delegation) => delegation.id));
+    // A write to a protected file is an access as well, and reads nothing: only a call that returns something reads.
+    const reads = new Set(accesses
+        .filter((access) => access.outcome === 'succeeded' && events.get(access.eventId)?.resultShape !== 'none')
+        .map((access) => access.eventId));
+    const byAgent = new Map();
+    const add = (agentId, source) => {
+        if (source.found.size === 0)
+            return;
+        const list = byAgent.get(agentId);
+        if (list === undefined)
+            byAgent.set(agentId, [source]);
+        else
+            list.push(source);
+    };
+    for (const event of model.events) {
+        const result = event.result;
+        // X10: only output the agent's model was handed carried a value to it. What a process printed, as a runtime
+        // recorded it, reached the agent only where it is also in something delivered.
+        if (result?.content === undefined || result.stage !== 'model' || delegating.has(event.id))
+            continue;
+        const kind = reads.has(event.id) ? 'read' : 'unprotected';
+        add(event.agentId, { record: result.evidence.record, kind, found: trace.foundIn(result.content), targets: event.targets });
+    }
+    for (const delivery of model.deliveries) {
+        if (delivery.status !== 'confirmed')
+            continue;
+        // Joined to a call by id, it is that call's output; joined to none, it is delivered output and no more.
+        const source = delivery.sourceId === undefined ? undefined : events.get(delivery.sourceId);
+        const kind = source !== undefined && reads.has(source.id) ? 'read' : source !== undefined ? 'unprotected' : 'delivered';
+        add(delivery.recipientAgentId, { record: delivery.evidence.record, kind, found: trace.foundIn(delivery.text), targets: source?.targets ?? [] });
+    }
+    // What came back from a delegation is a source for the agent it came back to: its result, unless that is a launch
+    // notice, and every report delivered for it (R3).
+    for (const delegation of model.delegations) {
+        const result = events.get(delegation.id)?.result;
+        if (result?.content !== undefined && result.launchNotice !== true) {
+            add(delegation.parentAgentId, { record: result.evidence.record, kind: 'returned', found: trace.foundIn(result.content), targets: [], delegationId: delegation.id });
+        }
+        for (const report of delegation.reports) {
+            add(delegation.parentAgentId, { record: report.evidence.record, kind: 'returned', found: trace.foundIn(report.content), targets: [], delegationId: delegation.id });
+        }
+    }
+    for (const list of byAgent.values()) {
+        list.sort((first, second) => first.record - second.record || SOURCE_ORDER.indexOf(first.kind) - SOURCE_ORDER.indexOf(second.kind));
+    }
+    return byAgent;
+}
+function stringsIn(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(stringsIn);
+    if (value !== null && typeof value === 'object')
+        return Object.values(value).flatMap(stringsIn);
+    return [];
+}

package/dist/core/access/words-before.js

@@ -0,0 +1,52 @@
+/**
+ * The words before every call of every agent.
+ *
+ * A block belongs to the **run** of calls that follows it, not to the first of them: measured on one
+ * session, one block stands before 1 call in 136 runs, 2 in 76, 3 in 15 and 4 in 10. A call that follows another
+ * call directly has no words of its own - 186 of 462 - and that is reported as the absence it is, never filled in
+ * from the run before.
+ *
+ * Order is the record's, which is the order the transcript was written in; nothing here is joined by time.
+ */
+export function wordsBeforeCalls(model) {
+    const before = new Map();
+    for (const agentId of new Set(model.events.map((event) => event.agentId))) {
+        for (const run of runsOf(model, agentId)) {
+            for (const call of run.calls)
+                before.set(call, { words: run.words, covers: run.calls.length });
+        }
+    }
+    return before;
+}
+/** One agent's records in order: each stretch of writing, and the calls that follow it before it writes again. */
+function runsOf(model, agentId) {
+    const calls = model.events
+        .filter((event) => event.agentId === agentId)
+        .map((event) => ({ at: event.evidence.record, id: event.id }));
+    const written = model.messages.filter((message) => message.agentId === agentId);
+    // A call and a message never share a record - measured, 149 of 149 text blocks and 249 of 249 reasoning blocks
+    // sit on lines of their own - so the record alone orders them.
+    const items = [
+        ...written.map((message) => ({ at: message.evidence.record, message })),
+        ...calls.map((call) => ({ at: call.at, call: call.id })),
+    ].sort((first, second) => first.at - second.at);
+    const runs = [];
+    let words = [];
+    let following = [];
+    for (const item of items) {
+        if ('message' in item) {
+            // Writing after a run closes it: what comes next stands before the calls that come next.
+            if (following.length > 0) {
+                runs.push({ words, calls: following });
+                words = [];
+                following = [];
+            }
+            words.push(item.message);
+            continue;
+        }
+        following.push(item.call);
+    }
+    if (following.length > 0)
+        runs.push({ words, calls: following });
+    return runs;
+}

package/dist/core/agent.js

@@ -0,0 +1 @@
+export const MAIN_AGENT_TYPE = 'main';

package/dist/core/capability.js

@@ -0,0 +1,11 @@
+/** The gap each unanswered question leaves: absent and unmeasured stay different answers to a reader. */
+export function capabilityGaps(records) {
+    return records.flatMap((record) => record.state === 'supported'
+        ? []
+        : [{
+                kind: record.state === 'absent' ? 'capability-absent' : 'capability-unmeasured',
+                question: record.question,
+                source: record.source,
+                ...(record.agentId === undefined ? {} : { agentId: record.agentId }),
+            }]);
+}

package/dist/core/combined-project-catalogue.js

@@ -0,0 +1,36 @@
+/**
+ * One list of the projects a person worked on with any AI (`which-project.md` V9; `2026-09-27-what-codex-wrote.md` X28).
+ * A folder with conversations in several AIs is one project: the same id for the same path. An id another project with a
+ * different path already holds is never merged into it and never renamed - its folder cannot be named without taking
+ * another's name, so it is counted, as a project whose folder was not said is (V17: a page names a project by its id).
+ */
+export class CombinedProjectCatalogue {
+    #catalogues;
+    constructor(catalogues) {
+        this.#catalogues = catalogues;
+    }
+    async list() {
+        const listings = await Promise.all(this.#catalogues.map((catalogue) => catalogue.list()));
+        const byId = new Map();
+        let unreadable = listings.reduce((sum, listing) => sum + listing.unreadable, 0);
+        for (const project of listings.flatMap((listing) => listing.projects)) {
+            const known = byId.get(project.id);
+            if (known === undefined)
+                byId.set(project.id, project);
+            else if (known.path === project.path)
+                byId.set(project.id, merged(known, project));
+            else
+                unreadable += 1;
+        }
+        return { projects: [...byId.values()].sort((a, b) => b.newest.modifiedAt - a.newest.modifiedAt), unreadable };
+    }
+}
+/** One folder's conversations in two AIs: counted together, and recognised by whichever holds the newer one. */
+function merged(first, second) {
+    return {
+        ...first,
+        exists: first.exists || second.exists,
+        conversations: first.conversations + second.conversations,
+        newest: second.newest.modifiedAt > first.newest.modifiedAt ? second.newest : first.newest,
+    };
+}

package/dist/core/combined-session-catalogue.js

@@ -0,0 +1,25 @@
+/**
+ * One list of a project's conversations, whichever AI held them (`2026-09-27-what-codex-wrote.md` XD5, X28): every
+ * catalogue is asked, every session kept with its provider - two AIs may use one id - and every place looked in is kept
+ * with whether it was there. The listing was `found` where any place was: a project only one AI worked in is still a
+ * project with conversations. Found by looking at a Codex-only project, which said it had none.
+ */
+export class CombinedSessionCatalogue {
+    #catalogues;
+    constructor(catalogues) {
+        if (catalogues.length === 0)
+            throw new Error('A combined catalogue needs a catalogue to combine.');
+        this.#catalogues = catalogues;
+    }
+    async list(workingDirectory) {
+        const listings = await Promise.all(this.#catalogues.map((catalogue) => catalogue.list(workingDirectory)));
+        const [first] = listings;
+        const found = listings.find((listing) => listing.found) ?? first;
+        return {
+            directory: found.directory,
+            found: found.found,
+            searched: listings.flatMap((listing) => listing.searched),
+            sessions: listings.flatMap((listing) => listing.sessions).sort((a, b) => b.modifiedAt - a.modifiedAt),
+        };
+    }
+}

package/dist/core/completeness.js

@@ -0,0 +1,10 @@
+/**
+ * A gap that leaves a relation unjoined makes the whole thing `unresolved`; any other gap makes it `partial`.
+ * The distinction matters because an unresolved relation means the event gets no outcome at all (§4.3 rule 6),
+ * while a partial one means the picture has holes we can name.
+ */
+export function completenessOf(gaps) {
+    if (gaps.some((gap) => gap.kind === 'relation-unresolved'))
+        return 'unresolved';
+    return gaps.length === 0 ? 'complete' : 'partial';
+}

package/dist/core/context.js

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