Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

refactor(coding-agent): add session action scheduler kernel (#573)

Sebastian Müllerc1b2a7d86b4e
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index 74cc3a8899..a544dac769 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -229,6 +229,18 @@ import {
type RlmUsage,
type SubagentRuntimeHost,
} from "./rlm-runtime.js";
+import {
+ ActionStore,
+ canSelectSessionAction,
+ type DeliveryPolicy,
+ type DeliveryRecord,
+ type RuntimeActivity,
+ type SessionAction,
+ type SessionCommandPayload,
+ type SessionTurnPayload,
+ shouldYieldLowerRun,
+ transitionSessionAction,
+} from "./session-action-store.js";
import type { BranchSummaryEntry, CompactionEntry, SessionContext, SessionMessageEntry } from "./session-manager.js";
import {
CURRENT_SESSION_VERSION,
@@ -575,22 +587,19 @@ interface PromptDispatchFence {
type QueuedAgentMessage = UserMessage | CustomMessage;
type SessionInputSchedule = "steer" | "followUp";
-interface PreparedPromptInput {
- kind: "prompt";
- text: string;
+interface PreparedTurnPayload extends SessionTurnPayload {
images?: ImageContent[];
content?: (TextContent | ImageContent)[];
customMessage?: CustomMessage;
- previewLabel?: string;
- queueKey?: string;
- agentMessageId?: string;
- prefixMessages: CustomMessage[];
- suppressAutonomousContinuation?: boolean;
- autoPump: boolean;
- preparation?: PreparedPromptPreparation;
- message: QueuedAgentMessage;
+ prepared?: PreparedPromptPreparation;
}
+interface PreparedCommandPayload extends SessionCommandPayload {
+ images?: ImageContent[];
+}
+
+type QueuedSessionAction = SessionAction<PreparedTurnPayload | PreparedCommandPayload>;
+
interface PreparedPromptPreparation {
result: Awaited<ReturnType<ExtensionRunner["emitBeforeAgentStart"]>>;
/** Base system prompt captured at emitBeforeAgentStart, for stale-base refresh at handoff. */
@@ -612,18 +621,6 @@ function oncePreflight(
};
}
-interface PreparedCommandInput {
- kind: "command";
- text: string;
- command: SessionSlashCommand;
- images?: ImageContent[];
- queueKey?: undefined;
- agentMessageId?: string;
- message?: undefined;
-}
-
-type QueuedSessionInput = PreparedPromptInput | PreparedCommandInput;
-
export interface QueuedAgentInputSnapshot {
text: string;
content?: (TextContent | ImageContent)[];
@@ -638,6 +635,10 @@ export interface AcceptedAgentInputSnapshot extends QueuedAgentInputSnapshot {
nextTurn: CustomMessage[];
}
+interface SessionActionRecoverySnapshot {
+ actions: readonly QueuedSessionAction[];
+}
+
function cloneCustomMessage(message: CustomMessage): CustomMessage {
return {
...message,
@@ -661,34 +662,48 @@ function createQueuedAgentInputSnapshotFromUserMessage(
return { text, content, ...(images.length > 0 ? { images } : {}) };
}
-function createQueuedAgentInputSnapshot(message: QueuedSessionInput): QueuedAgentInputSnapshot {
- if (message.kind === "command") {
+function primaryDeliveryRecord(action: QueuedSessionAction): DeliveryRecord {
+ if (action.payload.kind !== "turn") throw new Error(`Session action ${action.id} is not a turn`);
+ const record = action.payload.records.find((candidate) => candidate.role === "primary");
+ if (!record) throw new Error(`Turn action ${action.id} has no primary delivery record`);
+ return record;
+}
+
+function actionPrefixMessages(action: QueuedSessionAction): CustomMessage[] {
+ return action.payload.kind === "turn"
+ ? action.payload.records
+ .filter((record): record is DeliveryRecord & { message: CustomMessage } => record.role === "prefix")
+ .map((record) => record.message)
+ : [];
+}
+
+function createQueuedAgentInputSnapshot(action: QueuedSessionAction): QueuedAgentInputSnapshot {
+ const payload = action.payload;
+ if (payload.kind === "session_command") {
return {
- text: message.text,
- ...(message.images ? { images: message.images.map((image) => ({ ...image })) } : {}),
- ...(message.agentMessageId ? { agentMessageId: message.agentMessageId } : {}),
- customMessage: createSessionSlashCommandMessage(message.command),
+ text: payload.text,
+ ...(payload.images ? { images: payload.images.map((image) => ({ ...image })) } : {}),
+ ...(action.agentMessageId ? { agentMessageId: action.agentMessageId } : {}),
+ customMessage: createSessionSlashCommandMessage(payload.command),
};
}
- const legacySnapshot = createQueuedAgentInputSnapshotFromUserMessage(message.text, message.message);
+ const message = primaryDeliveryRecord(action).message;
+ const legacySnapshot = createQueuedAgentInputSnapshotFromUserMessage(payload.text, message);
+ const prefixMessages = actionPrefixMessages(action);
return {
...legacySnapshot,
- text: message.text,
- ...(message.content ? { content: message.content.map((block) => ({ ...block })) } : {}),
- ...(message.images ? { images: message.images.map((image) => ({ ...image })) } : {}),
- ...(message.customMessage ? { customMessage: cloneCustomMessage(message.customMessage) } : {}),
- ...(message.prefixMessages.length > 0
- ? { prefixMessages: message.prefixMessages.map((prefix) => cloneCustomMessage(prefix)) }
+ text: payload.text,
+ ...(payload.content ? { content: payload.content.map((block) => ({ ...block })) } : {}),
+ ...(payload.images ? { images: payload.images.map((image) => ({ ...image })) } : {}),
+ ...(payload.customMessage ? { customMessage: cloneCustomMessage(payload.customMessage) } : {}),
+ ...(prefixMessages.length > 0
+ ? { prefixMessages: prefixMessages.map((prefix) => cloneCustomMessage(prefix)) }
: {}),
- ...(message.agentMessageId ? { agentMessageId: message.agentMessageId } : {}),
- ...(message.queueKey ? { queueKey: message.queueKey } : {}),
+ ...(action.agentMessageId ? { agentMessageId: action.agentMessageId } : {}),
+ ...(action.queueKey ? { queueKey: action.queueKey } : {}),
};
}
-function queuedMessagePreview(message: { text: string; previewLabel?: string }): string {
- return message.previewLabel ? `${message.previewLabel}: ${message.text}` : message.text;
-}
-
function normalizeMessageContent(content: string | (TextContent | ImageContent)[]): {
text: string;
images?: ImageContent[];
@@ -702,14 +717,13 @@ function normalizeMessageContent(content: string | (TextContent | ImageContent)[
return { text, ...(images.length > 0 ? { images } : {}) };
}
-function queuedAgentMessagePreview(message: QueuedSessionInput): string {
- if (message.kind === "command") {
- return message.text;
- }
- if (message.customMessage && isAgentSessionMessage(message.customMessage)) {
- return `${AGENT_MESSAGE_RECEIVED_PREVIEW_LABEL}: ${message.customMessage.details.message}`;
+function queuedAgentMessagePreview(action: QueuedSessionAction): string {
+ const payload = action.payload;
+ if (payload.kind === "session_command") return payload.text;
+ if (payload.customMessage && isAgentSessionMessage(payload.customMessage)) {
+ return `${AGENT_MESSAGE_RECEIVED_PREVIEW_LABEL}: ${payload.customMessage.details.message}`;
}
- return queuedMessagePreview(message);
+ return payload.preview ?? payload.text;
}
const IPYTHON_SENT_AGENT_MESSAGE_CUSTOM_ENTRY = "ipython_sent_agent_message";
@@ -1019,9 +1033,8 @@ export class AgentSession {
private _eventListeners: AgentSessionEventListener[] = [];
private _agentEventQueue: Promise<void> = Promise.resolve();
- /** Session-owned typed queues. Items are never fed into Agent.steer/followUp. */
- private _steeringMessages: QueuedSessionInput[] = [];
- private _followUpMessages: QueuedSessionInput[] = [];
+ /** Session-owned actions. Items are never fed into Agent.steer/followUp. */
+ private readonly _actionStore = new ActionStore<QueuedSessionAction>();
private _sessionInputPump: Promise<void> = Promise.resolve();
private _sessionInputPumpRequested = false;
private _sessionInputPumpEpoch = 0;
@@ -1033,16 +1046,6 @@ export class AgentSession {
private _turnAdmissionOwner: symbol | undefined;
private readonly _turnAdmissionContext = new AsyncLocalStorage<symbol>();
private _pumpingSessionInput = false;
- private _activeSessionInput:
- | {
- kind: "prompt";
- lane: SessionInputSchedule;
- items: PreparedPromptInput[];
- phase: "preparing" | "handedOff";
- cancelled?: boolean;
- }
- | { kind: "command"; lane: SessionInputSchedule; item: PreparedCommandInput; phase: "executing" }
- | undefined;
private readonly _sessionInputCheckpointWaiters = new Set<() => void>();
/** Direct prompts between admission and agent handoff; restart checkpoints wait for zero. */
private _directPromptSectionCount = 0;
@@ -1396,8 +1399,8 @@ export class AgentSession {
private _emitQueueUpdate(): void {
this._emit({
type: "queue_update",
- steering: this._pendingSessionInputs("steer").map(queuedAgentMessagePreview),
- followUp: this._pendingSessionInputs("followUp").map(queuedAgentMessagePreview),
+ steering: this.legacyPendingProjection("next_turn_boundary").map(queuedAgentMessagePreview),
+ followUp: this.legacyPendingProjection("when_run_idle").map(queuedAgentMessagePreview),
});
}
@@ -1551,15 +1554,42 @@ export class AgentSession {
return goal;
}
+ private _cancelSessionActions(
+ predicate: (action: QueuedSessionAction) => boolean,
+ error: Error,
+ ): QueuedSessionAction[] {
+ const preparing = this._actionStore
+ .activeActions()
+ .filter(
+ (action): action is SessionAction<PreparedTurnPayload> =>
+ action.payload.kind === "turn" && action.lifecycle.state === "preparing",
+ );
+ const previousAnchor = preparing.at(-1);
+ const actions = this._actionStore.remove(predicate);
+ const removed = new Set(actions);
+ if (previousAnchor && removed.has(previousAnchor)) {
+ for (const action of preparing) {
+ if (!removed.has(action)) action.payload.prepared = undefined;
+ }
+ }
+ for (const action of actions) {
+ const ticket = this._actionStore.ticketFor(action);
+ ticket.settleDelivered({ status: "not_applicable" });
+ ticket.settleCompleted(error);
+ this._actionStore.releaseTerminal(action);
+ }
+ return actions;
+ }
+
private _clearQueuedGoalContexts(): void {
this.agent.removeQueuedMessages(
(message) => message.role === "custom" && message.customType === GOAL_CONTEXT_CUSTOM_TYPE,
);
- const isGoalContext = (input: QueuedSessionInput) =>
- input.kind === "prompt" && input.customMessage?.customType === GOAL_CONTEXT_CUSTOM_TYPE;
- this._removeActivePreparingPrompts(isGoalContext);
- this._steeringMessages = this._steeringMessages.filter((input) => !isGoalContext(input));
- this._followUpMessages = this._followUpMessages.filter((input) => !isGoalContext(input));
+ this._cancelSessionActions(
+ (action) =>
+ action.payload.kind === "turn" && action.payload.customMessage?.customType === GOAL_CONTEXT_CUSTOM_TYPE,
+ new Error("Queued goal context was cleared before delivery."),
+ );
this._emitQueueUpdate();
}
@@ -1854,13 +1884,11 @@ export class AgentSession {
resumeIfIdle: true,
});
} else {
- const input = this._createPreparedPromptInput(normalized.text, normalized.images, {
+ const action = this._createPreparedTurnAction("followUp", normalized.text, normalized.images, {
message,
resumeIfIdle: true,
});
- this._followUpMessages.unshift(input);
- this._sessionInputArrivalEpoch++;
- this._emitQueueUpdate();
+ this._enqueueSessionInput(action, { front: true, wake: false });
}
return;
}
@@ -1956,13 +1984,15 @@ export class AgentSession {
}
private get _steeringStopPending(): boolean {
- const activeSteeringHandoff =
- this._activeSessionInput?.kind === "prompt" &&
- this._activeSessionInput.lane === "steer" &&
- this._activeSessionInput.phase === "preparing" &&
- !this._activeSessionInput.cancelled &&
- this._activeSessionInput.items.length > 0;
- return this._steeringMessages.length > 0 || activeSteeringHandoff;
+ const activity = this._runtimeActivity(true);
+ if (shouldYieldLowerRun(this._actionStore, activity)) return true;
+ return this._actionStore
+ .activeActions("next_turn_boundary")
+ .some(
+ (action) =>
+ action.payload.kind === "turn" &&
+ (action.lifecycle.state === "selected" || action.lifecycle.state === "preparing"),
+ );
}
private _shouldStopBeforeTurn(): boolean {
@@ -2544,8 +2574,7 @@ export class AgentSession {
? autonomousMessage.content
: autonomousMessage.content.map((block) => (block.type === "text" ? block.text : "")).join("\n");
this._enqueueSessionInput(
- this._createPreparedPromptInput(text, undefined, { message: autonomousMessage }),
- "followUp",
+ this._createPreparedTurnAction("followUp", text, undefined, { message: autonomousMessage }),
);
return autonomousMessage;
}
@@ -2566,10 +2595,10 @@ export class AgentSession {
(message) => !queuedMessageSet.has(message),
);
this.agent.removeQueuedMessages((message) => queuedMessageSet.has(message));
- const isQueuedContinuation = (input: QueuedSessionInput) =>
- input.kind === "prompt" && queuedMessageSet.has(input.message);
- this._steeringMessages = this._steeringMessages.filter((input) => !isQueuedContinuation(input));
- this._followUpMessages = this._followUpMessages.filter((input) => !isQueuedContinuation(input));
+ this._cancelSessionActions(
+ (action) => action.payload.kind === "turn" && queuedMessageSet.has(primaryDeliveryRecord(action).message),
+ new Error("Queued autonomous continuation was cleared before delivery."),
+ );
this._emitQueueUpdate();
if (options.restoreAutonomousState) {
for (const queuedMessage of queuedMessages) {
@@ -3058,9 +3087,9 @@ export class AgentSession {
}
private _rejectQueuedAgentMessageDeliveries(deliveryError: Error, completionError = deliveryError): void {
- for (const message of [...this._steeringMessages, ...this._followUpMessages]) {
- this._settleAgentMessage(message.agentMessageId, "delivery", deliveryError);
- this._settleAgentMessage(message.agentMessageId, "completion", completionError);
+ for (const action of this._actionStore.unfinishedActions()) {
+ this._settleAgentMessage(action.agentMessageId, "delivery", deliveryError);
+ this._settleAgentMessage(action.agentMessageId, "completion", completionError);
}
}
@@ -3079,17 +3108,37 @@ export class AgentSession {
this._settleAgentMessage(acceptedPrompt.agentMessageId, "delivery");
acceptedPrompt.resolveAccepted();
}
- const activeInput =
- this._activeSessionInput?.kind === "prompt"
- ? this._activeSessionInput.items.find((input) => input.message === event.message)
- : undefined;
- this._settleAgentMessage(activeInput?.agentMessageId, "delivery");
+ if (event.message.role === "user" || event.message.role === "custom") {
+ for (const action of this._actionStore.activeActionsForMessage(event.message)) {
+ const record =
+ action.payload.kind === "turn"
+ ? action.payload.records.find((candidate) => candidate.message === event.message)
+ : undefined;
+ if (record) record.started = true;
+ if (record?.role === "primary") {
+ this._actionStore.ticketFor(action).settleDelivered({ status: "delivered" });
+ this._settleAgentMessage(action.agentMessageId, "delivery");
+ }
+ }
+ }
for (const observer of this._directDispatchObservers) {
if (observer.message === event.message) {
this._directDispatchObservers.delete(observer);
observer.resolve();
}
}
+ } else if (event.type === "message_end" && (event.message.role === "user" || event.message.role === "custom")) {
+ for (const action of this._actionStore.activeActionsForMessage(event.message)) {
+ const record =
+ action.payload.kind === "turn"
+ ? action.payload.records.find((candidate) => candidate.message === event.message)
+ : undefined;
+ if (record) record.durable = true;
+ if (record?.role === "primary" && action.lifecycle.state === "committing") {
+ transitionSessionAction(action, { state: "running", execution: "agent_turn" });
+ this._notifySessionInputCheckpointChange();
+ }
+ }
}
this._agentEventQueue = this._agentEventQueue.then(
() => this._processAgentEvent(event),
@@ -3725,8 +3774,7 @@ export class AgentSession {
if (outcome.delivery) this._settleAgentMessage(agentMessageId, "delivery", deliveryError);
if (outcome.completion) this._settleAgentMessage(agentMessageId, "completion", completionError);
}
- this._steeringMessages = [];
- this._followUpMessages = [];
+ this._cancelSessionActions(() => true, deliveryError);
this.agent.clearAllQueues();
this._extensionRunner.invalidate(
"This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().",
@@ -4325,6 +4373,7 @@ export class AgentSession {
previewLabel,
suppressAutonomousContinuation: options.suppressAutonomousContinuation,
resumeIfIdle: options.resumeIfIdle,
+ source: options.source ?? "internal",
});
return;
@@ -4390,6 +4439,7 @@ export class AgentSession {
previewLabel,
suppressAutonomousContinuation: options.suppressAutonomousContinuation,
resumeIfIdle: options.resumeIfIdle,
+ source: options.source ?? "internal",
});
} catch (error) {
// A failed enqueue must still settle the preflight outcome, or the
@@ -4504,18 +4554,14 @@ export class AgentSession {
this.hasAcceptedPromptInFlight ||
this._sessionInputPumpSuspended ||
this._queuedWorkPauses.size > 0 ||
- this._activeSessionInput !== undefined ||
+ this._actionStore.activeActions().length > 0 ||
this.pendingMessageCount > 0;
const schedule = options?.streamingBehavior ?? (this.isStreaming ? "steer" : "followUp");
const queued = this._enqueueSessionInput(
- {
- kind: "command",
- text: normalized.text,
- command: normalized.command,
- images: normalized.images,
+ this._createSessionCommandAction(normalized.text, normalized.command, normalized.images, schedule, {
agentMessageId: options?.agentMessageId,
- },
- schedule,
+ source: isInternalPrompt ? "internal" : (options?.source ?? "interactive"),
+ }),
);
reportPreflight(queued, queued);
releaseAdmission();
@@ -4560,6 +4606,7 @@ export class AgentSession {
suppressAutonomousContinuation: options.suppressAutonomousContinuation,
message: options.customMessage,
resumeIfIdle: options.resumeIfIdle,
+ source: isInternalPrompt ? "internal" : (options.source ?? "interactive"),
});
return;
@@ -4675,6 +4722,7 @@ export class AgentSession {
suppressAutonomousContinuation: options.suppressAutonomousContinuation,
message: options.customMessage,
resumeIfIdle: options.resumeIfIdle,
+ source: isInternalPrompt ? "internal" : (options.source ?? "interactive"),
});
} catch (error) {
// A failed enqueue must still settle the preflight outcome, or the
@@ -4890,18 +4938,28 @@ export class AgentSession {
return undefined;
}
return this._enqueueSessionInput(
- {
- kind: "command",
- text,
- command: customMessage.details.command,
- images,
+ this._createSessionCommandAction(text, customMessage.details.command, images, schedule, {
agentMessageId,
- },
- schedule,
+ source: "internal",
+ }),
{ restore: true },
);
}
+ private _restoreLegacyRecoveryPrompt(
+ schedule: SessionInputSchedule,
+ snapshot: QueuedAgentInputSnapshot,
+ ): Promise<boolean> {
+ return this._queuePreparedPrompt(schedule, snapshot.text, snapshot.images, {
+ queueKey: snapshot.queueKey,
+ agentMessageId: snapshot.agentMessageId,
+ content: snapshot.content,
+ message: snapshot.customMessage,
+ prefixMessages: snapshot.prefixMessages,
+ source: "internal",
+ });
+ }
+
async restoreSteeringMessage(
text: string,
images?: ImageContent[],
@@ -4918,11 +4976,13 @@ export class AgentSession {
)
return;
- await this._queuePreparedPrompt("steer", text, images, {
+ await this._restoreLegacyRecoveryPrompt("steer", {
+ text,
+ images,
queueKey: options.queueKey,
agentMessageId: options.agentMessageId,
content: options.content,
- message: options.customMessage,
+ customMessage: options.customMessage,
prefixMessages: options.prefixMessages,
});
}
@@ -4947,11 +5007,13 @@ export class AgentSession {
);
if (restoredCommand !== undefined) return restoredCommand;
- return this._queuePreparedPrompt("followUp", text, images, {
+ return this._restoreLegacyRecoveryPrompt("followUp", {
+ text,
+ images,
queueKey: options.queueKey,
agentMessageId: options.agentMessageId,
content: options.content,
- message: options.customMessage,
+ customMessage: options.customMessage,
prefixMessages: options.prefixMessages,
});
}
@@ -4959,9 +5021,7 @@ export class AgentSession {
private _buildPromptContent(text: string, images?: ImageContent[]): (TextContent | ImageContent)[] {
const content: (TextContent | ImageContent)[] = [];
content.push({ type: "text", text });
- if (images) {
- content.push(...images);
- }
+ if (images) content.push(...images);
return content;
}
@@ -4978,13 +5038,11 @@ export class AgentSession {
previewLabel?: string;
suppressAutonomousContinuation?: boolean;
resumeIfIdle?: boolean;
+ source?: InputSource | "internal";
} = {},
): Promise<void> {
const pendingNextTurnMessages = this._pendingNextTurnMessages;
this._pendingNextTurnMessages = [];
- // Preflight callbacks run outside the try: a throwing callback must not roll
- // back queue state for an input that was in fact enqueued (its prefixMessages
- // would be delivered twice).
let queued: boolean;
try {
queued = await this._queuePreparedPrompt(streamingBehavior, text, options.images, {
@@ -4995,10 +5053,9 @@ export class AgentSession {
previewLabel: options.previewLabel,
suppressAutonomousContinuation: options.suppressAutonomousContinuation,
resumeIfIdle: options.resumeIfIdle,
+ source: options.source,
});
- if (!queued) {
- this._pendingNextTurnMessages.unshift(...pendingNextTurnMessages);
- }
+ if (!queued) this._pendingNextTurnMessages.unshift(...pendingNextTurnMessages);
} catch (error) {
this._pendingNextTurnMessages.unshift(...pendingNextTurnMessages);
throw error;
@@ -5006,10 +5063,27 @@ export class AgentSession {
reportPreflight(queued, queued);
}
- /**
- * Internal: Queue a steering message (already expanded, no extension command check).
- */
- private _createPreparedPromptInput(
+ private _deliveryPolicy(schedule: SessionInputSchedule): DeliveryPolicy {
+ return schedule === "steer" ? "next_turn_boundary" : "when_run_idle";
+ }
+
+ private _createDeliveryRecord(
+ actionId: string,
+ role: DeliveryRecord["role"],
+ message: QueuedAgentMessage,
+ ): DeliveryRecord {
+ return {
+ id: randomUUID(),
+ role,
+ message,
+ started: false,
+ durable: false,
+ ownerActionId: actionId,
+ };
+ }
+
+ private _createPreparedTurnAction(
+ schedule: SessionInputSchedule,
text: string,
images: ImageContent[] | undefined,
options: {
@@ -5021,8 +5095,10 @@ export class AgentSession {
previewLabel?: string;
suppressAutonomousContinuation?: boolean;
resumeIfIdle?: boolean;
+ source?: InputSource | "internal";
},
- ): PreparedPromptInput {
+ ): QueuedSessionAction {
+ const id = randomUUID();
const content = options.content ?? this._buildPromptContent(text, images);
const message =
options.message ??
@@ -5031,56 +5107,105 @@ export class AgentSession {
content: content.map((block) => ({ ...block })),
timestamp: Date.now(),
} satisfies UserMessage);
- return {
- kind: "prompt",
+ const prefixMessages = options.prefixMessages?.map((prefix) => cloneCustomMessage(prefix)) ?? [];
+ const preview = options.previewLabel ? `${options.previewLabel}: ${text}` : undefined;
+ const payload: PreparedTurnPayload = {
+ kind: "turn",
text,
+ records: [
+ ...prefixMessages.map((prefix) => this._createDeliveryRecord(id, "prefix", prefix)),
+ this._createDeliveryRecord(id, "primary", message),
+ ],
+ preview,
images: images?.map((image) => ({ ...image })),
content: content.map((block) => ({ ...block })),
customMessage: options.message?.role === "custom" ? cloneCustomMessage(options.message) : undefined,
- previewLabel: options.previewLabel,
+ };
+ return {
+ id,
+ source: options.source ?? "internal",
+ delivery: this._deliveryPolicy(schedule),
+ wake:
+ options.resumeIfIdle === true
+ ? "immediate"
+ : schedule === "steer"
+ ? "on_lower_boundary"
+ : "external_resume",
+ payload,
+ lifecycle: { state: "queued" },
queueKey: options.queueKey,
agentMessageId: options.agentMessageId,
- prefixMessages: options.prefixMessages?.map((message) => cloneCustomMessage(message)) ?? [],
suppressAutonomousContinuation: options.suppressAutonomousContinuation,
- autoPump: options.resumeIfIdle === true,
- message,
};
}
- private _enqueueSessionInput(
- input: QueuedSessionInput,
+ private _createSessionCommandAction(
+ text: string,
+ command: SessionSlashCommand,
+ images: ImageContent[] | undefined,
schedule: SessionInputSchedule,
- options: { restore?: boolean } = {},
+ options: { agentMessageId?: string; source?: InputSource | "internal" } = {},
+ ): QueuedSessionAction {
+ return {
+ id: randomUUID(),
+ source: options.source ?? "internal",
+ delivery: this._deliveryPolicy(schedule),
+ wake: "immediate",
+ payload: { kind: "session_command", text, command, images },
+ lifecycle: { state: "queued" },
+ agentMessageId: options.agentMessageId,
+ };
+ }
+
+ private _coalescedFollowUpOwner(action: QueuedSessionAction): QueuedSessionAction | undefined {
+ if (action.delivery !== "when_run_idle" || action.payload.kind !== "turn" || !action.queueKey) return undefined;
+ return this._actionStore
+ .unfinishedActions("when_run_idle")
+ .find(
+ (candidate) =>
+ candidate.queueKey === action.queueKey &&
+ (candidate.lifecycle.state === "queued" ||
+ candidate.lifecycle.state === "selected" ||
+ candidate.lifecycle.state === "preparing"),
+ );
+ }
+
+ private _enqueueSessionInput(
+ action: QueuedSessionAction,
+ options: { restore?: boolean; front?: boolean; wake?: boolean } = {},
): boolean {
- const queue = schedule === "steer" ? this._steeringMessages : this._followUpMessages;
- const coalescedOwner =
- schedule === "followUp" && input.kind === "prompt" && input.queueKey
- ? (queue.find((item) => item.queueKey === input.queueKey) ??
- this._activePendingPromptWithQueueKey(input.queueKey))
- : undefined;
+ const coalescedOwner = this._coalescedFollowUpOwner(action);
if (coalescedOwner) {
- if (input.agentMessageId !== coalescedOwner.agentMessageId) {
+ if (action.agentMessageId !== coalescedOwner.agentMessageId) {
this._rejectAgentMessage(
- input.agentMessageId,
+ action.agentMessageId,
new Error("Prompt was not queued because an equivalent follow-up is already pending."),
);
}
return false;
}
- queue.push(input);
+ if (options.front) this._actionStore.enqueueFront(action);
+ else this._actionStore.enqueue(action);
+ this._actionStore.ticketFor(action).settleAccepted({
+ status: "accepted",
+ actionId: action.id,
+ disposition: "queued",
+ });
this._sessionInputArrivalEpoch++;
this._emitQueueUpdate();
if (
!options.restore &&
- ((schedule === "steer" && this.isStreaming) || input.kind === "command" || input.autoPump)
+ options.wake !== false &&
+ ((action.delivery === "next_turn_boundary" && this.isStreaming) ||
+ action.payload.kind === "session_command" ||
+ action.wake === "immediate")
) {
- if (input.kind === "prompt" && input.autoPump) this._sessionInputPumpSuspended = false;
+ if (action.payload.kind === "turn" && action.wake === "immediate") this._sessionInputPumpSuspended = false;
this._scheduleSessionInputPump();
}
return true;
}
- /** Queue a prepared prompt on one lane; steering always queues, follow-up may coalesce by queue key. */
private async _queuePreparedPrompt(
schedule: SessionInputSchedule,
text: string,
@@ -5094,18 +5219,38 @@ export class AgentSession {
previewLabel?: string;
suppressAutonomousContinuation?: boolean;
resumeIfIdle?: boolean;
+ source?: InputSource | "internal";
} = {},
): Promise<boolean> {
- const input = this._createPreparedPromptInput(text, images, options);
- if (options.suppressAutonomousContinuation) {
- this._markAutonomousContinuationSuppressed(input.message);
+ const action = this._createPreparedTurnAction(schedule, text, images, options);
+ if (action.suppressAutonomousContinuation) {
+ this._markAutonomousContinuationSuppressed(primaryDeliveryRecord(action).message);
}
- return this._enqueueSessionInput(input, schedule);
+ return this._enqueueSessionInput(action);
+ }
+
+ private _runtimeActivity(mandatoryCheckpointsComplete = true): RuntimeActivity {
+ return {
+ lowerAgentRun: this.isStreaming,
+ compaction: this.isCompacting,
+ retry: this.isRetrying,
+ bash: this.isBashRunning,
+ refinementApply: this._refineInFlight !== undefined,
+ branchMutation: this._branchSummaryOperation !== undefined || this._acceptedPromptCompletions.size > 0,
+ schedulerPauseCount: this._queuedWorkPauses.size + (this._sessionInputPumpSuspended ? 1 : 0),
+ disposing: this._disposed || this._disposing,
+ mandatoryCheckpointsComplete,
+ };
}
private _scheduleSessionInputPump(): void {
if (this._sessionInputPumpSuspended || this._queuedWorkPauses.size > 0) return;
- if (this._disposed || this._disposing || this._sessionInputPumpRequested || this.pendingMessageCount === 0) {
+ if (
+ this._disposed ||
+ this._disposing ||
+ this._sessionInputPumpRequested ||
+ this._actionStore.queuedActions().length === 0
+ ) {
return;
}
this._sessionInputPumpRequested = true;
@@ -5122,91 +5267,107 @@ export class AgentSession {
this._pumpingSessionInput = true;
let blocked = false;
try {
- while (!this._disposed && !this._disposing && this.pendingMessageCount > 0) {
+ while (!this._disposed && !this._disposing && this._actionStore.queuedActions().length > 0) {
const admission = await this._acquireTurnAdmission();
try {
await this.agent.waitForIdle();
if (epoch !== this._sessionInputPumpEpoch) return;
await this._agentEventQueue;
await this._waitForRefineIdle();
- if (this._isSessionInputHandoffDeferred(epoch)) {
+ if (this._isSessionInputHandoffDeferred(epoch) || !canSelectSessionAction(this._runtimeActivity())) {
blocked = true;
return;
}
- const queue = this._steeringMessages.length > 0 ? this._steeringMessages : this._followUpMessages;
- const mode = queue === this._steeringMessages ? this.steeringMode : this.followUpMode;
- const first = queue[0];
+ const first = this._actionStore.selectFirst();
if (!first) continue;
- const lane: SessionInputSchedule = queue === this._steeringMessages ? "steer" : "followUp";
- if (first.kind === "command") {
- queue.shift();
- this._activeSessionInput = { kind: "command", lane, item: first, phase: "executing" };
- this._notifySessionInputCheckpointChange();
- this._emitQueueUpdate();
- try {
- await this._executeQueuedSessionCommand(first);
- this._settleAgentMessage(first.agentMessageId, "completion");
- } catch (error) {
- this._rejectAgentMessage(first.agentMessageId, this._asError(error));
- } finally {
- this._activeSessionInput = undefined;
- this._notifySessionInputCheckpointChange();
- this._emitQueueUpdate();
- }
+ if (first.payload.kind === "session_command") {
+ await this._executeSelectedSessionCommand(first);
continue;
}
- const prompts: PreparedPromptInput[] = [];
- while (queue[0]?.kind === "prompt" && (mode === "all" || prompts.length === 0)) {
- prompts.push(queue.shift() as PreparedPromptInput);
+ const mode = first.delivery === "next_turn_boundary" ? this.steeringMode : this.followUpMode;
+ const actions: QueuedSessionAction[] = [first];
+ while (mode === "all") {
+ const next = this._actionStore.queuedActions(first.delivery)[0];
+ if (!next || next.payload.kind !== "turn") break;
+ this._actionStore.selectFirst();
+ actions.push(next);
}
if (epoch !== this._sessionInputPumpEpoch) {
- queue.unshift(...prompts);
+ for (const action of actions) this._actionStore.rollback(action);
return;
}
- this._activeSessionInput = {
- kind: "prompt",
- lane,
- items: prompts,
- phase: "preparing",
- };
+ for (const action of actions) transitionSessionAction(action, { state: "preparing" });
this._notifySessionInputCheckpointChange();
this._emitQueueUpdate();
try {
- await this._startPreparedPromptItems(prompts, epoch, admission.release);
- for (const prompt of prompts) {
- this._settleAgentMessage(prompt.agentMessageId, "completion");
+ await this._startPreparedTurnActions(actions, epoch, admission.release);
+ for (const action of actions) {
+ if (action.lifecycle.state === "committing") {
+ const primary = primaryDeliveryRecord(action);
+ if (this.agent.state.messages.includes(primary.message)) {
+ primary.durable = true;
+ transitionSessionAction(action, { state: "running", execution: "agent_turn" });
+ }
+ }
+ if (action.lifecycle.state === "running") {
+ transitionSessionAction(action, { state: "completed" });
+ this._actionStore.ticketFor(action).settleCompleted();
+ this._settleAgentMessage(action.agentMessageId, "completion");
+ }
}
} catch (error) {
- const delivered = new Set(this.agent.state.messages);
- const undelivered: PreparedPromptInput[] = [];
- for (const prompt of prompts) {
- prompt.prefixMessages = prompt.prefixMessages.filter((message) => !delivered.has(message));
- if (!delivered.has(prompt.message)) undelivered.push(prompt);
+ const transcript = this.agent.state.messages;
+ const delivered = new Set(transcript);
+ const undelivered: QueuedSessionAction[] = [];
+ for (const action of actions) {
+ if (action.payload.kind !== "turn" || action.lifecycle.state === "cancelled") continue;
+ for (const record of action.payload.records) record.durable = delivered.has(record.message);
+ action.payload.records = action.payload.records.filter((record) => {
+ if (record.role === "prefix") return !record.durable;
+ if (record.role === "next_turn") return record.durable;
+ return true;
+ });
+ if (!primaryDeliveryRecord(action).durable) undelivered.push(action);
}
if (this._isDeferredSessionInputError(error, epoch)) {
- if (!this._activeSessionInput?.cancelled && undelivered.length > 0) {
- queue.unshift(...undelivered);
- // Clear ownership before emitting so the requeued items are not
- // double-counted as both owned and queued.
- this._activeSessionInput = undefined;
- this._emitQueueUpdate();
+ for (const action of undelivered) {
+ if (action.lifecycle.state === "committing") {
+ this._actionStore.rollback(action, { dispatchSettled: true, transcript });
+ } else if (action.lifecycle.state === "preparing" || action.lifecycle.state === "selected") {
+ this._actionStore.rollback(action);
+ }
}
+ if (undelivered.length > 0) this._emitQueueUpdate();
blocked = true;
return;
}
const terminalError = this._asError(error);
- for (const prompt of undelivered) {
- this._settleAgentMessage(prompt.agentMessageId, "delivery", terminalError);
- }
- for (const prompt of prompts) {
- this._settleAgentMessage(prompt.agentMessageId, "completion", terminalError);
+ for (const action of actions) {
+ if (action.lifecycle.state === "cancelled") continue;
+ if (action.lifecycle.state !== "completed" && action.lifecycle.state !== "failed") {
+ transitionSessionAction(action, { state: "failed", error: terminalError });
+ }
+ if (undelivered.includes(action)) {
+ this._settleAgentMessage(action.agentMessageId, "delivery", terminalError);
+ }
+ this._settleAgentMessage(action.agentMessageId, "completion", terminalError);
+ this._actionStore.ticketFor(action).settleCompleted(terminalError);
}
this._surfaceSessionInputError(error);
} finally {
- this._activeSessionInput = undefined;
+ for (const action of actions) {
+ if (
+ action.lifecycle.state === "completed" ||
+ action.lifecycle.state === "failed" ||
+ action.lifecycle.state === "cancelled"
+ ) {
+ this._actionStore.releaseTerminal(action);
+ }
+ }
this._notifySessionInputCheckpointChange();
+ this._emitQueueUpdate();
}
} finally {
admission.release();
@@ -5214,18 +5375,35 @@ export class AgentSession {
}
} finally {
this._pumpingSessionInput = false;
- if (!blocked && epoch === this._sessionInputPumpEpoch && this.pendingMessageCount > 0) {
+ if (!blocked && epoch === this._sessionInputPumpEpoch && this._actionStore.queuedActions().length > 0) {
this._scheduleSessionInputPump();
}
}
}
- /**
- * Single busy truth table for turn-admission decision points:
- * "preflight" is queueIfBusy backpressure before pre-prompt work (streaming checked separately),
- * "handoff" re-checks adjacent to the agent.prompt() handoff (includes streaming),
- * "pump" is session-input pump deferral (adds lifecycle and pause state).
- */
+ private async _executeSelectedSessionCommand(action: QueuedSessionAction): Promise<void> {
+ if (action.payload.kind !== "session_command") throw new Error("Expected a selected session command");
+ transitionSessionAction(action, { state: "running", execution: "session_command" });
+ this._notifySessionInputCheckpointChange();
+ this._emitQueueUpdate();
+ try {
+ await this._executeQueuedSessionCommand(action);
+ transitionSessionAction(action, { state: "completed" });
+ this._actionStore.ticketFor(action).settleDelivered({ status: "not_applicable" });
+ this._actionStore.ticketFor(action).settleCompleted();
+ this._settleAgentMessage(action.agentMessageId, "completion");
+ } catch (error) {
+ const commandError = this._asError(error);
+ transitionSessionAction(action, { state: "failed", error: commandError });
+ this._actionStore.ticketFor(action).settleCompleted(commandError);
+ this._rejectAgentMessage(action.agentMessageId, commandError);
+ } finally {
+ this._actionStore.releaseTerminal(action);
+ this._notifySessionInputCheckpointChange();
+ this._emitQueueUpdate();
+ }
+ }
+
private _isBusyForSessionInput(
point: "preflight" | "handoff" | "pump",
ignoreAcceptedPrompt?: AcceptedAgentMessagePrompt,
@@ -5261,7 +5439,6 @@ export class AgentSession {
if (error instanceof DeferredSessionInputError) return true;
if (epoch !== this._sessionInputPumpEpoch) return true;
if (this._isBusyForSessionInput("pump")) {
- // Requeue, but surface the error: this was not a deliberate deferral.
this._surfaceSessionInputError(error);
return true;
}
@@ -5282,12 +5459,17 @@ export class AgentSession {
}
}
- private async _startPreparedPromptItems(
- prompts: PreparedPromptInput[],
+ private async _startPreparedTurnActions(
+ actions: QueuedSessionAction[],
epoch: number,
releaseAdmission: () => void,
): Promise<void> {
let nextTurnMessages: CustomMessage[] = [];
+ const activeTurns = () =>
+ actions.filter(
+ (action): action is SessionAction<PreparedTurnPayload> =>
+ action.payload.kind === "turn" && action.lifecycle.state === "preparing",
+ );
const preparation = await this._prepareForCommit(
{
initialRefineBarrier: "skip",
@@ -5302,36 +5484,37 @@ export class AgentSession {
}
},
prepare: async () => {
- while (!prompts.every((prompt) => prompt.preparation !== undefined)) {
+ while (activeTurns().some((action) => action.payload.prepared === undefined)) {
if (this._isSessionInputHandoffDeferred(epoch)) {
throw new DeferredSessionInputError("Session input paused before preparation");
}
- const preparationPrompt = prompts.at(-1);
- if (!preparationPrompt) return undefined;
+ const preparationAction = activeTurns().at(-1);
+ if (!preparationAction) return undefined;
const basePromptSnapshot = this._baseSystemPrompt;
const result = await this._extensionRunner.emitBeforeAgentStart(
- preparationPrompt.text,
- preparationPrompt.images,
+ preparationAction.payload.text,
+ preparationAction.payload.images,
basePromptSnapshot,
this._baseSystemPromptOptions,
);
- if (prompts.at(-1) !== preparationPrompt) continue;
- const preparation = { result, basePromptSnapshot };
- for (const prompt of prompts) prompt.preparation = preparation;
+ if (activeTurns().at(-1) !== preparationAction) continue;
+ const prepared = { result, basePromptSnapshot };
+ for (const action of activeTurns()) action.payload.prepared = prepared;
}
if (this._isSessionInputHandoffDeferred(epoch)) {
throw new DeferredSessionInputError("Session input paused before handoff");
}
- return prompts[0]?.preparation;
+ return activeTurns()[0]?.payload.prepared;
},
- shouldCommit: () => prompts.length > 0,
- commit: (preparation) => {
+ shouldCommit: () => activeTurns().length > 0,
+ commit: (prepared) => {
if (this._isSessionInputHandoffDeferred(epoch)) {
throw new DeferredSessionInputError("Session input paused before handoff");
}
- if (prompts.length === 0) return undefined;
- this._applyPreparedSystemPrompt(preparation, true);
- return preparation;
+ const turns = activeTurns();
+ if (turns.length === 0) return undefined;
+ this._applyPreparedSystemPrompt(prepared, true);
+ return prepared;
},
},
);
@@ -5342,29 +5525,32 @@ export class AgentSession {
if (this._isSessionInputHandoffDeferred(epoch)) {
throw new DeferredSessionInputError("Session input paused before handoff");
}
- if (prompts.length === 0) return;
- if (this.isStreaming) {
- // agent.prompt() would reject with its already-processing error; defer instead.
- throw new DeferredSessionInputError("Agent became active before session input handoff");
- }
+ const turns = activeTurns();
+ if (turns.length === 0) return;
+ if (this.isStreaming) throw new DeferredSessionInputError("Agent became active before session input handoff");
this._applyPreparedSystemPrompt(preparation, true);
- const messages: AgentMessage[] = [];
+ const preparedMessages: AgentMessage[] = [];
nextTurnMessages = this._pendingNextTurnMessages;
this._pendingNextTurnMessages = [];
- messages.push(...nextTurnMessages);
- for (const prompt of prompts) {
- messages.push(...prompt.prefixMessages, prompt.message);
- if (prompt.suppressAutonomousContinuation) {
- this._markAutonomousContinuationSuppressed(prompt.message);
- }
+ preparedMessages.push(...nextTurnMessages);
+ const first = turns[0];
+ if (first) {
+ first.payload.records.unshift(
+ ...nextTurnMessages.map((message) => this._createDeliveryRecord(first.id, "next_turn", message)),
+ );
}
- this._appendBeforeAgentStartMessages(messages, preparation.result);
- if (this._activeSessionInput?.kind === "prompt") {
- this._activeSessionInput.phase = "handedOff";
- this._notifySessionInputCheckpointChange();
- this._emitQueueUpdate();
+ for (const action of turns) {
+ preparedMessages.push(...actionPrefixMessages(action), primaryDeliveryRecord(action).message);
+ if (action.suppressAutonomousContinuation) {
+ this._markAutonomousContinuationSuppressed(primaryDeliveryRecord(action).message);
+ }
}
- dispatch = this._dispatchPromptWithFence(messages, prompts[prompts.length - 1]!.message, nextTurnMessages, {
+ this._appendBeforeAgentStartMessages(preparedMessages, preparation.result);
+ for (const action of turns) transitionSessionAction(action, { state: "committing" });
+ this._notifySessionInputCheckpointChange();
+ this._emitQueueUpdate();
+ const observedMessage = primaryDeliveryRecord(turns[turns.length - 1]!).message;
+ dispatch = this._dispatchPromptWithFence(preparedMessages, observedMessage, nextTurnMessages, {
releaseAdmission,
checkpointUntilDelivery: true,
cloneRestoredNextTurnMessages: false,
@@ -5372,11 +5558,13 @@ export class AgentSession {
await dispatch.promptPromise;
await this.waitForRetry();
await this._agentEventQueue;
- this._forgetConsumedPostCompactionContinuations(prompts.map((prompt) => prompt.message));
+ if (turns.some((action) => !this.agent.state.messages.includes(primaryDeliveryRecord(action).message))) {
+ throw new Error("Session input dispatch settled without durable delivery");
+ }
+ this._forgetConsumedPostCompactionContinuations(turns.map((action) => primaryDeliveryRecord(action).message));
} catch (error) {
- if (dispatch) {
- dispatch.restorePendingNextTurnMessages();
- } else {
+ if (dispatch) dispatch.restorePendingNextTurnMessages();
+ else {
const delivered = new Set(this.agent.state.messages);
this._pendingNextTurnMessages.unshift(...nextTurnMessages.filter((message) => !delivered.has(message)));
}
@@ -5384,9 +5572,12 @@ export class AgentSession {
}
}
- private async _executeQueuedSessionCommand(input: PreparedCommandInput): Promise<void> {
+ private async _executeQueuedSessionCommand(action: QueuedSessionAction): Promise<void> {
+ if (action.payload.kind !== "session_command") throw new Error("Expected a session command action");
+ const input = action.payload;
this._appendDurableSessionCommandMessage(input.text, input.command, false);
- this._settleAgentMessage(input.agentMessageId, "delivery");
+ this._actionStore.ticketFor(action).settleDelivered({ status: "not_applicable" });
+ this._settleAgentMessage(action.agentMessageId, "delivery");
try {
let resultText: string | undefined;
switch (input.command.name) {
@@ -5396,7 +5587,7 @@ export class AgentSession {
case "refine": {
const options = parseRefineCommandOptions(input.command.args);
const result = await this.refine(options, { skipAbort: true });
- const applied = result.appliedEdits.filter((edit) => edit.applied).length;
+ const applied = result.appliedEdits.filter((appliedEdit) => appliedEdit.applied).length;
resultText = `Refined continual harness state: ${applied} edit${applied === 1 ? "" : "s"} applied.`;
break;
}
@@ -5412,7 +5603,6 @@ export class AgentSession {
}
if (resultText) this._appendDurableSessionCommandMessage(resultText, input.command, true, false);
} catch (error) {
- // A skipped compaction is benign and already surfaced by compaction_end.
if (error instanceof CompactionSkippedError) return;
const commandError = error instanceof Error ? error : new Error(String(error));
try {
@@ -5594,106 +5784,67 @@ export class AgentSession {
* @returns Object with steering and followUp arrays
*/
clearQueue(): { steering: string[]; followUp: string[] } {
- const active =
- this._activeSessionInput?.kind === "prompt" &&
- this._activeSessionInput.phase === "preparing" &&
- !this._activeSessionInput.cancelled
- ? this._activeSessionInput
- : undefined;
- if (active) {
- active.cancelled = true;
+ const clearable = [...this._actionStore.clearableActions()];
+ if (clearable.some((action) => action.payload.kind === "turn" && action.lifecycle.state === "preparing")) {
this._sessionInputPumpEpoch++;
- const error = new Error("Queued prompt was cleared before delivery.");
- for (const input of active.items) {
- this._settleAgentMessage(input.agentMessageId, "delivery", error);
- this._settleAgentMessage(input.agentMessageId, "completion", error);
- }
}
- const activeTexts = active?.items.map((message) => message.text) ?? [];
- const steering = [
- ...(active?.lane === "steer" ? activeTexts : []),
- ...this._steeringMessages.map((message) => message.text),
- ];
- const followUp = [
- ...(active?.lane === "followUp" ? activeTexts : []),
- ...this._followUpMessages.map((message) => message.text),
- ];
- this._rejectQueuedAgentMessageDeliveries(new Error("Queued agent message was cleared before delivery."));
- this._steeringMessages = [];
- this._followUpMessages = [];
+ const steering = clearable
+ .filter((action) => action.delivery === "next_turn_boundary")
+ .map((action) => action.payload.text);
+ const followUp = clearable
+ .filter((action) => action.delivery === "when_run_idle")
+ .map((action) => action.payload.text);
+ const promptError = new Error("Queued prompt was cleared before delivery.");
+ const agentMessageError = new Error("Queued agent message was cleared before delivery.");
+ for (const action of clearable) {
+ const error =
+ action.payload.kind === "turn" && action.lifecycle.state === "preparing" ? promptError : agentMessageError;
+ this._settleAgentMessage(action.agentMessageId, "delivery", error);
+ this._settleAgentMessage(action.agentMessageId, "completion", error);
+ }
+ this._cancelSessionActions(() => true, agentMessageError);
this.agent.clearAllQueues();
this._emitQueueUpdate();
return { steering, followUp };
}
private _invalidateQueuedPromptPreparation(): void {
- for (const queue of [this._steeringMessages, this._followUpMessages]) {
- for (const input of queue) {
- if (input.kind === "prompt") input.preparation = undefined;
- }
- }
- }
-
- private _removeActivePreparingPrompts(predicate: (message: PreparedPromptInput) => boolean): {
- steering: PreparedPromptInput[];
- followUp: PreparedPromptInput[];
- } {
- const active = this._activeSessionInput;
- if (active?.kind !== "prompt" || active.phase !== "preparing") return { steering: [], followUp: [] };
- const removed = active.items.filter(predicate);
- if (removed.length === 0) return { steering: [], followUp: [] };
- const previousAnchor = active.items.at(-1);
- const removedSet = new Set(removed);
- active.items.splice(0, active.items.length, ...active.items.filter((message) => !removedSet.has(message)));
- if (active.items.at(-1) !== previousAnchor) {
- for (const message of active.items) message.preparation = undefined;
+ for (const action of this._actionStore.clearableActions()) {
+ if (action.payload.kind === "turn") action.payload.prepared = undefined;
}
- return active.lane === "steer" ? { steering: removed, followUp: [] } : { steering: [], followUp: removed };
}
clearQueuedUserMessagesMatching(predicate: (text: string) => boolean): { steering: string[]; followUp: string[] } {
- const steering = this._steeringMessages.filter(
- (message): message is PreparedPromptInput =>
- message.kind === "prompt" && message.agentMessageId !== undefined && predicate(message.text),
- );
- const followUp = this._followUpMessages.filter(
- (message): message is PreparedPromptInput =>
- message.kind === "prompt" && message.agentMessageId !== undefined && predicate(message.text),
- );
- const active = this._removeActivePreparingPrompts(
- (message) => message.agentMessageId !== undefined && predicate(message.text),
- );
- steering.push(...active.steering);
- followUp.push(...active.followUp);
+ const matching = this._actionStore
+ .clearableActions()
+ .filter(
+ (action) =>
+ action.payload.kind === "turn" && action.agentMessageId !== undefined && predicate(action.payload.text),
+ );
const accepted = this._acceptedAgentMessagePrompt;
const acceptedMatches =
accepted !== undefined && !accepted.turnStarted && !accepted.cleared && predicate(accepted.text);
- if (steering.length === 0 && followUp.length === 0 && !acceptedMatches) return { steering: [], followUp: [] };
- const steeringSet = new Set(steering);
- const followUpSet = new Set(followUp);
- this._steeringMessages = this._steeringMessages.filter(
- (message) => !steeringSet.has(message as PreparedPromptInput),
- );
- this._followUpMessages = this._followUpMessages.filter(
- (message) => !followUpSet.has(message as PreparedPromptInput),
- );
- for (const message of [...steering, ...followUp]) {
- this._rejectAgentMessage(
- message.agentMessageId,
- new Error("Queued agent message was cleared before delivery."),
- );
- }
- const removedSteering = steering.map((message) => message.text);
- const removedFollowUp = followUp.map((message) => message.text);
+ if (matching.length === 0 && !acceptedMatches) return { steering: [], followUp: [] };
+ const removedTexts = (delivery: DeliveryPolicy) =>
+ [
+ ...matching.filter((action) => action.delivery === delivery && action.lifecycle.state === "queued"),
+ ...matching.filter((action) => action.delivery === delivery && action.lifecycle.state !== "queued"),
+ ].map((action) => action.payload.text);
+ const removedSteering = removedTexts("next_turn_boundary");
+ const removedFollowUp = removedTexts("when_run_idle");
+ const error = new Error("Queued agent message was cleared before delivery.");
+ for (const action of matching) this._rejectAgentMessage(action.agentMessageId, error);
+ const matchingIds = new Set(matching.map((action) => action.id));
+ this._cancelSessionActions((action) => matchingIds.has(action.id), error);
if (acceptedMatches) {
accepted.cleared = true;
this.agent.state.messages = this.agent.state.messages.filter((message) => !accepted.messages.has(message));
this._pendingNextTurnMessages.unshift(
...undeliveredPendingNextTurnMessages(accepted).map((message) => ({ ...message })),
);
- const error = new Error("Accepted agent message was cleared before delivery.");
- this._rejectAgentMessage(accepted.agentMessageId, error);
- accepted.rejectAccepted(error);
+ const acceptedError = new Error("Accepted agent message was cleared before delivery.");
+ this._rejectAgentMessage(accepted.agentMessageId, acceptedError);
+ accepted.rejectAccepted(acceptedError);
this.agent.abort();
removedFollowUp.push(accepted.text);
}
@@ -5701,53 +5852,57 @@ export class AgentSession {
return { steering: removedSteering, followUp: removedFollowUp };
}
- /**
- * Items the pump moved out of the typed queues but has not yet delivered:
- * prompts still preparing and commands still executing. Once a prompt hands
- * off it reaches the transcript, so it stops counting as pending.
- */
- private _undeliveredActiveSessionInputs(lane: SessionInputSchedule): readonly QueuedSessionInput[] {
- const active = this._activeSessionInput;
- if (!active || active.lane !== lane) return [];
- if (active.kind === "command") return [active.item];
- return active.phase === "preparing" && !active.cancelled ? active.items : [];
- }
-
- private _pendingSessionInputs(lane: SessionInputSchedule): readonly QueuedSessionInput[] {
- const queue = lane === "steer" ? this._steeringMessages : this._followUpMessages;
- const owned = this._undeliveredActiveSessionInputs(lane);
- return owned.length === 0 ? queue : [...owned, ...queue];
+ /** Preserves the active-as-pending wire behavior until the PR 4 protocol break. */
+ private legacyPendingProjection(delivery: DeliveryPolicy): readonly QueuedSessionAction[] {
+ return this._actionStore.unfinishedActions(delivery).filter((action) => {
+ if (action.lifecycle.state === "queued") return true;
+ if (action.payload.kind === "session_command") {
+ return action.lifecycle.state === "selected" || action.lifecycle.state === "running";
+ }
+ return action.lifecycle.state === "selected" || action.lifecycle.state === "preparing";
+ });
}
- /** Number of pending messages (includes both steering and follow-up) */
get pendingMessageCount(): number {
- return this._pendingSessionInputs("steer").length + this._pendingSessionInputs("followUp").length;
+ return (
+ this.legacyPendingProjection("next_turn_boundary").length +
+ this.legacyPendingProjection("when_run_idle").length
+ );
}
- /** Get pending steering messages (read-only) */
getSteeringMessages(): readonly string[] {
- return this._pendingSessionInputs("steer").map((message) => message.text);
+ return this.legacyPendingProjection("next_turn_boundary").map((action) => action.payload.text);
}
getSteeringMessagePreviews(): readonly string[] {
- return this._pendingSessionInputs("steer").map(queuedAgentMessagePreview);
+ return this.legacyPendingProjection("next_turn_boundary").map(queuedAgentMessagePreview);
}
- /** Get pending follow-up messages (read-only) */
getFollowUpMessages(): readonly string[] {
- return this._pendingSessionInputs("followUp").map((message) => message.text);
+ return this.legacyPendingProjection("when_run_idle").map((action) => action.payload.text);
}
getFollowUpMessagePreviews(): readonly string[] {
- return this._pendingSessionInputs("followUp").map(queuedAgentMessagePreview);
+ return this.legacyPendingProjection("when_run_idle").map(queuedAgentMessagePreview);
+ }
+
+ private _sessionActionRecoverySnapshot(): SessionActionRecoverySnapshot {
+ return { actions: this._actionStore.snapshotActions() };
+ }
+
+ /** Private old-manifest adapter; deleted when PR 4 versions the recovery format. */
+ private _legacyRecoverySnapshots(delivery: DeliveryPolicy): readonly QueuedAgentInputSnapshot[] {
+ const recovery = this._sessionActionRecoverySnapshot().actions.filter((action) => action.delivery === delivery);
+ const legacy = this.legacyPendingProjection(delivery);
+ return (legacy.length === recovery.length ? recovery : legacy).map(createQueuedAgentInputSnapshot);
}
getSteeringQueueSnapshots(): readonly QueuedAgentInputSnapshot[] {
- return this._pendingSessionInputs("steer").map((message) => createQueuedAgentInputSnapshot(message));
+ return this._legacyRecoverySnapshots("next_turn_boundary");
}
getFollowUpQueueSnapshots(): readonly QueuedAgentInputSnapshot[] {
- return this._pendingSessionInputs("followUp").map((message) => createQueuedAgentInputSnapshot(message));
+ return this._legacyRecoverySnapshots("when_run_idle");
}
private _notifySessionInputCheckpointChange(): void {
@@ -5776,8 +5931,14 @@ export class AgentSession {
// An executing command was already shifted off the queue; the snapshot
// must wait for it or it vanishes from durable queued input.
while (
- (this._activeSessionInput?.kind === "prompt" && this._activeSessionInput.phase === "preparing") ||
- this._activeSessionInput?.kind === "command" ||
+ this._actionStore
+ .activeActions()
+ .some(
+ (action) =>
+ (action.payload.kind === "turn" &&
+ (action.lifecycle.state === "selected" || action.lifecycle.state === "preparing")) ||
+ (action.payload.kind === "session_command" && action.lifecycle.state === "running"),
+ ) ||
this._directPromptSectionCount > 0
) {
if (signal?.aborted) throw new Error("Update restart preparation cancelled");
@@ -5891,7 +6052,7 @@ export class AgentSession {
(options.allowStreaming === true && this.isStreaming) ||
options.allowPendingQueue === true ||
(this.pendingMessageCount === 0 &&
- this._activeSessionInput === undefined &&
+ this._actionStore.activeActions().length === 0 &&
!this._pumpingSessionInput &&
!this._sessionInputPumpRequested)
) {
@@ -5988,43 +6149,26 @@ export class AgentSession {
}
hasQueuedFollowUp(queueKey: string): boolean {
- return (
- this._followUpMessages.some((message) => message.queueKey === queueKey) ||
- this._activePendingPromptWithQueueKey(queueKey) !== undefined
- );
- }
-
- /**
- * The active-input prompt owning `queueKey` while it still counts as
- * pending. Once handed off it belongs to the running turn, so a same-key
- * follow-up must queue for the next turn instead of coalescing away.
- */
- private _activePendingPromptWithQueueKey(queueKey: string): PreparedPromptInput | undefined {
- const active = this._activeSessionInput;
- if (active?.kind !== "prompt" || active.phase !== "preparing" || active.cancelled) return undefined;
- return active.items.find((item) => item.queueKey === queueKey);
+ return this._actionStore
+ .unfinishedActions("when_run_idle")
+ .some(
+ (action) =>
+ action.queueKey === queueKey &&
+ (action.lifecycle.state === "queued" ||
+ action.lifecycle.state === "selected" ||
+ action.lifecycle.state === "preparing"),
+ );
}
removeQueuedFollowUp(queueKey: string): boolean {
- const removedSteering = this._steeringMessages.filter(
- (message): message is PreparedPromptInput => message.kind === "prompt" && message.queueKey === queueKey,
- );
- const removedFollowUp = this._followUpMessages.filter(
- (message): message is PreparedPromptInput => message.kind === "prompt" && message.queueKey === queueKey,
- );
- const active = this._removeActivePreparingPrompts((message) => message.queueKey === queueKey);
- removedSteering.push(...active.steering);
- removedFollowUp.push(...active.followUp);
- if (removedSteering.length === 0 && removedFollowUp.length === 0) return false;
- const removed = new Set<QueuedSessionInput>([...removedSteering, ...removedFollowUp]);
- this._steeringMessages = this._steeringMessages.filter((message) => !removed.has(message));
- this._followUpMessages = this._followUpMessages.filter((message) => !removed.has(message));
- for (const message of removed) {
- this._rejectAgentMessage(
- message.agentMessageId,
- new Error("Queued agent message was cleared before delivery."),
- );
- }
+ const matching = this._actionStore
+ .clearableActions()
+ .filter((action) => action.payload.kind === "turn" && action.queueKey === queueKey);
+ if (matching.length === 0) return false;
+ const error = new Error("Queued agent message was cleared before delivery.");
+ for (const action of matching) this._rejectAgentMessage(action.agentMessageId, error);
+ const ids = new Set(matching.map((action) => action.id));
+ this._cancelSessionActions((action) => ids.has(action.id), error);
this._emitQueueUpdate();
return true;
}
@@ -6831,10 +6975,10 @@ export class AgentSession {
this._scheduleAutoRefineAfterAgentEnd();
return;
}
- // An empty queue is not idle: the pump owns items moved into _activeSessionInput before handoff.
+ // An empty queue is not idle while the scheduler still owns active work.
if (
this.pendingMessageCount > 0 ||
- this._activeSessionInput !== undefined ||
+ this._actionStore.activeActions().length > 0 ||
this._pumpingSessionInput ||
this._sessionInputPumpRequested
) {
@@ -7601,7 +7745,9 @@ export class AgentSession {
const resumeAfterFailure = () => {
if (
reason === "requested" &&
- (shouldContinueAfterCompaction || this.agent.hasQueuedMessages() || this.pendingMessageCount > 0)
+ (shouldContinueAfterCompaction ||
+ this.agent.hasQueuedMessages() ||
+ this._actionStore.queuedActions().length > 0)
) {
this._schedulePostCompactionContinue();
}
@@ -7638,7 +7784,7 @@ export class AgentSession {
this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry, customInstructions });
// Queued work lives in both the agent queues and the session-owned queues.
- const hasQueuedMessages = this.agent.hasQueuedMessages() || this.pendingMessageCount > 0;
+ const hasQueuedMessages = this.agent.hasQueuedMessages() || this._actionStore.queuedActions().length > 0;
const willContinueAfterCompaction = willRetry || shouldContinueAfterCompaction || hasQueuedMessages;
if (willRetry) {
diff --git a/packages/coding-agent/src/core/session-action-store.ts b/packages/coding-agent/src/core/session-action-store.ts
new file mode 100644
index 0000000000..6f6a84b7c0
--- /dev/null
+++ b/packages/coding-agent/src/core/session-action-store.ts
@@ -0,0 +1,305 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { UserMessage } from "@earendil-works/pi-ai";
+import type { InputSource } from "./extensions/index.js";
+import type { CustomMessage } from "./messages.js";
+import type { SessionSlashCommand } from "./slash-commands.js";
+
+export type DeliveryPolicy = "next_turn_boundary" | "when_run_idle";
+export type WakePolicy = "immediate" | "on_lower_boundary" | "external_resume";
+
+export interface DeliveryRecord {
+ id: string;
+ role: "primary" | "prefix" | "next_turn";
+ message: UserMessage | CustomMessage;
+ started: boolean;
+ durable: boolean;
+ ownerActionId: string;
+}
+
+export interface SessionTurnPayload {
+ kind: "turn";
+ records: DeliveryRecord[];
+ text: string;
+ preview?: string;
+}
+
+export interface SessionCommandPayload {
+ kind: "session_command";
+ command: SessionSlashCommand;
+ text: string;
+}
+
+export type SessionActionPayload = SessionTurnPayload | SessionCommandPayload;
+
+export type ActionLifecycle =
+ | { state: "queued" }
+ | { state: "selected" }
+ | { state: "preparing"; preparation?: object }
+ | { state: "committing" }
+ | { state: "running"; execution: "agent_turn" | "session_command" }
+ | { state: "completed" }
+ | { state: "failed"; error: Error }
+ | { state: "cancelled" };
+
+export interface SessionAction<TPayload extends SessionActionPayload = SessionActionPayload> {
+ id: string;
+ source: InputSource | "internal";
+ delivery: DeliveryPolicy;
+ wake: WakePolicy;
+ payload: TPayload;
+ lifecycle: ActionLifecycle;
+ queueKey?: string;
+ agentMessageId?: string;
+ suppressAutonomousContinuation?: boolean;
+}
+
+export interface RollbackProof {
+ dispatchSettled: true;
+ transcript: readonly AgentMessage[];
+}
+
+const TERMINAL_STATES = new Set<ActionLifecycle["state"]>(["completed", "failed", "cancelled"]);
+const ACTIVE_STATES = new Set<ActionLifecycle["state"]>(["selected", "preparing", "committing", "running"]);
+const CLEARABLE_STATES = new Set<ActionLifecycle["state"]>(["queued", "selected", "preparing"]);
+
+const LEGAL_TRANSITIONS: Readonly<Record<ActionLifecycle["state"], ReadonlySet<ActionLifecycle["state"]>>> = {
+ queued: new Set(["selected", "failed", "cancelled"]),
+ selected: new Set(["queued", "preparing", "running", "failed", "cancelled"]),
+ preparing: new Set(["queued", "committing", "failed", "cancelled"]),
+ committing: new Set(["queued", "running", "failed", "cancelled"]),
+ running: new Set(["completed", "failed", "cancelled"]),
+ completed: new Set(),
+ failed: new Set(),
+ cancelled: new Set(),
+};
+
+function primaryRecords(action: SessionAction): readonly DeliveryRecord[] {
+ return action.payload.kind === "turn" ? action.payload.records.filter((record) => record.role === "primary") : [];
+}
+
+export function transitionSessionAction(
+ action: SessionAction,
+ next: ActionLifecycle,
+ options: { rollbackProof?: RollbackProof } = {},
+): void {
+ const previous = action.lifecycle.state;
+ if (!LEGAL_TRANSITIONS[previous].has(next.state)) {
+ throw new Error(`Illegal session action lifecycle transition: ${previous} -> ${next.state}`);
+ }
+ if (previous === "committing" && next.state === "queued") {
+ const proof = options.rollbackProof;
+ if (!proof?.dispatchSettled) {
+ throw new Error("Committing session action rollback requires a settled dispatch and transcript proof");
+ }
+ const transcript = new Set(proof.transcript);
+ if (primaryRecords(action).some((record) => transcript.has(record.message))) {
+ throw new Error("Cannot roll back a session action whose primary message is durable in the transcript");
+ }
+ }
+ action.lifecycle = next;
+}
+
+export type AdmissionDisposition = "starts_when_admitted" | "queued";
+export type SubmissionOutcome =
+ | { status: "accepted"; actionId: string; disposition: AdmissionDisposition }
+ | { status: "coalesced"; existingActionId: string }
+ | { status: "handled_without_turn" }
+ | { status: "extension_command"; completion: Promise<void> };
+export type DeliveryOutcome = { status: "delivered" } | { status: "not_applicable" };
+
+export interface ActionTicket {
+ id: string;
+ accepted: Promise<SubmissionOutcome>;
+ delivered: Promise<DeliveryOutcome>;
+ completed: Promise<void>;
+}
+
+interface Deferred<T> {
+ promise: Promise<T>;
+ settle(value: T): boolean;
+ reject(error: Error): boolean;
+}
+
+function createDeferred<T>(): Deferred<T> {
+ let settled = false;
+ let resolvePromise!: (value: T) => void;
+ let rejectPromise!: (error: Error) => void;
+ const promise = new Promise<T>((resolve, reject) => {
+ resolvePromise = resolve;
+ rejectPromise = reject;
+ });
+ void promise.catch(() => undefined);
+ return {
+ promise,
+ settle: (value) => {
+ if (settled) return false;
+ settled = true;
+ resolvePromise(value);
+ return true;
+ },
+ reject: (error) => {
+ if (settled) return false;
+ settled = true;
+ rejectPromise(error);
+ return true;
+ },
+ };
+}
+
+export class ActionTicketController {
+ readonly ticket: ActionTicket;
+ private readonly accepted = createDeferred<SubmissionOutcome>();
+ private readonly delivered = createDeferred<DeliveryOutcome>();
+ private readonly completed = createDeferred<void>();
+
+ constructor(id: string) {
+ this.ticket = {
+ id,
+ accepted: this.accepted.promise,
+ delivered: this.delivered.promise,
+ completed: this.completed.promise,
+ };
+ }
+
+ settleAccepted(outcome: SubmissionOutcome): boolean {
+ return this.accepted.settle(outcome);
+ }
+
+ settleDelivered(outcome: DeliveryOutcome): boolean {
+ return this.delivered.settle(outcome);
+ }
+
+ settleCompleted(error?: Error): boolean {
+ return error ? this.completed.reject(error) : this.completed.settle();
+ }
+}
+
+export class ActionStore<TAction extends SessionAction = SessionAction> {
+ private readonly nextTurnBoundary: TAction[] = [];
+ private readonly whenRunIdle: TAction[] = [];
+ private readonly tickets = new Map<string, ActionTicketController>();
+
+ enqueue(action: TAction): void {
+ this.assertNewAction(action);
+ this.list(action.delivery).push(action);
+ this.tickets.set(action.id, new ActionTicketController(action.id));
+ }
+
+ enqueueFront(action: TAction): void {
+ this.assertNewAction(action);
+ const list = this.list(action.delivery);
+ const firstQueued = list.findIndex((item) => item.lifecycle.state === "queued");
+ list.splice(firstQueued < 0 ? list.length : firstQueued, 0, action);
+ this.tickets.set(action.id, new ActionTicketController(action.id));
+ }
+
+ selectFirst(): TAction | undefined {
+ const action =
+ this.nextTurnBoundary.find((item) => item.lifecycle.state === "queued") ??
+ this.whenRunIdle.find((item) => item.lifecycle.state === "queued");
+ if (action) transitionSessionAction(action, { state: "selected" });
+ return action;
+ }
+
+ remove(predicate: (action: TAction) => boolean): TAction[] {
+ const removed = this.clearableActions().filter(predicate);
+ for (const action of removed) transitionSessionAction(action, { state: "cancelled" });
+ return removed;
+ }
+
+ rollback(action: TAction, proof?: RollbackProof): void {
+ transitionSessionAction(action, { state: "queued" }, { rollbackProof: proof });
+ }
+
+ queuedActions(policy?: DeliveryPolicy): readonly TAction[] {
+ return this.actions(policy).filter((action) => action.lifecycle.state === "queued");
+ }
+
+ clearableActions(policy?: DeliveryPolicy): readonly TAction[] {
+ return this.actions(policy).filter((action) => CLEARABLE_STATES.has(action.lifecycle.state));
+ }
+
+ snapshotActions(): readonly TAction[] {
+ return this.queuedActions();
+ }
+
+ unfinishedActions(policy?: DeliveryPolicy): readonly TAction[] {
+ return this.actions(policy).filter((action) => !TERMINAL_STATES.has(action.lifecycle.state));
+ }
+
+ activeActions(policy?: DeliveryPolicy): readonly TAction[] {
+ return this.actions(policy).filter((action) => ACTIVE_STATES.has(action.lifecycle.state));
+ }
+
+ queuePreview(policy: DeliveryPolicy): readonly string[] {
+ return this.queuedActions(policy).map((action) =>
+ action.payload.kind === "turn" ? (action.payload.preview ?? action.payload.text) : action.payload.text,
+ );
+ }
+
+ ticketFor(action: TAction): ActionTicketController {
+ const ticket = this.tickets.get(action.id);
+ if (!ticket) throw new Error(`Session action ${action.id} is not owned by this store`);
+ return ticket;
+ }
+
+ activeActionsForMessage(message: UserMessage | CustomMessage): readonly TAction[] {
+ return this.activeActions().filter(
+ (action) =>
+ action.payload.kind === "turn" && action.payload.records.some((record) => record.message === message),
+ );
+ }
+
+ releaseTerminal(action: TAction): void {
+ if (!TERMINAL_STATES.has(action.lifecycle.state)) {
+ throw new Error(`Cannot release nonterminal session action ${action.id}`);
+ }
+ const list = this.list(action.delivery);
+ const index = list.indexOf(action);
+ if (index >= 0) list.splice(index, 1);
+ this.tickets.delete(action.id);
+ }
+
+ private actions(policy?: DeliveryPolicy): readonly TAction[] {
+ if (policy) return this.list(policy);
+ return [...this.nextTurnBoundary, ...this.whenRunIdle];
+ }
+
+ private list(policy: DeliveryPolicy): TAction[] {
+ return policy === "next_turn_boundary" ? this.nextTurnBoundary : this.whenRunIdle;
+ }
+
+ private assertNewAction(action: TAction): void {
+ if (action.lifecycle.state !== "queued") throw new Error("Only queued session actions can be enqueued");
+ if (this.tickets.has(action.id)) throw new Error(`Duplicate session action id: ${action.id}`);
+ }
+}
+
+export interface RuntimeActivity {
+ lowerAgentRun: boolean;
+ compaction: boolean;
+ retry: boolean;
+ bash: boolean;
+ refinementApply: boolean;
+ branchMutation: boolean;
+ schedulerPauseCount: number;
+ disposing: boolean;
+ mandatoryCheckpointsComplete: boolean;
+}
+
+export function canSelectSessionAction(activity: RuntimeActivity): boolean {
+ return (
+ !activity.lowerAgentRun &&
+ !activity.compaction &&
+ !activity.retry &&
+ !activity.bash &&
+ !activity.refinementApply &&
+ !activity.branchMutation &&
+ activity.schedulerPauseCount === 0 &&
+ !activity.disposing
+ );
+}
+
+export function shouldYieldLowerRun(store: ActionStore, activity: RuntimeActivity): boolean {
+ return activity.mandatoryCheckpointsComplete && store.queuedActions("next_turn_boundary").length > 0;
+}
diff --git a/packages/coding-agent/test/session-action-store.test.ts b/packages/coding-agent/test/session-action-store.test.ts
new file mode 100644
index 0000000000..7dc46a78fc
--- /dev/null
+++ b/packages/coding-agent/test/session-action-store.test.ts
@@ -0,0 +1,233 @@
+import type { UserMessage } from "@earendil-works/pi-ai";
+import { describe, expect, it } from "vitest";
+import {
+ type ActionLifecycle,
+ ActionStore,
+ canSelectSessionAction,
+ type DeliveryPolicy,
+ type RuntimeActivity,
+ type SessionAction,
+ transitionSessionAction,
+} from "../src/core/session-action-store.js";
+
+let nextId = 0;
+
+function turn(text: string, delivery: DeliveryPolicy = "when_run_idle"): SessionAction {
+ const id = `action-${nextId++}`;
+ const message: UserMessage = { role: "user", content: text, timestamp: nextId };
+ return {
+ id,
+ source: "internal",
+ delivery,
+ wake: "external_resume",
+ payload: {
+ kind: "turn",
+ text,
+ records: [{ id: `record-${id}`, role: "primary", message, started: false, durable: false, ownerActionId: id }],
+ },
+ lifecycle: { state: "queued" },
+ };
+}
+
+function command(text: string, delivery: DeliveryPolicy = "when_run_idle"): SessionAction {
+ return {
+ id: `action-${nextId++}`,
+ source: "internal",
+ delivery,
+ wake: "immediate",
+ payload: {
+ kind: "session_command",
+ text,
+ command: { name: "compact", args: "", text },
+ },
+ lifecycle: { state: "queued" },
+ };
+}
+
+function selectBatch(store: ActionStore, mode: "one-at-a-time" | "all"): SessionAction[] {
+ const first = store.selectFirst();
+ if (!first) return [];
+ if (first.payload.kind === "session_command" || mode === "one-at-a-time") return [first];
+ const batch = [first];
+ while (store.queuedActions(first.delivery)[0]?.payload.kind === "turn") {
+ const next = store.selectFirst();
+ if (!next) break;
+ batch.push(next);
+ }
+ return batch;
+}
+
+function activity(overrides: Partial<RuntimeActivity> = {}): RuntimeActivity {
+ return {
+ lowerAgentRun: false,
+ compaction: false,
+ retry: false,
+ bash: false,
+ refinementApply: false,
+ branchMutation: false,
+ schedulerPauseCount: 0,
+ disposing: false,
+ mandatoryCheckpointsComplete: true,
+ ...overrides,
+ };
+}
+
+describe("ActionStore selection", () => {
+ it("uses structural policy priority and FIFO order within each policy", () => {
+ const store = new ActionStore();
+ const followUpOne = turn("f1");
+ const steerOne = turn("s1", "next_turn_boundary");
+ const followUpTwo = turn("f2");
+ const steerTwo = turn("s2", "next_turn_boundary");
+ for (const action of [followUpOne, steerOne, followUpTwo, steerTwo]) store.enqueue(action);
+
+ expect(store.selectFirst()).toBe(steerOne);
+ expect(store.selectFirst()).toBe(steerTwo);
+ expect(store.selectFirst()).toBe(followUpOne);
+ expect(store.selectFirst()).toBe(followUpTwo);
+ });
+
+ it("reads one/all mode at selection time and never batches across a command barrier or policy", () => {
+ const store = new ActionStore();
+ const first = turn("p1", "next_turn_boundary");
+ const second = turn("p2", "next_turn_boundary");
+ const barrier = command("/compact", "next_turn_boundary");
+ const afterBarrier = turn("p3", "next_turn_boundary");
+ const followUp = turn("f1");
+ for (const action of [first, second, barrier, afterBarrier, followUp]) store.enqueue(action);
+
+ const mode: "one-at-a-time" | "all" = "all";
+ expect(selectBatch(store, mode)).toEqual([first, second]);
+ expect(selectBatch(store, mode)).toEqual([barrier]);
+ expect(selectBatch(store, "one-at-a-time")).toEqual([afterBarrier]);
+ expect(selectBatch(store, mode)).toEqual([followUp]);
+ });
+
+ it("does not let an executing /compact see itself as a queued successor", () => {
+ const store = new ActionStore();
+ const compact = command("/compact");
+ store.enqueue(compact);
+ expect(store.selectFirst()).toBe(compact);
+ transitionSessionAction(compact, { state: "running", execution: "session_command" });
+
+ expect(store.queuedActions()).toEqual([]);
+ expect(store.activeActions()).toEqual([compact]);
+ });
+
+ it("supports front insertion without changing rollback-at-original-position", () => {
+ const store = new ActionStore();
+ const selected = turn("selected");
+ const tail = turn("tail");
+ store.enqueue(selected);
+ store.enqueue(tail);
+ expect(store.selectFirst()).toBe(selected);
+ const front = turn("goal context");
+ store.enqueueFront(front);
+
+ store.rollback(selected);
+ expect(store.queuedActions()).toEqual([selected, front, tail]);
+ });
+});
+
+describe("session action lifecycle", () => {
+ it("guards legal transitions and rejects post-dispatch rollback without non-delivery proof", () => {
+ const action = turn("hello");
+ transitionSessionAction(action, { state: "selected" });
+ transitionSessionAction(action, { state: "preparing" });
+ transitionSessionAction(action, { state: "committing" });
+
+ expect(() => transitionSessionAction(action, { state: "queued" })).toThrow(/transcript proof/);
+ const primary = action.payload.kind === "turn" ? action.payload.records[0] : undefined;
+ if (!primary) throw new Error("missing primary record");
+ expect(() =>
+ transitionSessionAction(
+ action,
+ { state: "queued" },
+ { rollbackProof: { dispatchSettled: true, transcript: [primary.message] } },
+ ),
+ ).toThrow(/durable/);
+ transitionSessionAction(
+ action,
+ { state: "queued" },
+ { rollbackProof: { dispatchSettled: true, transcript: [] } },
+ );
+ expect(action.lifecycle.state).toBe("queued");
+ });
+
+ it("enforces the complete legal-transition table", () => {
+ const states: ActionLifecycle["state"][] = [
+ "queued",
+ "selected",
+ "preparing",
+ "committing",
+ "running",
+ "completed",
+ "failed",
+ "cancelled",
+ ];
+ const legal: Record<ActionLifecycle["state"], readonly ActionLifecycle["state"][]> = {
+ queued: ["selected", "failed", "cancelled"],
+ selected: ["queued", "preparing", "running", "failed", "cancelled"],
+ preparing: ["queued", "committing", "failed", "cancelled"],
+ committing: ["queued", "running", "failed", "cancelled"],
+ running: ["completed", "failed", "cancelled"],
+ completed: [],
+ failed: [],
+ cancelled: [],
+ };
+ const lifecycle = (state: ActionLifecycle["state"]): ActionLifecycle => {
+ if (state === "running") return { state, execution: "agent_turn" };
+ if (state === "failed") return { state, error: new Error("failed") };
+ return { state };
+ };
+
+ for (const from of states) {
+ for (const to of states) {
+ const action = turn(`${from}-${to}`);
+ action.lifecycle = lifecycle(from);
+ const transition = () =>
+ transitionSessionAction(action, lifecycle(to), {
+ rollbackProof:
+ from === "committing" && to === "queued" ? { dispatchSettled: true, transcript: [] } : undefined,
+ });
+ if (legal[from].includes(to)) expect(transition).not.toThrow();
+ else expect(transition).toThrow(/Illegal/);
+ }
+ }
+ });
+
+ it("settles each ticket leg at most once", async () => {
+ const store = new ActionStore();
+ const action = turn("hello");
+ store.enqueue(action);
+ const controller = store.ticketFor(action);
+ expect(controller.settleAccepted({ status: "accepted", actionId: action.id, disposition: "queued" })).toBe(true);
+ expect(controller.settleAccepted({ status: "coalesced", existingActionId: action.id })).toBe(false);
+ expect(controller.settleDelivered({ status: "delivered" })).toBe(true);
+ expect(controller.settleDelivered({ status: "not_applicable" })).toBe(false);
+ expect(controller.settleCompleted()).toBe(true);
+ expect(controller.settleCompleted(new Error("late"))).toBe(false);
+
+ await expect(controller.ticket.accepted).resolves.toMatchObject({ status: "accepted" });
+ await expect(controller.ticket.delivered).resolves.toEqual({ status: "delivered" });
+ await expect(controller.ticket.completed).resolves.toBeUndefined();
+ });
+});
+
+describe("scheduler capabilities", () => {
+ it("blocks selection for each overlapping runtime owner", () => {
+ expect(canSelectSessionAction(activity())).toBe(true);
+ for (const blocked of [
+ { lowerAgentRun: true },
+ { compaction: true },
+ { retry: true },
+ { bash: true },
+ { refinementApply: true },
+ { branchMutation: true },
+ { schedulerPauseCount: 1 },
+ { disposing: true },
+ ]) {
+ expect(canSelectSessionAction(activity(blocked))).toBe(false);
+ }
+ });
+});
diff --git a/packages/coding-agent/test/suite/agent-session-compaction.test.ts b/packages/coding-agent/test/suite/agent-session-compaction.test.ts
index c159629dad..035ad18850 100644
--- a/packages/coding-agent/test/suite/agent-session-compaction.test.ts
+++ b/packages/coding-agent/test/suite/agent-session-compaction.test.ts
@@ -817,12 +817,13 @@ describe("AgentSession compaction characterization", () => {
_schedulePostCompactionContinue(): void;
_postCompactionContinuationMessages: AgentMessage[];
_postCompactionContinuationScheduled: boolean;
- _createPreparedPromptInput(
+ _createPreparedTurnAction(
+ schedule: "followUp",
text: string,
images: undefined,
options: { message?: AgentMessage; resumeIfIdle: boolean },
): unknown;
- _enqueueSessionInput(input: unknown, schedule: "followUp"): boolean;
+ _enqueueSessionInput(action: unknown): boolean;
};
const continuation = {
role: "user",
@@ -832,11 +833,10 @@ describe("AgentSession compaction characterization", () => {
if (tracked) sessionInternals._postCompactionContinuationMessages = [continuation];
harness.setResponses([fauxAssistantMessage(response)]);
sessionInternals._enqueueSessionInput(
- sessionInternals._createPreparedPromptInput(text, undefined, {
+ sessionInternals._createPreparedTurnAction("followUp", text, undefined, {
...(tracked && { message: continuation }),
resumeIfIdle: tracked,
}),
- "followUp",
);
const continueSpy = vi.spyOn(harness.session.agent, "continue");
diff --git a/packages/coding-agent/test/suite/agent-session-prompt.test.ts b/packages/coding-agent/test/suite/agent-session-prompt.test.ts
index f4a58ba464..748fe1a9b6 100644
--- a/packages/coding-agent/test/suite/agent-session-prompt.test.ts
+++ b/packages/coding-agent/test/suite/agent-session-prompt.test.ts
@@ -1476,10 +1476,16 @@ stale post-hook extension instructions`,
await harness.session.followUp("handed off", undefined, { resumeIfIdle: true });
pause.release();
await vi.waitFor(() => {
- const active = (harness.session as unknown as { _activeSessionInput?: { kind: string; phase?: string } })
- ._activeSessionInput;
- expect(active?.kind).toBe("prompt");
- expect(active?.phase).toBe("handedOff");
+ const store = (
+ harness.session as unknown as {
+ _actionStore: {
+ activeActions(): readonly { lifecycle: { state: string }; payload: { kind: string } }[];
+ };
+ }
+ )._actionStore;
+ const active = store.activeActions()[0];
+ expect(active?.payload.kind).toBe("turn");
+ expect(active?.lifecycle.state).toBe("committing");
});
let checkpointReleased = false;
diff --git a/packages/coding-agent/test/suite/agent-session-queue.test.ts b/packages/coding-agent/test/suite/agent-session-queue.test.ts
index 1cab98badd..2401fa008a 100644
--- a/packages/coding-agent/test/suite/agent-session-queue.test.ts
+++ b/packages/coding-agent/test/suite/agent-session-queue.test.ts
@@ -696,16 +696,19 @@ describe("AgentSession queue characterization", () => {
withStreaming(harness, false);
await vi.waitFor(() => expect(pause).toBeDefined());
await harness.session.waitForSessionInputIdle();
- const queued = (harness.session as unknown as { _followUpMessages: { preparation?: unknown }[] })
- ._followUpMessages;
- await vi.waitFor(() => expect(queued[0]?.preparation).toBeDefined());
+ const store = (
+ harness.session as unknown as {
+ _actionStore: { queuedActions(): readonly { payload: { prepared?: unknown } }[] };
+ }
+ )._actionStore;
+ await vi.waitFor(() => expect(store.queuedActions()[0]?.payload.prepared).toBeDefined());
const navigation = harness.session.navigateTree(target!.id, { summarize: false });
pause?.release();
pause = undefined;
await navigation;
- expect(queued[0]?.preparation).toBeUndefined();
+ expect(store.queuedActions()[0]?.payload.prepared).toBeUndefined();
});
it.each([
diff --git a/packages/coding-agent/test/suite/agent-session-serialized-refine.test.ts b/packages/coding-agent/test/suite/agent-session-serialized-refine.test.ts
index 89009aa61f..ad721c3862 100644
--- a/packages/coding-agent/test/suite/agent-session-serialized-refine.test.ts
+++ b/packages/coding-agent/test/suite/agent-session-serialized-refine.test.ts
@@ -25,7 +25,13 @@ type SerializedInternals = {
abort: AbortController,
): Promise<unknown>;
_serializedRefine: boolean;
- _steeringMessages: unknown[];
+ _createPreparedTurnAction(
+ schedule: "steer",
+ text: string,
+ images: undefined,
+ options: Record<string, never>,
+ ): unknown;
+ _enqueueSessionInput(action: unknown): boolean;
_pendingRequestedRefine: { instructions?: string; global?: boolean } | undefined;
_assistantTurnsSinceAutoRefine: number;
_lastAutoRefineReviewAt: number;
@@ -310,12 +316,7 @@ describe("Serialized agent-callable refine", () => {
const internals = harness.session as unknown as SerializedInternals;
const { applyRefine } = mockSerializedRefine(harness);
internals._pendingRequestedRefine = { instructions: "capture a lesson" };
- internals._steeringMessages.push({
- kind: "prompt",
- text: "steer",
- prefixMessages: [],
- message: { role: "user", content: "steer" },
- });
+ internals._enqueueSessionInput(internals._createPreparedTurnAction("steer", "steer", undefined, {}));
const compactionSpy = vi
.spyOn(
internals as unknown as { _shouldStopForThresholdCompaction: (ctx: unknown) => Promise<boolean> },
@@ -1710,12 +1711,7 @@ describe("P0 concurrency regressions", () => {
});
harnesses.push(harness);
const internals = harness.session as unknown as SerializedInternals;
- internals._steeringMessages.push({
- kind: "prompt",
- text: "steer",
- prefixMessages: [],
- message: { role: "user", content: "steer" },
- });
+ internals._enqueueSessionInput(internals._createPreparedTurnAction("steer", "steer", undefined, {}));
let planResolved = false;
let applyFinished = false;
diff --git a/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.ts b/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.ts
index a739109da6..f6f4dfbc98 100644
--- a/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.ts
+++ b/packages/coding-agent/test/suite/regressions/4257-update-restart-resume.test.ts
@@ -53,20 +53,6 @@ type AgentDaemonUpdateInternals = {
};
type QueueInternals = {
- _steeringMessages: Array<{
- text: string;
- queueKey?: string;
- agentMessageId?: string;
- prefixMessages: CustomMessage[];
- message: UserMessage | CustomMessage;
- }>;
- _followUpMessages: Array<{
- text: string;
- queueKey?: string;
- agentMessageId?: string;
- prefixMessages: CustomMessage[];
- message: UserMessage | CustomMessage;
- }>;
_pendingNextTurnMessages: CustomMessage[];
_acceptedAgentMessagePrompt?: {
text: string;
diff --git a/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.ts b/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.ts
index 7f2d173c2a..95d4ee9af9 100644
--- a/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.ts
+++ b/packages/coding-agent/test/suite/regressions/4482-heartbeat-injected-prompt.test.ts
@@ -303,21 +303,7 @@ describe("ENG-4482 heartbeat injected prompt UI", () => {
await harness.session.promptHeartbeat(createHeartbeat(), { streamingBehavior: "followUp" });
expect(harness.session.getFollowUpMessagePreviews()).toEqual([heartbeatPreview]);
- const internals = harness.session as unknown as {
- _activeSessionInput: {
- kind: "prompt";
- lane: "followUp";
- phase: "preparing";
- items: Array<{ text: string }>;
- };
- };
- internals._activeSessionInput = {
- kind: "prompt",
- lane: "followUp",
- phase: "preparing",
- items: [{ text: "preparing" }],
- };
- expect(harness.session.clearQueue()).toEqual({ steering: [], followUp: ["preparing", heartbeatText] });
+ expect(harness.session.clearQueue()).toEqual({ steering: [], followUp: [heartbeatText] });
releaseToolExecution?.();
await promptPromise;