@adecore/agents 0.31.11 → 0.32.0

package/dist/chat/acp-backend.d.ts

@@ -1,4 +1,4 @@
-import { type ModelSelection } from '@adecore/agent-contracts';
+import { type AgentKind, type ModelSelection } from '@adecore/agent-contracts';
 import { type AcpModeMap, type AcpPermissionRequest, type AcpSessionInfo, type AcpTurnUsage } from './acp-protocol.ts';
 import type { ApprovalDecision, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
 export interface AcpClientInfo {
@@ -9,6 +9,7 @@ export interface AcpClientInfo {
 export declare const DEFAULT_ACP_CLIENT: AcpClientInfo;
 export interface AcpAgentSpec {
     name: string;
+    kind?: AgentKind;
     env?: Record<string, string>;
     modes?: AcpModeMap;
     authMethod?: string | null;
@@ -60,13 +61,14 @@ export declare class AcpBackend implements ChatBackend {
     compact(): void;
     interrupt(): void;
     respondApproval(requestId: string, decision: ApprovalDecision): boolean;
-    respondQuestion(): boolean;
+    respondQuestion(requestId: string, answers: Record<string, string>): boolean;
     declineRequest(requestId: string): boolean;
     stop(): void;
     dispose(): Promise<void>;
     private respond;
     private fail;
     private handleFrame;
+    private ask;
     private holdEarly;
     private hostAllows;
     private handleExit;

package/dist/chat/acp-backend.js

@@ -4,7 +4,7 @@ import { pathToFileURL } from 'node:url';
 import { attachmentImageMime } from '@adecore/agent-contracts';
 import { errorText } from '../error-text.js';
 import { MODE_ORDER } from '../modes.js';
-import { ACP_AUTH_REQUIRED, ACP_PROTOCOL_VERSION, AcpProtocol, acpStopWords, autoAllows, parseInitialize, parseSessionInfo, promptUsageOf, resolveAcpMode, runtimeModeOf, sessionIdOf, sessionUpdateOf, thoughtLevelOf } from './acp-protocol.js';
+import { ACP_AUTH_REQUIRED, ACP_PROTOCOL_VERSION, AcpProtocol, acpErrorLimit, acpStopWords, autoAllows, GROK_QUESTION_METHODS, parseInitialize, parseSessionInfo, promptUsageOf, resolveAcpMode, runtimeModeOf, sessionIdOf, sessionUpdateOf, thoughtLevelOf } from './acp-protocol.js';
 import { attachmentNote } from './input.js';
 import { JsonRpcError, JsonRpcTransport } from './json-rpc-transport.js';
 export const DEFAULT_ACP_CLIENT = { name: 'agents', title: 'Agents', version: '0.1.0' };
@@ -49,7 +49,7 @@ export class AcpBackend {
         this.host = host;
         this.spec = spec;
         this.client = spec.client ?? DEFAULT_ACP_CLIENT;
-        this.protocol = new AcpProtocol(launch.generation, spec.modes ?? {}, acpStopWords(spec.name), spec.adoptTitles === true);
+        this.protocol = new AcpProtocol(launch.generation, spec.modes ?? {}, acpStopWords(spec.name), spec.adoptTitles === true, launch.now);
     }
     get running() {
         return this.transport !== null;
@@ -328,7 +328,7 @@ export class AcpBackend {
     sendTurn(input) {
         const transport = this.transport;
         if (!transport) {
-            this.emit({ type: 'failed', message: `session/prompt failed: ${this.spec.name} is not running` });
+            this.emit({ type: 'failed', message: `${this.spec.name} is not running` });
             return;
         }
         const prompt = this.promptBlocks(input);
@@ -347,7 +347,8 @@ export class AcpBackend {
             // A process that went has its exit tell the thread; anything else ends this turn alone.
             if (this.transport === transport && transport.alive && this.prompt === turn) {
                 this.prompt = null;
-                this.emitAll(this.protocol.abort(turn.promptId, turn.cancelled ? null : errorText(error)));
+                const limit = error instanceof JsonRpcError ? acpErrorLimit(error.code, error.data, this.spec.kind ?? null) : null;
+                this.emitAll(this.protocol.abort(turn.promptId, turn.cancelled ? null : errorText(error), limit));
             }
         });
     }
@@ -357,7 +358,7 @@ export class AcpBackend {
             this.sendTurn({ text: '/compact', preamble: null, attachments: [], mentions: [], skills: [] });
             return;
         }
-        this.emit({ type: 'note', level: 'warning', text: `${this.spec.name} cannot fold its context on request.` });
+        this.emit({ type: 'note', level: 'warning', text: `${this.spec.name} cannot compact its context.` });
         this.emit({ type: 'turn.done', state: 'done', costUsd: 0 });
     }
     /* Cancels the turn: every permission request still open is answered as cancelled, and the turn ends on the prompt's response. */
@@ -372,7 +373,7 @@ export class AcpBackend {
         }
         this.prompt.cancelled = true;
         try {
-            for (const cancelled of this.protocol.cancelPermissions()) {
+            for (const cancelled of this.protocol.cancelRequests()) {
                 transport.respond(cancelled.rpcId, cancelled.result);
                 this.emit({ type: 'request.withdrawn', requestId: cancelled.requestId });
             }
@@ -393,11 +394,22 @@ export class AcpBackend {
         this.emitAll(answer.events);
         return true;
     }
-    /* ACP asks no questions of its own; an agent asks in its message and the next prompt answers. */
-    respondQuestion() {
-        return false;
+    respondQuestion(requestId, answers) {
+        const answer = this.protocol.answerQuestion(requestId, answers);
+        if (!answer) {
+            return false;
+        }
+        if (!this.respond(requestId, answer.rpcId, answer.result)) {
+            return false;
+        }
+        this.emitAll(answer.events);
+        return true;
     }
     declineRequest(requestId) {
+        if (this.protocol.hasQuestion(requestId)) {
+            const cancelled = this.protocol.cancelQuestion(requestId);
+            return cancelled !== null && this.respond(requestId, cancelled.rpcId, cancelled.result);
+        }
         return this.protocol.hasPermission(requestId) && this.respondApproval(requestId, 'deny');
     }
     stop() {
@@ -441,10 +453,25 @@ export class AcpBackend {
         if (id === null) {
             return;
         }
+        if (typeof frame.method === 'string' && GROK_QUESTION_METHODS.includes(frame.method)) {
+            const question = this.protocol.question(id, this.sessionId, frame.params);
+            if (question === null) {
+                transport.respondError(id, -32602, 'Not a question of this session');
+                return;
+            }
+            this.ask(transport, question);
+            return;
+        }
         if (frame.method !== 'session/request_permission') {
             transport.respondError(id, -32601, `${nameOf(this.client)} does not handle ${String(frame.method)}`);
             return;
         }
+        // Before any runtime mode answers it: a question is never the agent's to allow.
+        const interaction = this.protocol.interaction(id, this.sessionId, frame.params);
+        if (interaction !== null) {
+            this.ask(transport, interaction);
+            return;
+        }
         const permission = this.protocol.permission(id, this.sessionId, frame.params);
         if (permission === null) {
             transport.respondError(id, -32602, 'Not a permission request of this session');
@@ -452,7 +479,7 @@ export class AcpBackend {
         }
         if (this.prompt?.cancelled) {
             this.emitAll(permission.events.filter((event) => event.type !== 'approval.requested'));
-            const answer = this.protocol.cancelPermissions().find((cancelled) => cancelled.requestId === permission.requestId);
+            const answer = this.protocol.cancelRequests().find((cancelled) => cancelled.requestId === permission.requestId);
             if (answer) {
                 transport.respond(answer.rpcId, answer.result);
             }
@@ -468,6 +495,18 @@ export class AcpBackend {
         }
         this.emitAll(permission.events);
     }
+    /* Puts a question to the person, or turns it down at once when the turn is being cancelled. */
+    ask(transport, question) {
+        if (this.prompt?.cancelled) {
+            this.emitAll(question.events.filter((event) => event.type !== 'question.requested'));
+            const cancelled = this.protocol.cancelQuestion(question.requestId);
+            if (cancelled) {
+                transport.respond(cancelled.rpcId, cancelled.result);
+            }
+            return;
+        }
+        this.emitAll(question.events);
+    }
     /* Holds an update until the session is known; of a history a load replays, only the commands, since the thread has the rest. */
     holdEarly(params) {
         const update = sessionUpdateOf(params);
@@ -489,7 +528,7 @@ export class AcpBackend {
         }
         this.transport = null;
         this.prompt = null;
-        this.protocol.cancelPermissions();
+        this.protocol.cancelRequests();
         this.emit({ type: 'exit', exitCode, ...(stderr === null ? {} : { stderr }) });
     }
     /* A cancelled turn still spent what it reports. A host that fails to keep it costs the record, never the end of the turn. */

package/dist/chat/acp-protocol.d.ts

@@ -1,4 +1,4 @@
-import { type ChatFileChange, type RuntimeMode } from '@adecore/agent-contracts';
+import { type AgentKind, type ChatFileChange, type ChatTurnLimit, type RuntimeMode } from '@adecore/agent-contracts';
 import { z } from 'zod';
 import type { ApprovalDecision, BackendEvent } from './backend.ts';
 export declare const ACP_PROTOCOL_VERSION = 1;
@@ -9,6 +9,7 @@ declare const DiffSchema: z.ZodObject<{
     oldText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     newText: z.ZodString;
 }, z.core.$loose>;
+export declare const GROK_QUESTION_METHODS: readonly string[];
 export interface AcpTurnUsage {
     input: number;
     cacheRead: number;
@@ -118,20 +119,31 @@ export interface AcpPermission {
     request: AcpPermissionRequest;
     events: BackendEvent[];
 }
+export interface AcpQuestion {
+    requestId: string;
+    rpcId: number | string;
+    events: BackendEvent[];
+}
 export interface AcpStopWords {
     maxTokens: string;
     maxTurnRequests: string;
     refusal: string;
+    ownAnswer: string;
 }
 export declare function acpStopWords(agentName: string): AcpStopWords;
+export declare function acpErrorLimit(code: number | null, data: unknown, kind: AgentKind | null): ChatTurnLimit | null;
+export declare function quotaResetOf(text: string, now: number): number | null;
 export declare class AcpProtocol {
     private readonly generation;
     private readonly modes;
     private readonly words;
     private readonly tools;
     private readonly permissions;
+    private readonly questions;
     private text;
     private refusalLine;
+    private quota;
+    private readonly now;
     private thought;
     private counter;
     private costUsd;
@@ -139,7 +151,7 @@ export declare class AcpProtocol {
     private vendorTokens;
     private readonly prompts;
     private readonly titles;
-    constructor(generation: number, modes: AcpModeMap, words: AcpStopWords, titles?: boolean);
+    constructor(generation: number, modes: AcpModeMap, words: AcpStopWords, titles?: boolean, now?: () => number);
     update(sessionId: string, params: unknown): BackendEvent[];
     private mapUpdate;
     private vendorUsage;
@@ -152,14 +164,27 @@ export declare class AcpProtocol {
         result: unknown;
         events: BackendEvent[];
     } | null;
-    cancelPermissions(): Array<{
+    question(rpcId: number | string, sessionId: string, params: unknown): AcpQuestion | null;
+    interaction(rpcId: number | string, sessionId: string, params: unknown): AcpQuestion | null;
+    private ask;
+    answerQuestion(requestId: string, answers: Record<string, string>): {
+        rpcId: number | string;
+        result: unknown;
+        events: BackendEvent[];
+    } | null;
+    cancelQuestion(requestId: string): {
+        rpcId: number | string;
+        result: unknown;
+    } | null;
+    cancelRequests(): Array<{
         requestId: string;
         rpcId: number | string;
         result: unknown;
     }>;
     hasPermission(requestId: string): boolean;
+    hasQuestion(requestId: string): boolean;
     finish(result: unknown, promptId: string | undefined, cancelled?: boolean): BackendEvent[];
-    abort(promptId: string | undefined, error: string | null): BackendEvent[];
+    abort(promptId: string | undefined, error: string | null, limit?: ChatTurnLimit | null): BackendEvent[];
     private messageChunk;
     private thoughtChunk;
     private closeText;

package/dist/chat/acp-protocol.js

@@ -39,6 +39,26 @@ const PermissionRequestSchema = z.looseObject({
     toolCall: ToolCallSchema,
     options: z.array(PermissionOptionSchema)
 });
+/*
+ * Grok's questions to the person (`_x.ai/ask_user_question` in xai-org/grok-build, `ask_user_question/types.rs`). The
+ * answer goes back keyed by the question's text, each a list of the labels picked.
+ */
+export const GROK_QUESTION_METHODS = ['_x.ai/ask_user_question', 'x.ai/ask_user_question'];
+const GrokQuestionSchema = z.looseObject({
+    question: z.string(),
+    header: z.string().nullish(),
+    options: z.array(z.unknown()).nullish(),
+    multiSelect: z.boolean().nullish()
+});
+const GrokChoiceSchema = z.looseObject({ label: z.string(), description: z.string().nullish() });
+const GrokQuestionRequestSchema = z.looseObject({ sessionId: z.string(), questions: z.array(z.unknown()) });
+// The label Grok takes for an answer in a person's own words, which ride along as the question's `notes`.
+const GROK_OWN_ANSWER = 'Other';
+/*
+ * The prefix Antigravity's ACP server 1.4.1 gives the tool call of a question it asks over `session/request_permission`,
+ * one request per question with an option per choice (`ExternalOnInteractionHook`).
+ */
+const INTERACTION_PREFIX = 'interaction_';
 const SessionNotificationSchema = z.looseObject({ sessionId: z.string(), update: z.looseObject({ sessionUpdate: z.string() }) });
 const PromptResponseSchema = z.looseObject({ stopReason: z.string() });
 const tokenCount = z.number().int().nonnegative();
@@ -325,6 +345,15 @@ const KIND_NAMES = {
 const KEPT_PROMPTS = 3;
 // What Copilot CLI 1.0.101 writes as a message of its own after a call a person turned down; the thread shows the refusal already.
 const REFUSAL_LINE = 'Info: Operation cancelled by user';
+/*
+ * What Antigravity's ACP server 1.4.1 writes in place of an answer once the account's quota ran out (`quota_errors.py`).
+ * Its turn still ends with `end_turn`, so this text is all that tells the limit apart.
+ */
+const QUOTA_HEAD = 'Usage Limit Reached\n\nYou have reached your current quota for this period.';
+/* Whether a message may still turn out to be one the thread does not show: the refusal line after a refusal, or a limit message. */
+function withheld(text, afterRefusal) {
+    return (afterRefusal && REFUSAL_LINE.startsWith(text)) || QUOTA_HEAD.startsWith(text) || text.startsWith(QUOTA_HEAD);
+}
 function foldSpace(text) {
     return text.replace(/\s+/g, ' ').trim();
 }
@@ -332,6 +361,8 @@ function str(value) {
     return typeof value === 'string' && value !== '' ? value : null;
 }
 /* A field of the agent's own input, which no schema promises; the first one that is a non-empty string. */
+// Where agents put the command a call runs; Antigravity names it `CommandLine`.
+const COMMAND_KEYS = ['command', 'cmd', 'CommandLine'];
 function rawField(raw, ...keys) {
     if (!isRecord(raw)) {
         return null;
@@ -375,7 +406,7 @@ export function toolRow(tool) {
     const raw = isRecord(tool.rawInput) ? tool.rawInput : {};
     switch (tool.kind) {
         case 'execute':
-            return { name: 'Bash', input: { ...raw, description, command: rawField(tool.rawInput, 'command', 'cmd') ?? description } };
+            return { name: 'Bash', input: { ...raw, description, command: rawField(tool.rawInput, ...COMMAND_KEYS) ?? description } };
         case 'read':
             return { name: 'Read', input: { ...raw, description, ...(path === null ? {} : { file_path: path }) } };
         case 'search':
@@ -408,11 +439,91 @@ function toolOutput(tool) {
 }
 export function acpStopWords(agentName) {
     return {
-        maxTokens: `${agentName} stopped: the response reached its token limit.`,
-        maxTurnRequests: `${agentName} stopped: the turn reached its limit of model requests.`,
-        refusal: `${agentName} refused to continue this turn.`
+        maxTokens: `${agentName} stopped because the reply hit its length limit.`,
+        maxTurnRequests: `${agentName} stopped because this turn hit its step limit.`,
+        refusal: `${agentName} refused to continue this turn.`,
+        ownAnswer: `${agentName} accepts only the answers it offered, so it did not get yours.`
     };
 }
+// Grok's code for a request its API turned down with a 429, after its own retry (`RATE_LIMITED_ERROR_CODE` in xai-org/grok-build).
+const GROK_RATE_LIMITED = -32003;
+// What that 429 says when an account on the free tier spent its usage; any other 429 is a rate limit.
+const GROK_FREE_USAGE = 'subscription:free-usage-exhausted';
+// The stream error types of an overloaded model, as Grok passes them on in its error text.
+const OVERLOADED_TYPES = /\b(overloaded_error|service_unavailable_error)\b/;
+/*
+ * The limit a failed `session/prompt` names in its JSON-RPC error; null for any other failure. ACP 1 has no code
+ * for a limit, so this reads Grok 1.0.62's: -32003 after a 429, which only Grok means that way, and -32603 with the
+ * HTTP status or the stream error of an overloaded model once its own retries ran out. Neither says when a limit lifts.
+ */
+export function acpErrorLimit(code, data, kind) {
+    const text = typeof data === 'string' ? data : isRecord(data) && typeof data.message === 'string' ? data.message : '';
+    if (code === GROK_RATE_LIMITED && kind === 'grok') {
+        return text.includes(GROK_FREE_USAGE) ? { kind: 'usage' } : { kind: 'overload' };
+    }
+    if (code !== -32603) {
+        return null;
+    }
+    const status = isRecord(data) && typeof data.http_status === 'number' ? data.http_status : null;
+    const overloaded = status === 529 || OVERLOADED_TYPES.test(text) || (status !== null && status >= 500 && /overloaded/i.test(text));
+    return overloaded ? { kind: 'overload' } : null;
+}
+function quotaLimit(quota) {
+    return { kind: 'usage', ...(quota.resetsAt === null ? {} : { resetsAt: quota.resetsAt }) };
+}
+const UNIT_MS = { second: 1000, minute: 60_000, hour: 3_600_000, day: 86_400_000 };
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/*
+ * When the quota in an Antigravity limit message lifts, rounded up: the server writes the two largest units of the
+ * delay and drops the rest (`will reset in 4 days, 23 hours.`), or the time to the minute (`will reset on Oct 21,
+ * 2026 14:05 UTC.`). Null when it names neither.
+ */
+export function quotaResetOf(text, now) {
+    const relative = /will reset in ([^.]+)\./.exec(text);
+    if (relative) {
+        let total = 0;
+        let smallest = Infinity;
+        for (const part of relative[1].split(',')) {
+            const amount = /^(\d+) (second|minute|hour|day)s?$/.exec(part.trim());
+            if (!amount) {
+                return null;
+            }
+            const unit = UNIT_MS[amount[2]];
+            total += Number(amount[1]) * unit;
+            smallest = Math.min(smallest, unit);
+        }
+        return now + total + smallest;
+    }
+    const absolute = /will reset on ([A-Z][a-z]{2}) (\d{1,2}), (\d{4}) (\d{2}):(\d{2}) UTC\./.exec(text);
+    const month = absolute ? MONTHS.indexOf(absolute[1]) : -1;
+    if (!absolute || month === -1) {
+        return null;
+    }
+    return Date.UTC(Number(absolute[3]), month, Number(absolute[2]), Number(absolute[4]), Number(absolute[5])) + UNIT_MS.minute;
+}
+/* The labels a person picked, out of the one answer a question card gives (choices joined with `, `); null for words of their own. */
+function pickedLabels(answer, labels, multiSelect) {
+    if (labels.includes(answer)) {
+        return [answer];
+    }
+    if (!multiSelect) {
+        return null;
+    }
+    // A label may hold `, ` itself, so the pieces join up again until they make one.
+    const picked = [];
+    let part = '';
+    for (const piece of answer.split(', ')) {
+        part = part === '' ? piece : `${part}, ${piece}`;
+        if (labels.includes(part)) {
+            picked.push(part);
+            part = '';
+        }
+    }
+    return part === '' && picked.length > 0 ? picked : null;
+}
+function cancelledAnswer(pending) {
+    return pending.shape === 'grok' ? { outcome: 'cancelled' } : { outcome: { outcome: 'cancelled' } };
+}
 /*
  * One ACP session's `session/update` stream, mapped onto backend events. A message's chunks become
  * one text item, cut where the agent switches to a thought or a tool; a tool call becomes a row that
@@ -424,10 +535,14 @@ export class AcpProtocol {
     words;
     tools = new Map();
     permissions = new Map();
-    // `held` while the message may still be the refusal line, whose chunks the thread has not heard yet.
+    questions = new Map();
+    // `held` while the message may still be the refusal line or a limit message, whose chunks the thread has not heard yet.
     text = null;
     // Set by a refusal until the next message shows whether it is the refusal line.
     refusalLine = false;
+    // The limit message of this turn, held back from the thread: it ends the turn as a limit, or shows as text when the turn ends otherwise.
+    quota = null;
+    now;
     thought = null;
     counter = 0;
     costUsd = 0;
@@ -438,11 +553,12 @@ export class AcpProtocol {
     prompts = [];
     titles;
     // `titles` takes the session titles the agent sends as the chat's suggested title.
-    constructor(generation, modes, words, titles = false) {
+    constructor(generation, modes, words, titles = false, now = Date.now) {
         this.generation = generation;
         this.modes = modes;
         this.words = words;
         this.titles = titles;
+        this.now = now;
     }
     /* One `session/update` notification; empty for another session, an unknown update or one that does not parse. */
     update(sessionId, params) {
@@ -548,7 +664,7 @@ export class AcpProtocol {
             description: tool.title === '' ? null : tool.title,
             canAllowAlways: options.some((option) => option.kind === 'allow_always')
         });
-        const command = rawField(tool.rawInput, 'command', 'cmd');
+        const command = rawField(tool.rawInput, ...COMMAND_KEYS);
         const asked = { kind: tool.kind, title: tool.title === '' ? null : tool.title, commands: [...(command === null ? [] : [command]), ...tool.text] };
         return { requestId, rpcId, kind: tool.kind, request: asked, events };
     }
@@ -586,19 +702,121 @@ export class AcpProtocol {
         this.refusalLine = true;
         return { rpcId: pending.rpcId, result, events: this.toolCall({ toolCallId: pending.toolCallId }, false) };
     }
-    /* Every permission request still open, answered as cancelled, which the protocol asks of a client that cancels a turn. */
-    cancelPermissions() {
-        const cancelled = [...this.permissions].map(([requestId, pending]) => ({
-            requestId,
-            rpcId: pending.rpcId,
-            result: { outcome: { outcome: 'cancelled' } }
+    /* A Grok `ask_user_question` request; null when it does not parse or asks nothing, which the caller answers with an error. */
+    question(rpcId, sessionId, params) {
+        const request = GrokQuestionRequestSchema.safeParse(params);
+        if (!request.success || request.data.sessionId !== sessionId) {
+            return null;
+        }
+        const questions = validItems(GrokQuestionSchema, request.data.questions).map((question, index) => ({
+            id: String(index),
+            header: question.header ?? '',
+            question: question.question,
+            choices: validItems(GrokChoiceSchema, question.options).map((choice) => ({ label: choice.label, description: choice.description ?? '' })),
+            multiSelect: question.multiSelect === true
         }));
+        if (questions.length === 0) {
+            return null;
+        }
+        return this.ask(rpcId, { shape: 'grok', rpcId, questions });
+    }
+    /*
+     * A `session/request_permission` that is a question rather than a permission, as Antigravity asks one: one choice of
+     * several, never a call to run. Null for every other permission request.
+     */
+    interaction(rpcId, sessionId, params) {
+        const request = PermissionRequestSchema.safeParse(params);
+        if (!request.success || request.data.sessionId !== sessionId) {
+            return null;
+        }
+        const call = request.data.toolCall;
+        const raw = call.rawInput;
+        const bare = raw === undefined || raw === null || (isRecord(raw) && Object.keys(raw).length === 0);
+        if (!call.toolCallId.startsWith(INTERACTION_PREFIX) || !bare || call.kind || request.data.options.length === 0) {
+            return null;
+        }
+        const question = {
+            id: '0',
+            header: '',
+            question: call.title ?? '',
+            choices: request.data.options.map((option) => ({ label: option.name, description: '' })),
+            multiSelect: false
+        };
+        return this.ask(rpcId, { shape: 'interaction', rpcId, question, options: request.data.options });
+    }
+    ask(rpcId, pending) {
+        const requestId = `acp-${this.generation}-${String(rpcId)}`;
+        this.questions.set(requestId, pending);
+        const questions = pending.shape === 'grok' ? pending.questions : [pending.question];
+        return { requestId, rpcId, events: [...this.closeText(), ...this.closeThought(), { type: 'question.requested', requestId, questions }] };
+    }
+    /* The answer to a question in the agent's own shape, from the card's answers keyed by question id. */
+    answerQuestion(requestId, answers) {
+        const pending = this.questions.get(requestId);
+        if (!pending) {
+            return null;
+        }
+        this.questions.delete(requestId);
+        if (pending.shape === 'interaction') {
+            const given = (answers[pending.question.id] ?? '').trim();
+            const option = pending.options.find((candidate) => candidate.name === given) ?? pending.options.find((candidate) => candidate.optionId === given);
+            if (option === undefined) {
+                return {
+                    rpcId: pending.rpcId,
+                    result: { outcome: { outcome: 'cancelled' } },
+                    events: [{ type: 'note', level: 'warning', text: this.words.ownAnswer }]
+                };
+            }
+            return { rpcId: pending.rpcId, result: { outcome: { outcome: 'selected', optionId: option.optionId } }, events: [] };
+        }
+        const picked = {};
+        const notes = {};
+        for (const question of pending.questions) {
+            const given = answers[question.id];
+            if (given === undefined) {
+                continue;
+            }
+            const labels = pickedLabels(given, question.choices.map((choice) => choice.label), question.multiSelect);
+            picked[question.question] = labels ?? [GROK_OWN_ANSWER];
+            if (labels === null) {
+                notes[question.question] = { notes: given };
+            }
+        }
+        return {
+            rpcId: pending.rpcId,
+            result: { outcome: 'accepted', answers: picked, ...(Object.keys(notes).length === 0 ? {} : { annotations: notes }) },
+            events: []
+        };
+    }
+    /* Turns one question down, in the shape its agent takes a refusal in. */
+    cancelQuestion(requestId) {
+        const pending = this.questions.get(requestId);
+        if (!pending) {
+            return null;
+        }
+        this.questions.delete(requestId);
+        return { rpcId: pending.rpcId, result: cancelledAnswer(pending) };
+    }
+    /* Every permission request and question still open, answered as cancelled, which the protocol asks of a client that cancels a turn. */
+    cancelRequests() {
+        const cancelled = [
+            ...[...this.permissions].map(([requestId, pending]) => ({
+                requestId,
+                rpcId: pending.rpcId,
+                result: { outcome: { outcome: 'cancelled' } }
+            })),
+            ...[...this.questions].map(([requestId, pending]) => ({ requestId, rpcId: pending.rpcId, result: cancelledAnswer(pending) }))
+        ];
         this.permissions.clear();
+        this.questions.clear();
         return cancelled;
     }
     hasPermission(requestId) {
         return this.permissions.has(requestId);
     }
+    hasQuestion(requestId) {
+        return this.questions.has(requestId);
+    }
     /*
      * The end of a turn, from the `stopReason` of its `session/prompt` response. Only a turn the client cancelled
      * (`cancelled`) ends aborted: Grok 1.0.62 answers `cancelled` by itself when a person turns a call down, and
@@ -611,6 +829,15 @@ export class AcpProtocol {
         this.refusalLine = false;
         const events = [...this.closeText(), ...this.closeThought(), ...this.vendorUsage(isRecord(result) ? result._meta : undefined)];
         const base = { ...(promptId === undefined ? {} : { promptId }), costUsd: this.costUsd };
+        const quota = this.quota;
+        this.quota = null;
+        if (quota !== null && reason !== 'cancelled') {
+            events.push({ type: 'turn.done', ...base, state: 'error', error: quota.text, limit: quotaLimit(quota) });
+            return events;
+        }
+        if (quota !== null) {
+            events.push({ type: 'text.done', ref: quota.ref, text: quota.text });
+        }
         switch (reason) {
             case 'cancelled':
                 events.push({ type: 'turn.done', ...base, state: 'aborted' });
@@ -629,15 +856,22 @@ export class AcpProtocol {
         }
         return events;
     }
-    /* A turn that ended without a `stopReason`: the request failed, or was cancelled before the agent said so. */
-    abort(promptId, error) {
+    /* A turn that ended without a `stopReason`: the request failed, on a limit its error names, or was cancelled before the agent said so. */
+    abort(promptId, error, limit = null) {
         this.refusalLine = false;
         const base = { ...(promptId === undefined ? {} : { promptId }), costUsd: this.costUsd };
-        return [
-            ...this.closeText(),
-            ...this.closeThought(),
-            error === null ? { type: 'turn.done', ...base, state: 'aborted' } : { type: 'turn.done', ...base, state: 'error', error }
-        ];
+        const events = [...this.closeText(), ...this.closeThought()];
+        const quota = this.quota;
+        this.quota = null;
+        if (quota !== null) {
+            events.push({ type: 'text.done', ref: quota.ref, text: quota.text });
+        }
+        // A failed request after the limit message still ran into that limit, so it pauses as one when the error names none.
+        const named = limit ?? (quota === null ? null : quotaLimit(quota));
+        events.push(error === null
+            ? { type: 'turn.done', ...base, state: 'aborted' }
+            : { type: 'turn.done', ...base, state: 'error', error, ...(named === null ? {} : { limit: named }) });
+        return events;
     }
     messageChunk(update) {
         const chunk = ContentChunkSchema.safeParse(update);
@@ -650,12 +884,13 @@ export class AcpProtocol {
             events.push(...this.closeText());
         }
         if (this.text === null) {
-            this.text = { ref: messageId === null ? `message-${++this.counter}` : `message-${messageId}`, messageId, text: '', held: this.refusalLine };
+            const ref = messageId === null ? `message-${++this.counter}` : `message-${messageId}`;
+            this.text = { ref, messageId, text: '', held: true, afterRefusal: this.refusalLine };
             this.refusalLine = false;
         }
         const text = this.text;
         text.text += chunk.data.content.text;
-        if (text.held && !REFUSAL_LINE.startsWith(text.text)) {
+        if (text.held && !withheld(text.text, text.afterRefusal)) {
             text.held = false;
             events.push({ type: 'text.delta', ref: text.ref, text: text.text });
         }
@@ -680,7 +915,11 @@ export class AcpProtocol {
     closeText() {
         const text = this.text;
         this.text = null;
-        if (text === null || (text.held && text.text === REFUSAL_LINE)) {
+        if (text === null || (text.held && text.afterRefusal && text.text === REFUSAL_LINE)) {
+            return [];
+        }
+        if (text.held && text.text.startsWith(QUOTA_HEAD)) {
+            this.quota = { ref: text.ref, text: text.text.trim(), resetsAt: quotaResetOf(text.text, this.now()) };
             return [];
         }
         return [{ type: 'text.done', ref: text.ref, text: text.text }];

package/dist/chat/backend.d.ts

@@ -15,6 +15,7 @@ export interface BackendLaunch {
     resumeNote: string | null;
     resumeInstructions?: string | null;
     goal?: ChatGoal;
+    cacheTtlMs?: number;
     folders?: readonly string[];
     projectConfig?: boolean;
     spawn?: SpawnChatProcess;
@@ -167,6 +168,8 @@ export type BackendEvent = {
     contextTokens?: number;
     contextWindow?: number;
     costUsd?: number;
+    cacheTtlMs?: number;
+    cacheExpiresAt?: number;
 } | {
     type: 'limits';
     update: LimitsUpdate;