mini-coder 0.5.13 → 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/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,17 +6,17 @@
 
 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,
   type SubmitTurnHooks,
   submitResolvedInput,
 } from "./submit.ts";
-import {
-  collapseWhitespaceToNull,
-  joinTextBlocks,
-  truncateText,
-} from "./text.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -58,8 +58,6 @@ interface HeadlessProcessStream {
   write(text: string, callback?: () => void): boolean;
 }
 
-const HEADLESS_ACTIVITY_MAX_CHARS = 160;
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -143,37 +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 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, HEADLESS_ACTIVITY_MAX_CHARS) : null;
-}
-
 function shouldWriteHeadlessJsonEvent(event: AgentEvent): boolean {
   switch (event.type) {
     case "user_message":
@@ -317,7 +284,7 @@ export async function runHeadlessPrompt(
  * The raw input is parsed with the same rules as interactive input. Slash
  * commands are rejected in headless mode. The final assistant text is written
  * to stdout, while lightweight assistant commentary snippets from tool-use
- * turns are written to stderr.
+ * 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.
@@ -378,6 +345,12 @@ export async function runHeadlessPromptText(
     if (finalText.length > 0) {
       finalOutput.write(finalText);
     }
+
+    const terminalErrorText = extractAssistantErrorText(finalAssistantMessage);
+    if (terminalErrorText) {
+      activityOutput.write(`${terminalErrorText}\n`);
+    }
+
     const [finalStopReason, activityStopReason] = await Promise.all([
       finalOutput.finalize(stopReason),
       activityOutput.finalize(stopReason),

package/src/index.ts

@@ -13,6 +13,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import type {
+  AssistantMessage,
   KnownProvider,
   Model,
   OAuthCredentials,
@@ -22,7 +23,16 @@ import type {
 } from "@mariozechner/pi-ai";
 import { getEnvApiKey, getModels, getProviders } from "@mariozechner/pi-ai";
 import { getOAuthApiKey, getOAuthProviders } from "@mariozechner/pi-ai/oauth";
-import type { ToolHandler } from "./agent.ts";
+import {
+  runAgentLoop,
+  type ToolHandler,
+  type ToolUpdateCallback,
+} from "./agent.ts";
+import {
+  extractAssistantActivitySnippet,
+  extractAssistantErrorText,
+  extractAssistantText,
+} from "./assistant-output.ts";
 import {
   type CliOptions,
   parseCliArgs,
@@ -30,6 +40,10 @@ import {
   shouldUseHeadlessMode,
   type TtyState,
 } from "./cli.ts";
+import {
+  readShellDelegationContext,
+  type ShellDelegationContext,
+} from "./delegation.ts";
 import { getErrorMessage } from "./errors.ts";
 import { type GitState, getGitState } from "./git.ts";
 import { discoverMcpServers, type McpServerState } from "./mcp.ts";
@@ -44,6 +58,8 @@ import {
   appendMessage,
   createConversationSnapshot,
   createSession,
+  deleteSession,
+  loadCompactedModelMessages,
   type loadMessages,
   openDatabase,
   type Session,
@@ -60,8 +76,12 @@ import {
 import { discoverSkills, type Skill } from "./skills.ts";
 import { DEFAULT_THEME, type Theme } from "./theme.ts";
 import {
+  createDelegateToolHandler,
+  createDelegationAwareShellToolHandler,
   createTodoReadToolHandler,
   createTodoWriteToolHandler,
+  type DelegateRunResult,
+  delegateTool,
   editTool,
   editToolHandler,
   grepTool,
@@ -71,7 +91,6 @@ import {
   readTool,
   readToolHandler,
   shellTool,
-  shellToolHandler,
   todoReadTool,
   todoWriteTool,
 } from "./tools.ts";
@@ -351,19 +370,128 @@ function selectModel(
 // Tool wiring
 // ---------------------------------------------------------------------------
 
+type ToolRuntimeState = Pick<
+  AppState,
+  | "agentsMd"
+  | "cwd"
+  | "db"
+  | "delegationDepth"
+  | "delegationBudgetRemaining"
+  | "effort"
+  | "git"
+  | "mcpServers"
+  | "messages"
+  | "providers"
+  | "skills"
+> & {
+  model: Model<string>;
+};
+
+/**
+ * Run one isolated delegated subtask with the current model and toolset.
+ *
+ * @param task - Raw delegated subtask prompt.
+ * @param state - Runtime state to inherit into the delegated child run.
+ * @param context - Delegation context reserved for the child run.
+ * @param signal - Optional abort signal from the parent run.
+ * @param onUpdate - Optional progressive tool-update callback.
+ * @returns The delegated subagent result summary.
+ */
+async function runDelegatedTask(
+  task: string,
+  state: ToolRuntimeState,
+  context: ShellDelegationContext,
+  signal?: AbortSignal,
+  onUpdate?: ToolUpdateCallback,
+): Promise<DelegateRunResult> {
+  const session = createSession(state.db, {
+    cwd: state.cwd,
+    model: `${state.model.provider}/${state.model.id}`,
+    effort: state.effort,
+  });
+  let finalAssistantMessage: AssistantMessage | null = null;
+
+  try {
+    const userMessage = {
+      role: "user",
+      content: task,
+      timestamp: Date.now(),
+    } satisfies UserMessage;
+    const turn = appendMessage(state.db, session.id, userMessage);
+    const messages = loadCompactedModelMessages(state.db, session.id);
+    const childState: ToolRuntimeState = {
+      ...state,
+      delegationDepth: context.depth,
+      delegationBudgetRemaining: context.remainingBudget,
+      messages,
+    };
+    const { tools, toolHandlers } = buildTools(childState);
+
+    const result = await runAgentLoop({
+      db: state.db,
+      sessionId: session.id,
+      turn,
+      model: state.model,
+      systemPrompt: buildPrompt(childState),
+      tools,
+      toolHandlers,
+      messages,
+      cwd: state.cwd,
+      apiKey: state.providers.get(state.model.provider),
+      effort: state.effort,
+      signal,
+      onEvent: (event) => {
+        switch (event.type) {
+          case "assistant_message": {
+            const snippet = extractAssistantActivitySnippet(event.message);
+            if (snippet) {
+              onUpdate?.({
+                content: [
+                  {
+                    type: "text",
+                    text: `Subagent: ${snippet}`,
+                  },
+                ],
+                isError: false,
+              });
+            }
+            break;
+          }
+          case "done":
+          case "error":
+          case "aborted":
+            finalAssistantMessage = event.message;
+            break;
+          default:
+            break;
+        }
+      },
+    });
+
+    return {
+      stopReason: result.stopReason,
+      finalText: extractAssistantText(finalAssistantMessage),
+      errorText: extractAssistantErrorText(finalAssistantMessage),
+    };
+  } finally {
+    deleteSession(state.db, session.id);
+  }
+}
+
 /**
  * Build tool definitions and handler map for the current model.
  *
  * Returns the `Tool[]` to send to the model and the handler map
  * for the agent loop to dispatch tool calls.
  */
-function buildTools(
-  model: Model<string>,
-  messages: AppState["messages"],
-  mcpServers: readonly McpServerState[],
-): { tools: Tool[]; toolHandlers: Map<string, ToolHandler> } {
+function buildTools(state: ToolRuntimeState): {
+  tools: Tool[];
+  toolHandlers: Map<string, ToolHandler>;
+} {
+  const { mcpServers, messages, model } = state;
   const tools: Tool[] = [
     shellTool,
+    delegateTool,
     readTool,
     grepTool,
     editTool,
@@ -371,7 +499,33 @@ function buildTools(
     todoReadTool,
   ];
   const toolHandlers = new Map<string, ToolHandler>([
-    [shellTool.name, shellToolHandler],
+    [
+      shellTool.name,
+      createDelegationAwareShellToolHandler({
+        getDelegationContext: () => ({
+          depth: state.delegationDepth,
+          remainingBudget: state.delegationBudgetRemaining,
+        }),
+        setDelegationContext: (context) => {
+          state.delegationBudgetRemaining = context.remainingBudget;
+        },
+      }),
+    ],
+    [
+      delegateTool.name,
+      createDelegateToolHandler({
+        getDelegationContext: () => ({
+          depth: state.delegationDepth,
+          remainingBudget: state.delegationBudgetRemaining,
+        }),
+        setDelegationContext: (context) => {
+          state.delegationBudgetRemaining = context.remainingBudget;
+        },
+        runSubagent: (task, context, signal, onUpdate) => {
+          return runDelegatedTask(task, state, context, signal, onUpdate);
+        },
+      }),
+    ],
     [readTool.name, readToolHandler],
     [grepTool.name, grepToolHandler],
     [editTool.name, editToolHandler],
@@ -527,6 +681,12 @@ export interface AppState {
   versionLabel: string;
   /** Current git state (null if not in a repo). */
   git: GitState | null;
+  /** Delegated-subagent depth inherited by this app process. */
+  delegationDepth: number;
+  /** Delegated-subagent budget reset at the start of each top-level agent run. */
+  delegationBudgetLimit: number;
+  /** Remaining delegated-subagent launches in the active run. */
+  delegationBudgetRemaining: number;
   /** Available provider credentials (provider → API key). */
   providers: Map<string, string>;
   /** OAuth credentials on disk. */
@@ -595,6 +755,7 @@ export async function init(): Promise<AppState> {
   }
 
   const mcpResult = await discoverMcpServers(effectiveSettings.mcp);
+  const delegation = readShellDelegationContext(process.env);
 
   const builtInModels = listAvailableModels(providers);
   const availableModels = [...builtInModels, ...customResult.models];
@@ -622,6 +783,9 @@ export async function init(): Promise<AppState> {
     theme: promptContext.theme,
     versionLabel: resolveAppVersionLabel(),
     git: promptContext.git,
+    delegationDepth: delegation.depth,
+    delegationBudgetLimit: delegation.remainingBudget,
+    delegationBudgetRemaining: delegation.remainingBudget,
     providers,
     oauthCredentials,
     settings,
@@ -663,7 +827,9 @@ function resolvePromptOs(): "linux" | "mac" | "docker" {
  * Separated from `init` because turns still rebuild the assembled prompt
  * from the session-stable prompt context plus the current runtime state.
  */
-export function buildPrompt(state: AppState): string {
+export function buildPrompt(
+  state: Pick<AppState, "cwd" | "model" | "git" | "agentsMd" | "skills">,
+): string {
   return buildSystemPrompt({
     cwd: state.cwd,
     modelLabel: state.model
@@ -683,8 +849,22 @@ export function buildToolList(state: AppState): {
   tools: Tool[];
   toolHandlers: Map<string, ToolHandler>;
 } {
-  if (!state.model) return { tools: [], toolHandlers: new Map() };
-  return buildTools(state.model, state.messages, state.mcpServers);
+  const { model } = state;
+  if (!model) return { tools: [], toolHandlers: new Map() };
+  return buildTools({
+    agentsMd: state.agentsMd,
+    cwd: state.cwd,
+    db: state.db,
+    delegationDepth: state.delegationDepth,
+    delegationBudgetRemaining: state.delegationBudgetRemaining,
+    effort: state.effort,
+    git: state.git,
+    mcpServers: state.mcpServers,
+    messages: state.messages,
+    model,
+    providers: state.providers,
+    skills: state.skills,
+  });
 }
 
 /**