@agentwhy/cli 0.0.0-dev

package/dist/adapter/codex/discovery/session-roots.js

@@ -0,0 +1,49 @@
+import { AMBIGUOUS, sessionOwners } from './session-owners.js';
+/** X3/X5: only unique first-line ids join. Roots are indices into the caller's input, never inferred new agents. */
+export function sessionRoots(headers) {
+    const owners = sessionOwners(headers.map((header) => header.id === '' ? undefined : header.id));
+    const resolved = new Map();
+    return headers.map((_, start) => {
+        const chain = new Set();
+        let index = start;
+        let relation;
+        while (true) {
+            const cached = resolved.get(index);
+            if (cached !== undefined) {
+                relation = cached;
+                break;
+            }
+            if (chain.has(index)) {
+                relation = { kind: 'unresolved', reason: 'cycle' };
+                break;
+            }
+            chain.add(index);
+            const header = headers[index];
+            if (header === undefined || header.id === '' || header.parent.kind === 'unknown') {
+                relation = { kind: 'unresolved', reason: 'invalid-identity' };
+                break;
+            }
+            if (owners.get(header.id) === AMBIGUOUS) {
+                relation = { kind: 'unresolved', reason: 'duplicate-id' };
+                break;
+            }
+            if (header.parent.kind === 'root') {
+                relation = { kind: 'resolved', root: index };
+                break;
+            }
+            const owner = owners.get(header.parent.id);
+            if (owner === undefined) {
+                relation = { kind: 'unresolved', reason: 'missing-parent' };
+                break;
+            }
+            if (owner === AMBIGUOUS) {
+                relation = { kind: 'unresolved', reason: 'duplicate-id' };
+                break;
+            }
+            index = owner;
+        }
+        for (const member of chain)
+            resolved.set(member, relation);
+        return relation;
+    });
+}

package/dist/adapter/codex/events/action-items.js

