@@ -12,6 +12,11 @@ import {
1212 type SubmitTurnHooks,
1313 submitResolvedInput,
1414 } from "./submit.ts";
15+import {
16+ collapseWhitespaceToNull,
17+ joinTextBlocks,
18+ truncateText,
19+} from "./text.ts";
1520
1621 // ---------------------------------------------------------------------------
1722 // Types
@@ -27,31 +32,47 @@ export interface HeadlessRunOptions {
2732
2833 /** Options for a headless final-text run. */
2934 export interface HeadlessTextRunOptions {
35+ /** Optional writer for lightweight assistant-activity snippets. */
36+ writeActivity?: (text: string) => void | Promise<void>;
3037 /** Optional writer for the final assistant text output. */
3138 writeText?: (text: string) => void | Promise<void>;
3239 }
3340
3441 interface HeadlessOutputController {
35- /** Queue text for stdout with broken-pipe handling. */
42+ /** Queue text for one output stream with broken-pipe handling. */
3643 write(text: string): void;
37- /** Attach SIGINT/stdout error handlers for the active run. */
44+ /** Attach error handlers for the active run. */
3845 attach(): void;
39- /** Remove SIGINT/stdout error handlers after the run. */
46+ /** Remove error handlers after the run. */
4047 detach(): void;
4148 /** Wait for queued writes and resolve the final stop reason. */
4249 finalize(stopReason: HeadlessStopReason): Promise<HeadlessStopReason>;
4350 }
4451
52+interface HeadlessProcessStream {
53+ /** Register an output-stream error handler. */
54+ on(event: "error", listener: (error: unknown) => void): void;
55+ /** Remove an output-stream error handler. */
56+ off(event: "error", listener: (error: unknown) => void): void;
57+ /** Write a text chunk to the stream. */
58+ write(text: string, callback?: () => void): boolean;
59+}
60+
61+const HEADLESS_ACTIVITY_MAX_CHARS = 160;
62+
4563 // ---------------------------------------------------------------------------
4664 // Helpers
4765 // ---------------------------------------------------------------------------
4866
49-function defaultWrite(text: string): Promise<void> {
67+function defaultWrite(
68+ stream: HeadlessProcessStream,
69+ text: string,
70+): Promise<void> {
5071 return new Promise((resolve, reject) => {
5172 let settled = false;
5273
5374 const cleanup = (): void => {
54- process.stdout.off("error", handleError);
75+ stream.off("error", handleError);
5576 };
5677
5778 const settle = (callback: () => void): void => {
@@ -69,9 +90,9 @@ function defaultWrite(text: string): Promise<void> {
6990 });
7091 };
7192
72- process.stdout.on("error", handleError);
93+ stream.on("error", handleError);
7394 try {
74- process.stdout.write(text, () => {
95+ stream.write(text, () => {
7596 settle(resolve);
7697 });
7798 } catch (error) {
@@ -142,6 +163,17 @@ function extractAssistantText(message: AssistantMessage | null): string {
142163 .join("");
143164 }
144165
166+function extractAssistantActivitySnippet(
167+ message: AssistantMessage,
168+): string | null {
169+ if (!message.content.some((block) => block.type === "toolCall")) {
170+ return null;
171+ }
172+
173+ const text = collapseWhitespaceToNull(joinTextBlocks(message.content));
174+ return text ? truncateText(text, HEADLESS_ACTIVITY_MAX_CHARS) : null;
175+}
176+
145177 function shouldWriteHeadlessJsonEvent(event: AgentEvent): boolean {
146178 switch (event.type) {
147179 case "user_message":
@@ -158,12 +190,17 @@ function shouldWriteHeadlessJsonEvent(event: AgentEvent): boolean {
158190
159191 function createHeadlessOutputController(
160192 state: AppState,
193+ stream: HeadlessProcessStream,
161194 writeImpl: (text: string) => void | Promise<void>,
195+ options?: {
196+ attachSigint?: boolean;
197+ },
162198 ): HeadlessOutputController {
163199 let brokenPipe = false;
164200 let outputError: unknown = null;
165201 let pendingWrite = Promise.resolve();
166202 const sigintHandler = createSigintHandler(state);
203+ const attachSigint = options?.attachSigint ?? true;
167204
168205 const stopForBrokenPipe = (): void => {
169206 if (brokenPipe) {
@@ -183,7 +220,7 @@ function createHeadlessOutputController(
183220 state.abortController?.abort();
184221 };
185222
186- const stdoutErrorHandler = (error: unknown): void => {
223+ const streamErrorHandler = (error: unknown): void => {
187224 failOutput(error);
188225 };
189226
@@ -206,12 +243,16 @@ function createHeadlessOutputController(
206243 });
207244 },
208245 attach() {
209- process.stdout.on("error", stdoutErrorHandler);
210- process.on("SIGINT", sigintHandler);
246+ stream.on("error", streamErrorHandler);
247+ if (attachSigint) {
248+ process.on("SIGINT", sigintHandler);
249+ }
211250 },
212251 detach() {
213- process.stdout.off("error", stdoutErrorHandler);
214- process.off("SIGINT", sigintHandler);
252+ stream.off("error", streamErrorHandler);
253+ if (attachSigint) {
254+ process.off("SIGINT", sigintHandler);
255+ }
215256 },
216257 async finalize(stopReason) {
217258 await pendingWrite;
@@ -244,7 +285,8 @@ export async function runHeadlessPrompt(
244285 const content = resolveHeadlessContent(state, rawInput);
245286 const output = createHeadlessOutputController(
246287 state,
247- options?.writeLine ?? ((line) => defaultWrite(`${line}\n`)),
288+ process.stdout,
289+ options?.writeLine ?? ((line) => defaultWrite(process.stdout, `${line}\n`)),
248290 );
249291 const hooks: SubmitTurnHooks = {
250292 onEvent: (event) => {
@@ -270,11 +312,12 @@ export async function runHeadlessPrompt(
270312 }
271313
272314 /**
273- * Run a single headless prompt to completion and write only the final assistant text.
315+ * Run a single headless prompt to completion and write the final assistant text.
274316 *
275317 * The raw input is parsed with the same rules as interactive input. Slash
276- * commands are rejected in headless mode. Only the final persisted assistant
277- * message's text content is written to stdout.
318+ * commands are rejected in headless mode. The final assistant text is written
319+ * to stdout, while lightweight assistant commentary snippets from tool-use
320+ * turns are written to stderr.
278321 *
279322 * @param state - Mutable application state for the run.
280323 * @param rawInput - Exact raw prompt text supplied by the user.
@@ -287,20 +330,43 @@ export async function runHeadlessPromptText(
287330 options?: HeadlessTextRunOptions,
288331 ): Promise<HeadlessStopReason> {
289332 const content = resolveHeadlessContent(state, rawInput);
290- const output = createHeadlessOutputController(
333+ const finalOutput = createHeadlessOutputController(
334+ state,
335+ process.stdout,
336+ options?.writeText ?? ((text) => defaultWrite(process.stdout, text)),
337+ );
338+ const activityOutput = createHeadlessOutputController(
291339 state,
292- options?.writeText ?? defaultWrite,
340+ process.stderr,
341+ options?.writeActivity ?? ((text) => defaultWrite(process.stderr, text)),
342+ { attachSigint: false },
293343 );
294344 let finalAssistantMessage: AssistantMessage | null = null;
295345 const hooks: SubmitTurnHooks = {
296346 onEvent: (event) => {
297- if (event.type === "assistant_message") {
298- finalAssistantMessage = event.message;
347+ switch (event.type) {
348+ case "assistant_message": {
349+ const activitySnippet = extractAssistantActivitySnippet(
350+ event.message,
351+ );
352+ if (activitySnippet) {
353+ activityOutput.write(`${activitySnippet}\n`);
354+ }
355+ return;
356+ }
357+ case "done":
358+ case "error":
359+ case "aborted":
360+ finalAssistantMessage = event.message;
361+ return;
362+ default:
363+ return;
299364 }
300365 },
301366 };
302367
303- output.attach();
368+ finalOutput.attach();
369+ activityOutput.attach();
304370 try {
305371 const stopReason = await submitResolvedInput(
306372 rawInput,
@@ -310,10 +376,17 @@ export async function runHeadlessPromptText(
310376 );
311377 const finalText = extractAssistantText(finalAssistantMessage);
312378 if (finalText.length > 0) {
313- output.write(finalText);
379+ finalOutput.write(finalText);
314380 }
315- return await output.finalize(stopReason);
381+ const [finalStopReason, activityStopReason] = await Promise.all([
382+ finalOutput.finalize(stopReason),
383+ activityOutput.finalize(stopReason),
384+ ]);
385+ return finalStopReason === "stop" || activityStopReason === "stop"
386+ ? "stop"
387+ : stopReason;
316388 } finally {
317- output.detach();
389+ activityOutput.detach();
390+ finalOutput.detach();
318391 }
319392 }