@@ -4,6 +4,7 @@
44 * @module
55 */
66
7+import type { AssistantMessage, UserMessage } from "@mariozechner/pi-ai";
78 import type { AppState } from "./index.ts";
89 import {
910 resolveRawInput,
@@ -15,18 +16,37 @@ import {
1516 // Types
1617 // ---------------------------------------------------------------------------
1718
18-/** Options for a headless one-shot run. */
19+type HeadlessStopReason = "stop" | "length" | "error" | "aborted";
20+
21+/** Options for a headless NDJSON run. */
1922 export interface HeadlessRunOptions {
2023 /** Optional line writer for NDJSON event output. */
2124 writeLine?: (line: string) => void;
2225 }
2326
27+/** Options for a headless final-text run. */
28+export interface HeadlessTextRunOptions {
29+ /** Optional writer for the final assistant text output. */
30+ writeText?: (text: string) => void;
31+}
32+
33+interface HeadlessOutputController {
34+ /** Write text to stdout with broken-pipe handling. */
35+ write(text: string): void;
36+ /** Attach SIGINT/stdout error handlers for the active run. */
37+ attach(): void;
38+ /** Remove SIGINT/stdout error handlers after the run. */
39+ detach(): void;
40+ /** Resolve the final stop reason, converting broken pipes into quiet shutdowns. */
41+ finalize(stopReason: HeadlessStopReason): HeadlessStopReason;
42+}
43+
2444 // ---------------------------------------------------------------------------
2545 // Helpers
2646 // ---------------------------------------------------------------------------
2747
28-function defaultWriteLine(line: string): void {
29- process.stdout.write(`${line}\n`);
48+function defaultWrite(text: string): void {
49+ process.stdout.write(text);
3050 }
3151
3252 function isBrokenPipeError(error: unknown): boolean {
@@ -52,23 +72,10 @@ function buildCommandError(command: string): Error {
5272 );
5373 }
5474
55-/**
56- * Run a single headless prompt to completion and stream NDJSON events.
57- *
58- * The raw input is parsed with the same rules as interactive input. Slash
59- * commands are rejected in headless mode. Assistant/tool events are written as
60- * one JSON object per line.
61- *
62- * @param state - Mutable application state for the run.
63- * @param rawInput - Exact raw prompt text supplied by the user.
64- * @param options - Optional event-output overrides.
65- * @returns The terminal stop reason for the agent loop.
66- */
67-export async function runHeadlessPrompt(
75+function resolveHeadlessContent(
6876 state: AppState,
6977 rawInput: string,
70- options?: HeadlessRunOptions,
71-): Promise<"stop" | "length" | "error" | "aborted"> {
78+): UserMessage["content"] {
7279 const resolved = resolveRawInput(rawInput, state);
7380 switch (resolved.type) {
7481 case "empty":
@@ -78,11 +85,38 @@ export async function runHeadlessPrompt(
7885 case "command":
7986 throw buildCommandError(resolved.command);
8087 case "message":
81- break;
88+ return resolved.content;
89+ }
90+}
91+
92+function extractAssistantText(message: AssistantMessage | null): string {
93+ if (!message) {
94+ return "";
8295 }
8396
97+ return message.content
98+ .filter(
99+ (
100+ block,
101+ ): block is Extract<
102+ AssistantMessage["content"][number],
103+ { type: "text" }
104+ > => {
105+ return block.type === "text";
106+ },
107+ )
108+ .map((block) => block.text)
109+ .join("");
110+}
111+
112+function createHeadlessOutputController(
113+ state: AppState,
114+ writeImpl: (text: string) => void,
115+): HeadlessOutputController {
84116 let brokenPipe = false;
85117 let outputError: unknown = null;
118+ const sigintHandler = createSigintHandler(state);
119+
86120 const stopForBrokenPipe = (): void => {
87121 if (brokenPipe) {
88122 return;
@@ -90,51 +124,136 @@ export async function runHeadlessPrompt(
90124 brokenPipe = true;
91125 state.abortController?.abort();
92126 };
93- const writeLineImpl = options?.writeLine ?? defaultWriteLine;
94- const writeLine = (line: string): void => {
95- if (brokenPipe) {
127+
128+ const stdoutErrorHandler = (error: unknown): void => {
129+ if (isBrokenPipeError(error)) {
130+ stopForBrokenPipe();
96131 return;
97132 }
98133
99- try {
100- writeLineImpl(line);
101- } catch (error) {
102- if (!isBrokenPipeError(error)) {
103- throw error;
134+ outputError = error;
135+ state.abortController?.abort();
136+ };
137+
138+ return {
139+ write(text) {
140+ if (brokenPipe) {
141+ return;
104142 }
105- stopForBrokenPipe();
106- }
143+
144+ try {
145+ writeImpl(text);
146+ } catch (error) {
147+ if (!isBrokenPipeError(error)) {
148+ throw error;
149+ }
150+ stopForBrokenPipe();
151+ }
152+ },
153+ attach() {
154+ process.stdout.on("error", stdoutErrorHandler);
155+ process.on("SIGINT", sigintHandler);
156+ },
157+ detach() {
158+ process.stdout.off("error", stdoutErrorHandler);
159+ process.off("SIGINT", sigintHandler);
160+ },
161+ finalize(stopReason) {
162+ if (outputError) {
163+ throw outputError;
164+ }
165+ return brokenPipe ? "stop" : stopReason;
166+ },
107167 };
168+}
169+
170+/**
171+ * Run a single headless prompt to completion and stream NDJSON events.
172+ *
173+ * The raw input is parsed with the same rules as interactive input. Slash
174+ * commands are rejected in headless mode. Assistant/tool events are written as
175+ * one JSON object per line.
176+ *
177+ * @param state - Mutable application state for the run.
178+ * @param rawInput - Exact raw prompt text supplied by the user.
179+ * @param options - Optional event-output overrides.
180+ * @returns The terminal stop reason for the agent loop.
181+ */
182+export async function runHeadlessPrompt(
183+ state: AppState,
184+ rawInput: string,
185+ options?: HeadlessRunOptions,
186+): Promise<HeadlessStopReason> {
187+ const content = resolveHeadlessContent(state, rawInput);
188+ const output = createHeadlessOutputController(
189+ state,
190+ options?.writeLine ?? ((line) => defaultWrite(`${line}\n`)),
191+ );
108192 const hooks: SubmitTurnHooks = {
109193 onEvent: (event) => {
110- writeLine(JSON.stringify(event));
194+ output.write(JSON.stringify(event));
111195 },
112196 };
113- const sigintHandler = createSigintHandler(state);
114- const stdoutErrorHandler = (error: unknown): void => {
115- if (isBrokenPipeError(error)) {
116- stopForBrokenPipe();
117- return;
118- }
119- outputError = error;
120- state.abortController?.abort();
197+
198+ output.attach();
199+ try {
200+ const stopReason = await submitResolvedInput(
201+ rawInput,
202+ content,
203+ state,
204+ hooks,
205+ );
206+ return output.finalize(stopReason);
207+ } finally {
208+ output.detach();
209+ }
210+}
211+
212+/**
213+ * Run a single headless prompt to completion and write only the final assistant text.
214+ *
215+ * The raw input is parsed with the same rules as interactive input. Slash
216+ * commands are rejected in headless mode. Only the final persisted assistant
217+ * message's text content is written to stdout.
218+ *
219+ * @param state - Mutable application state for the run.
220+ * @param rawInput - Exact raw prompt text supplied by the user.
221+ * @param options - Optional final-text output overrides.
222+ * @returns The terminal stop reason for the agent loop.
223+ */
224+export async function runHeadlessPromptText(
225+ state: AppState,
226+ rawInput: string,
227+ options?: HeadlessTextRunOptions,
228+): Promise<HeadlessStopReason> {
229+ const content = resolveHeadlessContent(state, rawInput);
230+ const output = createHeadlessOutputController(
231+ state,
232+ options?.writeText ?? defaultWrite,
233+ );
234+ let finalAssistantMessage: AssistantMessage | null = null;
235+ const hooks: SubmitTurnHooks = {
236+ onEvent: (event) => {
237+ if (event.type === "assistant_message") {
238+ finalAssistantMessage = event.message;
239+ }
240+ },
121241 };
122242
123- process.stdout.on("error", stdoutErrorHandler);
124- process.on("SIGINT", sigintHandler);
243+ output.attach();
125244 try {
126245 const stopReason = await submitResolvedInput(
127246 rawInput,
128- resolved.content,
247+ content,
129248 state,
130249 hooks,
131250 );
132- if (outputError) {
133- throw outputError;
251+ const finalText = extractAssistantText(finalAssistantMessage);
252+ if (finalText.length > 0) {
253+ output.write(finalText);
134254 }
135- return brokenPipe ? "stop" : stopReason;
255+ return output.finalize(stopReason);
136256 } finally {
137- process.stdout.off("error", stdoutErrorHandler);
138- process.off("SIGINT", sigintHandler);
257+ output.detach();
139258 }
140259 }