mini-coder 0.5.12 → 0.5.14

package/src/tool-delegate.ts

@@ -0,0 +1,125 @@
+/**
+ * First-class delegated-subagent tool.
+ *
+ * @module
+ */
+
+import type { Static, Tool } from "@mariozechner/pi-ai";
+import { Type } from "@mariozechner/pi-ai";
+import type { ToolHandler, ToolUpdateCallback } from "./agent.ts";
+import {
+  reserveToolDelegation,
+  type ShellDelegationContext,
+} from "./delegation.ts";
+import { textResult, validateBuiltinToolArgs } from "./tool-common.ts";
+
+const delegateToolParameters = Type.Object({
+  task: Type.String({
+    description:
+      "Bounded subtask prompt for the delegated subagent. Include the specific goal, constraints, and expected deliverable.",
+  }),
+});
+
+/** Arguments for the `delegate` tool. */
+export type DelegateArgs = Static<typeof delegateToolParameters>;
+
+/** Structured details preserved on a persisted `delegate` tool result. */
+export interface DelegateResultDetails {
+  /** How the delegated subagent run ended. */
+  stopReason: "stop" | "length" | "error" | "aborted";
+}
+
+/** Summarized output returned from one delegated subagent run. */
+export interface DelegateRunResult {
+  /** How the delegated subagent run ended. */
+  stopReason: DelegateResultDetails["stopReason"];
+  /** Final assistant text emitted by the subagent. */
+  finalText: string;
+  /** Terminal assistant error text when the subagent failed. */
+  errorText: string | null;
+}
+
+/** pi-ai tool definition for `delegate`. */
+export const delegateTool: Tool<typeof delegateToolParameters> = {
+  name: "delegate",
+  description:
+    "Run a bounded subtask in an isolated subagent session using the current model, prompt context, and tools. " +
+    "Use this when a focused second agent pass will help, and prefer it over shelling out to `mc -p` unless you are explicitly testing the CLI itself.",
+  parameters: delegateToolParameters,
+};
+
+/** Options for a `delegate` handler that enforces delegation safeguards. */
+export interface CreateDelegateToolHandlerOpts {
+  /** Return the current subagent-delegation context for the active run. */
+  getDelegationContext: () => ShellDelegationContext;
+  /** Persist the updated delegation context after a launch reservation. */
+  setDelegationContext: (context: ShellDelegationContext) => void;
+  /** Execute one delegated subagent run. */
+  runSubagent: (
+    task: string,
+    context: ShellDelegationContext,
+    signal?: AbortSignal,
+    onUpdate?: ToolUpdateCallback,
+  ) => Promise<DelegateRunResult>;
+}
+
+/**
+ * Format the model-visible text payload returned from a delegated subagent run.
+ *
+ * @param result - Delegated subagent result.
+ * @returns Text content suitable for the parent tool result.
+ */
+export function formatDelegateResultText(result: DelegateRunResult): string {
+  const lines = [`Subagent stop reason: ${result.stopReason}`];
+
+  if (result.finalText.length > 0) {
+    lines.push("", "Final answer:", result.finalText);
+  } else {
+    lines.push("", "Final answer:", "(no final text)");
+  }
+
+  if (result.errorText) {
+    lines.push("", "Terminal error:", result.errorText);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Create a `delegate` tool handler that enforces delegation limits.
+ *
+ * @param opts - Delegation-context accessors plus the delegated-run executor.
+ * @returns A tool handler for first-class delegated subagent runs.
+ */
+export function createDelegateToolHandler(
+  opts: CreateDelegateToolHandlerOpts,
+): ToolHandler {
+  return async (args, _cwd, signal, onUpdate) => {
+    const validatedArgs = validateBuiltinToolArgs(delegateTool, args);
+    const reservation = reserveToolDelegation(opts.getDelegationContext());
+    if (!reservation.ok) {
+      return textResult(reservation.error, true);
+    }
+
+    opts.setDelegationContext(reservation.reservation.updatedContext);
+    const result = await opts.runSubagent(
+      validatedArgs.task,
+      reservation.reservation.childContext,
+      signal,
+      onUpdate,
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: formatDelegateResultText(result),
+        },
+      ],
+      details: {
+        stopReason: result.stopReason,
+      } satisfies DelegateResultDetails,
+      isError: result.stopReason === "error" || result.stopReason === "aborted",
+    };
+  };
+}

package/src/tool-shell.ts

@@ -7,6 +7,12 @@
 import type { Static, Tool } from "@mariozechner/pi-ai";
 import { Type } from "@mariozechner/pi-ai";
 import type { ToolHandler, ToolUpdateCallback } from "./agent.ts";
