mini-coder 0.5.12 → 0.5.14

package/src/assistant-output.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared helpers for extracting user-visible assistant output.
+ *
+ * @module
+ */
+
+import type { AssistantMessage } from "@mariozechner/pi-ai";
+import {
+  collapseWhitespaceToNull,
+  joinTextBlocks,
+  truncateText,
+} from "./text.ts";
+
+const ASSISTANT_ACTIVITY_MAX_CHARS = 160;
+
+/**
+ * Extract concatenated text blocks from an assistant message.
+ *
+ * @param message - Assistant message to inspect.
+ * @returns The combined text content, or an empty string when none exists.
+ */
+export function extractAssistantText(message: AssistantMessage | null): string {
+  if (!message) {
+    return "";
+  }
+
+  return message.content
+    .filter(
+      (
+        block,
+      ): block is Extract<
+        AssistantMessage["content"][number],
+        { type: "text" }
+      > => {
+        return block.type === "text";
+      },
+    )
+    .map((block) => block.text)
+    .join("");
+}
+
+/**
+ * Extract a short assistant activity snippet from a tool-using message.
+ *
+ * @param message - Assistant message to inspect.
+ * @returns A collapsed activity snippet, or `null` when no snippet applies.
+ */
+export function extractAssistantActivitySnippet(
+  message: AssistantMessage,
+): string | null {
+  if (!message.content.some((block) => block.type === "toolCall")) {
+    return null;
+  }
+
+  const text = collapseWhitespaceToNull(joinTextBlocks(message.content));
+  return text ? truncateText(text, ASSISTANT_ACTIVITY_MAX_CHARS) : null;
+}
+
+/**
+ * Extract terminal assistant error text from a failed assistant message.
+ *
+ * @param message - Assistant message to inspect.
+ * @returns Collapsed error text, or `null` when the message is not terminally errored.
+ */
+export function extractAssistantErrorText(
+  message: AssistantMessage | null,
+): string | null {
+  if (!message || message.stopReason !== "error" || !message.errorMessage) {
+    return null;
+  }
+
+  return collapseWhitespaceToNull(message.errorMessage) ?? null;
+}

package/src/cli.ts

