@peakflo/agent-harness 0.2.9-rc.4 → 0.2.9-rc.6

package/dist/adapters/codex-approval-text.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * What a person is shown when `codex app-server` asks for an approval.
+ *
+ * The card used to show the protocol itself: `item/fileChange/requestApproval`
+ * and `id: exec-…`, with the file name only in the item above it. This module
+ * turns each kind of request the app-server can send into a first line that
+ * says what will happen ("Write: src/a.ts", "Run: npm test") and further lines
+ * with what helps to decide (where, why, which files).
+ *
+ * The first line is the title; the control plane's card shows it on its own.
+ * No ids: nobody can decide anything from one.
+ *
+ * Request kinds, from `codex app-server generate-json-schema` (ServerRequest):
+ *   item/commandExecution/requestApproval   a command, or input to a terminal
+ *   item/fileChange/requestApproval         a patch; the files are on the item
+ *   item/permissions/requestApproval        wider sandbox access for the turn
+ *   mcpServer/elicitation/request           an MCP server asks (incl. to run
+ *                                           one of its tools)
+ *   item/tool/requestUserInput              the model asks a question
+ *   execCommandApproval, applyPatchApproval the older forms of the first two
+ * Kept out of the adapter, which is a copy of 20x's, so it can be tested alone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFileChanges = readFileChanges;
+exports.describeCodexApproval = describeCodexApproval;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/** One line, however the value was written. */
+function oneLine(value) {
+    return value.replace(/\s*\n\s*/g, ' ⏎ ').trim();
+}
+const MAX_LISTED_PATHS = 12;
+/** `/work/space/src/a.ts` in `/work/space` → `src/a.ts`. Others unchanged. */
+function relativeTo(workspaceDir, path) {
+    const root = (workspaceDir ?? '').replace(/\/+$/, '');
+    if (!root)
+        return path;
+    // macOS reports the same directory as /tmp/… and /private/tmp/….
+    for (const prefix of [
+        root,
+        `/private${root}`,
+        root.replace(/^\/private/, '')
+    ]) {
+        if (prefix && path.startsWith(`${prefix}/`)) {
+            return path.slice(prefix.length + 1);
+        }
+    }
+    return path;
+}
+function countDiff(diff) {
+    let added = 0;
+    let removed = 0;
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            continue;
+        if (line.startsWith('+'))
+            added += 1;
+        else if (line.startsWith('-'))
+            removed += 1;
+    }
+    return { added, removed };
+}
+function changeKind(value) {
+    if (typeof value === 'string')
+        return value;
+    if (isRecord(value)) {
+        return text(value.type) || Object.keys(value)[0] || 'update';
+    }
+    return 'update';
+}
+/**
+ * The files of a change, from either shape Codex uses:
+ *   v2 item       `changes: [{ path, kind: { type }, diff }]`
+ *   older request `fileChanges: { [path]: { add | delete | update: {…} } }`
+ */
+function readFileChanges(source) {
+    if (Array.isArray(source)) {
+        const changes = [];
+        for (const entry of source) {
+            if (!isRecord(entry) || !text(entry.path))
+                continue;
+            const diff = text(entry.diff);
+            const kind = changeKind(entry.kind);
+            // A new file's "diff" is its whole content, without `+` marks.
+            const counted = kind === 'add' && diff && !/^[+-]/m.test(diff)
+                ? { added: diff.split('\n').length, removed: 0 }
+                : countDiff(diff);
+            changes.push({ path: text(entry.path), kind, ...counted });
+        }
+        return changes;
+    }
+    if (isRecord(source)) {
+        return Object.entries(source).map(([path, change]) => {
+            const kind = changeKind(change);
+            const body = isRecord(change) && isRecord(change[kind]) ? change[kind] : {};
+            const diff = text(body.unified_diff) || text(body.diff);
+            const content = text(body.content);
+            return {
+                path,
+                kind,
+                ...(diff
+                    ? countDiff(diff)
+                    : { added: content ? content.split('\n').length : 0, removed: 0 })
+            };
+        });
+    }
+    return [];
+}
+function verbFor(kind) {
+    if (kind === 'add')
+        return 'Create';
+    if (kind === 'delete')
+        return 'Delete';
+    return 'Write';
+}
+function changeSummary(change) {
+    if (change.kind === 'delete')
+        return '';
+    const parts = [];
+    if (change.added)
+        parts.push(`+${change.added}`);
+    if (change.removed)
+        parts.push(`−${change.removed}`);
+    return parts.length ? ` (${parts.join(' ')})` : '';
+}
+function describeFileChanges(changes) {
+    if (changes.length === 0)
+        return ['Write: files in the workspace'];
+    if (changes.length === 1) {
+        const [only] = changes;
+        return [`${verbFor(only.kind)}: ${only.path}${changeSummary(only)}`];
+    }
+    const kinds = new Set(changes.map((change) => change.kind));
+    const verb = kinds.size === 1 ? verbFor(changes[0].kind) : 'Change';
+    const lines = [`${verb}: ${changes.length} files`];
+    for (const change of changes.slice(0, MAX_LISTED_PATHS)) {
+        // Said once in the first line when every file is the same kind of change.
+        const mark = kinds.size === 1
+            ? ''
+            : change.kind === 'add'
+                ? 'new'
+                : change.kind === 'delete'
+                    ? 'deleted'
+                    : '';
+        lines.push(`• ${change.path}${changeSummary(change)}${mark ? ` — ${mark}` : ''}`);
+    }
+    if (changes.length > MAX_LISTED_PATHS) {
+        lines.push(`• and ${changes.length - MAX_LISTED_PATHS} more`);
+    }
+    return lines;
+}
+/**
+ * `/bin/zsh -lc 'npm test'` → `npm test`. Codex runs every command through a
+ * login shell; the wrapper is the same every time and hides the command. Only
+ * the plain one-quoted form is unwrapped, so nothing is ever shown that is not
+ * literally what the shell will be given.
+ */
+function unwrapShell(command) {
+    const match = /^(?:\/(?:usr\/)?bin\/)?(?:zsh|bash|sh) -l?c (['"])([\s\S]*)\1$/.exec(command.trim());
+    if (!match)
+        return command;
+    const [, quote, inner] = match;
+    return inner.includes(quote) || inner.includes('\\') ? command : inner;
+}
+function commandText(value) {
+    if (Array.isArray(value)) {
+        return value
+            .filter((part) => typeof part === 'string')
+            .join(' ');
+    }
+    return text(value);
+}
+function describePermissions(permissions) {
+    const lines = [];
+    if (!isRecord(permissions))
+        return lines;
+    if (isRecord(permissions.network) && permissions.network.enabled === true) {
+        lines.push('• network access');
+    }
+    if (isRecord(permissions.fileSystem)) {
+        const fileSystem = permissions.fileSystem;
+        const list = (key, label) => {
+            const paths = Array.isArray(fileSystem[key])
+                ? fileSystem[key].filter((path) => typeof path === 'string')
+                : [];
+            for (const path of paths)
+                lines.push(`• ${label} ${path}`);
+        };
+        list('write', 'write to');
+        list('read', 'read');
+        if (Array.isArray(fileSystem.entries)) {
+            for (const entry of fileSystem.entries) {
+                if (!isRecord(entry))
+                    continue;
+                const path = isRecord(entry.path)
+                    ? text(entry.path.path) || JSON.stringify(entry.path)
+                    : text(entry.path);
+                const access = text(entry.access) || 'access';
+                if (path)
+                    lines.push(`• ${access} ${path}`);
+            }
+        }
+    }
+    return lines;
+}
+/** `item/somethingNew/requestApproval` → "something new". */
+function humanise(method) {
+    const words = method
+        .replace(/^item\//, '')
+        .replace(/\/?(requestApproval|request)$/i, '')
+        .replace(/Approval$/i, '')
+        .replace(/[/_]/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .trim()
+        .toLowerCase();
+    return words || 'an action';
+}
+/**
+ * The text of one approval request.
+ *
+ * @param item the thread item the request is about, when the adapter has seen
+ *   it (`item/started` arrives before the request). A file change's paths are
+ *   only there.
+ */
+function describeCodexApproval(method, params, item, 
+/** The session's workspace; paths inside it are shown relative to it. */
+workspaceDir) {
+    const reason = text(params.reason);
+    const lines = [];
+    const shown = (path) => relativeTo(workspaceDir, path);
+    if (method === 'item/commandExecution/requestApproval' ||
+        method === 'execCommandApproval') {
+        const command = unwrapShell(commandText(params.command) || commandText(item?.command) || '');
+        const network = isRecord(params.networkApprovalContext)
+            ? params.networkApprovalContext
+            : null;
+        if (params.kind === 'writeStdin') {
+            lines.push(`Send input to a running command: ${oneLine(command)}`);
+        }
+        else if (command) {
+            lines.push(`Run: ${oneLine(command)}`);
+        }
+        else if (network) {
+            lines.push(`Network access: ${text(network.host)}`);
+        }
+        else {
+            lines.push('Run: a command');
+        }
+        const cwd = text(params.cwd) || text(item?.cwd);
+        // The workspace itself goes without saying; anywhere else is worth a line.
+        const where = cwd
+            ? shown(`${cwd.replace(/\/+$/, '')}/.`).replace(/\/?\.$/, '')
+            : '';
+        if (where)
+            lines.push(`In: ${where}`);
+        if (network && command) {
+            lines.push(`Network access: ${text(network.host)}${text(network.protocol) ? ` (${text(network.protocol)})` : ''}`);
+        }
+    }
+    else if (method === 'item/fileChange/requestApproval' ||
+        method === 'applyPatchApproval') {
+        lines.push(...describeFileChanges(readFileChanges(params.fileChanges ?? item?.changes).map((change) => ({
+            ...change,
+            path: shown(change.path)
+        }))));
+        const root = text(params.grantRoot);
+        if (root)
+            lines.push(`Also asks to write under: ${root}`);
+    }
+    else if (method === 'item/permissions/requestApproval') {
+        const wanted = describePermissions(params.permissions);
+        lines.push('Grant more access for this turn');
+        lines.push(...(wanted.length ? wanted : ['• wider sandbox access']));
+        const cwd = text(params.cwd);
+        if (cwd)
+            lines.push(`In: ${cwd}`);
+    }
+    else if (method === 'mcpServer/elicitation/request') {
+        const server = text(params.serverName) || 'An MCP server';
+        const message = text(params.message);
+        lines.push(message
+            ? `${server} asks: ${oneLine(message)}`
+            : `${server} asks to continue`);
+        const url = text(params.url);
+        if (url)
+            lines.push(`Opens: ${url}`);
+    }
+    else if (method === 'item/tool/requestUserInput') {
+        const first = Array.isArray(params.questions) ? params.questions[0] : null;
+        const question = isRecord(first)
+            ? text(first.question) || text(first.header)
+            : '';
+        lines.push(question ? `Codex asks: ${oneLine(question)}` : 'Codex asks a question');
+    }
+    else {
+        // A kind this build does not know. Say what is asked in plain words and
+        // show what the request itself says about it, never the method name alone.
+        const command = commandText(params.command);
+        lines.push(`Codex asks to approve: ${humanise(method)}`);
+        if (command)
+            lines.push(`Command: ${oneLine(command)}`);
+        const cwd = text(params.cwd);
+        if (cwd)
+            lines.push(`In: ${cwd}`);
+    }
+    if (reason)
+        lines.push(`Reason: ${oneLine(reason)}`);
+    return lines.join('\n');
+}

package/dist/adapters/cursor-acp.d.ts

@@ -0,0 +1,84 @@
+/**
+ * What the runner has to know about Cursor's ACP agent (`cursor-agent acp`)
+ * that the generic ACP adapter does not: how a model is named on the wire,
+ * which Cursor mode a permission mode maps to, and how the account's plan
+ * limit shows up.
+ *
+ * Kept out of `acp-adapter.ts`, which is a copy of the 20x adapter, so the
+ * copy stays close to its source and these rules can be tested on their own.
+ */
+/** One entry of `configOptions` in a `session/new` or `session/load` result. */
+interface AcpConfigOption {
+    id: string;
+    values: Array<{
+        value: string;
+        name: string;
+    }>;
+}
+/** The `configOptions` of a session result, in a shape that is safe to read. */
+export declare function readAcpConfigOptions(sessionResult: unknown): AcpConfigOption[];
+/**
+ * The value to send in `session/set_config_option { configId: 'model' }` for
+ * the model an agent names, or null when the session offers nothing that
+ * matches — in which case nothing is sent and Cursor keeps its own default.
+ *
+ * WHY THIS IS NOT THE ID ITSELF. Cursor's ACP agent accepts only the values it
+ * lists in the session's own `model` option, and those carry parameters:
+ * `default[]` (shown as "Auto"), `composer-2.5[fast=true]`,
+ * `gpt-5.6-sol[context=272k,reasoning=medium,fast=false]`. The ids an agent
+ * holds come from `cursor-agent models` (`auto`, `composer-2.5`,
+ * `gpt-5.6-sol-medium`), which is a different list. Sending such an id gave
+ * `Failed to set model: Invalid params` on every turn, "Auto" included.
+ *
+ * Tried in order: the exact value, the option's display name, the part before
+ * `[`, then the longest such part the id starts with (`gpt-5.6-sol-medium`
+ * → `gpt-5.6-sol[…]`). `auto` is Cursor's `default`.
+ */
+export declare function resolveCursorModelValue(model: string | undefined, sessionResult: unknown): string | null;
+export type CursorMode = 'agent' | 'plan' | 'ask';
+/**
+ * The Cursor mode a turn must run in.
+ *
+ * FAIL CLOSED. In its `agent` mode Cursor asks only about commands that are
+ * not on the allow-list in the runner owner's `~/.cursor/cli-config.json`
+ * (seen: "Not in allowlist: cat, echo"). The runner must not read or change
+ * that list, so it cannot know which actions Cursor will run unasked, and a
+ * permission mode that promises a question before EACH action cannot be
+ * promised for Cursor. Every asking mode therefore runs
+ * Cursor in one of its own read-only modes — stricter than what was asked for,
+ * never looser:
+ *
+ *   plan                       → Cursor `plan` (reads and proposes a plan)
+ *   default, acceptEdits       → Cursor `ask`  (reads and answers, no changes)
+ *   bypassPermissions          → Cursor `agent` (the only mode that may act)
+ *
+ * A permission request Cursor does raise is still put to the person.
+ */
+export declare function cursorModeFor(config: {
+    permissionMode?: string;
+    sandboxMode?: string;
+}): CursorMode;
+/**
+ * The exact value of the session's `mode` option for a Cursor mode, or null
+ * when the session does not offer it. The caller must refuse the turn on null
+ * for a read-only mode rather than run in whatever mode Cursor starts in.
+ */
+export declare function resolveCursorModeValue(mode: CursorMode, sessionResult: unknown): string | null;
+/**
+ * Is this whole assistant reply Cursor's plan-limit notice?
+ *
+ * Cursor does not report its account limit as an error. It sends the sentence
+ * "Upgrade your plan to continue" as the model's answer and ends the turn
+ * normally. Matched on the WHOLE reply only, so an answer that merely quotes
+ * the sentence is left alone.
+ */
+export declare function isCursorPlanLimitReply(text: string | undefined): boolean;
+/** Could this partial reply still grow into the plan-limit notice? */
+export declare function mayBecomeCursorPlanLimitReply(text: string | undefined): boolean;
+export declare const CURSOR_PLAN_LIMIT_ERROR: string;
+/** `error.message`, plus `error.data.message` when the agent sent one. */
+export declare function describeAcpRpcError(error: {
+    message?: unknown;
+    data?: unknown;
+}): string;
+export {};

package/dist/adapters/cursor-acp.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * What the runner has to know about Cursor's ACP agent (`cursor-agent acp`)
+ * that the generic ACP adapter does not: how a model is named on the wire,
+ * which Cursor mode a permission mode maps to, and how the account's plan
+ * limit shows up.
+ *
+ * Kept out of `acp-adapter.ts`, which is a copy of the 20x adapter, so the
+ * copy stays close to its source and these rules can be tested on their own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURSOR_PLAN_LIMIT_ERROR = void 0;
+exports.readAcpConfigOptions = readAcpConfigOptions;
+exports.resolveCursorModelValue = resolveCursorModelValue;
+exports.cursorModeFor = cursorModeFor;
+exports.resolveCursorModeValue = resolveCursorModeValue;
+exports.isCursorPlanLimitReply = isCursorPlanLimitReply;
+exports.mayBecomeCursorPlanLimitReply = mayBecomeCursorPlanLimitReply;
+exports.describeAcpRpcError = describeAcpRpcError;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readOptionValues(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const values = [];
+    for (const entry of raw) {
+        if (!isRecord(entry))
+            continue;
+        // A grouped option list: `{ group, name, options: [...] }`.
+        if (Array.isArray(entry.options)) {
+            values.push(...readOptionValues(entry.options));
+            continue;
+        }
+        if (typeof entry.value !== 'string')
+            continue;
+        values.push({
+            value: entry.value,
+            name: typeof entry.name === 'string' ? entry.name : entry.value
+        });
+    }
+    return values;
+}
+/** The `configOptions` of a session result, in a shape that is safe to read. */
+function readAcpConfigOptions(sessionResult) {
+    if (!isRecord(sessionResult) || !Array.isArray(sessionResult.configOptions)) {
+        return [];
+    }
+    const options = [];
+    for (const entry of sessionResult.configOptions) {
+        if (!isRecord(entry) || typeof entry.id !== 'string')
+            continue;
+        options.push({ id: entry.id, values: readOptionValues(entry.options) });
+    }
+    return options;
+}
+function optionValues(sessionResult, id) {
+    return (readAcpConfigOptions(sessionResult).find((option) => option.id === id)
+        ?.values ?? []);
+}
+/** `composer-2.5[fast=true]` → `composer-2.5`. */
+function baseOf(value) {
+    const bracket = value.indexOf('[');
+    return (bracket >= 0 ? value.slice(0, bracket) : value).trim().toLowerCase();
+}
+/**
+ * The value to send in `session/set_config_option { configId: 'model' }` for
+ * the model an agent names, or null when the session offers nothing that
+ * matches — in which case nothing is sent and Cursor keeps its own default.
+ *
+ * WHY THIS IS NOT THE ID ITSELF. Cursor's ACP agent accepts only the values it
+ * lists in the session's own `model` option, and those carry parameters:
+ * `default[]` (shown as "Auto"), `composer-2.5[fast=true]`,
+ * `gpt-5.6-sol[context=272k,reasoning=medium,fast=false]`. The ids an agent
+ * holds come from `cursor-agent models` (`auto`, `composer-2.5`,
+ * `gpt-5.6-sol-medium`), which is a different list. Sending such an id gave
+ * `Failed to set model: Invalid params` on every turn, "Auto" included.
+ *
+ * Tried in order: the exact value, the option's display name, the part before
+ * `[`, then the longest such part the id starts with (`gpt-5.6-sol-medium`
+ * → `gpt-5.6-sol[…]`). `auto` is Cursor's `default`.
+ */
+function resolveCursorModelValue(model, sessionResult) {
+    const wanted = (model ?? '').trim().toLowerCase();
+    if (!wanted)
+        return null;
+    const values = optionValues(sessionResult, 'model');
+    if (values.length === 0)
+        return null;
+    const exact = values.find((entry) => entry.value.toLowerCase() === wanted);
+    if (exact)
+        return exact.value;
+    const byName = values.find((entry) => entry.name.trim().toLowerCase() === wanted);
+    if (byName)
+        return byName.value;
+    const wantedBase = wanted === 'auto' ? 'default' : baseOf(wanted);
+    const byBase = values.find((entry) => baseOf(entry.value) === wantedBase);
+    if (byBase)
+        return byBase.value;
+    let best = null;
+    for (const entry of values) {
+        const base = baseOf(entry.value);
+        if (!base || !wantedBase.startsWith(`${base}-`))
+            continue;
+        if (!best || base.length > best.base.length) {
+            best = { value: entry.value, base };
+        }
+    }
+    return best?.value ?? null;
+}
+/**
+ * The Cursor mode a turn must run in.
+ *
+ * FAIL CLOSED. In its `agent` mode Cursor asks only about commands that are
+ * not on the allow-list in the runner owner's `~/.cursor/cli-config.json`
+ * (seen: "Not in allowlist: cat, echo"). The runner must not read or change
+ * that list, so it cannot know which actions Cursor will run unasked, and a
+ * permission mode that promises a question before EACH action cannot be
+ * promised for Cursor. Every asking mode therefore runs
+ * Cursor in one of its own read-only modes — stricter than what was asked for,
+ * never looser:
+ *
+ *   plan                       → Cursor `plan` (reads and proposes a plan)
+ *   default, acceptEdits       → Cursor `ask`  (reads and answers, no changes)
+ *   bypassPermissions          → Cursor `agent` (the only mode that may act)
+ *
+ * A permission request Cursor does raise is still put to the person.
+ */
+function cursorModeFor(config) {
+    // Only an explicit "allow" may act. An unknown value is treated as asking.
+    if (config.permissionMode === 'allow')
+        return 'agent';
+    return config.sandboxMode === 'read-only' ? 'plan' : 'ask';
+}
+/**
+ * The exact value of the session's `mode` option for a Cursor mode, or null
+ * when the session does not offer it. The caller must refuse the turn on null
+ * for a read-only mode rather than run in whatever mode Cursor starts in.
+ */
+function resolveCursorModeValue(mode, sessionResult) {
+    const values = optionValues(sessionResult, 'mode');
+    const found = values.find((entry) => entry.value.toLowerCase() === mode);
+    if (found)
+        return found.value;
+    // Older agents list modes under `modes.availableModes` instead.
+    if (isRecord(sessionResult) && isRecord(sessionResult.modes)) {
+        const available = sessionResult.modes.availableModes;
+        if (Array.isArray(available)) {
+            for (const entry of available) {
+                if (isRecord(entry) &&
+                    typeof entry.id === 'string' &&
+                    entry.id.toLowerCase() === mode) {
+                    return entry.id;
+                }
+            }
+        }
+    }
+    return null;
+}
+const CURSOR_PLAN_LIMIT_TEXT = 'upgrade your plan to continue';
+function normalise(text) {
+    return text
+        .trim()
+        .replace(/[.!]+$/, '')
+        .replace(/\s+/g, ' ')
+        .toLowerCase();
+}
+/**
+ * Is this whole assistant reply Cursor's plan-limit notice?
+ *
+ * Cursor does not report its account limit as an error. It sends the sentence
+ * "Upgrade your plan to continue" as the model's answer and ends the turn
+ * normally. Matched on the WHOLE reply only, so an answer that merely quotes
+ * the sentence is left alone.
+ */
+function isCursorPlanLimitReply(text) {
+    return typeof text === 'string' && normalise(text) === CURSOR_PLAN_LIMIT_TEXT;
+}
+/** Could this partial reply still grow into the plan-limit notice? */
+function mayBecomeCursorPlanLimitReply(text) {
+    if (typeof text !== 'string')
+        return false;
+    const partial = normalise(text);
+    return partial.length > 0 && CURSOR_PLAN_LIMIT_TEXT.startsWith(partial);
+}
+exports.CURSOR_PLAN_LIMIT_ERROR = 'Cursor answered "Upgrade your plan to continue" and did no work. This ' +
+    'comes from the Cursor account that is signed in on the runner, not from ' +
+    'Peakflo: its plan does not include the selected model or has reached its ' +
+    'limit. Choose the "Auto" model for this agent, upgrade or change the ' +
+    'Cursor account on the runner machine, or choose another harness.';
+/** `error.message`, plus `error.data.message` when the agent sent one. */
+function describeAcpRpcError(error) {
+    const message = typeof error.message === 'string' ? error.message : 'ACP error';
+    const detail = isRecord(error.data) && typeof error.data.message === 'string'
+        ? error.data.message
+        : typeof error.data === 'string'
+            ? error.data
+            : '';
+    return detail && !message.includes(detail)
+        ? `${message}: ${detail}`
+        : message;
+}

package/dist/runtime/session-runner.d.ts

@@ -277,6 +277,35 @@ export declare function decodeQuestionAnswers(answer: string | undefined): Recor
  * Codex's "Allow" read as a denial.
  */
 export declare function isApprovingOptionId(optionId: string): boolean;
+/**
+ * Decide what a user's answer actually means, and fail closed when it is not
+ * clear.
+ *
+ * THREE PATHS REACH HERE AND THEY DO NOT CARRY THE SAME INFORMATION:
+ *
+ *   1. An option BUTTON in the question card. Sends `optionId`. Unambiguous,
+ *      and this is the ordinary case.
+ *   2. The card's Reject button. Sends no `optionId` and the fixed text
+ *      "Rejected by the user."
+ *   3. The COMPOSER. When a question is open, typing a message posts it as an
+ *      answer instead (composer.tsx:76-106) — with no `optionId` at all.
+ *
+ * So free text has to be interpreted, and the rule is: interpret it only when
+ * it plainly matches something the backend offered. Anything else DENIES, and
+ * says so in the transcript rather than silently doing the safer thing without
+ * telling the user why they are being asked again.
+ */
+export declare function resolveApproval(command: {
+    answer?: string;
+    optionId?: string;
+}, open: {
+    knownOptionIds: Set<string>;
+    optionIdByLabel: Map<string, string>;
+}): {
+    approved: boolean;
+    optionId?: string;
+    transcriptText: string;
+};
 export interface McpCheckState {
     checked: Map<string, number>;
     failed: Map<string, FailedMcpCheck>;

package/dist/runtime/session-runner.js

@@ -29,6 +29,7 @@ exports.modelGatewayRefusal = modelGatewayRefusal;
 exports.permissionFingerprint = permissionFingerprint;
 exports.decodeQuestionAnswers = decodeQuestionAnswers;
 exports.isApprovingOptionId = isApprovingOptionId;
+exports.resolveApproval = resolveApproval;
 const node_crypto_1 = require("node:crypto");
 const model_gateway_1 = require("../adapters/model-gateway");
 const contract_1 = require("../contract");
@@ -1869,7 +1870,11 @@ class SessionRunner {
                         question: approval.question,
                         options: approval.options.map((option) => ({
                             id: option.optionId,
-                            label: option.name
+                            label: option.name,
+                            // Whether this answer says yes, decided HERE by the same rule
+                            // that will read the answer back. The card colours its buttons
+                            // from this and never from the words on them.
+                            kind: isApprovingOptionId(option.optionId) ? 'allow' : 'reject'
                         }))
                     }
                 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.9-rc.4",
+  "version": "0.2.9-rc.6",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",