diff --git a/apps/cli/src/ui/interactive-mode.ts b/apps/cli/src/ui/interactive-mode.ts index fff1f334..ec30f6d5 100644 --- a/apps/cli/src/ui/interactive-mode.ts +++ b/apps/cli/src/ui/interactive-mode.ts @@ -155,7 +155,6 @@ import { wireInteractiveRuntime, wireStartupInput } from "./runtime/index.ts"; import { clipboardPaste, handleStartupSubmit, - isExtensionCommand, rightClickPaste, wireKeyHandlers, wireSubmitHandler, @@ -4126,9 +4125,9 @@ export class InteractiveMode { const text = (this.editor.getExpandedText?.() ?? this.editor.getText()).trim(); if (!text) return; - // Queue input during compaction (extension commands execute immediately) + // Queue input during compaction (commands execute immediately) if (this.session.isCompacting) { - if (this.isExtensionCommand(text)) { + if (this.isCommandInput(text)) { this.editor.addToHistory?.(text); this.editor.setText(""); await this.session.prompt(text); @@ -4142,15 +4141,15 @@ export class InteractiveMode { } // Alt+Enter queues a follow-up message (waits until agent finishes) - // This handles extension commands (execute immediately), prompt template expansion, and queueing + // This handles commands (execute immediately), prompt template expansion, and queueing if (this.session.isStreaming) { this.editor.addToHistory?.(text); this.editor.setText(""); const { text: message, images } = await resolvePastedImages(this.pastedImages, text, { autoResizeImages: this.settingsManager.getImageAutoResize(), }); - await this.session.prompt(message, { - streamingBehavior: "followUp", + await this.session.submit(message, { + duringRun: "followUp", images: images.length ? images : undefined, }); this.updatePendingMessagesDisplay(); @@ -4431,7 +4430,7 @@ export class InteractiveMode { if (this.session.isAutoClmCompacting) { this.editor.addToHistory?.(text); this.editor.setText(""); - void this.session.prompt(text, { streamingBehavior: mode, images }).catch((error) => { + void this.session.submit(text, { duringRun: mode, images }).catch((error) => { this.editor.setText(text); this.showError(error instanceof Error ? error.message : String(error)); }); @@ -4465,8 +4464,9 @@ export class InteractiveMode { return name; } - isExtensionCommand(text: string): boolean { - return isExtensionCommand(this.session.extensionRunner, text); + /** Would `text` run as a command now, rather than become a message or wait in a queue? */ + isCommandInput(text: string): boolean { + return this.session.isCommandInput(text); } async flushCompactionQueue(options?: { willRetry?: boolean }): Promise { @@ -4493,7 +4493,7 @@ export class InteractiveMode { if (options?.willRetry) { // When retry is pending, queue messages for the retry turn for (const message of queuedMessages) { - if (this.isExtensionCommand(message.text)) { + if (this.isCommandInput(message.text)) { await this.session.prompt(message.text); } else if (message.mode === "followUp") { await this.session.followUp(message.text, message.images); @@ -4505,17 +4505,17 @@ export class InteractiveMode { return; } - // Find first non-extension-command message to use as prompt - const firstPromptIndex = queuedMessages.findIndex((message) => !this.isExtensionCommand(message.text)); + // Find first non-command message to use as prompt + const firstPromptIndex = queuedMessages.findIndex((message) => !this.isCommandInput(message.text)); if (firstPromptIndex === -1) { - // All extension commands - execute them all + // All commands - execute them all for (const message of queuedMessages) { await this.session.prompt(message.text); } return; } - // Execute any extension commands before the first prompt + // Execute any commands before the first prompt const preCommands = queuedMessages.slice(0, firstPromptIndex); const firstPrompt = queuedMessages[firstPromptIndex]; const rest = queuedMessages.slice(firstPromptIndex + 1); @@ -4526,8 +4526,8 @@ export class InteractiveMode { // Start a prompt when idle, or queue it into a run still finishing compaction. const promptPromise = this.session - .prompt(firstPrompt.text, { - streamingBehavior: firstPrompt.mode, + .submit(firstPrompt.text, { + duringRun: firstPrompt.mode, images: firstPrompt.images?.length ? firstPrompt.images : undefined, }) .catch((error) => { @@ -4536,7 +4536,7 @@ export class InteractiveMode { // Queue remaining messages for (const message of rest) { - if (this.isExtensionCommand(message.text)) { + if (this.isCommandInput(message.text)) { await this.session.prompt(message.text); } else if (message.mode === "followUp") { await this.session.followUp(message.text, message.images); diff --git a/apps/cli/src/ui/runtime/context.ts b/apps/cli/src/ui/runtime/context.ts index 702db137..bfb2458a 100644 --- a/apps/cli/src/ui/runtime/context.ts +++ b/apps/cli/src/ui/runtime/context.ts @@ -175,7 +175,7 @@ export interface RuntimeContext { handleShareCommand(): Promise; handleStepLogoutCommand(): Promise; handleThinkingCommand(searchTerm?: string): void; - isExtensionCommand(text: string): boolean; + isCommandInput(text: string): boolean; queueCompactionMessage(text: string, mode: "steer" | "followUp", images?: ImageContent[]): void; showModelSelector(initialSearchInput?: string): void; addCommandInputToChat(text: string): void; diff --git a/apps/cli/src/ui/runtime/input-dispatch.ts b/apps/cli/src/ui/runtime/input-dispatch.ts index db83f3dd..fbf912db 100644 --- a/apps/cli/src/ui/runtime/input-dispatch.ts +++ b/apps/cli/src/ui/runtime/input-dispatch.ts @@ -25,7 +25,6 @@ import * as fs from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; import { - type AgentSession, APP_NAME, cleanPastedPath, extensionForImageMimeType, @@ -40,15 +39,6 @@ import type { RuntimeContext } from "./context.ts"; import { handleEscape } from "./interrupt.ts"; import { resolvePastedImages } from "./pasted-images.ts"; -/** Pure recognizer: is `text` a slash command provided by a loaded extension? */ -export function isExtensionCommand(extensionRunner: AgentSession["extensionRunner"], text: string): boolean { - if (!text.startsWith("/")) return false; - - const spaceIndex = text.indexOf(" "); - const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex); - return !!extensionRunner.getCommand(commandName); -} - export async function rightClickPaste(ctx: RuntimeContext): Promise { const target = ctx.renderer.getFocusedComponent(); const handleInput = target?.handleInput; @@ -431,7 +421,7 @@ export function wireSubmitHandler(ctx: RuntimeContext): void { // Queue input during compaction (extension commands execute immediately) if (ctx.session.isCompacting) { - if (ctx.isExtensionCommand(text)) { + if (ctx.isCommandInput(text)) { ctx.editor.addToHistory?.(text); ctx.editor.setText(""); await ctx.session.prompt(text); @@ -452,7 +442,7 @@ export function wireSubmitHandler(ctx: RuntimeContext): void { const { text: message, images } = await resolvePastedImages(ctx.pastedImages, text, { autoResizeImages: ctx.settingsManager.getImageAutoResize(), }); - await ctx.session.prompt(message, { streamingBehavior: "steer", images: images.length ? images : undefined }); + await ctx.session.submit(message, { duringRun: "steer", images: images.length ? images : undefined }); ctx.updatePendingMessagesDisplay(); ctx.redraw.requestRender(); return; diff --git a/apps/cli/test/interactive-mode-compaction.test.ts b/apps/cli/test/interactive-mode-compaction.test.ts index 57520f63..282bfd31 100644 --- a/apps/cli/test/interactive-mode-compaction.test.ts +++ b/apps/cli/test/interactive-mode-compaction.test.ts @@ -38,13 +38,13 @@ describe("InteractiveMode compaction events", () => { test("forwards terminal input to the active automatic CLM queue so maintenance is interrupted", async () => { const fakeThis = { compactionQueuedMessages: [], - session: { isAutoClmCompacting: true, prompt: vi.fn().mockResolvedValue(undefined) }, + session: { isAutoClmCompacting: true, submit: vi.fn().mockResolvedValue(undefined) }, editor: { addToHistory: vi.fn(), setText: vi.fn() }, updatePendingMessagesDisplay: vi.fn(), showStatus: vi.fn(), showError: vi.fn(), }; const queue = Reflect.get(InteractiveMode.prototype, "queueCompactionMessage") as (this: typeof fakeThis, text: string, mode: "steer" | "followUp") => void; queue.call(fakeThis, "Preserve output order", "steer"); - expect(fakeThis.session.prompt).toHaveBeenCalledWith("Preserve output order", { streamingBehavior: "steer", images: undefined }); + expect(fakeThis.session.submit).toHaveBeenCalledWith("Preserve output order", { duringRun: "steer", images: undefined }); expect(fakeThis.compactionQueuedMessages).toEqual([]); }); test("uses the cache miss notice setting for compaction and branch summary costs", () => { @@ -279,10 +279,11 @@ describe("InteractiveMode compaction events", () => { session: { clearQueue: vi.fn(), prompt: vi.fn().mockResolvedValue(undefined), + submit: vi.fn().mockResolvedValue(undefined), steer: vi.fn().mockResolvedValue(undefined), followUp: vi.fn().mockResolvedValue(undefined), }, - isExtensionCommand: vi.fn().mockReturnValue(false), + isCommandInput: vi.fn().mockReturnValue(false), updatePendingMessagesDisplay: vi.fn(), showError: vi.fn(), }; @@ -294,7 +295,7 @@ describe("InteractiveMode compaction events", () => { await flushCompactionQueue.call(fakeThis, { willRetry: false }); - expect(fakeThis.session.prompt).toHaveBeenCalledWith("change direction", { streamingBehavior: "steer" }); + expect(fakeThis.session.submit).toHaveBeenCalledWith("change direction", { duringRun: "steer" }); expect(fakeThis.compactionQueuedMessages).toEqual([]); expect(fakeThis.showError).not.toHaveBeenCalled(); }); diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index c1d66b99..0a83485d 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -4,6 +4,7 @@ ### Fixed +- `steer()` and `followUp()` now refuse the session's own `/clm` family as well as registered extension commands; queued as text, `/clm status` used to reach the model as a literal line. The session also exposes the decision the two methods depend on: `isCommandInput()` and `submit()`, the entry that runs a command immediately and otherwise starts a turn or joins the running one. - Summary requests now use the provider's model output limit and remaining-context sizing instead of fixed compaction/branch caps or reserve-derived budgets. Existing reserve arguments remain accepted for call compatibility; automatic trigger and branch source-selection settings are unchanged. - Compaction and branch-summary inputs omit provider thinking blocks while retaining visible replies, tool calls, diagnostic output, and existing skill-retention rules. Original session history is unchanged. These changes adapt Pi commits `15e7bdc` and `6fcb486` (upstream PR #11036). - Recognize `search_files`, `find_files`, and `list_directory` when selecting default system-prompt file-exploration guidance. diff --git a/packages/coding-agent/docs/rpc.md b/packages/coding-agent/docs/rpc.md index a614557a..0195c256 100644 --- a/packages/coding-agent/docs/rpc.md +++ b/packages/coding-agent/docs/rpc.md @@ -79,7 +79,7 @@ The `images` field is optional. Each image uses `ImageContent` format: `{"type": #### steer -Queue a steering message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead). +Queue a steering message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. Skill commands and prompt templates are expanded. Commands are refused, both registered extension commands and the session's own `/clm` family: they run on the spot, so send them with `prompt`. ```json {"type": "steer", "message": "Stop and do this instead"} @@ -101,7 +101,7 @@ See [set_steering_mode](#set_steering_mode) for controlling how steering message #### follow_up -Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead). +Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. Skill commands and prompt templates are expanded. Commands are refused, as for `steer`: use `prompt`. ```json {"type": "follow_up", "message": "After you're done, also do this"} diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md index 78e805cf..b81d0144 100644 --- a/packages/coding-agent/docs/sdk.md +++ b/packages/coding-agent/docs/sdk.md @@ -101,7 +101,12 @@ interface AgentSession { // Send a prompt and wait for completion prompt(text: string, options?: PromptOptions): Promise; - // Queue messages during streaming + // Submit what the user typed: commands run now, messages run or join the run + submit(text: string, options?: SubmitOptions): Promise; + // Whether `text` is a command the kernel runs instead of sending to the model + isCommandInput(text: string): boolean; + + // Queue messages during streaming (they refuse commands; prefer submit) steer(text: string): Promise; followUp(text: string): Promise; @@ -235,6 +240,11 @@ interface PromptOptions { source?: InputSource; preflightResult?: (success: boolean) => void; } + +// submit() takes the same options, minus the queueing choice it decides itself +interface SubmitOptions extends Omit { + duringRun?: "steer" | "followUp"; +} ``` `preflightResult` is called once per `prompt()` invocation: @@ -269,6 +279,18 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo - **`preflightResult(true)`**: Means the prompt was accepted, queued, or handled immediately. - **`preflightResult(false)`**: Means preflight rejected before acceptance. +**Prefer `submit()` from a host.** It is `prompt()` with the queueing choice made from the state at the call, so a host never has to look at `isStreaming` first: + +```typescript +// A command runs immediately; text runs as a turn or joins the running one. +await session.submit(input, { duringRun: "steer" }); // default +await session.submit(input, { duringRun: "followUp" }); +``` + +The distinction that matters: a command is not a message. `prompt()` and `submit()` dispatch it before they look at the run, so it executes during streaming and during compaction. `steer()` and `followUp()` are for a host that has already decided a line is a message — they throw for commands, and a host that queues one itself sends the literal line to the model. `isCommandInput(text)` answers the same question without side effects, for a host that keeps its own editable queue and must not park a command there. + +One case stays with the host: compaction refuses new prompts outright, commands aside, so text submitted while the context is being compacted throws. A host that queues during compaction (both the CLI and the Web host do) keeps that queue and calls `submit()` when compaction ends. + For explicit queueing during streaming: ```typescript @@ -279,7 +301,7 @@ await session.steer("New instruction"); await session.followUp("After you're done, also do this"); ``` -Both `steer()` and `followUp()` expand file-based prompt templates but error on extension commands (extension commands cannot be queued). +Both `steer()` and `followUp()` expand file-based prompt templates but refuse commands (registered extension commands and the session's own `/clm` family). ### Agent and AgentState diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts index c5575cd2..99aa5997 100644 --- a/packages/coding-agent/src/core/agent-session.ts +++ b/packages/coding-agent/src/core/agent-session.ts @@ -345,6 +345,16 @@ export interface ModelMutationOptions { persist?: boolean; } +/** + * Options for `AgentSession.submit()`: everything `prompt()` takes, except the + * queueing choice, which is a preference rather than a requirement because + * `submit()` reads the run state itself. + */ +export interface SubmitOptions extends Omit { + /** How the input joins a run that is already going. Defaults to "steer". */ + duringRun?: "steer" | "followUp"; +} + /** Result from cycleModel() */ export interface ModelCycleResult { model: Model; @@ -399,6 +409,25 @@ function estimateRequestOverheadTokens(context: AgentContext): number { /** Consecutive automatic threshold-compaction failures after which v2 pauses automatic compaction. */ const AUTO_COMPACTION_FAILURE_LIMIT = 3; +/** + * Commands `_handleLiveContextCommand` answers itself, before any registered + * extension command. They are dispatched by `prompt()` like any other command, + * so a host that queues or steers them as text sends the literal line to the + * model instead. + */ +const LIVE_CONTEXT_COMMAND_NAMES: ReadonlySet = new Set(["clm", "clm-compact"]); + +/** + * The `` of a leading `/` line, split the way the kernel splits it + * (up to the first space), or undefined when `text` is not one. `/skill:x` and + * `/template` are names too — they are simply not commands. + */ +function slashCommandNameOf(text: string): string | undefined { + if (!text.startsWith("/")) return undefined; + const spaceIndex = text.indexOf(" "); + return spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex); +} + // ============================================================================ // AgentSession Class // ============================================================================ @@ -1222,7 +1251,7 @@ export class AgentSession { } private async _handleLiveContextCommand(name: string, args: string): Promise { - if (name !== "clm" && name !== "clm-compact") return false; + if (!LIVE_CONTEXT_COMMAND_NAMES.has(name)) return false; const ctx = this._extensionRunner.createCommandContext(); const action = name === "clm-compact" ? "compact" : args.trim() || "status"; if ((action === "on" || action === "off" || action === "reset" || action === "compact") && !this.isIdle) { @@ -2345,6 +2374,44 @@ export class AgentSession { return this.agent.hasDeliverableQueuedMessage(this._queueDeliveryAllowed) ? "deliver" : "stop"; } + /** + * Whether `text` is a line the kernel runs on the spot instead of handing to + * the model: a live-context command (`/clm`) or a registered extension command + * (`/goal`, `/btw`, a plugin's own). Prompt templates and `/skill:` lines are + * not — they expand into a message. + * + * A host that keeps its own queue asks this before queueing, because a command + * must never wait there: `prompt()` dispatches it immediately, and `steer()` / + * `followUp()` refuse it outright. + */ + isCommandInput(text: string): boolean { + const name = slashCommandNameOf(text); + return name !== undefined && this._isCommandName(name); + } + + /** Whether a command is registered under `name`, in the order `prompt()` dispatches. */ + private _isCommandName(name: string): boolean { + return LIVE_CONTEXT_COMMAND_NAMES.has(name) || this._extensionRunner.getCommand(name) !== undefined; + } + + /** + * Submit input the user just produced, from any host surface. + * + * This is the entry that cannot get the order wrong, and the one a host should + * call: `prompt()` dispatches a command before it looks at the run, so a + * command runs here immediately whether or not one is in flight. Everything + * else starts a turn when idle and joins the running one otherwise, as + * `duringRun` asks — decided here, from the state at the call, so a run that + * starts in between cannot turn the input into a rejected prompt. + * + * `steer()` and `followUp()` remain for a host that has already decided; they + * throw for commands, which is the mistake this method exists to prevent. + */ + async submit(text: string, options?: SubmitOptions): Promise { + const { duringRun, ...rest } = options ?? {}; + return this.prompt(text, { ...rest, streamingBehavior: duringRun ?? "steer" }); + } + /** * Send a prompt to the agent. * - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming @@ -2549,8 +2616,8 @@ export class AgentSession { source: InputSource = "interactive", ): Promise { // Parse command name and args + const commandName = slashCommandNameOf(text) ?? ""; const spaceIndex = text.indexOf(" "); - const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex); const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1); if (await this._handleLiveContextCommand(commandName, args)) { @@ -2637,15 +2704,13 @@ export class AgentSession { * Queue a steering message while the agent is running. * Delivered after the current assistant turn finishes executing its tool calls, * before the next LLM call. - * Expands skill commands and prompt templates. Errors on extension commands. + * Expands skill commands and prompt templates. Refuses commands. * @param images Optional image attachments to include with the message - * @throws Error if text is an extension command + * @throws Error if text is a command */ async steer(text: string, images?: ImageContent[]): Promise { - // Check for extension commands (cannot be queued) - if (text.startsWith("/")) { - this._throwIfExtensionCommand(text); - } + // A command is not a message: it runs on the spot, so it cannot be queued. + this._throwIfCommand(text); // Expand skill commands and prompt templates let expandedText = this._expandSkillCommand(text); @@ -2657,15 +2722,13 @@ export class AgentSession { /** * Queue a follow-up message to be processed after the agent finishes. * Delivered only when agent has no more tool calls or steering messages. - * Expands skill commands and prompt templates. Errors on extension commands. + * Expands skill commands and prompt templates. Refuses commands. * @param images Optional image attachments to include with the message - * @throws Error if text is an extension command + * @throws Error if text is a command */ async followUp(text: string, images?: ImageContent[]): Promise { - // Check for extension commands (cannot be queued) - if (text.startsWith("/")) { - this._throwIfExtensionCommand(text); - } + // A command is not a message: it runs on the spot, so it cannot be queued. + this._throwIfCommand(text); // Expand skill commands and prompt templates let expandedText = this._expandSkillCommand(text); @@ -2718,18 +2781,18 @@ export class AgentSession { } /** - * Throw an error if the text is an extension command. + * Throw an error if `text` is a command the kernel runs immediately. + * + * A command is not a message: it would be dispatched by `prompt()` (or + * `submit()`) whether or not a run is going, and running it as a queued user + * turn would either be refused or send the literal line to the model. */ - private _throwIfExtensionCommand(text: string): void { - const spaceIndex = text.indexOf(" "); - const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex); - const command = this._extensionRunner.getCommand(commandName); - - if (command) { - throw new Error( - `Extension command "/${commandName}" cannot be queued. Use prompt() or execute the command when not streaming.`, - ); - } + private _throwIfCommand(text: string): void { + const commandName = slashCommandNameOf(text); + if (commandName === undefined || !this._isCommandName(commandName)) return; + throw new Error( + `Command "/${commandName}" cannot be queued as a message. Use prompt() or submit() to run it, during or between runs.`, + ); } /** diff --git a/packages/coding-agent/src/core/index.ts b/packages/coding-agent/src/core/index.ts index 0afd552a..6961e6a4 100644 --- a/packages/coding-agent/src/core/index.ts +++ b/packages/coding-agent/src/core/index.ts @@ -12,6 +12,7 @@ export { type ModelCycleResult, type PromptOptions, type SessionStats, + type SubmitOptions, } from "./agent-session.ts"; export { AgentSessionRuntime, diff --git a/packages/coding-agent/src/index.ts b/packages/coding-agent/src/index.ts index 2bbdc121..4cc75201 100644 --- a/packages/coding-agent/src/index.ts +++ b/packages/coding-agent/src/index.ts @@ -44,6 +44,7 @@ export { type PromptOptions, parseSkillBlock, type SessionStats, + type SubmitOptions, } from "./core/agent-session.ts"; export { SessionImportFileNotFoundError } from "./core/agent-session-runtime.ts"; export { readStoredCredential } from "./core/auth-storage.ts"; 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 5b6f2327..a69b8be4 100644 --- a/packages/coding-agent/test/suite/agent-session-queue.test.ts +++ b/packages/coding-agent/test/suite/agent-session-queue.test.ts @@ -398,7 +398,7 @@ describe("AgentSession queue characterization", () => { harnesses.push(harness); await expect(harness.session.steer("/testcmd queued")).rejects.toThrow( - 'Extension command "/testcmd" cannot be queued. Use prompt() or execute the command when not streaming.', + 'Command "/testcmd" cannot be queued as a message. Use prompt() or submit() to run it, during or between runs.', ); }); @@ -416,7 +416,7 @@ describe("AgentSession queue characterization", () => { harnesses.push(harness); await expect(harness.session.followUp("/testcmd queued")).rejects.toThrow( - 'Extension command "/testcmd" cannot be queued. Use prompt() or execute the command when not streaming.', + 'Command "/testcmd" cannot be queued as a message. Use prompt() or submit() to run it, during or between runs.', ); }); diff --git a/packages/coding-agent/test/suite/agent-session-submit.test.ts b/packages/coding-agent/test/suite/agent-session-submit.test.ts new file mode 100644 index 00000000..89e43a9a --- /dev/null +++ b/packages/coding-agent/test/suite/agent-session-submit.test.ts @@ -0,0 +1,167 @@ +import type { AgentTool } from "@step-harness/agent-core"; +import type { ExtensionAPI } from "@step-harness/coding-agent"; +import { fauxAssistantMessage, fauxToolCall } from "@step-harness/providers"; +import { Type } from "typebox"; +import { afterEach, describe, expect, it } from "vitest"; +import { createHarness, getAssistantTexts, getUserTexts, type Harness } from "./harness.ts"; + +/** + * `submit()` is the one entry a host should call: a command runs immediately + * whether or not a run is going, and everything else runs as a turn or joins + * the running one. These tests pin that ordering, because a host that instead + * guesses (`steer()` while a run is going, a queue of its own) has to know + * something about the kernel it should not have to know. + */ +describe("AgentSession.submit", () => { + const harnesses: Harness[] = []; + + afterEach(() => { + while (harnesses.length > 0) { + harnesses.pop()?.cleanup(); + } + }); + + async function createRunningHarness(commandRuns: string[] = []): Promise<{ + harness: Harness; + releaseToolExecution: () => void; + promptPromise: Promise; + }> { + let releaseToolExecution: (() => void) | undefined; + const toolRelease = new Promise((resolve) => { + releaseToolExecution = resolve; + }); + const waitTool: AgentTool = { + name: "wait", + label: "Wait", + description: "Wait for release", + parameters: Type.Object({}), + execute: async () => { + await toolRelease; + return { content: [{ type: "text", text: "released" }], details: {} }; + }, + }; + const harness = await createHarness({ + tools: [waitTool], + extensionFactories: [ + (pi: ExtensionAPI) => { + pi.registerCommand("testcmd", { + description: "Test command", + handler: async (args) => { + commandRuns.push(args); + }, + }); + }, + ], + }); + harnesses.push(harness); + harness.setResponses([fauxAssistantMessage(fauxToolCall("wait", {}), { stopReason: "toolUse" })]); + const waitForToolStart = new Promise((resolve) => { + const unsubscribe = harness.session.subscribe((event) => { + if (event.type === "tool_execution_start" && event.toolName === "wait") { + unsubscribe(); + resolve(); + } + }); + }); + const promptPromise = harness.session.prompt("start"); + await waitForToolStart; + return { harness, releaseToolExecution: () => releaseToolExecution?.(), promptPromise }; + } + + it("recognizes the lines the kernel runs instead of sending", async () => { + const harness = await createHarness({ + extensionFactories: [ + (pi) => { + pi.registerCommand("testcmd", { description: "Test command", handler: async () => {} }); + }, + ], + }); + harnesses.push(harness); + harness.setResponses([]); + + expect(harness.session.isCommandInput("/testcmd")).toBe(true); + expect(harness.session.isCommandInput("/testcmd with args")).toBe(true); + // Handled by the session itself, before any registered command. + expect(harness.session.isCommandInput("/clm status")).toBe(true); + expect(harness.session.isCommandInput("/clm-compact")).toBe(true); + // Expanded into a message, so they queue like text. + expect(harness.session.isCommandInput("/skill:anything")).toBe(false); + // Not a command: an unknown name, a path, prose, and bare slashes. + expect(harness.session.isCommandInput("/usr/local/bin is missing")).toBe(false); + expect(harness.session.isCommandInput("/")).toBe(false); + expect(harness.session.isCommandInput("plain words")).toBe(false); + }); + + it("runs a command sent during a run instead of queueing it", async () => { + const commandRuns: string[] = []; + const { harness, releaseToolExecution, promptPromise } = await createRunningHarness(commandRuns); + + await harness.session.submit("/testcmd now"); + + // Already ran, and nowhere in either queue: a command is not a message. + expect(commandRuns).toEqual(["now"]); + expect(harness.session.getSteeringMessages()).toEqual([]); + expect(harness.session.getFollowUpMessages()).toEqual([]); + + releaseToolExecution(); + await promptPromise; + }); + + it("queues text into the running turn, steering by default", async () => { + const { harness, releaseToolExecution, promptPromise } = await createRunningHarness(); + + await harness.session.submit("go left"); + + expect(harness.session.getSteeringMessages()).toEqual(["go left"]); + expect(harness.session.getFollowUpMessages()).toEqual([]); + + releaseToolExecution(); + await promptPromise; + }); + + it("queues text as a follow-up when asked", async () => { + const { harness, releaseToolExecution, promptPromise } = await createRunningHarness(); + + await harness.session.submit("after this", { duringRun: "followUp" }); + + expect(harness.session.getFollowUpMessages()).toEqual(["after this"]); + expect(harness.session.getSteeringMessages()).toEqual([]); + + releaseToolExecution(); + await promptPromise; + }); + + it("starts a turn when nothing runs, without the caller checking first", async () => { + const harness = await createHarness(); + harnesses.push(harness); + harness.setResponses([fauxAssistantMessage("answered")]); + + await harness.session.submit("hello there", { duringRun: "followUp" }); + + expect(getUserTexts(harness)).toEqual(["hello there"]); + expect(getAssistantTexts(harness)).toEqual(["answered"]); + }); + + it("refuses to steer a session-handled command too", async () => { + const harness = await createHarness(); + harnesses.push(harness); + + // `/clm` is dispatched by the session itself, not by an extension, and it + // used to slip past the guard and reach the model as literal text. + await expect(harness.session.steer("/clm status")).rejects.toThrow( + 'Command "/clm" cannot be queued as a message.', + ); + expect(harness.session.getSteeringMessages()).toEqual([]); + }); + + it("keeps a skill command a message rather than a command", async () => { + const { harness, releaseToolExecution, promptPromise } = await createRunningHarness(); + + // An unknown skill passes through as text, so it joins the run as a steer. + await harness.session.submit("/skill:missing do this"); + expect(harness.session.getSteeringMessages()).toEqual(["/skill:missing do this"]); + + releaseToolExecution(); + await promptPromise; + }); +});