@@ -0,0 +1,138 @@
+import { basename } from 'node:path';
+import { isJsonObject } from '../../../shared/json.js';
+import { ACTION_ITEMS, CHANGE_KINDS, COMMAND, FILE_CHANGE, IMAGE_VIEW, ITEM, ITEM_STATUSES, MCP, OMISSION_NOTICE, SHELL_FLAGS, SHELLS, WEB_SEARCH, } from '../contract/actions.js';
+/** The action item types the contract names, whether or not it has a profile for them (X6). */
+export function isActionItem(type) {
+    return Object.values(ACTION_ITEMS).some((known) => known === type);
+}
+/**
+ * One action item, read as X6-X11 say. An item type the contract does not name is read the same way as `Extension`:
+ * an unknown tool whose recorded fields are kept as raw input, with no targets and no effect - the caller adds the
+ * capability gap that says an item was not understood.
+ */
+export function readAction(item) {
+    const execution = executionOf(item);
+    switch (item[ITEM.type]) {
+        case ACTION_ITEMS.command:
+            return command(item, execution);
+        case ACTION_ITEMS.fileChange:
+            return fileChange(item, execution);
+        case ACTION_ITEMS.mcp:
+            return {
+                ...unknownTool('McpToolCall', pick(item, [MCP.server, MCP.tool, MCP.arguments]), execution),
+                ...rawOutput(item[MCP.result]),
+            };
+        case ACTION_ITEMS.webSearch:
+            return { ...unknownTool('WebSearch', pick(item, [WEB_SEARCH.action]), execution), ...rawOutput(item[WEB_SEARCH.results]) };
+        case ACTION_ITEMS.imageView: {
+            const path = item[IMAGE_VIEW.path];
+            return unknownTool('ImageView', typeof path === 'string' ? { path } : {}, execution);
+        }
+        case ACTION_ITEMS.extension:
+            return unknownTool('Extension', withoutEnvelope(item), execution);
+        default:
+            return unknownTool('unrecognised action', withoutEnvelope(item), execution);
+    }
+}
+/** X11: the status an item recorded, which says it ran and never what it reached. An item_completed with none completed. */
+function executionOf(item) {
+    const status = item[ITEM.status];
+    const exitCode = item[COMMAND.exitCode];
+    const known = status === undefined ? 'completed' : status === ITEM_STATUSES.completed ? 'completed' : status === ITEM_STATUSES.failed ? 'failed' : 'unrecognised';
+    return { status: known, ...(typeof exitCode === 'number' && Number.isInteger(exitCode) ? { exitCode } : {}) };
+}
+/**
+ * X7, X8: the command line is `command[2]` only when `command` is exactly `[shell, -lc|-c, line]` with a listed shell;
+ * any other shape keeps the whole array as input and is not read as a line. `parsed_cmd` is never read. A read line is
+ * named by the shell the record says ran it, `zsh (cat)` beside Claude Code's `Bash (cat)`: a listed name, never the
+ * record's text. Any other shape keeps the item's type as its name.
+ */
+function command(item, execution) {
+    const words = item[COMMAND.command];
+    const directory = item[COMMAND.workingDirectory];
+    const input = { command: words, ...(typeof directory === 'string' ? { cwd: directory } : {}) };
+    const shape = Array.isArray(words) && words.length === 3 && SHELL_FLAGS.some((flag) => flag === words[1]) && typeof words[2] === 'string'
+        ? { shell: shellOf(words[0]), line: words[2] }
+        : undefined;
+    const output = item[COMMAND.output];
+    const recorded = typeof output === 'string'
+        ? { output: { text: output, completeness: OMISSION_NOTICE.test(output) ? 'partial' : 'unknown' } }
+        : {};
+    if (shape?.shell === undefined)
+        return { ...unknownTool('CommandExecution', input, execution), ...recorded };
+    return {
+        toolName: shape.shell, input, targets: [], commands: [shape.line], resultShape: 'listing', toolKnown: true, execution, ...recorded, unanswered: [],
+    };
+}
+/** The listed shell `program` names, by its file name: `/bin/zsh` is `zsh`. */
+function shellOf(program) {
+    return typeof program === 'string' ? SHELLS.find((shell) => shell === basename(program)) : undefined;
+}
+/**
+ * X9: the targets are the keys of `changes` and every `move_path`; `written` is the text of an add and the added lines of
+ * an update, for a completed change only. A failed change keeps its proposed text in its raw input and writes nothing; a
+ * change kind or diff this does not read writes nothing either, and says so.
+ */
+function fileChange(item, execution) {
+    const changes = item[FILE_CHANGE.changes];
+    if (!isJsonObject(changes))
+        return unknownTool('FileChange', withoutEnvelope(item), execution);
+    const targets = [];
+    const written = [];
+    let unread = false;
+    for (const [path, change] of Object.entries(changes)) {
+        targets.push(path);
+        if (!isJsonObject(change)) {
+            unread = true;
+            continue;
+        }
+        const moved = change[FILE_CHANGE.movePath];
+        if (typeof moved === 'string' && moved !== '')
+            targets.push(moved);
+        const kind = change[FILE_CHANGE.kind];
+        const content = change[FILE_CHANGE.content];
+        const diff = change[FILE_CHANGE.diff];
+        if (kind === CHANGE_KINDS.add && typeof content === 'string')
+            written.push(content);
+        else if (kind === CHANGE_KINDS.update && typeof diff === 'string')
+            written.push(...addedLines(diff));
+        else if (kind !== CHANGE_KINDS.delete)
+            unread = true;
+    }
+    const completed = execution.status === 'completed';
+    return {
+        toolName: 'FileChange',
+        input: { changes },
+        targets,
+        commands: [],
+        resultShape: 'none',
+        toolKnown: true,
+        ...(completed ? { written } : {}),
+        execution,
+        // X9: a change this does not read adds nothing it may have saved. A failed one is an unestablished effect already,
+        // which the core says as such.
+        unanswered: completed && unread ? ['access'] : [],
+    };
+}
+/** The lines an update adds, never the lines it removes: a value only there was in the file already (R7). */
+function addedLines(diff) {
+    return diff.split('\n').filter((line) => line.startsWith('+') && !line.startsWith('+++')).map((line) => line.slice(1));
+}
+function unknownTool(toolName, input, execution) {
+    return { toolName, input, targets: [], commands: [], resultShape: 'none', toolKnown: false, execution, unanswered: [] };
+}
+/**
+ * A result whose text fields the contract does not name (X10): kept whole as raw text, so a value in it is still found and
+ * redacted, and never said to be complete.
+ */
+function rawOutput(value) {
+    if (value === undefined || value === null)
+        return {};
+    return { output: { text: typeof value === 'string' ? value : JSON.stringify(value), completeness: 'unknown' } };
+}
+function pick(item, keys) {
+    return Object.fromEntries(keys.filter((key) => key in item).map((key) => [key, item[key]]));
+}
+function withoutEnvelope(item) {
+    return Object.fromEntries(Object.entries(item).filter(([key]) => key !== ITEM.type && key !== ITEM.id));
+}

package/dist/adapter/codex/events/capability-records.js

