One live console to monitor Claude Code and Codex agents across machines, track context and spend, and unblock sessions that need you.
// Responding to a waiting session from the dashboard. Held in memory only: the open asks with their content, a closed ask's
// outcome for a while, and the answers and messages sent from the browser until the reporter says what became of them. Nothing
// here is written to the database, and a restart loses it all; reporters re-send their open asks with every report, so they come
// back by themselves.
import { randomBytes } from 'node:crypto';
import { MAIN_LOOP, PLAN_MODES, RESPOND_LIMITS } from './protocol.js';
import type { ActivityStore } from './activity.js';
import type { Ask, AskClose, AskClosure, AskDetail, AskOutcome, AskQuestion, AskState, AskSummary, DashboardCommand, Delivery, DeliveryKind, DeliveryResult, PlanMode, QuestionAnswer, Report, RespondInfo, RespondKind } from './protocol.js';
/** A closed ask stays readable this long, or until the session's next ask opens. */
export const CLOSED_KEEP_MS = 10 * 60_000;
/** A report that no longer lists an open ask closes it only if the ask opened at least this long before the report was made. */
const UNLISTED_GRACE_MS = 5000;
/** Held answer requests kept per ask and in all; past either, the oldest is answered "none" to make room. */
const HOLDS_PER_ASK = 4;
const HOLDS_TOTAL = 200;
/** What a held request is answered with when nothing came for it. */
const NOTHING: HoldResult = { kind: 'none' };
/** Where a dashboard answer, message or command shows: its loop's live activity feed (the fleet hands over its ActivityStore). */
export type DashboardFeed = Pick<ActivityStore, 'addDashboard' | 'updateDashboard' | 'removeDashboard'>;
/** An answer, message or command the server holds until the reporter says what became of it. */
interface Held {
delivery: Delivery;
result: DeliveryResult | null;
/** The reporter has been given it, so it can no longer be discarded. */
handedOver: boolean;
}
/** How an ask closed, as the panel shows it, and `implicit`: inferred from a report that stopped listing the ask, which the reporter's own close may still replace. */
type Closure = AskClosure & { implicit: boolean };
/** A closure as the panel gets it: `implicit` is the store's own business. */
const shownClosure = ({ outcome, at, by, answer, planApproved }: Closure): AskClosure => ({ outcome, at, by, answer, planApproved });
interface TrackedAsk {
ask: Ask;
answer: Held | null;
closure: Closure | null;
/** A report made after the ask closed showed the session running: the turn it closed in is under way. */
ranAfterClose?: boolean;
}
interface SessionState {
/** Report.session.respond as last reported. */
info: RespondInfo | null;
asks: Map<string, TrackedAsk>;
/** Messages and commands, oldest first. */
messages: Held[];
}
/** A reporter's held answer request, parked until something answers it. */
interface HeldRequest {
sessionId: string;
askId: string;
resolve: (r: HoldResult) => void;
timer: ReturnType<typeof setTimeout>;
}
/** Why the server let go of a delivery that has no result. */
export type DropWhy = 'discarded' | 'ask-closed' | 'session-ended' | 'queued-session-ended' | 'session-deleted' | 'answering-off';
/** What became of a delivery after the server took it, for the server log: never its text. */
export type DeliveryTrail = { sessionId: string; delivery: Delivery } & ({ kind: 'result'; result: DeliveryResult } | { kind: 'dropped'; why: DropWhy });
/** What a held answer request comes back with: the answer, nothing in time, an ask the server does not know, or how it closed. */
export type HoldResult = { kind: 'delivery'; delivery: Delivery } | { kind: 'none' | 'unknown' } | { kind: 'closed'; outcome: AskOutcome };
/** Hears that a session's asks changed. */
type SessionChanged = (sessionId: string) => void;
/** An answer or message from the browser: taken, as this delivery, or turned away with the reason. */
export type Taken = { ok: true; delivery: Delivery } | { ok: false; err: AnswerError };
/** What announcing an ask did: stored it, found it closed, or found as many asks open as a session may have. */
export type AnnounceOutcome = 'ok' | 'closed' | 'full';
/** What a delivery's result did: recorded a new one, matched the one recorded, or named a delivery the server does not hold. */
export type ResultOutcome = 'new' | 'repeat' | 'unknown';
/** Why an answer or message from the browser was not taken; the routes send all but `status` as the body. */
export type AnswerError =
/** No such ask. */
| { status: 404; error: 'unknown ask' }
/** The ask closed before the answer came. */
| { status: 410; error: 'this ask has closed'; outcome: AskOutcome; at: number }
/** The ask has an answer already, from `by` at `at`. */
| { status: 409; error: 'this ask has its answer already'; by: string; at: number }
/** The session does not take this kind of answer now. */
| { status: 422; error: 'the session does not take this kind now'; kind: string }
/** The body does not fit the ask or the limits. */
| { status: 400; error: string; path: string }
/** As many messages as a session may have waiting already wait. */
| { status: 429; error: string };
// ---- what the feed and the log say ----------------------------------------------------------------
/** How the feed words each plan approval mode. */
const PLAN_MODE_WORDS: Record<PlanMode, string> = { auto: 'and use auto mode', acceptEdits: 'auto-accept edits', default: 'manually approve edits' };
/** How the feed names the call a permission ask is about: a shell command (Claude Bash, Codex Shell) on one line, else the tool. */
function callName(ask: Ask): string {
const tool = ask.tool;
if (tool === undefined) return 'the tool';
const command = tool.input.command;
const isShell = tool.name === 'Bash' || tool.name === 'Shell';
return isShell && typeof command === 'string' ? command.replace(/\s+/g, ' ').trim().slice(0, 120) : tool.name;
}
const RECOMMENDED = '(recommended)';
/**
* A label with Claude Code's trailing "(Recommended)" taken off, in any case, along with the spaces before it. Compared by hand,
* since a regex would take quadratic time on a long run of spaces.
*/
const stripRecommended = (label: string): string => {
const end = label.trimEnd();
const marked = end.length >= RECOMMENDED.length && end.slice(-RECOMMENDED.length).toLowerCase() === RECOMMENDED;
return marked ? end.slice(0, -RECOMMENDED.length).trimEnd() : label;
};
/** How the feed and a close word a question answer: per answered question its options (", ") or typed text, joined with "; ". */
export const questionSummary = (ask: Ask, answers: readonly QuestionAnswer[]): string =>
(ask.questions ?? [])
.map((question, i) => {
const answer = answers[i];
if (!answer) return '';
return 'text' in answer ? answer.text.trim() : answer.options.map((n) => stripRecommended(question.options[n]?.label ?? '')).join(', ');
})
.filter((part) => part !== '')
.join('; ');
/** What a delivery says, trimmed; '' when it carries no text. */
const spoken = (d: Delivery): string => d.text?.trim() ?? '';
/** The feed's line for each kind of delivery ("answered: …", "approved the plan (…)", "allowed once: …"). */
const FEED_LINES: Record<DeliveryKind, (d: Delivery, ask: Ask | null) => string> = {
question: (d, ask) => `answered: ${ask ? questionSummary(ask, d.answers ?? []) : ''}`,
'plan-approve': (d) => `approved the plan (${PLAN_MODE_WORDS[d.mode ?? 'auto']})`,
'plan-feedback': (d) => (spoken(d) ? `No, keep planning: ${spoken(d)}` : 'No, keep planning'),
'allow-once': (_d, ask) => `allowed once: ${ask ? callName(ask) : ''}`,
deny: (d, ask) => {
const reason = spoken(d);
return `denied: ${ask ? callName(ask) : ''}${reason ? `. ${reason}` : ''}`;
},
command: (d) => `/${d.command ?? ''}`,
message: (d) => spoken(d),
reply: (d) => spoken(d),
};
/** What the log says was done for each kind of delivery; never what was said. */
const LOG_WORDS: Record<DeliveryKind, (d: Delivery) => string> = {
question: () => 'Answered a question',
reply: () => 'Sent a message in place of an answer',
'plan-approve': (d) => `Approved a plan (${d.mode ?? ''})`,
'plan-feedback': () => 'Sent a plan back',
'allow-once': () => 'Allowed a tool once',
deny: () => 'Denied a tool',
command: (d) => `Ran /${d.command ?? ''}`,
message: () => 'Sent a message',
};
/** What the server log says a delivery did; never what it said. */
export const logWords = (d: Delivery): string => LOG_WORDS[d.kind](d);
/** The noun the feed uses for each kind of ask. */
const ASK_NOUN: Record<Ask['kind'], string> = { question: 'question', plan: 'plan', permission: 'request' };
/** The note on a delivery's feed line: an answer replaced by a message, a message or command queued, a /clear that took. */
function feedNote(d: Delivery, ask: Ask | null, result: DeliveryResult | null): string | null {
if (d.kind === 'reply') return ask ? `(in place of an answer; the ${ASK_NOUN[ask.kind]} closes)` : null;
const waitsForIdle = d.kind === 'message' || d.kind === 'command';
if (waitsForIdle && result === 'queued') return '(queued until the session is idle)';
if (d.kind === 'command' && d.command === 'clear' && result === 'took') return '(cleared: the conversation goes on under a new session id)';
return null;
}
/** A fresh delivery id: `dlv_` and 24 random hex digits. */
const newDeliveryId = (): string => `dlv_${randomBytes(12).toString('hex')}`;
/** The id the log shows for a delivery, enough to match its lines up: `dlv_` and its first 8 hex digits. */
export const shortDeliveryId = (d: Delivery): string => d.id.slice(0, 12);
// ---- the store ----------------------------------------------------------------------------------
export class RespondStore {
/** Told what became of each delivery, when set; the routes point it at the server log. */
trail: ((t: DeliveryTrail) => void) | null = null;
private readonly sessions = new Map<string, SessionState>();
/** The reporters' held answer requests, oldest first. */
private readonly holds = new Set<HeldRequest>();
/**
* `onChange` hears that a session's asks changed, so its card and the panel need a new SessionView; `feed` shows the dashboard's
* deliveries on their loops' activity (none for a store whose feed nobody watches).
*/
constructor(
private readonly now: () => number,
private readonly onChange: SessionChanged = () => {},
private readonly feed: DashboardFeed | null = null,
) {}
/** A session's state, made empty the first time it is needed. */
private stateFor(sessionId: string): SessionState {
const known = this.sessions.get(sessionId);
if (known !== undefined) return known;
const fresh: SessionState = { info: null, asks: new Map(), messages: [] };
this.sessions.set(sessionId, fresh);
return fresh;
}
private tracked(sessionId: string, askId: string): TrackedAsk | undefined {
return this.sessions.get(sessionId)?.asks.get(askId);
}
/** What the session last reported it takes (Report.session.respond); null until a report since the server started has said. */
takes(sessionId: string): RespondInfo | null {
const state = this.sessions.get(sessionId);
return state === undefined ? null : state.info;
}
/**
* A validated report of the session `sid` (its id on the server). Keeps what the session says it takes. When the report carries
* its asks (responding is on), any ask the server does not know (after a restart) is learnt and an open one no longer listed is
* taken as closed. A finished session closes them all.
*/
noteReport(sid: string, report: Report, takeAsks: boolean): void {
const { session } = report;
if (session.respond) this.stateFor(sid).info = session.respond;
else {
const known = this.sessions.get(sid);
if (known) known.info = null;
}
if (session.status === 'done') {
this.endSession(sid);
return;
}
const reported = session.asks;
if (!takeAsks || !reported) return;
const listed = new Set(reported.map((a) => a.id));
for (const ask of reported) this.announce(sid, ask);
this.closeUnlisted(sid, listed, report.sentAt);
this.forgetFinishedAsks(sid, report);
}
/** Takes as closed each open ask a report made at `sentAt` left out, unless it opened within UNLISTED_GRACE_MS of it. */
private closeUnlisted(sessionId: string, listed: ReadonlySet<string>, sentAt: number): void {
const state = this.sessions.get(sessionId);
if (!state) return;
for (const tracked of state.asks.values()) {
const { ask, closure } = tracked;
if (closure || listed.has(ask.id) || ask.openedAt > sentAt - UNLISTED_GRACE_MS) continue;
this.setClosed(sessionId, tracked, { outcome: 'closed', at: this.now(), by: null, answer: null, planApproved: false, implicit: true });
}
}
/**
* Forgets closed asks once their turn is over: the session was seen running after they closed, and now reports itself idle
* (`waiting`) with nothing open. An idle report without a running one in between may be the moment before the session takes
* the answer, and a report made before the ask closed says nothing about it.
*/
private forgetFinishedAsks(sessionId: string, report: Report): void {
const state = this.sessions.get(sessionId);
if (!state) return;
const { status } = report.session;
if (status === 'running') {
for (const tracked of state.asks.values()) if (tracked.closure && tracked.closure.at < report.sentAt) tracked.ranAfterClose = true;
return;
}
if (status !== 'waiting' || [...state.asks.values()].some((t) => !t.closure)) return;
const over = [...state.asks].filter(([, t]) => t.closure && t.ranAfterClose).map(([id]) => id);
for (const id of over) state.asks.delete(id);
if (over.length > 0) this.onChange(sessionId);
}
/** The reporter announces an ask (PUT), any number of times: a new body replaces the stored one while no answer is pending. */
announce(sessionId: string, ask: Ask): AnnounceOutcome {
const state = this.stateFor(sessionId);
const tracked = state.asks.get(ask.id);
if (tracked === undefined) return this.openAsk(sessionId, state, ask);
const closure = tracked.closure;
if (closure && !closure.implicit) return 'closed';
if (closure) {
// Listed again after an implicit close, so open again; an answer that close dropped is gone, and it takes a new one.
tracked.closure = null;
if (tracked.answer?.result === 'closed') tracked.answer = null;
this.onChange(sessionId);
}
if (!tracked.answer) tracked.ask = ask;
return 'ok';
}
private openAsk(sessionId: string, state: SessionState, ask: Ask): Exclude<AnnounceOutcome, 'closed'> {
if ([...state.asks.values()].filter((t) => !t.closure).length >= RESPOND_LIMITS.asks) return 'full';
// Every closed ask stops being readable once a new one opens.
for (const [id, tracked] of state.asks) if (tracked.closure) state.asks.delete(id);
state.asks.set(ask.id, { ask, answer: null, closure: null });
this.onChange(sessionId);
return 'ok';
}
/**
* The reporter's held request: the answer now, or as soon as one arrives, or nothing within `waitMs`. `signal` aborts when the
* reporter's connection closes, so an answer arriving later is not marked handed over to a request nobody reads.
*/
async hold(sessionId: string, askId: string, waitMs: number, signal?: AbortSignal): Promise<HoldResult> {
if (signal?.aborted) return NOTHING;
const tracked = this.tracked(sessionId, askId);
if (!tracked) return { kind: 'unknown' };
if (tracked.closure) return { kind: 'closed', outcome: tracked.closure.outcome };
const ready = this.handOver(sessionId, tracked);
return ready ? { kind: 'delivery', delivery: ready } : new Promise((resolve) => this.park(sessionId, askId, waitMs, resolve, signal));
}
/**
* Parks a held request until an answer comes, its wait runs out, or its reporter goes. To make room, the oldest request parked
* on the same ask is let go first once HOLDS_PER_ASK wait there, and then the oldest of all once HOLDS_TOTAL wait in all.
*/
private park(sessionId: string, askId: string, waitMs: number, resolve: (r: HoldResult) => void, signal?: AbortSignal): void {
const sameAsk = this.parkedOn(sessionId, askId);
if (sameAsk.length >= HOLDS_PER_ASK) this.release(sameAsk[0]!, NOTHING);
const oldest = this.holds.values().next();
if (this.holds.size >= HOLDS_TOTAL && !oldest.done) this.release(oldest.value, NOTHING);
const letGo = (): void => this.release(held, NOTHING);
const held: HeldRequest = { sessionId, askId, resolve, timer: setTimeout(letGo, waitMs) };
held.timer.unref?.();
this.holds.add(held);
signal?.addEventListener('abort', letGo, { once: true });
}
/** The requests parked on one ask, oldest first. */
private parkedOn(sessionId: string, askId: string): HeldRequest[] {
return Array.from(this.holds).filter((h) => h.askId === askId && h.sessionId === sessionId);
}
/** Answers a parked request once; a request already answered is left as it is. */
private release(held: HeldRequest, r: HoldResult): void {
const parked = this.holds.delete(held);
if (parked) {
clearTimeout(held.timer);
held.resolve(r);
}
}
/** Answers each request parked on one ask with what `outcome` returns, asked afresh for each. */
private wake(sessionId: string, askId: string, outcome: () => HoldResult): void {
for (const held of this.parkedOn(sessionId, askId)) this.release(held, outcome());
}
/** How many held requests are parked now. */
get holding(): number {
return this.holds.size;
}
/** The answer to hand the reporter for an ask: one taken and still without a result. The first hand-over is noted. */
private handOver(sessionId: string, tracked: TrackedAsk): Delivery | null {
const held = tracked.answer;
if (held === null || held.result !== null) return null;
if (!held.handedOver) {
held.handedOver = true;
this.onChange(sessionId);
}
return held.delivery;
}
/** The reporter says an ask closed without the dashboard's answer. An answer it was not yet handed is dropped. */
close(sessionId: string, askId: string, { outcome, at, answer, planApproved }: AskClose): void {
const tracked = this.tracked(sessionId, askId);
// Only an implicit close gives way to the reporter's own.
if (!tracked || (tracked.closure && !tracked.closure.implicit)) return;
this.setClosed(sessionId, tracked, { outcome, at, by: null, answer: answer ?? null, planApproved: planApproved === true, implicit: false });
}
/** Closes an ask: an answer not yet handed over is dropped with its feed line, and the requests parked on it learn the outcome. */
private setClosed(sessionId: string, tracked: TrackedAsk, closure: Closure): void {
tracked.closure = closure;
const held = tracked.answer;
if (held !== null && held.result === null && !held.handedOver) {
held.result = 'closed';
this.feed?.removeDashboard(sessionId, held.delivery.id);
this.trail?.({ kind: 'dropped', sessionId, delivery: held.delivery, why: 'ask-closed' });
}
this.wake(sessionId, tracked.ask.id, () => ({ kind: 'closed', outcome: closure.outcome }));
this.onChange(sessionId);
}
/** The session ended or left the live set: each open ask closes as `ended`, and the messages waiting for it go. */
endSession(sessionId: string): void {
const state = this.sessions.get(sessionId);
if (!state) return;
for (const tracked of state.asks.values()) {
if (!tracked.closure) this.setClosed(sessionId, tracked, { outcome: 'ended', at: this.now(), by: null, answer: null, planApproved: false, implicit: false });
}
// A message with no result never reached the session. One it queued may still be read, so the log says only that the
// session ended first; one with a final result already has its log line.
for (const m of state.messages) {
const why: DropWhy | null = m.result === null ? 'session-ended' : m.result === 'queued' ? 'queued-session-ended' : null;
if (why !== null) this.trail?.({ kind: 'dropped', sessionId, delivery: m.delivery, why });
}
state.messages = [];
}
/** The session is gone, or answering was turned off: everything held for it goes, and the requests parked on its asks learn it ended. */
dropSession(sessionId: string, why: DropWhy = 'session-deleted'): void {
const state = this.sessions.get(sessionId);
if (!state) return;
const answers = [...state.asks.values()].flatMap((t) => (t.answer ? [t.answer] : []));
for (const held of [...state.messages, ...answers]) {
if (held.result === null) this.trail?.({ kind: 'dropped', sessionId, delivery: held.delivery, why });
}
for (const tracked of state.asks.values()) this.wake(sessionId, tracked.ask.id, () => ({ kind: 'closed', outcome: 'ended' }));
this.sessions.delete(sessionId);
}
/**
* Answering or the activity feed it needs was turned off: every session's asks, answers, messages and commands go as if the
* session were gone, so none survives to be handed over once both are on again. A parked
* request is only ever on an open ask the store tracks, so waking each session's asks lets go of every one.
*/
clear(): void {
for (const sessionId of [...this.sessions.keys()]) {
this.dropSession(sessionId, 'answering-off');
this.onChange(sessionId);
}
}
/** Every second: an ask closed longer than CLOSED_KEEP_MS ago goes. */
expire(): void {
const now = this.now();
for (const [sid, state] of this.sessions) {
const old = [...state.asks].filter(([, t]) => t.closure !== null && now - t.closure.at > CLOSED_KEEP_MS).map(([id]) => id);
for (const id of old) state.asks.delete(id);
if (old.length > 0) this.onChange(sid);
}
}
/** A session's asks as the state and the stream carry them: no questions, plan or tool input. */
summaries(sessionId: string): AskSummary[] {
const state = this.sessions.get(sessionId);
if (!state) return [];
const out: AskSummary[] = [];
for (const tracked of state.asks.values()) {
const { id, kind, agentId, openedAt, questions } = tracked.ask;
out.push({ id, kind, agentId, openedAt, count: kind === 'question' ? (questions?.length ?? 1) : 1, state: askState(tracked) });
}
return out;
}
/** The whole ask, for the signed-in owner. */
detail(sessionId: string, askId: string, lastSeenAt: number): AskDetail | null {
const tracked = this.tracked(sessionId, askId);
if (!tracked) return null;
const { ask, answer: held, closure } = tracked;
return {
ask,
state: askState(tracked),
// Single-owner mode: every delivery is the signed-in owner's own.
delivery: held ? { ...held.delivery, result: held.result, mine: true, handedOver: held.handedOver } : null,
closed: closure && shownClosure(closure),
lastSeenAt,
};
}
/** An answer from the browser, checked against the ask and what the session last said it takes. The first answer wins. */
answer(sessionId: string, askId: string, by: string, body: unknown): Taken {
const tracked = this.tracked(sessionId, askId);
if (!tracked) return { ok: false, err: { status: 404, error: 'unknown ask' } };
const { closure, answer: earlier } = tracked;
if (closure) return { ok: false, err: { status: 410, error: 'this ask has closed', outcome: closure.outcome, at: closure.at } };
// An answer the session refused leaves the ask open to another.
if (earlier && earlier.result !== 'refused') return { ok: false, err: { status: 409, error: 'this ask has its answer already', by: earlier.delivery.by, at: earlier.delivery.at } };
const checked = parseAnswer(body, tracked.ask, this.takes(sessionId)?.accepts ?? []);
if (!checked.ok) return { ok: false, err: checked.err };
const delivery: Delivery = { id: newDeliveryId(), askId, by, at: this.now(), ...checked.fields };
tracked.answer = { delivery, result: null, handedOver: false };
const line = { at: delivery.at, text: FEED_LINES[delivery.kind](delivery, tracked.ask), by, note: feedNote(delivery, tracked.ask, null) };
this.feed?.addDashboard(sessionId, tracked.ask.agentId ?? MAIN_LOOP, delivery.id, line);
this.wake(sessionId, askId, () => ({ kind: 'delivery', delivery: this.handOver(sessionId, tracked) ?? delivery }));
this.onChange(sessionId);
return { ok: true, delivery };
}
/** A new message or command from the browser. One sent while the session runs waits until it is idle. */
message(sessionId: string, by: string, body: unknown): Taken {
const checked = parseMessage(body, this.takes(sessionId)?.accepts ?? []);
if (!checked.ok) return { ok: false, err: checked.err };
const state = this.stateFor(sessionId);
const waiting = state.messages.filter((m) => m.result === null).length;
if (waiting >= RESPOND_LIMITS.deliveries) {
return { ok: false, err: { status: 429, error: `at most ${String(RESPOND_LIMITS.deliveries)} messages can wait for one session` } };
}
const delivery: Delivery = { id: newDeliveryId(), askId: null, by, at: this.now(), ...checked.fields };
state.messages.push({ delivery, result: null, handedOver: false });
this.feed?.addDashboard(sessionId, MAIN_LOOP, delivery.id, { at: delivery.at, text: FEED_LINES[delivery.kind](delivery, null), by, note: null });
return { ok: true, delivery };
}
/** The messages and commands a report's reply carries: those still without a result, oldest first, marked handed over now. */
handOverMessages(sessionId: string): Delivery[] {
const due = (this.sessions.get(sessionId)?.messages ?? []).filter((m) => m.result === null).slice(0, RESPOND_LIMITS.deliveries);
for (const m of due) m.handedOver = true;
return due.map((m) => m.delivery);
}
/** The reporter says what became of a delivery: 'new', 'repeat' for a result already recorded, 'unknown' when it is not held. */
result(sessionId: string, deliveryId: string, result: DeliveryResult): ResultOutcome {
const state = this.sessions.get(sessionId);
if (!state) return 'unknown';
const message = state.messages.find((m) => m.delivery.id === deliveryId);
if (message) return this.messageResult(sessionId, state, message, result);
const tracked = [...state.asks.values()].find((t) => t.answer?.delivery.id === deliveryId);
if (!tracked || !tracked.answer) return 'unknown';
return this.answerResult(sessionId, tracked, tracked.answer, result);
}
private messageResult(sessionId: string, state: SessionState, message: Held, result: DeliveryResult): Exclude<ResultOutcome, 'unknown'> {
if (message.result === result) return 'repeat';
message.result = result;
const { delivery } = message;
this.trail?.({ kind: 'result', sessionId, delivery, result });
if (result === 'refused' || result === 'closed') this.feed?.removeDashboard(sessionId, delivery.id);
else this.feed?.updateDashboard(sessionId, delivery.id, feedNote(delivery, null, result));
// A message with its final result is done: only those still waiting for one, or queued, stay.
state.messages = state.messages.filter((m) => m.result === null || m.result === 'queued');
return 'new';
}
private answerResult(sessionId: string, tracked: TrackedAsk, held: Held, result: DeliveryResult): Exclude<ResultOutcome, 'unknown'> {
if (held.result === result) return 'repeat';
held.result = result;
const { delivery } = held;
this.trail?.({ kind: 'result', sessionId, delivery, result });
switch (result) {
case 'took':
if (!tracked.closure || tracked.closure.implicit) {
tracked.closure = { outcome: 'dashboard', at: this.now(), by: delivery.by, answer: null, planApproved: delivery.kind === 'plan-approve', implicit: false };
}
this.wake(sessionId, tracked.ask.id, () => ({ kind: 'closed', outcome: 'dashboard' }));
break;
case 'refused':
// Refused by the session: the ask takes an answer again, from its terminal or from the dashboard.
tracked.answer = null;
this.feed?.removeDashboard(sessionId, delivery.id);
break;
case 'closed':
case 'not-taken':
// It never reached the session (the ask closed first, or the engine did not take an approval): the feed does not claim it.
this.feed?.removeDashboard(sessionId, delivery.id);
break;
default:
// `queued` changes nothing for an answer.
break;
}
this.onChange(sessionId);
return 'new';
}
/** "Discard my answer": drops an answer or message before the reporter is handed it. */
discard(deliveryId: string): 'ok' | 'handed-over' | 'unknown' {
for (const [sid, state] of this.sessions) {
const index = state.messages.findIndex((m) => m.delivery.id === deliveryId);
const tracked = index === -1 ? [...state.asks.values()].find((t) => t.answer?.delivery.id === deliveryId) : undefined;
const held = index === -1 ? tracked?.answer : state.messages[index];
if (!held) continue;
if (held.handedOver || held.result !== null) return 'handed-over';
if (index !== -1) state.messages.splice(index, 1);
else if (tracked) tracked.answer = null;
this.feed?.removeDashboard(sid, deliveryId);
this.trail?.({ kind: 'dropped', sessionId: sid, delivery: held.delivery, why: 'discarded' });
this.onChange(sid);
return 'ok';
}
return 'unknown';
}
}
/** Where an ask stands, as its card and the panel show it. */
function askState(tracked: TrackedAsk): AskState {
if (tracked.closure) return 'closed';
const result = tracked.answer?.result;
if (result === 'not-taken') return 'not-taken';
return tracked.answer && result !== 'refused' ? 'pending' : 'open';
}
// ---- checking what the browser sends -------------------------------------------------------
type Fields = Omit<Delivery, 'id' | 'askId' | 'by' | 'at'>;
type Checked = { ok: true; fields: Fields } | { ok: false; err: AnswerError };
const accepted = (fields: Fields): Checked => ({ ok: true, fields });
const invalid = (error: string, path: string): Checked => ({ ok: false, err: { status: 400, error, path } });
const refusedKind = (kind: string): Checked => ({ ok: false, err: { status: 422, error: 'the session does not take this kind now', kind } });
const CONTROLS_BUT_TAB_AND_LF = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
/** Text typed in the browser, every control character but tab and line feed turned to a space; null when not a string or over `max`. */
function typedText(v: unknown, max: number): string | null {
if (typeof v !== 'string') return null;
const cleaned = v.replace(CONTROLS_BUT_TAB_AND_LF, ' ');
return cleaned.length <= max ? cleaned : null;
}
/** Optional typed text: '' when absent, null when it is not a string or is over `max`. */
const optionalText = (v: unknown, max: number): string | null => (v === undefined ? '' : typedText(v, max));
const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
type AnswerKind = Exclude<DeliveryKind, 'reply' | 'message' | 'command'>;
/** The ask each kind of answer fits, and the `accepts` entry the session must list for it. */
const ANSWER_FITS: Record<AnswerKind, { ask: Ask['kind']; needs: RespondKind }> = {
question: { ask: 'question', needs: 'question' },
'plan-approve': { ask: 'plan', needs: 'plan-approve' },
'plan-feedback': { ask: 'plan', needs: 'plan-feedback' },
'allow-once': { ask: 'permission', needs: 'permission' },
deny: { ask: 'permission', needs: 'permission' },
};
/** The `accepts` entry a message sent in place of an answer needs: feedback for a plan; for a question or a permission, its own kind. */
const replyNeeds = (kind: Ask['kind']): RespondKind => (kind === 'plan' ? 'plan-feedback' : kind);
/**
* Checks an answer from the browser against its ask and what the session takes. Nothing over a limit is cut: it is refused. The
* ask's own flags say what its provider can take: a reply instead of an answer only with `allowsReply`, a typed answer
* only with `allowsText`, a reason with a deny only with `tool.denyReason`.
*/
export function parseAnswer(body: unknown, ask: Ask, accepts: readonly RespondKind[]): Checked {
if (!isRecord(body)) return invalid('expected an object', '$');
const kind = body.kind;
if (kind === 'reply') return checkReply(body.text, ask, accepts);
if (typeof kind !== 'string' || !(kind in ANSWER_FITS)) return invalid('expected kind question, reply, plan-approve, plan-feedback, allow-once or deny', '$.kind');
const fit = ANSWER_FITS[kind as AnswerKind];
if (fit.ask !== ask.kind || !accepts.includes(fit.needs)) return refusedKind(kind);
if (kind === 'question') return checkQuestionAnswers(body.answers, ask);
if (kind === 'plan-approve') {
const mode = PLAN_MODES.find((m) => m === body.mode);
return mode === undefined ? invalid('expected mode auto, acceptEdits or default', '$.mode') : accepted({ kind, mode });
}
if (kind === 'plan-feedback') {
const text = optionalText(body.text, RESPOND_LIMITS.message);
return text === null ? invalid(`expected feedback of at most ${String(RESPOND_LIMITS.message)} characters`, '$.text') : accepted({ kind, text });
}
// Allow once on a request the owner could not see whole is refused; Deny still works.
if (kind === 'allow-once') return ask.tool?.cut ? refusedKind('allow-once') : accepted({ kind });
return checkDeny(body.text, ask);
}
function checkReply(raw: unknown, ask: Ask, accepts: readonly RespondKind[]): Checked {
if (!ask.allowsReply || !accepts.includes(replyNeeds(ask.kind))) return refusedKind('reply');
const text = typedText(raw, RESPOND_LIMITS.message);
if (text === null || !text.trim()) return invalid(`expected a message of 1 to ${String(RESPOND_LIMITS.message)} characters`, '$.text');
return accepted({ kind: 'reply', text });
}
function checkQuestionAnswers(raw: unknown, ask: Ask): Checked {
const questions = ask.questions ?? [];
if (!Array.isArray(raw) || raw.length !== questions.length) return invalid(`expected ${String(questions.length)} answers, one per question`, '$.answers');
const answers: QuestionAnswer[] = [];
for (let i = 0; i < raw.length; i++) {
const one = checkOneAnswer(raw[i] as unknown, questions[i]!, `$.answers[${String(i)}]`);
if ('error' in one) return invalid(one.error, one.path);
answers.push(one.answer);
}
if (answers.every((a) => a === null)) return invalid('answer at least one question', '$.answers');
return accepted({ kind: 'question', answers });
}
/** One question's answer: null for skipped, typed text where the question takes it, or option indexes (stored in order). */
function checkOneAnswer(raw: unknown, question: AskQuestion, at: string): { answer: QuestionAnswer } | { error: string; path: string } {
if (raw === null) return { answer: null };
if (isRecord(raw) && 'text' in raw) {
if (!question.allowsText) return { error: 'this question takes one of its options, not a typed answer', path: `${at}.text` };
const text = typedText(raw.text, RESPOND_LIMITS.answer);
if (text === null || !text.trim()) return { error: `expected an answer of 1 to ${String(RESPOND_LIMITS.answer)} characters`, path: `${at}.text` };
return { answer: { text } };
}
if (isRecord(raw) && Array.isArray(raw.options)) {
const picked = raw.options as unknown[];
const inRange = picked.every((n) => Number.isInteger(n) && (n as number) >= 0 && (n as number) < question.options.length);
if (!inRange) return { error: 'an option index is out of range', path: `${at}.options` };
if (new Set(picked).size !== picked.length) return { error: 'an option is chosen twice', path: `${at}.options` };
const rightCount = question.multiSelect ? picked.length > 0 : picked.length === 1;
if (!rightCount) return { error: question.multiSelect ? 'choose at least one option' : 'choose exactly one option', path: `${at}.options` };
return { answer: { options: [...(picked as number[])].sort((x, y) => x - y) } };
}
return { error: 'expected options, text or null', path: at };
}
function checkDeny(raw: unknown, ask: Ask): Checked {
const text = optionalText(raw, RESPOND_LIMITS.answer);
if (text === null) return invalid(`expected a reason of at most ${String(RESPOND_LIMITS.answer)} characters`, '$.text');
if (text.trim() !== '' && ask.tool?.denyReason === false) return invalid('this request takes no reason with a deny', '$.text');
return accepted({ kind: 'deny', text });
}
/**
* Reads typed text as a command: the command it names, why it is refused, or null when it does not start with
* `/`. Only `/clear` and `/compact` are sent from here, each on its own.
*/
export function commandOf(text: string): { command: DashboardCommand } | { refused: string } | null {
const typed = text.trim();
if (!typed.startsWith('/')) return null;
const name = typed.slice(1).split(/\s/)[0] ?? '';
if (name !== 'clear' && name !== 'compact') return { refused: `/${name} runs only in the terminal. From here you can send /clear and /compact.` };
return typed === `/${name}` ? { command: name } : { refused: `/${name} takes nothing after it from here. Send /${name} on its own, or use the terminal.` };
}
/** A command, when the session takes commands now. */
function asCommand(command: DashboardCommand, accepts: readonly RespondKind[]): Checked {
return accepts.includes('command') ? accepted({ kind: 'command', command }) : refusedKind('command');
}
/** Checks a new message or command from the browser: a `command` field, or text that may itself be a command. */
export function parseMessage(body: unknown, accepts: readonly RespondKind[]): Checked {
if (!isRecord(body)) return invalid('expected an object', '$');
const command = body.command;
if (command !== undefined) {
if (command !== 'clear' && command !== 'compact') return invalid('/clear and /compact are the only commands', '$.command');
return asCommand(command, accepts);
}
const text = typedText(body.text, RESPOND_LIMITS.message);
if (text === null || !text.trim()) return invalid(`expected a message of 1 to ${String(RESPOND_LIMITS.message)} characters`, '$.text');
const named = commandOf(text);
if (named === null) return accepts.includes('message') ? accepted({ kind: 'message', text }) : refusedKind('message');
return 'refused' in named ? invalid(named.refused, '$.text') : asCommand(named.command, accepts);
}