One live console to monitor Claude Code and Codex agents across machines, track context and spend, and unblock sessions that need you.
// Responding to daemon-hosted Codex threads from the dashboard, on the server's respond routes and with the
// Claude reporter's mechanics: announce an ask (PUT), wait for its answer on the held request (GET …/answer?wait=20), close it
// with `terminal` when the terminal answers first, and post what became of every delivery. Messages and /compact arrive in
// report replies.
//
// The daemon is told nothing except the exact answer the dashboard gave to an open ask (`daemon.answer`), an owner's
// message (`turn/start`; an answer to an async question is one, steered with `turn/steer` into the turn that runs) or
// `/compact` (`thread/compact/start`). A thread is rejoined only to act — when its status changes into a
// waiting flag, when a reply turns responding on, or to deliver a message, an answer or `/compact` — only if it is loaded and
// known not to be ephemeral, and is left once the request resolves or the command was accepted.
import { setTimeout as sleep } from 'node:timers/promises';
import { acceptsFor, RESPOND_LIMITS, sessionKey, type Ask, type AskQuestion, type Delivery, type DeliveryResult, type RespondInfo, type RespondKind, type RespondLevel, type RespondLimit } from '../../server/src/fleet/protocol.js';
import type {
CommandExecutionRequestApprovalParams,
FileChangeRequestApprovalParams,
PermissionsRequestApprovalParams,
RequestId,
RequestPermissionProfile,
ServerRequestMethod,
ToolRequestUserInputParams,
ToolRequestUserInputQuestion,
} from './codex-protocol/v2.js';
import type { Daemon } from './daemon.js';
import type { Fleet, Session, Thread } from './mapping.js';
import { REPLY_CLOSE, REPLY_OPEN, type AsyncQuestion } from './sessionFiles.js';
import { clip, clipFreeText, redact } from './report.js';
import { isDelivery, retryDelay, serverCall, type HttpResult, type Transport } from './transport.js';
const L = RESPOND_LIMITS;
const OUTBOX_MAX = 50;
const ACTED_KEPT = 100;
/** A rejoin that brings no request this reporter maps is left after this long, so no subscription lingers. */
const LEAVE_EMPTY_MS = 5000;
/** How long a file approval waits for our hook's paths: the async PreToolUse hook can land just after the request. */
const HOOK_WAIT_MS = 2000;
/** The wait note of a secret question, which the dashboard never takes; the band already says where to answer ("Answer in its terminal."). */
export const SECRET_NOTE = 'A secret question, typed in the terminal only.';
/**
* What a thread's `session_meta.originator` adds beside `observe-only` when the daemon does not host it: `desktop-app` for one
* the Codex desktop app started (observed in its session files), `not-interactive` for a `codex exec` run, whose process
* sets the originator `codex_exec` (`exec/src/lib.rs:268`) that a new thread takes (`core/src/thread_manager.rs:2015-2024`).
* A Map, so an originator such as `constructor` matches nothing.
*/
const ORIGINATOR_LIMIT: ReadonlyMap<string, RespondLimit> = new Map([
['Codex Desktop', 'desktop-app'],
['codex_exec', 'not-interactive'],
]);
/** An ask's route under its session's. */
const askPath = (a: { ask: Ask }) => `/asks/${encodeURIComponent(a.ask.id)}`;
/** What a cut text ends with, worded as the Claude reporter words it: "[cut off at 40,000 characters]". */
const cutMark = (max: number) => `[cut off at ${max.toLocaleString('en-US')} characters]`;
/** `text` if it fits in `max` characters, else its first `max` followed by `marker`. */
const fit = (text: string, max: number, marker = '') => (text.length <= max ? text : text.slice(0, max) + marker);
/** A block of an ask (a question, an option's description): redacted, line breaks kept (CRLF as LF), a cut one marked as cut. */
const block = (v: unknown, max: number) => fit(redact(String(v ?? '').replace(/\r\n?/g, '\n')), max, `\n\n${cutMark(max)}`);
/** A one-line field of an ask (a header, a label): redacted, whitespace folded to single spaces, cut without a marker. */
const oneLine = (v: unknown, max: number) => fit(redact(String(v ?? '').replace(/\s+/g, ' ').trim()), max);
/** How deep, and how many array items, a tool's arguments are shown before the rest is left out. */
const INPUT_DEPTH = 6;
const INPUT_ITEMS = 50;
/**
* A tool's arguments as an ask shows them: every string redacted (a file approval's `patch` line by line, so no rule reaches
* across a line break and each line of the diff is judged on its own) and held to RESPOND_LIMITS.toolInput, nesting and arrays
* bounded, the whole held to the same limit as JSON. `cut` says the owner is not seeing the request exactly as made — something
* was left out or redacted — and an answer may only be to what was shown (the cut rule).
*/
export function toolInput(input: Record<string, unknown>): { input: Record<string, unknown>; cut: boolean } {
const max = L.toolInput;
let altered = false;
const shown = (v: unknown, depth: number, key = ''): unknown => {
if (typeof v === 'string') {
const clean = depth === 1 && key === 'patch' ? v.split('\n').map((line) => redact(line)).join('\n') : redact(v);
altered ||= clean !== v || clean.length > max;
return fit(clean, max, ` ${cutMark(max)}`);
}
if (v === null || typeof v !== 'object') return v;
if (depth > INPUT_DEPTH) {
altered = true;
return '[cut off]';
}
if (Array.isArray(v)) {
altered ||= v.length > INPUT_ITEMS;
return v.slice(0, INPUT_ITEMS).map((item) => shown(item, depth + 1));
}
// fromEntries, not assignment, so a `__proto__` key stays a plain key.
return Object.fromEntries(Object.entries(v).map(([key, item]) => [key, shown(item, depth + 1, key)]));
};
const out = shown(input, 0) as Record<string, unknown>;
if (JSON.stringify(out).length > max) return { input: { note: 'The input is too long to show here.' }, cut: true };
return { input: out, cut: altered };
}
/** The id Codex gives one async question: `JSON.stringify([tool name, item id, index])` (tui/src/bottom_pane/async_questions/state.rs:21-23). */
const asyncQuestionId = (callId: string, index: number) => JSON.stringify(['request_user_input_async', callId, index]);
/**
* The ask for an async question call: each title as the question — and, cut to the header's length, as its tab label,
* the way Codex's TUI names a question by its title (tui/src/chatwidget/questions.rs:28-31) — its options as given, a typed
* answer always taken ("The UI always allows a free-text answer"). Null past the limits, as questionAsk, or when the call id
* cannot be an ask id.
*/
function asyncQuestionAsk(callId: string, openedAt: number, qs: readonly AsyncQuestion[]): Ask | null {
if (qs.length < 1 || qs.length > L.questions || qs.some((q) => q.options.length > L.options) || !callId || callId.length > 200) return null;
const questions: AskQuestion[] = qs.map((q) => ({
question: block(q.title, L.question),
header: oneLine(q.title, L.header),
multiSelect: false,
options: q.options.map((label) => ({ label: oneLine(label, L.label), description: '', preview: null })),
allowsText: true,
}));
return { id: callId, kind: 'question', agentId: null, openedAt, allowsReply: false, questions };
}
/** `text` cut to at most `max` UTF-8 bytes on a character boundary (Rust's `floor_char_boundary`). */
function cutBytes(text: string, max: number): string {
let out = '';
let bytes = 0;
for (const ch of text) {
bytes += Buffer.byteLength(ch);
if (bytes > max) break;
out += ch;
}
return out;
}
/**
* The message answering an async question ask, written as Codex's AnsweredQuestion writes it
* (`context-fragments/src/answered_question.rs:17-24, 41-57`): the reply envelope around a JSON array of `{answer, question,
* questionItemId}`, one per question answered here and not already answered by a reply in the session file (`replied`, by
* index), the question its title cut to 512 bytes with line breaks as spaces. An answer is the typed text, or the chosen
* option's label exactly as Codex gave it (only unaltered labels are shown), trimmed (state.rs:131-139); null when nothing is
* left to send.
*/
function asyncReplyText(r: { callId: string; questions: readonly AsyncQuestion[] }, d: Delivery, replied: ReadonlySet<number>): string | null {
const replies: { answer: string; question: string; questionItemId: string }[] = [];
r.questions.forEach((q, i) => {
const given = d.answers?.[i];
if (!given || replied.has(i)) return;
const label = 'options' in given ? q.options[given.options[0] ?? -1] : undefined;
const answer = ('text' in given ? String(given.text ?? '') : (label ?? '')).trim();
if (answer) replies.push({ answer, question: cutBytes(q.title, 512).replace(/[\n\r]/g, ' '), questionItemId: asyncQuestionId(r.callId, i) });
});
return replies.length ? `${REPLY_OPEN}\n${JSON.stringify(replies)}\n${REPLY_CLOSE}` : null;
}
/** The turn Codex reports active when it refuses a steer for naming another one (`tui/src/app.rs:786-808`); null otherwise. */
function activeTurnOf(err: unknown): string | null {
const message = typeof (err as { message?: unknown } | null)?.message === 'string' ? (err as { message: string }).message : '';
const prefix = 'expected active turn id `';
const separator = '` but found `';
const rest = message.startsWith(prefix) ? message.slice(prefix.length) : null;
const at = rest?.indexOf(separator) ?? -1;
return rest && at !== -1 && rest.endsWith('`') ? rest.slice(at + separator.length, -1) : null;
}
/**
* Whether Codex refused a `turn/steer` in a way Codex's TUI meets by queueing or starting a new turn (`tui/src/app.rs:768-807`):
* the active turn is not steerable (`codexErrorInfo.activeTurnNotSteerable` in the error's data), there is no active turn, or
* (after the one retry) the expected turn is still not the active one.
*/
function steerFallsBack(err: unknown): boolean {
const e = err as { message?: unknown; data?: unknown } | null;
const message = typeof e?.message === 'string' ? e.message : '';
if (message === 'no active turn to steer' || message.startsWith('expected active turn id `')) return true;
const info = (e?.data as { codexErrorInfo?: unknown } | null | undefined)?.codexErrorInfo;
return !!info && typeof info === 'object' && 'activeTurnNotSteerable' in info;
}
interface Native {
rpcId: RequestId;
method: ServerRequestMethod;
threadId: string;
askId: string | null;
blocking: boolean;
}
interface OpenAsk {
ask: Ask;
kind: RespondKind;
sessionId: string;
threadId: string;
/** The daemon request it answers; null for an async question ask, which no request backs. */
native: Native | null;
done: boolean;
announced: boolean;
/** Something waits on the server for this ask's answer; once that stops, the ask stops riding in reports. */
listening: boolean;
/** The question ask's questions as Codex asked them: answers by position are turned back into these. */
questions?: ToolRequestUserInputQuestion[];
/** The permissions request's profile as Codex asked for it: Allow once grants exactly this. */
permissions?: RequestPermissionProfile;
/** An async question ask: the call it answers and its questions as kept, for the reply message. */
reply?: { callId: string; questions: AsyncQuestion[] };
}
interface Held {
sessionId: string;
threadId: string;
d: Delivery;
/** `queued` has been reported for it. */
queued: boolean;
}
export interface Store {
acted: string[];
save(): void;
}
export class Responder {
private readonly asks = new Map<string, OpenAsk>();
private readonly natives = new Map<string, Native>();
/** What a waiting thread waits on, for the session's wait note (`Shell(…)`, `Edit(…)`, or SECRET_NOTE). */
readonly notes = new Map<string, string>();
private outbox: { sessionId: string; path: string; body: Record<string, unknown> }[] = [];
private held: Held[] = [];
private readonly joining = new Set<string>();
/** Threads with a message or /compact being delivered now. */
private readonly acting = new Set<string>();
/** Threads left while still waiting, on something this dashboard cannot answer: not rejoined until their status changes. */
private readonly unanswerable = new Set<string>();
/** Async question calls this dashboard has answered: their asks are not announced again. */
private readonly answeredCalls = new Set<string>();
constructor(
private readonly fleet: Fleet,
private readonly daemon: Daemon,
private readonly level: RespondLevel,
private readonly activityFeed: boolean,
private readonly serverUrl: string,
private readonly token: string,
private readonly transportOf: (sessionId: string) => Transport | undefined,
private readonly store: Store,
/** Reads the hook lines already in the spool (main.ts readHooks), so a file approval sees paths recorded just before it. */
private readonly readSpool: () => void,
/** This machine's id; null while it cannot be read (main.ts readThisMachine). */
private readonly machineId: () => string | null,
) {}
// ---- what the session takes ------------------------------------------------------------------------
/**
* Report.session.respond: a daemon-hosted thread takes the level's kinds (acceptsFor); any other is
* `observe-only` — a desktop-app local thread, an excluded CLI run, `codex exec`, or a machine without a daemon. Its
* originator may add one more (ORIGINATOR_LIMIT): `desktop-app`, answered in the Codex app, or `not-interactive`, a
* headless run, counted as background like `claude -p`. A desktop-app thread in the daemon (a remote project) is answerable
* like any other.
*/
respondInfo(s: Session): RespondInfo {
const root = this.fleet.thread(s.id);
const hosted = this.daemon.connected && this.fleet.isDaemonHosted(root);
const own = root.originator === null ? undefined : ORIGINATOR_LIMIT.get(root.originator);
const limits: RespondLimit[] = hosted ? [] : own ? ['observe-only', own] : ['observe-only'];
return { level: this.level, accepts: acceptsFor(this.level, limits, this.activityFeed), limits };
}
private responding(sessionId: string, kind: RespondKind): boolean {
const s = this.fleet.sessions.get(sessionId);
return !!s && !!this.transportOf(sessionId)?.respond && !this.fleet.thread(sessionId).ended && this.respondInfo(s).accepts.includes(kind);
}
/** The asks open now for a session, sent with its report while the server takes answers. */
asksFor(sessionId: string): Ask[] {
return [...this.asks.values()].filter((a) => !a.done && a.listening && a.sessionId === sessionId).map((a) => a.ask);
}
// ---- rejoining to act -------------------------------------------------------------------------------
/**
* Rejoins a daemon-hosted thread that waits on an approval or a question the dashboard can answer now: the last reply said
* `respond: true`, the level covers the kind (questions for user input, everything for approvals), and the thread is known
* not to be ephemeral. The pending request is replayed on rejoin. Called only on three triggers — a status
* change (main.ts), a thread first seen, a reply that turns responding on — and never for a thread whose request was already
* seen to be unanswerable, until its status changes. A failed rejoin ("no rollout found") is tried again on the next status
* change; meanwhile the ask is answer-in-terminal.
*/
async considerRejoin(threadId: string): Promise<void> {
const t = this.fleet.threads.get(threadId);
if (!t || !t.loaded || !this.daemon.connected || this.daemon.subscribed.has(threadId) || this.joining.has(threadId) || this.unanswerable.has(threadId)) return;
const waiting = this.fleet.waitingOn(t);
if (!waiting || !this.responding(t.sessionId, waiting === 'approval' ? 'permission' : 'question')) return;
this.joining.add(threadId);
try {
if (!(await this.resumable(t))) return;
await this.daemon.rejoin(threadId);
setTimeout(() => void this.maybeLeave(threadId), LEAVE_EMPTY_MS);
} catch {
// tried again on the next status change
} finally {
this.joining.delete(threadId);
}
}
/** A `thread/status/changed` broadcast for the thread: a request seen unanswerable on it no longer holds a rejoin back. */
statusBroadcast(threadId: string): void {
this.unanswerable.delete(threadId);
}
/**
* Whether a thread may be rejoined: connected, loaded in the daemon, and known not to be ephemeral. Unknown is read
* first with the read-only `thread/read`; anything but `ephemeral: false` afterwards is no.
*/
private async resumable(t: Thread): Promise<boolean> {
if (!this.daemon.connected || !t.loaded) return false;
if (t.ephemeral === null) await this.daemon.readThread(t.id).catch(() => null);
return this.daemon.connected && t.loaded && t.ephemeral === false;
}
/**
* Leaves a rejoined thread once nothing of ours is open on it. A thread left while it still waits waits on something the
* dashboard cannot answer (a secret question, a request not mapped, one the level does not cover), so it is marked and not
* rejoined for that again until its status changes. (One left just as its request resolved, before the status broadcast
* that says so, is marked for that moment only: the broadcast clears it.)
*/
private async maybeLeave(threadId: string): Promise<void> {
if (!this.daemon.subscribed.has(threadId) || this.acting.has(threadId) || this.joining.has(threadId)) return;
if ([...this.natives.values()].some((n) => n.threadId === threadId)) return;
const t = this.fleet.threads.get(threadId);
if (t && this.fleet.waitingOn(t)) this.unanswerable.add(threadId);
await this.daemon.unsubscribe(threadId);
}
// ---- requests ---------------------------------------------------------------------------------------
/** A mapped request from a rejoined thread (live, or replayed on rejoin). Never answered here: only an answer from the dashboard is. */
async request(rpcId: RequestId, method: ServerRequestMethod, params: Record<string, unknown>, now = Date.now()): Promise<void> {
const threadId = typeof params.threadId === 'string' ? params.threadId : null;
const itemId = typeof params.itemId === 'string' ? params.itemId : null;
if (!threadId || !itemId) return;
const t = this.fleet.thread(threadId);
const approvalId = typeof params.approvalId === 'string' && params.approvalId ? params.approvalId : null;
const askId = approvalId ? `${itemId}:${approvalId}` : itemId;
const native: Native = { rpcId, method, threadId, askId: null, blocking: method !== 'item/tool/requestUserInput' || params.isBlocking !== false };
this.natives.set(String(rpcId), native);
const agentId = this.fleet.isChild(t) ? t.id : null;
const openedAt = typeof params.startedAtMs === 'number' ? params.startedAtMs : now;
let built: { ask: Ask; kind: RespondKind; note: string; questions?: ToolRequestUserInputQuestion[]; permissions?: RequestPermissionProfile } | null = null;
if (method === 'item/commandExecution/requestApproval') built = this.commandAsk(askId, agentId, openedAt, params as unknown as CommandExecutionRequestApprovalParams);
else if (method === 'item/fileChange/requestApproval') built = await this.fileAsk(rpcId, askId, agentId, openedAt, params as unknown as FileChangeRequestApprovalParams);
else if (method === 'item/permissions/requestApproval') built = this.permissionsAsk(askId, agentId, openedAt, params as unknown as PermissionsRequestApprovalParams);
else if (method === 'item/tool/requestUserInput') {
const q = params as unknown as ToolRequestUserInputParams;
// A secret question is not answerable here and never announced.
if (Array.isArray(q.questions) && q.questions.some((x) => x?.isSecret)) this.notes.set(threadId, SECRET_NOTE);
else built = this.questionAsk(askId, agentId, openedAt, q);
}
if (!this.natives.has(String(rpcId))) return; // resolved while the file paths were read
if (built) this.notes.set(threadId, built.note);
this.fleet.session(t.sessionId).dirty = true;
if (!built || !this.responding(t.sessionId, built.kind)) {
// Not answerable from the dashboard now: left to the terminal, and nothing of ours holds the thread.
this.natives.delete(String(rpcId));
return void this.maybeLeave(threadId);
}
native.askId = askId;
const was = this.asks.get(askId);
const a: OpenAsk = was && !was.done ? { ...was, native, listening: true } : { ask: built.ask, kind: built.kind, sessionId: t.sessionId, threadId, native, done: false, announced: false, listening: true, questions: built.questions, permissions: built.permissions };
this.asks.set(askId, a);
await this.announce(a);
void this.waitForAnswer(a);
}
/** A status change: a thread that no longer waits has no wait note. */
statusChanged(threadId: string): void {
const t = this.fleet.threads.get(threadId);
if (t && !this.fleet.waitingOn(t)) this.notes.delete(threadId);
}
/** The session ended: the server closes its asks itself; the waits here just stop. */
sessionEnded(sessionId: string): void {
for (const a of [...this.asks.values()]) if (a.sessionId === sessionId) this.finish(a);
}
private commandAsk(id: string, agentId: string | null, openedAt: number, p: CommandExecutionRequestApprovalParams) {
const command = typeof p.command === 'string' ? p.command : '';
const input: Record<string, unknown> = { command };
if (p.cwd) input.cwd = p.cwd;
if (p.reason) input.reason = p.reason;
if (p.kind === 'writeStdin') input.stdin = true;
if (p.networkApprovalContext) input.network = `${p.networkApprovalContext.protocol}://${p.networkApprovalContext.host}`;
if (p.additionalPermissions != null) input.additionalPermissions = p.additionalPermissions;
const shown = toolInput(input);
// Codex may list the decisions this prompt can take; when it does without `accept`, Allow once is not one of them.
const decisions = p.availableDecisions;
const acceptOffered = decisions == null || (Array.isArray(decisions) && decisions.includes('accept'));
// Allow once (`accept`, "User approved the command") approves this one command; it never applies a proposed exec- or
// network-policy amendment, which only `acceptWithExecpolicyAmendment` / `applyNetworkPolicyAmendment` do and this reporter
// never sends, so a proposal alone does not make the ask Deny-only. Deny only: a cut or empty command, a stdin
// write, a network-access prompt, an extra filesystem or network grant, or a prompt that does not offer `accept`.
const denyOnly =
shown.cut ||
!command.trim() ||
p.kind !== 'command' ||
!!p.networkApprovalContext ||
p.additionalPermissions != null ||
!acceptOffered;
const ask: Ask = { id, kind: 'permission', agentId, openedAt, allowsReply: false, tool: { name: 'Shell', input: shown.input, cut: denyOnly, denyReason: false } };
// The wait note is display text taken from the command: the broader rules too (the ask's input keeps the narrow ones).
return { ask, kind: 'permission' as const, note: `Shell(${clipFreeText(command.replace(/\s+/g, ' ').trim(), 153)})` };
}
/**
* A file approval's changes come from our PreToolUse hook for the same call — its `tool_use_id` equals the request's
* `itemId` (observed on Codex 0.164.0) — because Codex's `thread/items/read` reads only completed items, and a
* pending approval's item has not completed. The spool is read now and then every 100 ms for up to HOOK_WAIT_MS until
* the paths appear or the request resolves; with no wait while `hooks/list` reports our hooks untrusted. The ask shows each
* change's operation and path (`changes`: add, delete, update, or a move with its destination), as Codex's own approval names
* them (codex-hook.mjs patchPaths), and the patch itself (`patch`, from the same hook line), which lives only in the open ask,
* as a Claude Write or Edit's content does. Allow once is offered only when the owner sees all of what `accept` applies
* (the cut rule): Deny only when no change is recorded, when the recorded list leaves any path or change out (the hook
* keeps at most 50 and drops an unusable one, and marks the list cut — Codex's `accept` applies the whole patch), when
* the patch is missing or not shown whole (redacted, longer than the limit, or past toolInput's bound — then the changes are
* shown without it), when the shown input was cut, or with a grantRoot (writes under it for the rest of the session, which
* the dashboard never grants).
*/
private async fileAsk(rpcId: RequestId, id: string, agentId: string | null, openedAt: number, p: FileChangeRequestApprovalParams) {
const recorded = () => {
this.readSpool();
return this.fleet.threads.get(p.threadId)?.patchPaths.get(p.itemId) ?? { paths: [], changes: [], cut: false, patch: undefined, patchCut: false };
};
let found = recorded();
const waiting = () => found.paths.length === 0 && this.fleet.hooksTrusted !== false && this.natives.has(String(rpcId));
for (let waited = 0; waited < HOOK_WAIT_MS && waiting(); waited += 100) {
await sleep(100);
found = recorded();
}
const { paths, changes, patch } = found;
const extra: Record<string, unknown> = {};
if (p.reason) extra.reason = p.reason;
if (p.grantRoot) extra.grantRoot = p.grantRoot;
const withPatch = patch === undefined ? null : toolInput({ changes, patch, ...extra });
// Past toolInput's bound the whole input becomes a note: the changes are then shown without the patch. A line from the
// hook before `changes` existed names only paths: those are shown, and the ask is Deny-only (no changes).
const shown = withPatch && 'patch' in withPatch.input ? withPatch : toolInput(changes.length || !paths.length ? { changes, ...extra } : { paths, ...extra });
const denyOnly =
shown.cut || !('patch' in shown.input) || found.patchCut || changes.length === 0 || found.cut || (p.grantRoot !== null && p.grantRoot !== undefined);
const ask: Ask = { id, kind: 'permission', agentId, openedAt, allowsReply: false, tool: { name: 'Edit', input: shown.input, cut: denyOnly, denyReason: false } };
const first = paths[0] ?? '';
return { ask, kind: 'permission' as const, note: clip(`Edit(${first}${paths.length > 1 ? ` +${paths.length - 1}` : ''})`, 160) };
}
private permissionsAsk(id: string, agentId: string | null, openedAt: number, p: PermissionsRequestApprovalParams) {
const input: Record<string, unknown> = { permissions: p.permissions ?? {} };
if (p.cwd) input.cwd = p.cwd;
if (p.reason) input.reason = p.reason;
const shown = toolInput(input);
const ask: Ask = { id, kind: 'permission', agentId, openedAt, allowsReply: false, tool: { name: 'Permissions', input: shown.input, cut: shown.cut || !p.permissions, denyReason: false } };
// The wait note is display text: the reason gets the broader rules too, as the mod's note for any tool but a path does.
return { ask, kind: 'permission' as const, note: `Permissions(${clipFreeText((p.reason ?? '').replace(/\s+/g, ' ').trim(), 147)})`, permissions: p.permissions };
}
/** 1–4 questions, one answer each; options as given; a typed answer only with `isOther` or no options. */
private questionAsk(id: string, agentId: string | null, openedAt: number, p: ToolRequestUserInputParams) {
const qs = Array.isArray(p.questions) ? p.questions : [];
if (qs.length < 1 || qs.length > L.questions) return null;
const questions: AskQuestion[] = [];
for (const q of qs) {
const options = Array.isArray(q?.options) ? q.options : [];
if (typeof q?.question !== 'string' || options.length > L.options) return null;
questions.push({
question: block(q.question, L.question),
header: oneLine(q.header, L.header),
multiSelect: false,
options: options.map((o) => ({ label: oneLine(o?.label, L.label), description: block(o?.description ?? '', L.description), preview: null })),
allowsText: q.isOther === true || options.length === 0,
});
}
const ask: Ask = { id, kind: 'question', agentId, openedAt, allowsReply: false, questions };
// The note is built from the question as Codex asked it, so the broader rules see it whole before their own cut.
return { ask, kind: 'question' as const, note: clipFreeText(String(qs[0]!.header || qs[0]!.question).replace(/\s+/g, ' ').trim(), 160), questions: qs };
}
/** The request resolved: by our answer, or by another client first (the terminal), or on its own (a non-blocking question). */
resolved(threadId: string, requestId: RequestId): void {
const native = this.natives.get(String(requestId));
if (!native || native.threadId !== threadId) return;
this.natives.delete(String(requestId));
if (![...this.natives.values()].some((n) => n.threadId === threadId)) this.notes.delete(threadId);
const a = native.askId ? this.asks.get(native.askId) : undefined;
if (a && !a.done && a.native === native) {
this.finish(a);
if (a.announced) this.queueClose(a, native.blocking ? 'terminal' : 'closed');
}
this.fleet.session(this.fleet.thread(threadId).sessionId).dirty = true;
void this.maybeLeave(threadId);
}
/** The daemon connection ended: no request can be answered by this client any more, and nothing seen on it still holds. */
disconnected(): void {
this.natives.clear();
this.notes.clear();
this.unanswerable.clear();
for (const a of this.asks.values()) if (!a.done) this.finish(a);
for (const h of this.held.splice(0)) this.queueResult(h.sessionId, h.d.id, 'not-taken');
}
private finish(a: OpenAsk): void {
a.done = true;
this.asks.delete(a.ask.id);
const s = this.fleet.sessions.get(a.sessionId);
if (s) s.dirty = true;
}
// ---- the server side (the respond routes) --------------------------------------------------------------
/**
* One call on `path` under the route of the session `sessionId` names, which takes its id there: that id at this machine's
* (sessionKey). Null when it could not be made: offline, or this machine's id not yet read, so asks, closes and results wait
* as the reports do.
*/
private call(method: string, sessionId: string, path: string, body: unknown, timeoutMs: number): Promise<HttpResult | null> {
const machine = this.machineId();
if (machine === null) return Promise.resolve(null);
return serverCall(this.serverUrl, this.token, method, `/api/fleet/sessions/${encodeURIComponent(sessionKey(sessionId, machine))}${path}`, body, timeoutMs);
}
private async announce(a: OpenAsk): Promise<number> {
const res = await this.call('PUT', a.sessionId, askPath(a), a.ask, 15_000);
if (res?.status === 200) a.announced = true;
return res?.status ?? 0;
}
private queueOut(item: { sessionId: string; path: string; body: Record<string, unknown> }): void {
this.outbox = [...this.outbox, item].slice(-OUTBOX_MAX);
}
private queueResult(sessionId: string, deliveryId: string, result: DeliveryResult): void {
this.queueOut({ sessionId, path: `/deliveries/${encodeURIComponent(deliveryId)}/result`, body: { result, at: Date.now() } });
}
private queueClose(a: OpenAsk, outcome: 'terminal' | 'closed' | 'ended'): void {
this.queueOut({ sessionId: a.sessionId, path: `${askPath(a)}/close`, body: { outcome, at: Date.now() } });
}
/** Sends the queued closes and results, oldest first. A call that could not be made keeps the rest; any answer drops the item. */
async flushOutbox(): Promise<void> {
while (this.outbox.length) {
const item = this.outbox[0]!;
const res = await this.call('POST', item.sessionId, item.path, item.body, 15_000);
if (!res) return;
this.outbox.shift();
}
}
/** Notes a delivery as acted on, kept across restarts, so one handed over twice acts once. */
private markActed(id: string): boolean {
const acted = this.store.acted;
if (acted.includes(id)) return false;
acted.push(id);
while (acted.length > ACTED_KEPT) acted.shift();
this.store.save();
return true;
}
/** What the held answer request handed over: the delivery a 200 answer carries; null for any other answer or body. */
private deliveryOf(res: HttpResult | null): Delivery | null {
if (res?.status !== 200) return null;
let body: unknown;
try {
body = JSON.parse(res.text);
} catch {
return null;
}
const d = (body as { delivery?: unknown } | null)?.delivery;
return isDelivery(d) ? d : null;
}
/**
* An answer this ask takes, while the dashboard may still answer it: one that arrives after responding stopped (the last
* reply turned it off, the session ended, its root is no longer daemon-hosted) is refused, never sent: `responding` is
* checked again here for the question and permission races, as the Claude reporter's `wanted` predicates check it.
*/
private wanted(a: OpenAsk, d: Delivery): boolean {
const fits = a.kind === 'question' ? d.kind === 'question' : d.kind === 'deny' || (d.kind === 'allow-once' && !a.ask.tool?.cut);
return fits && this.responding(a.sessionId, a.kind);
}
/**
* The held-answer loop (the Claude reporter's pollAnswer) while the ask is open and the server takes answers — and, for a daemon
* request's ask, while its thread is joined (an async question ask has no request to join for).
*/
private async waitForAnswer(a: OpenAsk): Promise<void> {
while (!a.done && this.responding(a.sessionId, a.kind) && (a.native === null || this.daemon.subscribed.has(a.threadId))) {
const res = await this.call('GET', a.sessionId, `${askPath(a)}/answer?wait=${L.holdSeconds}`, undefined, (L.holdSeconds + 10) * 1000);
if (a.done) {
const d = this.deliveryOf(res);
if (d && this.markActed(d.id)) this.queueResult(a.sessionId, d.id, 'closed');
return;
}
if (!res) {
await sleep(retryDelay(1));
continue;
}
if (res.status === 204) continue;
if (res.status === 404) {
if ((await this.announce(a)) !== 200) await sleep(retryDelay(2));
continue;
}
const d = this.deliveryOf(res);
if (!d) break;
if (!this.markActed(d.id)) {
await sleep(1000);
continue;
}
if (d.askId === a.ask.id && this.wanted(a, d) && this.act(a, d)) return;
this.queueResult(a.sessionId, d.id, 'refused');
}
if (!a.done) {
a.listening = false;
const s = this.fleet.sessions.get(a.sessionId);
if (s) s.dirty = true;
}
}
/** The native response for an answer from the dashboard; null when it cannot be expressed. */
private nativeAnswer(a: OpenAsk, d: Delivery): unknown {
const method = a.native?.method;
if (method === 'item/tool/requestUserInput') {
const answers: Record<string, { answers: string[] }> = {};
(a.questions ?? []).forEach((q, i) => {
const ans = d.answers?.[i];
if (!ans || typeof q?.id !== 'string') return;
if ('text' in ans) {
const text = typeof ans.text === 'string' ? ans.text : '';
if (text.trim() && (q.isOther || !q.options?.length)) answers[q.id] = { answers: [text] };
} else if (Array.isArray(ans.options) && ans.options.length) {
const label = q.options?.[ans.options[0]!]?.label;
if (typeof label === 'string') answers[q.id] = { answers: [label] };
}
});
return { answers };
}
const allow = d.kind === 'allow-once';
if (method === 'item/permissions/requestApproval') {
const p = a.permissions;
const granted = allow && p ? { ...(p.network ? { network: p.network } : {}), ...(p.fileSystem ? { fileSystem: p.fileSystem } : {}) } : {};
return { permissions: granted, scope: 'turn' };
}
return { decision: allow ? 'accept' : 'decline' };
}
/**
* Sends the dashboard's answer once: as the reply to the daemon request it answers, or for an async question ask as the reply
* message, through the message path (the delivery's results are the answer's). False when it took nothing: an async
* answer to questions all already answered in the session file, which waitForAnswer refuses and keeps waiting past, as it
* does an answer the ask cannot take.
*/
private act(a: OpenAsk, d: Delivery): boolean {
if (a.reply && !a.done) {
const text = asyncReplyText(a.reply, d, this.fleet.threads.get(a.threadId)?.asyncQuestions.get(a.reply.callId)?.replied ?? new Set());
if (text === null) return false;
this.finish(a);
this.answeredCalls.add(a.reply.callId);
if (this.answeredCalls.size > ACTED_KEPT) this.answeredCalls.delete(this.answeredCalls.values().next().value as string);
void this.steer(a.sessionId, { ...d, kind: 'message', text });
return true;
}
if (a.done || !a.native || !this.natives.has(String(a.native.rpcId))) {
this.queueResult(a.sessionId, d.id, 'closed');
return true;
}
const sent = this.daemon.answer(a.native.rpcId, this.nativeAnswer(a, d));
this.finish(a);
this.queueResult(a.sessionId, d.id, sent ? 'took' : 'not-taken');
return true;
}
// ---- Codex async questions ----------------------------------------------------------------------------------
/**
* Codex asks async questions with `request_user_input_async`: an agent message, read from the session file, and no daemon
* request. Each one a root thread still has open is announced as a question ask while the session takes questions, once its
* session file has been read to the end; the ask closes when the file shows replies naming all its questions or the call,
* from any client (`terminal`), when its turn ended (`closed`; Codex's TUI drops pending questions then), or when Codex
* refused the call (`closed`). An answer this dashboard already took is delivered all the same. Called every tick, after the
* session files are read.
*/
asyncQuestions(): void {
for (const t of this.fleet.threads.values()) {
// Codex offers the tool to root threads only (core/tests/suite/request_user_input_async.rs, the "subagent" cases).
if (this.fleet.isChild(t)) continue;
for (const [callId, q] of t.asyncQuestions) {
const a = this.asks.get(callId);
if (q.state !== 'open') {
if (a?.reply && !a.done) {
this.finish(a);
if (a.announced) this.queueClose(a, q.state === 'replied' ? 'terminal' : 'closed');
}
continue;
}
if (!this.responding(t.sessionId, 'question')) continue;
if (a?.reply && !a.done && !a.listening) {
a.listening = true;
void this.waitForAnswer(a);
continue;
}
// Only once the session file has been read to its end: a file re-read from its start (a restart, a first attach) must
// not revive a question its later lines answered or ended.
if (a || this.answeredCalls.has(callId) || !t.rollout?.tail?.caughtUp()) continue;
const ask = asyncQuestionAsk(callId, q.at, q.questions);
if (!ask) continue; // over the limits: answered in its terminal, as questionAsk leaves them
const open: OpenAsk = { ask, kind: 'question', sessionId: t.sessionId, threadId: t.id, native: null, done: false, announced: false, listening: true, reply: { callId, questions: q.questions } };
this.asks.set(callId, open);
this.fleet.session(t.sessionId).dirty = true;
void this.announce(open).then(() => this.waitForAnswer(open));
}
}
}
/**
* An async question's answer goes into the running turn, as Codex's TUI sends it (`tui/src/app/user_turn_submission.rs:30-90`,
* `tui/src/app_server_session.rs:1543-1565`): with the thread joined like a message, `turn/steer` naming the turn the session
* file shows running. When Codex answers that another turn is active, the steer is tried once more naming that turn
* (user_turn_submission.rs:66-79). With no turn known, or when Codex answers that the turn is not steerable, that no turn is
* active, or (after that retry) that another turn still is (`tui/src/app.rs:768-807`), it goes the message way instead — idle:
* `turn/start`; else held until idle — as the TUI falls back to its queue or a new turn. A steer taken is `took`.
*/
private async steer(sessionId: string, d: Delivery): Promise<void> {
const root = this.fleet.thread(sessionId);
const turnId = root.turnId;
if (turnId === null || this.acting.has(root.id)) return this.deliver(sessionId, d);
let fallBack = false;
this.acting.add(root.id);
try {
if (!(await this.resumable(root))) return this.queueResult(sessionId, d.id, 'not-taken');
if (!this.daemon.subscribed.has(root.id)) await this.daemon.rejoin(root.id);
try {
await this.daemon.steerTurn(root.id, turnId, d.text ?? '');
} catch (err) {
const actual = activeTurnOf(err);
if (actual === null || actual === turnId) throw err;
await this.daemon.steerTurn(root.id, actual, d.text ?? '');
}
this.queueResult(sessionId, d.id, 'took');
} catch (err) {
if (steerFallsBack(err)) fallBack = true;
else this.queueResult(sessionId, d.id, 'not-taken');
} finally {
this.acting.delete(root.id);
void this.maybeLeave(root.id);
}
if (fallBack) await this.deliver(sessionId, d);
}
// ---- messages and commands (report-reply deliveries) ----------------------------------------------------
/** Messages and commands from one reply: each acted on once, within the session's own level. */
handleDeliveries(sessionId: string, list: Delivery[]): void {
for (const d of list) {
if (!this.markActed(d.id)) continue;
if (d.kind === 'message' && typeof d.text === 'string' && d.text.trim() && this.responding(sessionId, 'message')) void this.deliver(sessionId, d);
else if (d.kind === 'command' && d.command === 'compact' && this.responding(sessionId, 'command')) void this.deliver(sessionId, d);
else this.queueResult(sessionId, d.id, 'refused'); // includes /clear: Codex has no equivalent
}
}
/**
* Idle: rejoin and act now. Running: `queued`, held until idle. Not loaded in the daemon, or not known to be non-ephemeral
* once read: `not-taken`.
*/
private async deliver(sessionId: string, d: Delivery): Promise<void> {
const root = this.fleet.thread(sessionId);
if (!(await this.resumable(root))) return this.queueResult(sessionId, d.id, 'not-taken');
if (root.status?.type === 'idle' && !this.acting.has(root.id) && !this.held.some((h) => h.threadId === root.id)) void this.run({ sessionId, threadId: root.id, d, queued: false });
else {
this.held.push({ sessionId, threadId: root.id, d, queued: true });
this.queueResult(sessionId, d.id, 'queued');
}
}
/** Called on every status change and tick: a held message or command goes once its thread is idle. */
pump(): void {
for (const h of [...this.held]) {
const t = this.fleet.threads.get(h.threadId);
if (!t || !t.loaded || !this.daemon.connected) {
this.held.splice(this.held.indexOf(h), 1);
this.queueResult(h.sessionId, h.d.id, 'not-taken');
continue;
}
if (t.status?.type !== 'idle' || this.acting.has(h.threadId)) continue;
if (this.held.find((x) => x.threadId === h.threadId) !== h) continue; // one at a time, oldest first
this.held.splice(this.held.indexOf(h), 1);
void this.run(h);
}
}
private async run(h: Held): Promise<void> {
this.acting.add(h.threadId);
try {
const t = this.fleet.threads.get(h.threadId);
if (!t || !(await this.resumable(t))) return this.queueResult(h.sessionId, h.d.id, 'not-taken');
// The status right before `turn/start` or `thread/compact/start`: the one the broadcasts keep while we are joined, else the
// rejoin's own answer. A turn started meanwhile (from the terminal, or since the idle check) holds this again rather than
// steering a running turn.
const status = this.daemon.subscribed.has(h.threadId) ? t.status : ((await this.daemon.rejoin(h.threadId))?.status ?? null);
if (status?.type !== 'idle') {
if (!h.queued) this.queueResult(h.sessionId, h.d.id, 'queued');
this.held.unshift({ ...h, queued: true });
return;
}
if (h.d.kind === 'message') await this.daemon.startTurn(h.threadId, h.d.text ?? '');
else await this.daemon.compact(h.threadId);
this.queueResult(h.sessionId, h.d.id, 'took');
} catch {
this.queueResult(h.sessionId, h.d.id, 'not-taken');
} finally {
this.acting.delete(h.threadId);
void this.maybeLeave(h.threadId);
}
}
}