@@ -0,0 +1,26 @@
+import { MEASURED_PROFILES, UNKNOWN_MODE_ANSWERS, UNMEASURED_PROFILES } from '../contract/capabilities.js';
+/**
+ * The questions a file answers, declared per source (X23): its build and history mode choose the contract's profile, and
+ * what its reading found adds to it. An unrecognised part or an interrupted turn makes the action stream `unmeasured`
+ * beside whatever the profile says, and never less.
+ */
+export function capabilitiesOf(header, source, agentId, facts) {
+    const agent = agentId === undefined ? {} : { agentId };
+    const answers = { ...answersFor(header) };
+    if (facts.hiddenReasoning)
+        answers.reasoning = 'absent';
+    if (facts.permissionsRecorded)
+        answers.permissions = facts.permissionsIncomplete ? 'unmeasured' : 'supported';
+    const records = Object.entries(answers).map(([question, state]) => ({
+        question: question, state: state, source, ...agent,
+    }));
+    if (facts.unrecognised || facts.interrupted)
+        records.push({ question: 'actions', state: 'unmeasured', source, ...agent });
+    return records;
+}
+function answersFor(header) {
+    if (header.historyMode === 'unknown')
+        return UNKNOWN_MODE_ANSWERS;
+    const measured = MEASURED_PROFILES.find((profile) => header.version !== undefined && profile.builds.includes(header.version) && profile.historyModes.includes(header.historyMode));
+    return measured?.answers ?? UNMEASURED_PROFILES[header.historyMode];
+}

package/dist/adapter/codex/events/codex-session-source.js