@@ -32,7 +32,8 @@ export interface TtyState {
  * Parse supported CLI arguments.
  *
  * Supports `-p, --prompt <text>` for headless one-shot mode and `--json`
- * to stream NDJSON events instead of the default final-text output.
+ * to stream NDJSON events instead of the default final-text mode
+ * (stdout final answer plus stderr activity snippets).
  * Unknown flags and positional arguments fail eagerly.
  *
  * @param argv - Process arguments excluding the Bun executable and script path.

package/src/delegation.ts

@@ -0,0 +1,238 @@
+/**
+ * Subagent delegation safeguards.
+ *
+ * Tracks a shallow delegation depth plus a small per-run delegation budget so
+ * first-class `delegate` tool runs and shell-authored `mc -p` child processes
+ * cannot recurse forever.
+ *
+ * @module
+ */
+
+const SHELL_DELEGATION_COMMAND =
+  /(?:^|[;&|()\s])(?:[^\s;&|()]+\/)?mc\s+(?:-p\b|--prompt(?:\b|=))/g;
+
+/** Environment variable carrying the current subagent-delegation depth. */
+export const SHELL_DELEGATION_DEPTH_ENV = "MC_SUBAGENT_DEPTH";
+
+/** Environment variable carrying the remaining subagent-delegation budget. */
+export const SHELL_DELEGATION_BUDGET_ENV = "MC_SUBAGENT_BUDGET";
+
+/** Maximum allowed subagent delegation depth. */
+export const MAX_SHELL_DELEGATION_DEPTH = 1;
+
+/** Default number of delegated subagent launches allowed per agent run. */
+export const DEFAULT_SHELL_DELEGATION_BUDGET = 4;
+
+/** Current subagent-delegation context for one app run. */
+export interface ShellDelegationContext {
+  /** Current subagent-delegation depth for this app process. */
+  depth: number;
+  /** Remaining delegated-subagent launches available in the active run. */
+  remainingBudget: number;
+}
+
+/** Result of reserving subagent-delegation budget for one launch. */
+export interface ShellDelegationReservation {
+  /** Number of delegated-subagent launches reserved by the request. */
+  launchCount: number;
+  /** Updated parent-run context after reserving any delegated launches. */
+  updatedContext: ShellDelegationContext;
+  /** Context that delegated child runs should inherit for this request. */
+  childContext: ShellDelegationContext;
+}
+
+/** Successful or blocked delegation-reservation outcome. */
+export type ReserveShellDelegationResult =
+  | {
+      /** Whether the delegation request may proceed. */
+      ok: true;
+      /** Reserved delegation details for the request. */
+      reservation: ShellDelegationReservation;
+    }
+  | {
+      /** Whether the delegation request may proceed. */
+      ok: false;
+      /** Human-readable tool error for the blocked delegation attempt. */
+      error: string;
+    };
+
+type DelegationReservationError = "nested" | "exhausted" | "over_budget";
+
+function readNonNegativeInteger(
+  value: string | undefined,
+  fallback: number,
+): number {
+  if (value == null || value === "") {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function reserveDelegationBudget(
+  context: ShellDelegationContext,
+  launchCount: number,
+):
+  | {
+      ok: true;
+      reservation: ShellDelegationReservation;
+    }
+  | {
+      ok: false;
+      reason: DelegationReservationError;
+    } {
+  if (launchCount === 0) {
+    const unchanged = { ...context };
+    return {
+      ok: true,
+      reservation: {
+        launchCount,
+        updatedContext: unchanged,
+        childContext: unchanged,
+      },
+    };
+  }
+
+  if (context.depth >= MAX_SHELL_DELEGATION_DEPTH) {
+    return {
+      ok: false,
+      reason: "nested",
+    };
+  }
+
+  if (context.remainingBudget === 0) {
+    return {
+      ok: false,
+      reason: "exhausted",
+    };
+  }
+
+  if (launchCount > context.remainingBudget) {
+    return {
+      ok: false,
+      reason: "over_budget",
+    };
+  }
+
+  const remainingBudget = context.remainingBudget - launchCount;
+  return {
+    ok: true,
+    reservation: {
+      launchCount,
+      updatedContext: {
+        depth: context.depth,
+        remainingBudget,
+      },
+      childContext: {
+        depth: context.depth + 1,
+        remainingBudget,
+      },
+    },
+  };
+}
+
+/**
+ * Read the current subagent-delegation context from environment variables.
+ *
+ * Missing or invalid values fall back to the safe root-run defaults.
+ *
+ * @param env - Environment variables to inspect.
+ * @returns The parsed subagent-delegation context.
+ */
+export function readShellDelegationContext(
+  env: Readonly<Record<string, string | undefined>>,
+): ShellDelegationContext {
+  return {
+    depth: readNonNegativeInteger(env[SHELL_DELEGATION_DEPTH_ENV], 0),
+    remainingBudget: readNonNegativeInteger(
+      env[SHELL_DELEGATION_BUDGET_ENV],
+      DEFAULT_SHELL_DELEGATION_BUDGET,
+    ),
+  };
+}
+
+/**
+ * Build the environment-variable overrides for a subagent-delegation context.
+ *
+ * @param context - Subagent-delegation context to serialize.
+ * @returns Environment overrides for child shell processes.
+ */
+export function buildShellDelegationEnv(
+  context: ShellDelegationContext,
+): Record<string, string> {
+  return {
+    [SHELL_DELEGATION_DEPTH_ENV]: String(context.depth),
+    [SHELL_DELEGATION_BUDGET_ENV]: String(context.remainingBudget),
+  };
+}
+
+/**
+ * Count likely shell-authored `mc -p` / `mc --prompt` launches in one command.
+ *
+ * The detector is intentionally narrow and optimized for the prompt-guided
+ * `mc -p "subtask"` pattern mini-coder still supports for CLI-level testing.
+ *
+ * @param command - Raw shell command.
+ * @returns Number of likely `mc -p` launches in the command.
+ */
+export function countShellDelegationLaunches(command: string): number {
+  return command.match(SHELL_DELEGATION_COMMAND)?.length ?? 0;
+}
+
+/**
+ * Reserve first-class `delegate` tool budget for one delegated subagent run.
+ *
+ * @param context - Current subagent-delegation context for the active run.
+ * @returns Reservation details, or a blocking error when this delegation would
+ *          exceed the allowed subagent-delegation policy.
+ */
+export function reserveToolDelegation(
+  context: ShellDelegationContext,
+): ReserveShellDelegationResult {
+  const reservation = reserveDelegationBudget(context, 1);
+  if (!reservation.ok) {
+    return {
+      ok: false,
+      error:
+        reservation.reason === "nested"
+          ? "Tool delegation blocked: delegated `delegate` tool runs may not delegate again."
+          : "Tool delegation blocked: this run has no remaining `delegate` delegation budget.",
+    };
+  }
+
+  return reservation;
+}
+
+/**
+ * Reserve shell-level delegation budget for a command before execution.
+ *
+ * Non-delegating commands pass through unchanged. Commands that would exceed
+ * the per-run delegation budget or the maximum allowed depth are rejected with
+ * a user-visible tool error.
+ *
+ * @param command - Raw shell command to inspect.
+ * @param context - Current subagent-delegation context for the active run.
+ * @returns Reservation details, or a blocking error when the command would
+ *          exceed the allowed shell-level delegation policy.
+ */
+export function reserveShellDelegation(
+  command: string,
+  context: ShellDelegationContext,
+): ReserveShellDelegationResult {
+  const launchCount = countShellDelegationLaunches(command);
+  const reservation = reserveDelegationBudget(context, launchCount);
+  if (!reservation.ok) {
+    return {
+      ok: false,
+      error:
+        reservation.reason === "nested"
+          ? "Shell delegation blocked: delegated `mc -p` runs may not launch more `mc -p` subagents."
+          : reservation.reason === "exhausted"
+            ? "Shell delegation blocked: this run has no remaining `mc -p` delegation budget."
+            : "Shell delegation blocked: this command appears to launch more `mc -p` subagents than the remaining delegation budget allows.",
+    };
+  }
+
+  return reservation;
+}

package/src/headless.ts

@@ -6,6 +6,11 @@
 
 import type { AssistantMessage, UserMessage } from "@mariozechner/pi-ai";
 import type { AgentEvent } from "./agent.ts";
+import {
+  extractAssistantActivitySnippet,
+  extractAssistantErrorText,
+  extractAssistantText,
+} from "./assistant-output.ts";
 import type { AppState } from "./index.ts";
 import {
   resolveRawInput,
@@ -27,31 +32,45 @@ export interface HeadlessRunOptions {
 
 /** Options for a headless final-text run. */
 export interface HeadlessTextRunOptions {
+  /** Optional writer for lightweight assistant-activity snippets. */
+  writeActivity?: (text: string) => void | Promise<void>;
   /** Optional writer for the final assistant text output. */
   writeText?: (text: string) => void | Promise<void>;
 }
 
 interface HeadlessOutputController {
-  /** Queue text for stdout with broken-pipe handling. */
+  /** Queue text for one output stream with broken-pipe handling. */
   write(text: string): void;
-  /** Attach SIGINT/stdout error handlers for the active run. */
+  /** Attach error handlers for the active run. */
   attach(): void;
-  /** Remove SIGINT/stdout error handlers after the run. */
+  /** Remove error handlers after the run. */
   detach(): void;
   /** Wait for queued writes and resolve the final stop reason. */
   finalize(stopReason: HeadlessStopReason): Promise<HeadlessStopReason>;
 }
 
+interface HeadlessProcessStream {
+  /** Register an output-stream error handler. */
+  on(event: "error", listener: (error: unknown) => void): void;
+  /** Remove an output-stream error handler. */
+  off(event: "error", listener: (error: unknown) => void): void;
+  /** Write a text chunk to the stream. */
+  write(text: string, callback?: () => void): boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-function defaultWrite(text: string): Promise<void> {
+function defaultWrite(
+  stream: HeadlessProcessStream,
+  text: string,
+): Promise<void> {
   return new Promise((resolve, reject) => {
     let settled = false;
 
     const cleanup = (): void => {
-      process.stdout.off("error", handleError);
+      stream.off("error", handleError);
     };
 
     const settle = (callback: () => void): void => {
@@ -69,9 +88,9 @@ function defaultWrite(text: string): Promise<void> {
       });
     };
 
-    process.stdout.on("error", handleError);
+    stream.on("error", handleError);
     try {
-      process.stdout.write(text, () => {
+      stream.write(text, () => {
         settle(resolve);
       });
     } catch (error) {
@@ -122,26 +141,6 @@ function resolveHeadlessContent(
   }
 }
 
-function extractAssistantText(message: AssistantMessage | null): string {
-  if (!message) {
-    return "";
-  }
-
-  return message.content
-    .filter(
-      (
-        block,
-      ): block is Extract<
-        AssistantMessage["content"][number],
-        { type: "text" }
-      > => {
-        return block.type === "text";
-      },
-    )
-    .map((block) => block.text)
-    .join("");
-}
-
 function shouldWriteHeadlessJsonEvent(event: AgentEvent): boolean {
   switch (event.type) {
     case "user_message":
@@ -158,12 +157,17 @@ function shouldWriteHeadlessJsonEvent(event: AgentEvent): boolean {
 
 function createHeadlessOutputController(
   state: AppState,
+  stream: HeadlessProcessStream,
   writeImpl: (text: string) => void | Promise<void>,
+  options?: {
+    attachSigint?: boolean;
+  },
 ): HeadlessOutputController {
   let brokenPipe = false;
   let outputError: unknown = null;
   let pendingWrite = Promise.resolve();
   const sigintHandler = createSigintHandler(state);
+  const attachSigint = options?.attachSigint ?? true;
 
   const stopForBrokenPipe = (): void => {
     if (brokenPipe) {
@@ -183,7 +187,7 @@ function createHeadlessOutputController(
     state.abortController?.abort();
   };
 
-  const stdoutErrorHandler = (error: unknown): void => {
+  const streamErrorHandler = (error: unknown): void => {
     failOutput(error);
   };
 
@@ -206,12 +210,16 @@ function createHeadlessOutputController(
       });
     },
     attach() {
-      process.stdout.on("error", stdoutErrorHandler);
-      process.on("SIGINT", sigintHandler);
+      stream.on("error", streamErrorHandler);
+      if (attachSigint) {
+        process.on("SIGINT", sigintHandler);
+      }
     },
     detach() {
-      process.stdout.off("error", stdoutErrorHandler);
-      process.off("SIGINT", sigintHandler);
+      stream.off("error", streamErrorHandler);
+      if (attachSigint) {
+        process.off("SIGINT", sigintHandler);
+      }
     },
     async finalize(stopReason) {
       await pendingWrite;
@@ -244,7 +252,8 @@ export async function runHeadlessPrompt(
   const content = resolveHeadlessContent(state, rawInput);
   const output = createHeadlessOutputController(
     state,
-    options?.writeLine ?? ((line) => defaultWrite(`${line}\n`)),
+    process.stdout,
+    options?.writeLine ?? ((line) => defaultWrite(process.stdout, `${line}\n`)),
   );
   const hooks: SubmitTurnHooks = {
     onEvent: (event) => {
@@ -270,11 +279,12 @@ export async function runHeadlessPrompt(
 }
 
 /**
- * Run a single headless prompt to completion and write only the final assistant text.
+ * Run a single headless prompt to completion and write the final assistant text.
  *
  * The raw input is parsed with the same rules as interactive input. Slash
- * commands are rejected in headless mode. Only the final persisted assistant
- * message's text content is written to stdout.
+ * commands are rejected in headless mode. The final assistant text is written
+ * to stdout, while lightweight assistant commentary snippets from tool-use
+ * turns and terminal assistant error messages are written to stderr.
  *
  * @param state - Mutable application state for the run.
  * @param rawInput - Exact raw prompt text supplied by the user.
@@ -287,20 +297,43 @@ export async function runHeadlessPromptText(
   options?: HeadlessTextRunOptions,
 ): Promise<HeadlessStopReason> {
   const content = resolveHeadlessContent(state, rawInput);
-  const output = createHeadlessOutputController(
+  const finalOutput = createHeadlessOutputController(
+    state,
+    process.stdout,
+    options?.writeText ?? ((text) => defaultWrite(process.stdout, text)),
+  );
+  const activityOutput = createHeadlessOutputController(
     state,
-    options?.writeText ?? defaultWrite,
+    process.stderr,
+    options?.writeActivity ?? ((text) => defaultWrite(process.stderr, text)),
+    { attachSigint: false },
   );
   let finalAssistantMessage: AssistantMessage | null = null;
   const hooks: SubmitTurnHooks = {
     onEvent: (event) => {
-      if (event.type === "assistant_message") {
-        finalAssistantMessage = event.message;
+      switch (event.type) {
+        case "assistant_message": {
+          const activitySnippet = extractAssistantActivitySnippet(
+            event.message,
+          );
+          if (activitySnippet) {
+            activityOutput.write(`${activitySnippet}\n`);
+          }
+          return;
+        }
+        case "done":
+        case "error":
+        case "aborted":
+          finalAssistantMessage = event.message;
+          return;
+        default:
+          return;
       }
     },
   };
 
-  output.attach();
+  finalOutput.attach();
+  activityOutput.attach();
   try {
     const stopReason = await submitResolvedInput(
       rawInput,
@@ -310,10 +343,23 @@ export async function runHeadlessPromptText(
     );
     const finalText = extractAssistantText(finalAssistantMessage);
     if (finalText.length > 0) {
-      output.write(finalText);
+      finalOutput.write(finalText);
     }
-    return await output.finalize(stopReason);
+
+    const terminalErrorText = extractAssistantErrorText(finalAssistantMessage);
+    if (terminalErrorText) {
+      activityOutput.write(`${terminalErrorText}\n`);
+    }
+
+    const [finalStopReason, activityStopReason] = await Promise.all([
+      finalOutput.finalize(stopReason),
+      activityOutput.finalize(stopReason),
+    ]);
+    return finalStopReason === "stop" || activityStopReason === "stop"
+      ? "stop"
+      : stopReason;
   } finally {
-    output.detach();
+    activityOutput.detach();
+    finalOutput.detach();
   }
 }