+import {
+  buildShellDelegationEnv,
+  reserveShellDelegation,
+  type ShellDelegationContext,
+} from "./delegation.ts";
+import { readFiniteNumber, readString, toRecord } from "./shared.ts";
 import {
   detectLineEnding,
   normalizeLineEndings,
@@ -32,6 +38,18 @@ export interface ShellOpts {
   signal?: AbortSignal;
   /** Callback for progressive output updates while the command is running. */
   onUpdate?: ToolUpdateCallback;
+  /** Optional environment overrides for the spawned shell process. */
+  env?: Record<string, string>;
+}
+
+/** Structured shell result preserved on tool-result messages and events. */
+export interface ShellResultDetails {
+  /** Captured stdout text after shell-tool truncation. */
+  stdout: string;
+  /** Captured stderr text after shell-tool truncation. */
+  stderr: string;
+  /** Process exit code. */
+  exitCode: number;
 }
 
 /** pi-ai tool definition for `shell`. */
@@ -59,27 +77,178 @@ export const shellToolHandler: ToolHandler = (args, cwd, signal, onUpdate) =>
     ...(onUpdate ? { onUpdate } : {}),
   });
 
+/** Options for a shell handler that enforces shell-level delegation safeguards. */
+export interface DelegationAwareShellToolHandlerOpts {
+  /** Return the current shell-level delegation context for the active run. */
+  getDelegationContext: () => ShellDelegationContext;
+  /** Persist the updated delegation context after a launch reservation. */
+  setDelegationContext: (context: ShellDelegationContext) => void;
+}
+
+/**
+ * Create a shell handler that propagates and enforces `mc -p` delegation limits.
+ *
+ * @param opts - Delegation-context accessors for the active run.
+ * @returns A shell tool handler that blocks recursive or over-budget delegation.
+ */
+export function createDelegationAwareShellToolHandler(
+  opts: DelegationAwareShellToolHandlerOpts,
+): ToolHandler {
+  return (args, cwd, signal, onUpdate) => {
+    const validatedArgs = validateBuiltinToolArgs(shellTool, args);
+    const reservation = reserveShellDelegation(
+      validatedArgs.command,
+      opts.getDelegationContext(),
+    );
+    if (!reservation.ok) {
+      return textResult(reservation.error, true);
+    }
+
+    opts.setDelegationContext(reservation.reservation.updatedContext);
+    return executeShell(validatedArgs, cwd, {
+      ...(signal ? { signal } : {}),
+      ...(onUpdate ? { onUpdate } : {}),
+      env: buildShellDelegationEnv(reservation.reservation.childContext),
+    });
+  };
+}
+
 type ShellProcess = ReturnType<typeof Bun.spawn>;
 
 const DEFAULT_MAX_LINES = 1000;
 const DEFAULT_MAX_BYTES = 50_000;
 const SHELL_UPDATE_INTERVAL_MS = 75;
 const SHELL_STREAM_DRAIN_TIMEOUT_MS = 25;
+const LEGACY_SHELL_STDERR_PREFIX = "[stderr]\n";
+const LEGACY_SHELL_STDERR_SEPARATOR = `\n\n${LEGACY_SHELL_STDERR_PREFIX}`;
 
-/** Format combined stdout/stderr for display in tool results. */
+/** Format combined stdout/stderr for the legacy text payload preserved for model context. */
 function formatShellOutput(stdout: string, stderr: string): string {
   if (stdout && stderr) {
-    return `${stdout}\n\n[stderr]\n${stderr}`;
+    return `${stdout}${LEGACY_SHELL_STDERR_SEPARATOR}${stderr}`;
   }
   if (stdout) {
     return stdout;
   }
   if (stderr) {
-    return `[stderr]\n${stderr}`;
+    return `${LEGACY_SHELL_STDERR_PREFIX}${stderr}`;
   }
   return "";
 }
 
