Skip to content

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

Rust

refactor(coding-agent): extract session action contract helpers (#572)

Sebastian Müller387ca6af6b56
diff --git a/packages/agent/test/agent.test.ts b/packages/agent/test/agent.test.ts
index dbe5cceb32..4bbe248d6c 100644
--- a/packages/agent/test/agent.test.ts
+++ b/packages/agent/test/agent.test.ts
@@ -157,6 +157,31 @@ describe("Agent", () => {
expect(agent.state.isStreaming).toBe(false);
});
+ it("can commit only a prefix of a prompt batch when a listener fails", async () => {
+ const agent = new Agent();
+ const first: AgentMessage = {
+ role: "user",
+ content: [{ type: "text", text: "first" }],
+ timestamp: Date.now(),
+ };
+ const second: AgentMessage = {
+ role: "user",
+ content: [{ type: "text", text: "second" }],
+ timestamp: Date.now(),
+ };
+ agent.subscribe((event) => {
+ if (event.type === "message_end" && event.message === first) {
+ throw new Error("listener failed between batched messages");
+ }
+ });
+
+ await agent.prompt([first, second]);
+
+ expect(agent.state.messages).toContain(first);
+ expect(agent.state.messages).not.toContain(second);
+ expect(agent.state.errorMessage).toBe("listener failed between batched messages");
+ });
+
it("waitForIdle should wait for async subscribers", async () => {
const barrier = createDeferred();
const agent = new Agent({
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index 6c1ff7e91b..74cc3a8899 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -530,6 +530,48 @@ interface InternalPromptOptions extends PromptOptions {
agentMessageId?: string;
}
+type SubmissionExtensionCommandPolicy = "execute" | "reject" | "ignore";
+
+interface SubmissionNormalizationPolicy {
+ parseSessionCommands: boolean;
+ extensionCommands: SubmissionExtensionCommandPolicy;
+ inputSource?: InputSource;
+ expandSkills: boolean;
+ expandPromptTemplates: boolean;
+}
+
+type NormalizedSubmission =
+ | { kind: "prompt"; text: string; images?: ImageContent[] }
+ | { kind: "sessionCommand"; text: string; images?: ImageContent[]; command: SessionSlashCommand }
+ | { kind: "extensionCommand"; completion: Promise<void> }
+ | { kind: "handled" };
+
+type PreTurnCompactionTiming = "beforeModelSelection" | "afterModelSelection" | "skip";
+type RefineBarrierPolicy = "always" | "ifInFlight" | "skip";
+
+interface CommitPreparationPolicy {
+ initialRefineBarrier: RefineBarrierPolicy;
+ flushPendingBashBeforeValidation: boolean;
+ preTurnCompaction: PreTurnCompactionTiming;
+ finalRefineBarrier: RefineBarrierPolicy;
+}
+
+interface CommitPreparationSteps<TPrepared, TCommitted> {
+ afterValidation?: () => void;
+ prepare: () => Promise<TPrepared>;
+ shouldCommit?: (prepared: TPrepared) => boolean;
+ beforeFinalRefineBarrier?: (prepared: TPrepared) => void;
+ commit: (prepared: TPrepared, passedFinalRefineBarrier: boolean) => TCommitted;
+}
+
+interface PromptDispatchFence {
+ promptPromise: Promise<void>;
+ deliveryObserved?: Promise<true>;
+ wasDeliveryObserved(): boolean;
+ stopDeliveryObservation(): void;
+ restorePendingNextTurnMessages(isDelivered?: (message: CustomMessage) => boolean): void;
+}
+
type QueuedAgentMessage = UserMessage | CustomMessage;
type SessionInputSchedule = "steer" | "followUp";
@@ -3985,6 +4027,149 @@ export class AgentSession {
return extensionPrompt.replace(baseSnapshot, () => this._baseSystemPrompt);
}
+ private _finishSubmissionNormalization(
+ text: string,
+ images: ImageContent[] | undefined,
+ policy: SubmissionNormalizationPolicy,
+ ): NormalizedSubmission {
+ let expandedText = text;
+ if (policy.expandSkills) expandedText = this._expandSkillCommand(expandedText);
+ if (policy.expandPromptTemplates) {
+ expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+ }
+ return { kind: "prompt", text: expandedText, images };
+ }
+
+ private _normalizeSubmission(
+ text: string,
+ images: ImageContent[] | undefined,
+ policy: SubmissionNormalizationPolicy,
+ ): NormalizedSubmission | Promise<NormalizedSubmission> {
+ if (policy.parseSessionCommands) {
+ const command = parseSessionSlashCommand(text);
+ if (command) return { kind: "sessionCommand", text, images, command };
+ }
+
+ if (text.startsWith("/")) {
+ if (policy.extensionCommands === "execute") {
+ const completion = this._executeExtensionCommand(text);
+ if (completion) return { kind: "extensionCommand", completion };
+ } else if (policy.extensionCommands === "reject") {
+ this._throwIfExtensionCommand(text);
+ }
+ }
+
+ if (policy.inputSource !== undefined && this._extensionRunner.hasHandlers("input")) {
+ return this._extensionRunner.emitInput(text, images, policy.inputSource).then((result) => {
+ if (result.action === "handled") return { kind: "handled" };
+ if (result.action === "transform") {
+ return this._finishSubmissionNormalization(result.text, result.images ?? images, policy);
+ }
+ return this._finishSubmissionNormalization(text, images, policy);
+ });
+ }
+
+ return this._finishSubmissionNormalization(text, images, policy);
+ }
+
+ private async _runPreTurnCompaction(): Promise<void> {
+ const lastAssistant = this._findLastAssistantMessage();
+ if (lastAssistant) await this._checkCompaction(lastAssistant, false, false);
+ }
+
+ private async _prepareForCommit<TPrepared, TCommitted>(
+ policy: CommitPreparationPolicy,
+ steps: CommitPreparationSteps<TPrepared, TCommitted>,
+ ): Promise<TCommitted | undefined> {
+ if (
+ policy.initialRefineBarrier === "always" ||
+ (policy.initialRefineBarrier === "ifInFlight" && this._refineInFlight)
+ ) {
+ await this._waitForRefineIdle();
+ }
+ if (policy.flushPendingBashBeforeValidation) this._flushPendingBashMessages();
+ await this._validateCanStartAgentRun();
+ steps.afterValidation?.();
+ if (!policy.flushPendingBashBeforeValidation) this._flushPendingBashMessages();
+
+ if (policy.preTurnCompaction === "beforeModelSelection") await this._runPreTurnCompaction();
+ const pendingModelSelectEmit = this._pendingModelSelectEmit();
+ if (pendingModelSelectEmit) await pendingModelSelectEmit;
+ if (policy.preTurnCompaction === "afterModelSelection") await this._runPreTurnCompaction();
+
+ const prepared = await steps.prepare();
+ if (steps.shouldCommit && !steps.shouldCommit(prepared)) return undefined;
+ steps.beforeFinalRefineBarrier?.(prepared);
+ let passedFinalRefineBarrier = false;
+ if (
+ policy.finalRefineBarrier === "always" ||
+ (policy.finalRefineBarrier === "ifInFlight" && this._refineInFlight)
+ ) {
+ await this._waitForRefineIdle();
+ passedFinalRefineBarrier = true;
+ }
+ return steps.commit(prepared, passedFinalRefineBarrier);
+ }
+
+ private _applyPreparedSystemPrompt(
+ preparation: PreparedPromptPreparation | undefined,
+ preserveEmptyExtensionPrompt: boolean,
+ ): void {
+ const extensionPrompt = preparation?.result?.systemPrompt;
+ const hasExtensionPrompt = preserveEmptyExtensionPrompt
+ ? extensionPrompt !== undefined
+ : Boolean(extensionPrompt);
+ this.agent.state.systemPrompt =
+ hasExtensionPrompt && extensionPrompt !== undefined && preparation !== undefined
+ ? this._refreshExtensionSystemPrompt(extensionPrompt, preparation.basePromptSnapshot)
+ : this._baseSystemPrompt;
+ }
+
+ private _dispatchPromptWithFence(
+ messages: AgentMessage[],
+ observedMessage: AgentMessage | undefined,
+ pendingNextTurnMessages: CustomMessage[],
+ options: {
+ releaseAdmission: () => void;
+ suppressAutonomousContinuation?: boolean;
+ checkpointUntilDelivery?: boolean;
+ cloneRestoredNextTurnMessages?: boolean;
+ },
+ ): PromptDispatchFence {
+ const dispatchObserver = observedMessage ? this._observeDirectDispatch(observedMessage) : undefined;
+ const endCheckpointSection = options.checkpointUntilDelivery ? this._enterDirectPromptSection() : undefined;
+ const promptPromise = options.suppressAutonomousContinuation
+ ? this._runWithAutonomousContinuationSuppressed(() => this.agent.prompt(messages))
+ : this.agent.prompt(messages);
+ options.releaseAdmission();
+
+ if (endCheckpointSection && dispatchObserver) {
+ const settleCheckpointSection = () => {
+ dispatchObserver.stop();
+ endCheckpointSection();
+ };
+ void Promise.race([promptPromise.catch(() => undefined), dispatchObserver.observed]).then(
+ settleCheckpointSection,
+ settleCheckpointSection,
+ );
+ }
+
+ return {
+ promptPromise,
+ deliveryObserved: dispatchObserver?.observed,
+ wasDeliveryObserved: () => dispatchObserver?.wasObserved() ?? false,
+ stopDeliveryObservation: () => dispatchObserver?.stop(),
+ restorePendingNextTurnMessages: (isDelivered = (message) => this.agent.state.messages.includes(message)) => {
+ const undelivered = pendingNextTurnMessages.filter((message) => !isDelivered(message));
+ this._pendingNextTurnMessages.unshift(
+ ...(options.cloneRestoredNextTurnMessages === false
+ ? undelivered
+ : undelivered.map((message) => ({ ...message }))),
+ );
+ },
+ };
+ }
+
/**
* Send a prompt to the agent.
* - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming
@@ -4120,9 +4305,8 @@ export class AgentSession {
let messages: AgentMessage[] | undefined;
let drainedNextTurnMessages: CustomMessage[] = [];
+ let preparation: PreparedPromptPreparation | undefined;
const previewLabel = injectedMessagePreviewLabel(message);
- let extensionResult: Awaited<ReturnType<typeof this._extensionRunner.emitBeforeAgentStart>> | undefined;
- let basePromptSnapshot: string | undefined;
try {
const shouldQueueForStreaming = this.isStreaming;
const shouldQueueForPendingWork = options?.queueIfBusy === true && this._isBusyForSessionInput("preflight");
@@ -4146,36 +4330,36 @@ export class AgentSession {
return;
}
- await this._waitForRefineIdle();
- this._flushPendingBashMessages();
- await this._validateCanStartAgentRun();
-
- const lastAssistant = this._findLastAssistantMessage();
- if (lastAssistant) {
- await this._checkCompaction(lastAssistant, false, false);
- }
-
- const pendingModelSelectEmit = this._pendingModelSelectEmit();
- if (pendingModelSelectEmit) {
- await pendingModelSelectEmit;
- }
-
- drainedNextTurnMessages = this._pendingNextTurnMessages;
- this._pendingNextTurnMessages = [];
- messages = [...drainedNextTurnMessages, message];
-
- basePromptSnapshot = this._baseSystemPrompt;
- extensionResult = await this._extensionRunner.emitBeforeAgentStart(
- text,
- undefined,
- basePromptSnapshot,
- this._baseSystemPromptOptions,
+ messages = await this._prepareForCommit(
+ {
+ initialRefineBarrier: "always",
+ flushPendingBashBeforeValidation: true,
+ preTurnCompaction: "beforeModelSelection",
+ finalRefineBarrier: "ifInFlight",
+ },
+ {
+ prepare: async () => {
+ drainedNextTurnMessages = this._pendingNextTurnMessages;
+ this._pendingNextTurnMessages = [];
+ const preparedMessages: AgentMessage[] = [...drainedNextTurnMessages, message];
+ const basePromptSnapshot = this._baseSystemPrompt;
+ const result = await this._extensionRunner.emitBeforeAgentStart(
+ text,
+ undefined,
+ basePromptSnapshot,
+ this._baseSystemPromptOptions,
+ );
+ preparation = { result, basePromptSnapshot };
+ this._appendBeforeAgentStartMessages(preparedMessages, result);
+ this._applyPreparedSystemPrompt(preparation, true);
+ return { messages: preparedMessages, preparation };
+ },
+ commit: (prepared, passedFinalRefineBarrier) => {
+ if (passedFinalRefineBarrier) this._applyPreparedSystemPrompt(prepared.preparation, true);
+ return prepared.messages;
+ },
+ },
);
- this._appendBeforeAgentStartMessages(messages, extensionResult);
- this.agent.state.systemPrompt =
- extensionResult?.systemPrompt !== undefined
- ? this._refreshExtensionSystemPrompt(extensionResult.systemPrompt, basePromptSnapshot)
- : this._baseSystemPrompt;
} catch (error) {
reportPreflight(false);
throw error;
@@ -4185,18 +4369,11 @@ export class AgentSession {
endDirectPromptSection();
return;
}
-
if (this._refineInFlight) {
await this._waitForRefineIdle();
- if (extensionResult?.systemPrompt !== undefined && basePromptSnapshot !== undefined) {
- this.agent.state.systemPrompt = this._refreshExtensionSystemPrompt(
- extensionResult.systemPrompt,
- basePromptSnapshot,
- );
- } else {
- this.agent.state.systemPrompt = this._baseSystemPrompt;
- }
}
+ this._applyPreparedSystemPrompt(preparation, true);
+
const shouldQueueAtHandoff = options?.queueIfBusy === true && this._isBusyForSessionInput("handoff");
if (shouldQueueAtHandoff) {
this._pendingNextTurnMessages.unshift(...drainedNextTurnMessages.map((pending) => ({ ...pending })));
@@ -4225,13 +4402,10 @@ export class AgentSession {
}
if (options?.suppressAutonomousContinuation) this._markAutonomousContinuationSuppressed(message);
- // Register the observer before dispatch so a synchronously-emitted
- // message_start cannot be missed.
- const dispatchObserver = this._observeDirectDispatch(message);
- const promptPromise = options?.suppressAutonomousContinuation
- ? this._runWithAutonomousContinuationSuppressed(() => this.agent.prompt(messages))
- : this.agent.prompt(messages);
- releaseAdmission();
+ const dispatch = this._dispatchPromptWithFence(messages, message, drainedNextTurnMessages, {
+ releaseAdmission,
+ suppressAutonomousContinuation: options?.suppressAutonomousContinuation,
+ });
// Settle the preflight outcome at the handoff, not after the whole turn: the
// direct-prompt section must keep fencing update-restart checkpoints until
// message_start proves the input reached the run's event stream, and a
@@ -4239,18 +4413,18 @@ export class AgentSession {
// is not proof: Agent.prompt() converts lifecycle failures into a synthetic
// error turn without the message ever reaching agent state.
const dispatched = await Promise.race([
- promptPromise.then(
- () => dispatchObserver.wasObserved() || this.agent.state.messages.includes(message),
+ dispatch.promptPromise.then(
+ () => dispatch.wasDeliveryObserved() || this.agent.state.messages.includes(message),
() => false,
),
- dispatchObserver.observed,
+ dispatch.deliveryObserved!,
]);
- dispatchObserver.stop();
+ dispatch.stopDeliveryObservation();
reportPreflight(dispatched);
try {
- await promptPromise;
+ await dispatch.promptPromise;
} catch (error) {
- this._pendingNextTurnMessages.unshift(...drainedNextTurnMessages.map((pending) => ({ ...pending })));
+ dispatch.restorePendingNextTurnMessages(() => false);
throw error;
}
await this.waitForRetry();
@@ -4307,16 +4481,21 @@ export class AgentSession {
let primaryPromptMessage: QueuedAgentMessage | undefined;
let acceptedAgentMessagePrompt: AcceptedAgentMessagePrompt | undefined;
let drainedNextTurnMessages: CustomMessage[] = [];
+ let preparation: PreparedPromptPreparation | undefined;
let expandedText = text;
let currentImages = options?.images;
- let extensionResult: Awaited<ReturnType<typeof this._extensionRunner.emitBeforeAgentStart>> | undefined;
- let basePromptSnapshot: string | undefined;
try {
- let currentText = text;
- const shouldHandleBuiltInSlashCommands = !isInternalPrompt && !options?.skipPrePromptWork;
- const sessionCommand = shouldHandleBuiltInSlashCommands ? parseSessionSlashCommand(currentText) : undefined;
- if (sessionCommand) {
+ const normalizationResult = this._normalizeSubmission(text, currentImages, {
+ parseSessionCommands: !isInternalPrompt && !options?.skipPrePromptWork,
+ extensionCommands: expandPromptTemplates ? "execute" : "ignore",
+ inputSource:
+ !isInternalPrompt && !options?.skipInputHandlers ? (options?.source ?? "interactive") : undefined,
+ expandSkills: expandPromptTemplates,
+ expandPromptTemplates,
+ });
+ const normalized = normalizationResult instanceof Promise ? await normalizationResult : normalizationResult;
+ if (normalized.kind === "sessionCommand") {
const wasBusy =
this.isStreaming ||
this.isCompacting ||
@@ -4331,9 +4510,9 @@ export class AgentSession {
const queued = this._enqueueSessionInput(
{
kind: "command",
- text: currentText,
- command: sessionCommand,
- images: currentImages,
+ text: normalized.text,
+ command: normalized.command,
+ images: normalized.images,
agentMessageId: options?.agentMessageId,
},
schedule,
@@ -4343,49 +4522,23 @@ export class AgentSession {
if (!wasBusy && !options?.returnAfterAccepted) await this._sessionInputPump;
return;
}
-
- // Handle extension commands first (execute immediately, even during streaming)
- // Extension commands manage their own LLM interaction via pi.sendMessage()
- if (expandPromptTemplates && currentText.startsWith("/")) {
- const commandCompletion = this._executeExtensionCommand(currentText);
- if (commandCompletion) {
- reportPreflight(true);
- void commandCompletion.then(
- () => this._settleAgentMessage(options?.agentMessageId, "completion"),
- (error) => this._settleAgentMessage(options?.agentMessageId, "completion", error),
- );
- void commandCompletion.catch(() => undefined);
- if (!options?.returnAfterAccepted) await commandCompletion.catch(() => undefined);
- return;
- }
- }
-
- // Emit input event for extension interception (before skill/template expansion).
- // Agent-to-agent and internal host prompts bypass input handlers so
- // extensions cannot rewrite or swallow direct delivery.
- if (!isInternalPrompt && !options?.skipInputHandlers && this._extensionRunner.hasHandlers("input")) {
- const inputResult = await this._extensionRunner.emitInput(
- currentText,
- currentImages,
- options?.source ?? "interactive",
+ if (normalized.kind === "extensionCommand") {
+ reportPreflight(true);
+ void normalized.completion.then(
+ () => this._settleAgentMessage(options?.agentMessageId, "completion"),
+ (error) => this._settleAgentMessage(options?.agentMessageId, "completion", error),
);
- if (inputResult.action === "handled") {
- reportPreflight(true);
- this._settleAgentMessage(options?.agentMessageId, "completion");
- return;
- }
- if (inputResult.action === "transform") {
- currentText = inputResult.text;
- currentImages = inputResult.images ?? currentImages;
- }
+ void normalized.completion.catch(() => undefined);
+ if (!options?.returnAfterAccepted) await normalized.completion.catch(() => undefined);
+ return;
}
-
- // Expand skill commands (/skill:name args) and prompt templates (/template args)
- expandedText = currentText;
- if (expandPromptTemplates) {
- expandedText = this._expandSkillCommand(expandedText);
- expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+ if (normalized.kind === "handled") {
+ reportPreflight(true);
+ this._settleAgentMessage(options?.agentMessageId, "completion");
+ return;
}
+ expandedText = normalized.text;
+ currentImages = normalized.images;
// If streaming, or a caller explicitly asked to respect existing queued work,
// enqueue according to the requested behavior.
@@ -4412,105 +4565,77 @@ export class AgentSession {
return;
}
- if (!options?.returnAfterAccepted) {
- await this._waitForRefineIdle();
- }
-
- // Flush any pending bash messages before the new prompt, including accepted agent messages.
- this._flushPendingBashMessages();
- await this._validateCanStartAgentRun();
-
- const pendingModelSelectEmit = this._pendingModelSelectEmit();
- if (pendingModelSelectEmit) {
- await pendingModelSelectEmit;
- }
- const buildUserContent = (): (TextContent | ImageContent)[] => {
- const userContent: (TextContent | ImageContent)[] = options?.content
- ? options.content.map((block) => ({ ...block }))
- : [{ type: "text", text: expandedText }];
- if (!options?.content && currentImages) {
- userContent.push(...currentImages);
- }
- return userContent;
- };
- if (options?.skipPrePromptWork) {
- this.agent.state.systemPrompt = this._baseSystemPrompt;
- messages = [];
- drainedNextTurnMessages = this._pendingNextTurnMessages;
- for (const msg of drainedNextTurnMessages) {
- messages.push(msg);
- }
- this._pendingNextTurnMessages = [];
- primaryPromptMessage = options.customMessage
- ? cloneCustomMessage(options.customMessage)
- : {
- role: "user",
- content: buildUserContent(),
- timestamp: Date.now(),
+ messages = await this._prepareForCommit(
+ {
+ initialRefineBarrier: options?.returnAfterAccepted ? "skip" : "always",
+ flushPendingBashBeforeValidation: true,
+ preTurnCompaction: options?.skipPrePromptWork ? "skip" : "afterModelSelection",
+ finalRefineBarrier: "ifInFlight",
+ },
+ {
+ prepare: async () => {
+ const buildUserContent = (): (TextContent | ImageContent)[] => {
+ const userContent: (TextContent | ImageContent)[] = options?.content
+ ? options.content.map((block) => ({ ...block }))
+ : [{ type: "text", text: expandedText }];
+ if (!options?.content && currentImages) userContent.push(...currentImages);
+ return userContent;
};
- messages.push(primaryPromptMessage);
- if (options.agentMessageId !== undefined && options.returnAfterAccepted) {
- let resolveAccepted = () => {};
- let rejectAccepted = (_error: Error) => {};
- const accepted = new Promise<void>((resolve, reject) => {
- resolveAccepted = resolve;
- rejectAccepted = reject;
- });
- acceptedAgentMessagePrompt = {
- text: expandedText,
- agentMessageId: options.agentMessageId,
- message: primaryPromptMessage,
- messages: new Set<AgentMessage>([...drainedNextTurnMessages, primaryPromptMessage]),
- pendingNextTurnMessages: drainedNextTurnMessages,
- deliveredPendingNextTurnMessages: new Set(),
- accepted,
- resolveAccepted,
- rejectAccepted,
- turnStarted: false,
- cleared: false,
- };
- }
- } else {
- // Check if we need to compact before sending (catches aborted responses)
- const lastAssistant = this._findLastAssistantMessage();
- if (lastAssistant) {
- await this._checkCompaction(lastAssistant, false, false);
- }
-
- // Build messages array (custom message if any, then user message)
- messages = [];
+ drainedNextTurnMessages = this._pendingNextTurnMessages;
+ this._pendingNextTurnMessages = [];
+ const preparedMessages: AgentMessage[] = [...drainedNextTurnMessages];
+ primaryPromptMessage = options?.customMessage
+ ? cloneCustomMessage(options.customMessage)
+ : { role: "user", content: buildUserContent(), timestamp: Date.now() };
+ preparedMessages.push(primaryPromptMessage);
+
+ if (options?.skipPrePromptWork) {
+ this.agent.state.systemPrompt = this._baseSystemPrompt;
+ if (options.agentMessageId !== undefined && options.returnAfterAccepted) {
+ let resolveAccepted = () => {};
+ let rejectAccepted = (_error: Error) => {};
+ const accepted = new Promise<void>((resolve, reject) => {
+ resolveAccepted = resolve;
+ rejectAccepted = reject;
+ });
+ acceptedAgentMessagePrompt = {
+ text: expandedText,
+ agentMessageId: options.agentMessageId,
+ message: primaryPromptMessage,
+ messages: new Set<AgentMessage>([...drainedNextTurnMessages, primaryPromptMessage]),
+ pendingNextTurnMessages: drainedNextTurnMessages,
+ deliveredPendingNextTurnMessages: new Set(),
+ accepted,
+ resolveAccepted,
+ rejectAccepted,
+ turnStarted: false,
+ cleared: false,
+ };
+ }
+ return { messages: preparedMessages, preparation: undefined };
+ }
- // Inject any pending "nextTurn" messages as context before the user message.
- drainedNextTurnMessages = this._pendingNextTurnMessages;
- for (const msg of drainedNextTurnMessages) {
- messages.push(msg);
- }
- this._pendingNextTurnMessages = [];
-
- primaryPromptMessage = options?.customMessage
- ? cloneCustomMessage(options.customMessage)
- : {
- role: "user",
- content: buildUserContent(),
- timestamp: Date.now(),
- };
- messages.push(primaryPromptMessage);
-
- // Emit before_agent_start extension event
- basePromptSnapshot = this._baseSystemPrompt;
- extensionResult = await this._extensionRunner.emitBeforeAgentStart(
- expandedText,
- currentImages,
- basePromptSnapshot,
- this._baseSystemPromptOptions,
- );
- // Add all custom messages from extensions
- this._appendBeforeAgentStartMessages(messages, extensionResult);
- // Apply extension-modified system prompt, or reset to base
- this.agent.state.systemPrompt = extensionResult?.systemPrompt
- ? this._refreshExtensionSystemPrompt(extensionResult.systemPrompt, basePromptSnapshot)
- : this._baseSystemPrompt;
- }
+ const basePromptSnapshot = this._baseSystemPrompt;
+ const result = await this._extensionRunner.emitBeforeAgentStart(
+ expandedText,
+ currentImages,
+ basePromptSnapshot,
+ this._baseSystemPromptOptions,
+ );
+ preparation = { result, basePromptSnapshot };
+ this._appendBeforeAgentStartMessages(preparedMessages, result);
+ this._applyPreparedSystemPrompt(preparation, false);
+ return { messages: preparedMessages, preparation };
+ },
+ beforeFinalRefineBarrier: () => {
+ if (acceptedAgentMessagePrompt) this._acceptedAgentMessagePrompt = acceptedAgentMessagePrompt;
+ },
+ commit: (prepared, passedFinalRefineBarrier) => {
+ if (passedFinalRefineBarrier) this._applyPreparedSystemPrompt(prepared.preparation, false);
+ return prepared.messages;
+ },
+ },
+ );
} catch (error) {
reportPreflight(false);
throw error;
@@ -4520,23 +4645,11 @@ export class AgentSession {
endDirectPromptSection();
return;
}
-
- if (acceptedAgentMessagePrompt) {
- this._acceptedAgentMessagePrompt = acceptedAgentMessagePrompt;
- }
- // Re-check adjacent to the handoff: extension before_agent_start handlers
- // above may have suspended this turn long enough for a refine to start.
if (this._refineInFlight) {
await this._waitForRefineIdle();
- if (extensionResult?.systemPrompt && basePromptSnapshot !== undefined) {
- this.agent.state.systemPrompt = this._refreshExtensionSystemPrompt(
- extensionResult.systemPrompt,
- basePromptSnapshot,
- );
- } else {
- this.agent.state.systemPrompt = this._baseSystemPrompt;
- }
}
+ this._applyPreparedSystemPrompt(preparation, false);
+
if (acceptedAgentMessagePrompt?.cleared) {
reportPreflight(false);
throw new Error("Accepted agent message was cleared before delivery.");
@@ -4581,28 +4694,30 @@ export class AgentSession {
reportPreflight(false);
throw new Error("Direct prompt is missing its primary message");
}
- const dispatchObserver = acceptedAgentMessagePrompt
- ? undefined
- : this._observeDirectDispatch(primaryPromptMessage);
- const promptPromise = options?.suppressAutonomousContinuation
- ? this._runWithAutonomousContinuationSuppressed(() => this.agent.prompt(messages))
- : this.agent.prompt(messages);
- releaseAdmission();
+ const dispatch = this._dispatchPromptWithFence(
+ messages,
+ acceptedAgentMessagePrompt ? undefined : primaryPromptMessage,
+ drainedNextTurnMessages,
+ {
+ releaseAdmission,
+ suppressAutonomousContinuation: options?.suppressAutonomousContinuation,
+ },
+ );
const promptAccepted = Symbol("promptAccepted");
const acceptance = acceptedAgentMessagePrompt
? acceptedAgentMessagePrompt.accepted.then(
() => promptAccepted,
(error: unknown) => error,
)
- : dispatchObserver!.observed.then(() => promptAccepted);
+ : dispatch.deliveryObserved!.then(() => promptAccepted);
const firstOutcome = await Promise.race([
- promptPromise.then(
+ dispatch.promptPromise.then(
() => undefined,
(error: unknown) => error,
),
acceptance,
]);
- dispatchObserver?.stop();
+ dispatch.stopDeliveryObservation();
if (firstOutcome !== undefined && firstOutcome !== promptAccepted) {
// A cleared prompt stays set until the aborted run's agent_end cleanup nulls it;
// nulling here would let the run's late events re-persist cleared messages.
@@ -4613,19 +4728,14 @@ export class AgentSession {
this._acceptedAgentMessagePrompt = undefined;
}
if (acceptedAgentMessagePrompt && !acceptedAgentMessagePrompt.cleared) {
- // The prompt was never accepted, so next-turn context drained for it
- // was not consumed by the model and must remain available to retry.
- this._pendingNextTurnMessages.unshift(
- ...undeliveredPendingNextTurnMessages(acceptedAgentMessagePrompt).map((message) => ({
- ...message,
- })),
- );
+ const deliveredPendingNextTurnMessages = acceptedAgentMessagePrompt.deliveredPendingNextTurnMessages;
+ dispatch.restorePendingNextTurnMessages((message) => deliveredPendingNextTurnMessages.has(message));
}
reportPreflight(false);
throw firstOutcome;
}
reportPreflight(true);
- const promptCompletion = promptPromise.then(async () => {
+ const promptCompletion = dispatch.promptPromise.then(async () => {
await this.waitForRetry();
});
if (options?.agentMessageId) {
@@ -4723,16 +4833,17 @@ export class AgentSession {
images?: ImageContent[],
options: { queueKey?: string; agentMessageId?: string; resumeIfIdle?: boolean } = {},
): Promise<void> {
- // Check for extension commands (cannot be queued)
- if (text.startsWith("/")) {
- this._throwIfExtensionCommand(text);
+ const normalized = this._normalizeSubmission(text, images, {
+ parseSessionCommands: false,
+ extensionCommands: "reject",
+ expandSkills: true,
+ expandPromptTemplates: true,
+ });
+ if (normalized instanceof Promise || normalized.kind !== "prompt") {
+ throw new Error("Queued prompt normalization did not produce a prompt");
}
- // Expand skill commands and prompt templates
- let expandedText = this._expandSkillCommand(text);
- expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-
- await this._queuePreparedPrompt("steer", expandedText, images, {
+ await this._queuePreparedPrompt("steer", normalized.text, normalized.images, {
queueKey: options.queueKey,
agentMessageId: options.agentMessageId,
resumeIfIdle: options.resumeIfIdle,
@@ -4751,16 +4862,17 @@ export class AgentSession {
images?: ImageContent[],
options: { queueKey?: string; agentMessageId?: string; resumeIfIdle?: boolean } = {},
): Promise<boolean> {
- // Check for extension commands (cannot be queued)
- if (text.startsWith("/")) {
- this._throwIfExtensionCommand(text);
+ const normalized = this._normalizeSubmission(text, images, {
+ parseSessionCommands: false,
+ extensionCommands: "reject",
+ expandSkills: true,
+ expandPromptTemplates: true,
+ });
+ if (normalized instanceof Promise || normalized.kind !== "prompt") {
+ throw new Error("Queued prompt normalization did not produce a prompt");
}
- // Expand skill commands and prompt templates
- let expandedText = this._expandSkillCommand(text);
- expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-
- return this._queuePreparedPrompt("followUp", expandedText, images, {
+ return this._queuePreparedPrompt("followUp", normalized.text, normalized.images, {
queueKey: options.queueKey,
agentMessageId: options.agentMessageId,
resumeIfIdle: options.resumeIfIdle,
@@ -5175,98 +5287,99 @@ export class AgentSession {
epoch: number,
releaseAdmission: () => void,
): Promise<void> {
- await this._validateCanStartAgentRun();
- if (this._isSessionInputHandoffDeferred(epoch)) {
- throw new DeferredSessionInputError("Session input paused before preflight");
- }
- this._flushPendingBashMessages();
- const lastAssistant = this._findLastAssistantMessage();
- if (lastAssistant) await this._checkCompaction(lastAssistant, false, false);
- const pendingModelSelectEmit = this._pendingModelSelectEmit();
- if (pendingModelSelectEmit) await pendingModelSelectEmit;
-
- while (!prompts.every((prompt) => prompt.preparation !== undefined)) {
- if (this._isSessionInputHandoffDeferred(epoch)) {
- throw new DeferredSessionInputError("Session input paused before preparation");
- }
- const preparationPrompt = prompts.at(-1);
- if (!preparationPrompt) return;
- const basePromptSnapshot = this._baseSystemPrompt;
- const result = await this._extensionRunner.emitBeforeAgentStart(
- preparationPrompt.text,
- preparationPrompt.images,
- basePromptSnapshot,
- this._baseSystemPromptOptions,
- );
- if (prompts.at(-1) !== preparationPrompt) continue;
- const preparation = { result, basePromptSnapshot };
- for (const prompt of prompts) prompt.preparation = preparation;
- }
- if (this._isSessionInputHandoffDeferred(epoch)) {
- throw new DeferredSessionInputError("Session input paused before handoff");
- }
- if (prompts.length === 0) return;
-
- // Re-check adjacent to the handoff: background refine planning may have
- // completed and entered _applyRefine during the awaits above,
- // disconnecting event handling. Wait for it to finish so the new
- // turn's events are not lost.
- await this._waitForRefineIdle();
- if (this._isSessionInputHandoffDeferred(epoch)) {
- throw new DeferredSessionInputError("Session input paused before handoff");
- }
- // Assemble the handoff snapshot only after the last await: a clear that runs
- // during the waits above must still be able to remove prompts from
- // active.items before they are captured for agent.prompt().
- if (prompts.length === 0) return;
- const messages: AgentMessage[] = [];
- const 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);
- }
- const preparation = prompts[0]?.preparation;
- const result = preparation?.result;
- this._appendBeforeAgentStartMessages(messages, result);
- // The base prompt may have changed (e.g. refine) since preparation; splice the
- // current base into an extension-modified prompt exactly like the direct path.
- this.agent.state.systemPrompt =
- result?.systemPrompt !== undefined && preparation !== undefined
- ? this._refreshExtensionSystemPrompt(result.systemPrompt, preparation.basePromptSnapshot)
- : this._baseSystemPrompt;
+ let nextTurnMessages: CustomMessage[] = [];
+ const preparation = await this._prepareForCommit(
+ {
+ initialRefineBarrier: "skip",
+ flushPendingBashBeforeValidation: false,
+ preTurnCompaction: "beforeModelSelection",
+ finalRefineBarrier: "always",
+ },
+ {
+ afterValidation: () => {
+ if (this._isSessionInputHandoffDeferred(epoch)) {
+ throw new DeferredSessionInputError("Session input paused before preflight");
+ }
+ },
+ prepare: async () => {
+ while (!prompts.every((prompt) => prompt.preparation !== undefined)) {
+ if (this._isSessionInputHandoffDeferred(epoch)) {
+ throw new DeferredSessionInputError("Session input paused before preparation");
+ }
+ const preparationPrompt = prompts.at(-1);
+ if (!preparationPrompt) return undefined;
+ const basePromptSnapshot = this._baseSystemPrompt;
+ const result = await this._extensionRunner.emitBeforeAgentStart(
+ preparationPrompt.text,
+ preparationPrompt.images,
+ basePromptSnapshot,
+ this._baseSystemPromptOptions,
+ );
+ if (prompts.at(-1) !== preparationPrompt) continue;
+ const preparation = { result, basePromptSnapshot };
+ for (const prompt of prompts) prompt.preparation = preparation;
+ }
+ if (this._isSessionInputHandoffDeferred(epoch)) {
+ throw new DeferredSessionInputError("Session input paused before handoff");
+ }
+ return prompts[0]?.preparation;
+ },
+ shouldCommit: () => prompts.length > 0,
+ commit: (preparation) => {
+ if (this._isSessionInputHandoffDeferred(epoch)) {
+ throw new DeferredSessionInputError("Session input paused before handoff");
+ }
+ if (prompts.length === 0) return undefined;
+ this._applyPreparedSystemPrompt(preparation, true);
+ return preparation;
+ },
+ },
+ );
+ if (!preparation) return;
+ let dispatch: PromptDispatchFence | undefined;
try {
+ if (this._refineInFlight) await this._waitForRefineIdle();
+ 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");
}
+ this._applyPreparedSystemPrompt(preparation, true);
+ const messages: 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);
+ }
+ }
+ this._appendBeforeAgentStartMessages(messages, preparation.result);
if (this._activeSessionInput?.kind === "prompt") {
this._activeSessionInput.phase = "handedOff";
this._notifySessionInputCheckpointChange();
this._emitQueueUpdate();
}
- // The phase flipped to handedOff before dispatch; hold a checkpoint section
- // until dispatch so a restart snapshot cannot miss the accepted messages.
- const endHandoffSection = this._enterDirectPromptSection();
- const dispatchObserver = this._observeDirectDispatch(prompts[prompts.length - 1]!.message);
- const settleHandoffSection = () => {
- dispatchObserver.stop();
- endHandoffSection();
- };
- const promptPromise = this.agent.prompt(messages);
- releaseAdmission();
- void Promise.race([promptPromise.catch(() => undefined), dispatchObserver.observed]).then(
- settleHandoffSection,
- settleHandoffSection,
- );
- await promptPromise;
+ dispatch = this._dispatchPromptWithFence(messages, prompts[prompts.length - 1]!.message, nextTurnMessages, {
+ releaseAdmission,
+ checkpointUntilDelivery: true,
+ cloneRestoredNextTurnMessages: false,
+ });
+ await dispatch.promptPromise;
await this.waitForRetry();
await this._agentEventQueue;
this._forgetConsumedPostCompactionContinuations(prompts.map((prompt) => prompt.message));
} catch (error) {
- const delivered = new Set(this.agent.state.messages);
- this._pendingNextTurnMessages.unshift(...nextTurnMessages.filter((message) => !delivered.has(message)));
+ if (dispatch) {
+ dispatch.restorePendingNextTurnMessages();
+ } else {
+ const delivered = new Set(this.agent.state.messages);
+ this._pendingNextTurnMessages.unshift(...nextTurnMessages.filter((message) => !delivered.has(message)));
+ }
throw error;
}
}
diff --git a/packages/coding-agent/test/suite/agent-session-action-contracts.test.ts b/packages/coding-agent/test/suite/agent-session-action-contracts.test.ts
new file mode 100644
index 0000000000..f9faf7e8a9
--- /dev/null
+++ b/packages/coding-agent/test/suite/agent-session-action-contracts.test.ts
@@ -0,0 +1,114 @@
+import { fauxAssistantMessage } from "@earendil-works/pi-ai";
+import { afterEach, describe, expect, it } from "vitest";
+import { createHarness, getUserTexts, type Harness } from "./harness.js";
+import { withStreaming } from "./scheduling.js";
+
+describe("AgentSession action contracts", () => {
+ const harnesses: Harness[] = [];
+
+ afterEach(() => {
+ while (harnesses.length > 0) harnesses.pop()?.cleanup();
+ });
+
+ it("parses session commands only through prompt provenance", async () => {
+ const harness = await createHarness();
+ harnesses.push(harness);
+ harness.setResponses([fauxAssistantMessage("literal handled")]);
+
+ await harness.session.prompt("/compact");
+ expect(harness.getPendingResponseCount()).toBe(1);
+ expect(
+ harness.session.messages.some(
+ (message) => message.role === "custom" && message.customType === "session_slash_command",
+ ),
+ ).toBe(true);
+
+ await harness.session.steer("/compact", undefined, { resumeIfIdle: true });
+ await harness.session.waitForIdle();
+
+ expect(getUserTexts(harness)).toEqual(["/compact"]);
+ expect(harness.getPendingResponseCount()).toBe(0);
+ });
+
+ it("runs input handlers before deciding whether busy submissions enter a queue", async () => {
+ const harness = await createHarness({
+ extensionFactories: [
+ (pi) => {
+ pi.on("input", async (event) =>
+ event.text === "handled"
+ ? { action: "handled" }
+ : { action: "transform", text: `transformed:${event.text}` },
+ );
+ },
+ ],
+ });
+ harnesses.push(harness);
+ withStreaming(harness, true);
+
+ await harness.session.prompt("queued", { streamingBehavior: "followUp" });
+ await harness.session.prompt("handled", { streamingBehavior: "followUp" });
+
+ expect(harness.session.getFollowUpMessages()).toEqual(["transformed:queued"]);
+ expect(harness.session.pendingMessageCount).toBe(1);
+ withStreaming(harness, false);
+ expect(harness.session.clearQueue()).toEqual({ steering: [], followUp: ["transformed:queued"] });
+ });
+
+ it("gives nextTurn delivery precedence over triggerTurn", async () => {
+ const harness = await createHarness();
+ harnesses.push(harness);
+ harness.setResponses([fauxAssistantMessage("done")]);
+
+ await harness.session.sendCustomMessage(
+ { customType: "precedence", content: "context only", display: true },
+ { triggerTurn: true, deliverAs: "nextTurn" },
+ );
+
+ expect(harness.session.messages).toEqual([]);
+ expect(harness.session.pendingMessageCount).toBe(0);
+ expect(harness.getPendingResponseCount()).toBe(1);
+
+ await harness.session.prompt("consume context");
+ expect(harness.session.messages.map((message) => message.role)).toEqual(["custom", "user", "assistant"]);
+ expect(harness.getPendingResponseCount()).toBe(0);
+ });
+
+ it("restores normalized payloads without interception, parsing, or an idle wake", async () => {
+ let inputHandlerRuns = 0;
+ let extensionCommandRuns = 0;
+ const harness = await createHarness({
+ extensionFactories: [
+ (pi) => {
+ pi.on("input", async () => {
+ inputHandlerRuns++;
+ return { action: "transform", text: "rewritten" };
+ });
+ pi.registerCommand("literal", {
+ description: "must stay literal",
+ handler: async () => {
+ extensionCommandRuns++;
+ },
+ });
+ },
+ ],
+ });
+ harnesses.push(harness);
+ harness.setResponses([fauxAssistantMessage("steer done"), fauxAssistantMessage("follow-up done")]);
+
+ await harness.session.restoreFollowUpMessage("/compact");
+ await harness.session.restoreSteeringMessage("/literal keep text");
+ await Promise.resolve();
+
+ expect(inputHandlerRuns).toBe(0);
+ expect(extensionCommandRuns).toBe(0);
+ expect(harness.session.getSteeringMessages()).toEqual(["/literal keep text"]);
+ expect(harness.session.getFollowUpMessages()).toEqual(["/compact"]);
+ expect(harness.session.messages).toEqual([]);
+
+ expect(harness.session.resumeQueuedWork()).toBe(true);
+ await harness.session.waitForIdle();
+ expect(getUserTexts(harness)).toEqual(["/literal keep text", "/compact"]);
+ expect(inputHandlerRuns).toBe(0);
+ expect(extensionCommandRuns).toBe(0);
+ });
+});