@@ -0,0 +1,121 @@
+import { basename } from 'node:path';
+import { MAIN_AGENT_TYPE } from '../../../core/agent.js';
+import { correlate } from '../../../core/correlation/correlate.js';
+import { agentSource, mainSource, reviewSource } from '../../../core/evidence.js';
+import { scanRollout } from './rollout-scan.js';
+/**
+ * Reads a Codex conversation into the core's model: the rollout asked for and every rollout whose recorded parents lead
+ * to it (X5), each read by `scanRollout`, joined by `correlate`. A reviewer's file is a review, never an agent (X19).
+ */
+export class CodexSessionSource {
+    #discovery;
+    #files;
+    #sessionsRoot;
+    #index;
+    constructor(dependencies) {
+        this.#discovery = dependencies.discovery;
+        this.#files = dependencies.files;
+        this.#sessionsRoot = dependencies.sessionsRoot;
+        this.#index = dependencies.index;
+    }
+    async read(input) {
+        const collected = emptyCollection();
+        const tree = await this.#discovery.tree(input, this.#sessionsRoot, this.#index?.latest());
+        if (tree.kind !== 'tree') {
+            // Not a Codex session, or not readable: there is no session to report on, and saying so is the whole answer.
+            collected.gaps.push({ kind: 'session-missing' });
+            return correlate(recordsOf(basename(input), collected));
+        }
+        const roles = rolesOf(tree.members);
+        const root = roles[0];
+        collected.agents.push({ id: root.agentId, type: MAIN_AGENT_TYPE, depth: 0 });
+        for (const role of roles.slice(1))
+            if (role.kind === 'agent')
+                collected.agents.push(agentOf(role));
+        // The root's id is another file's too, so no child could join it (X3); and a folder or file the search could not
+        // read may have held a part of this conversation. A file it read whose first line is no Codex session's could not:
+        // the chain is found by that line alone (X5), so it is no member of any tree, and `doctor` is where it is counted.
+        if (tree.rootShared)
+            collected.gaps.push({ kind: 'relation-unresolved', agentId: root.agentId });
+        collected.gaps.push(...tree.gaps.filter((gap) => gap.reason !== 'unknown-format').map(() => ({ kind: 'source-missing' })));
+        for (const [index, member] of tree.members.entries())
+            await scanRollout(this.#files, member.path, roles[index], collected);
+        // A started agent whose own file is not here still started: it is kept, and its missing record said (X16).
+        const known = new Set(collected.agents.map((agent) => agent.id));
+        for (const entry of collected.delegationIndex) {
+            if (known.has(entry.agentId))
+                continue;
+            known.add(entry.agentId);
+            collected.agents.push({ id: entry.agentId, ...(entry.requestedType === undefined ? {} : { type: entry.requestedType }) });
+            collected.gaps.push({ kind: 'source-missing', agentId: entry.agentId });
+        }
+        return correlate(recordsOf(root.agentId, collected));
+    }
+}
+/** Who each file is, from the tree alone: the root is the conversation; a child is an agent, a reviewer, or unknown. */
+function rolesOf(members) {
+    const threads = new Map(members.map((member) => [member.header.id, member.header]));
+    return members.map((member, index) => {
+        const id = member.header.id;
+        const parent = member.parent === undefined ? undefined : members[member.parent];
+        const reviewer = index > 0 && member.header.origin.kind === 'reviewer';
+        return {
+            header: member.header,
+            kind: reviewer ? 'reviewer' : 'agent',
+            agentId: id,
+            source: index === 0 ? mainSource() : reviewer ? reviewSource(id) : agentSource(id),
+            ...(reviewer && parent !== undefined && parent.header.origin.kind !== 'reviewer' ? { reviewedAgentId: parent.header.id } : {}),
+            idScope: index === 0 ? '' : `${index}:`,
+            childByPath: childrenByPath(members, index),
+            threads,
+        };
+    });
+}
+/** An agent's started children by `agent_path`. A name two of them share names neither (X18). */
+function childrenByPath(members, index) {
+    const byPath = new Map();
+    for (const member of members) {
+        const origin = member.header.origin;
+        if (member.parent !== index || origin.kind !== 'spawned' || origin.agentPath === undefined)
+            continue;
+        byPath.set(origin.agentPath, byPath.has(origin.agentPath) ? undefined : member.header.id);
+    }
+    return byPath;
+}
+/** X15: a started agent's type is its role where one is set, and `subagent` otherwise; its depth is the one recorded. */
+function agentOf(role) {
+    const origin = role.header.origin;
+    if (origin.kind !== 'spawned')
+        return { id: role.agentId };
+    return { id: role.agentId, type: origin.role ?? 'subagent', ...(origin.depth === undefined ? {} : { depth: origin.depth }) };
+}
+function emptyCollection() {
+    return {
+        agents: [], calls: [], results: [], delegations: [], delegationIndex: [], followUps: [], followUpIndex: [], messages: [],
+        agentReports: [], turns: [], reviews: [], contexts: [], deliveries: [], capabilities: [], gaps: [], workingDirectories: new Set(),
+    };
+}
+function recordsOf(sessionId, collected) {
+    return {
+        sessionId,
+        provider: 'codex',
+        agents: collected.agents,
+        calls: collected.calls,
+        results: collected.results,
+        delegations: collected.delegations,
+        delegationIndex: collected.delegationIndex,
+        messages: collected.messages,
+        // Codex names no call when a report comes back; its reports name their agents (X18).
+        deliveredReports: [],
+        agentReports: collected.agentReports,
+        followUps: collected.followUps,
+        followUpIndex: collected.followUpIndex,
+        turns: collected.turns,
+        reviews: collected.reviews,
+        contexts: collected.contexts,
+        deliveries: collected.deliveries,
+        capabilities: collected.capabilities,
+        workingDirectories: [...collected.workingDirectories],
+        gaps: collected.gaps,
+    };
+}

package/dist/adapter/codex/events/hook-refusals.js

@@ -0,0 +1,27 @@
+import { HOOK_REFUSAL } from '../contract/hook-refusals.js';
+/**
+ * agentwhy's own reason (`refuse/render/refusal-words.ts` `refusalReason`), after Codex's words for a hook's refusal: "it
+ * names P", "W expands to P" or "this search would read P", then "which this project's policy protects (R)". A test
+ * reads `refusalReason`'s own sentences back through this, so the two cannot drift apart unnoticed.
+ */
+const REFUSED = new RegExp(escaped(HOOK_REFUSAL.blocked) +
+    "(agentwhy refused this command: (?:it names (.+?)|\\S+ expands to (.+?)|this search would read (.+?)), which this project's policy protects \\((.+?)\\)[^\\n]*?)" +
+    '(?:' + escaped(HOOK_REFUSAL.command) + '([^\\n]*))?$', 'gm');
+/**
+ * Every command agentwhy's Codex hook refused in one cell's output, in order (CK12). A hook's refusal in any other words
+ * is not read: Codex types none (XB1), and a reason nobody here wrote is not guessed at.
+ */
+export function hookRefusalsIn(text) {
+    return [...text.matchAll(REFUSED)].flatMap((match) => {
+        const path = match[2] ?? match[3] ?? match[4];
+        const pattern = match[5];
+        const reason = match[1];
+        if (path === undefined || pattern === undefined || reason === undefined)
+            return [];
+        const command = match[6]?.trim();
+        return [{ path, pattern, reason, ...(command === undefined || command === '' ? {} : { command }) }];
+    });
+}
+function escaped(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}