+/** Format the shell result as the legacy text payload stored in tool content. */
+export function formatShellResultText(result: ShellResultDetails): string {
+  const body = formatShellOutput(result.stdout, result.stderr) || "(no output)";
+  return `Exit code: ${result.exitCode}\n${body}`;
+}
+
+/** Parse structured shell-result details from a persisted tool-result message. */
+export function parseShellResultDetails(
+  details: unknown,
+): ShellResultDetails | null {
+  const record = toRecord(details);
+  if (!record) {
+    return null;
+  }
+
+  const stdout = readString(record, "stdout");
+  const stderr = readString(record, "stderr");
+  const exitCode = readFiniteNumber(record, "exitCode");
+  if (stdout === null || stderr === null || exitCode === null) {
+    return null;
+  }
+
+  return { stdout, stderr, exitCode };
+}
+
+/** Parse the legacy flattened shell-result text stored by older builds. */
+export function parseLegacyShellResult(
+  text: string,
+): ShellResultDetails | null {
+  const match = /^Exit code: (\d+)(?:\n([\s\S]*))?$/.exec(
+    normalizeLineEndings(text, "\n"),
+  );
+  if (!match) {
+    return null;
+  }
+
+  const exitCodeText = match[1];
+  if (!exitCodeText) {
+    return null;
+  }
+
+  const exitCode = Number.parseInt(exitCodeText, 10);
+  const body = match[2] ?? "";
+  if (body === "" || body === "(no output)") {
+    return { stdout: "", stderr: "", exitCode };
+  }
+  if (body.startsWith(LEGACY_SHELL_STDERR_PREFIX)) {
+    return {
+      stdout: "",
+      stderr: body.slice(LEGACY_SHELL_STDERR_PREFIX.length),
+      exitCode,
+    };
+  }
+
+  const separatorIndex = body.indexOf(LEGACY_SHELL_STDERR_SEPARATOR);
+  if (separatorIndex === -1) {
+    return { stdout: body, stderr: "", exitCode };
+  }
+
+  return {
+    stdout: body.slice(0, separatorIndex),
+    stderr: body.slice(separatorIndex + LEGACY_SHELL_STDERR_SEPARATOR.length),
+    exitCode,
+  };
+}
+
+function truncateShellResult(
+  result: ShellResultDetails,
+  maxLines: number,
+  maxBytes: number,
+): ShellResultDetails {
+  if (result.stdout === "" || result.stderr === "") {
+    return {
+      stdout:
+        result.stdout === ""
+          ? ""
+          : truncateOutput(result.stdout, maxLines, maxBytes),
+      stderr:
+        result.stderr === ""
+          ? ""
+          : truncateOutput(result.stderr, maxLines, maxBytes),
+      exitCode: result.exitCode,
+    };
+  }
+
+  return {
+    stdout: truncateOutput(
+      result.stdout,
+      Math.max(1, Math.ceil(maxLines / 2)),
+      Math.max(1, Math.ceil(maxBytes / 2)),
+    ),
+    stderr: truncateOutput(
+      result.stderr,
+      Math.max(1, Math.floor(maxLines / 2)),
+      Math.max(1, Math.floor(maxBytes / 2)),
+    ),
+    exitCode: result.exitCode,
+  };
+}
+
+function buildShellToolResult(
+  result: ShellResultDetails,
+  maxLines: number,
+  maxBytes: number,
+): ToolExecResult {
+  const truncated = truncateShellResult(result, maxLines, maxBytes);
+  return {
+    content: [{ type: "text", text: formatShellResultText(truncated) }],
+    details: truncated,
+    isError: truncated.exitCode !== 0,
+  };
+}
+
 interface ShellCommandLines {
   lines: string[];
   lineEnding: "\n" | "\r\n";
@@ -488,9 +657,13 @@ async function finalizeShellStreamCaptures(
   await Promise.all(captures.map((capture) => capture.close()));
 }
 
-function buildShellSpawnOptions(cwd: string): Parameters<typeof Bun.spawn>[1] {
+function buildShellSpawnOptions(
+  cwd: string,
+  env?: Record<string, string>,
+): Parameters<typeof Bun.spawn>[1] {
   return {
     cwd,
+    ...(env ? { env: { ...process.env, ...env } } : {}),
     stdout: "pipe",
     stderr: "pipe",
     ...(process.platform === "win32" ? {} : { detached: true }),
@@ -621,7 +794,10 @@ export async function executeShell(
     };
 
     const command = normalizeShellCommand(args.command);
-    const proc = Bun.spawn([shell, "-c", command], buildShellSpawnOptions(cwd));
+    const proc = Bun.spawn(
+      [shell, "-c", command],
+      buildShellSpawnOptions(cwd, opts?.env),
+    );
     cleanupAbort = registerShellAbort(opts?.signal, proc);
     stdoutCapture = startShellStreamCapture(
       proc.stdout as ReadableStream<Uint8Array>,
@@ -648,9 +824,15 @@ export async function executeShell(
       opts.onUpdate(textResult(output, false));
     }
 
-    const isError = exitCode !== 0;
-    const body = output || "(no output)";
-    return textResult(`Exit code: ${exitCode}\n${body}`, isError);
+    return buildShellToolResult(
+      {
+        stdout: stdoutCapture?.getOutput().trimEnd() ?? "",
+        stderr: stderrCapture?.getOutput().trimEnd() ?? "",
+        exitCode,
+      },
+      maxLines,
+      maxBytes,
+    );
   } catch (err) {
     cleanupAbort?.();
     cleanupAbort = null;