mini-coder 0.5.13 → 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,11 @@
 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,
@@ -33,6 +38,8 @@ 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. */
@@ -70,6 +77,42 @@ 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;
@@ -614,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 }),
@@ -747,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>,

package/src/tools.ts

@@ -1,9 +1,10 @@
 /**
- * Built-in tool implementations: `shell`, `read`, `grep`, `edit`, `todoWrite`,
- * `todoRead`, and `readImage`.
+ * Built-in tool implementations: `shell`, `delegate`, `read`, `grep`, `edit`,
+ * `todoWrite`, `todoRead`, and `readImage`.
  *
- * Shell, read, and grep live in dedicated modules and are re-exported here so
- * the rest of the codebase can keep a single built-in-tools import surface.
+ * Shell, delegate, read, and grep live in dedicated modules and are re-exported
+ * here so the rest of the codebase can keep a single built-in-tools import
+ * surface.
  *
  * Each tool is exposed as a pure-ish execute function that takes typed
  * arguments and a working directory, returning a result object. The pi-ai
@@ -15,6 +16,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, isAbsolute, join } from "node:path";
+import { crc32, inflateSync } from "node:zlib";
 import type {
   Message,
   Static,
@@ -33,6 +35,15 @@ import {
 } from "./tool-common.ts";
 
 export type { ToolExecResult } from "./tool-common.ts";
+export {
+  type CreateDelegateToolHandlerOpts,
+  createDelegateToolHandler,
+  type DelegateArgs,
+  type DelegateResultDetails,
+  type DelegateRunResult,
+  delegateTool,
+  formatDelegateResultText,
+} from "./tool-delegate.ts";
 export {
   DEFAULT_GREP_LIMIT,
   executeGrep,
@@ -58,6 +69,8 @@ export {
   readToolHandler,
 } from "./tool-read.ts";
 export {
+  createDelegationAwareShellToolHandler,
+  type DelegationAwareShellToolHandlerOpts,
   executeShell,
   formatShellResultText,
   parseLegacyShellResult,
@@ -703,6 +716,312 @@ const IMAGE_MIME_TYPES: Record<string, string> = {
   ".webp": "image/webp",
 };
 
+const PNG_SIGNATURE = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8]);
+const GIF_SIGNATURES = ["GIF87a", "GIF89a"];
+const WEBP_RIFF_SIGNATURE = "RIFF";
+const WEBP_FILE_SIGNATURE = "WEBP";
+
+interface PngChunk {
+  typeBytes: Buffer;
+  type: string;
+  data: Buffer;
+}
+
+interface PngValidationState {
+  sawIHDR: boolean;
+  sawIDAT: boolean;
+  sawIEND: boolean;
+  width: number;
+  height: number;
+  bitDepth: number;
+  colorType: number;
+  interlaceMethod: number;
+  compressedParts: Buffer[];
+}
+
+function createPngValidationState(): PngValidationState {
+  return {
+    sawIHDR: false,
+    sawIDAT: false,
+    sawIEND: false,
+    width: 0,
+    height: 0,
+    bitDepth: 0,
+    colorType: 0,
+    interlaceMethod: 0,
+    compressedParts: [],
+  };
+}
+
+function isValidPngColorFormat(bitDepth: number, colorType: number): boolean {
+  switch (colorType) {
+    case 0:
+      return [1, 2, 4, 8, 16].includes(bitDepth);
+    case 2:
+    case 4:
+    case 6:
+      return bitDepth === 8 || bitDepth === 16;
+    case 3:
+      return [1, 2, 4, 8].includes(bitDepth);
+    default:
+      return false;
+  }
+}
+
+function getPngScanlineByteLength(
+  width: number,
+  bitDepth: number,
+  colorType: number,
+): number {
+  const samplesPerPixel =
+    colorType === 0 || colorType === 3
+      ? 1
+      : colorType === 4
+        ? 2
+        : colorType === 2
+          ? 3
+          : 4;
+  return Math.ceil((width * bitDepth * samplesPerPixel) / 8);
+}
+
+function readPngChunk(
+  data: Buffer,
+  offset: number,
+): { chunk: PngChunk; nextOffset: number } | string {
+  if (offset + 12 > data.length) {
+    return "truncated PNG chunk header";
+  }
+
+  const length = data.readUInt32BE(offset);
+  const typeBytes = data.subarray(offset + 4, offset + 8);
+  const type = typeBytes.toString("ascii");
+  const dataOffset = offset + 8;
+  const nextOffset = dataOffset + length + 4;
+
+  if (nextOffset > data.length) {
+    return `truncated PNG chunk ${type}`;
+  }
+
+  const chunkData = data.subarray(dataOffset, dataOffset + length);
+  const storedCrc = data.readUInt32BE(dataOffset + length);
+  const computedCrc = crc32(Buffer.concat([typeBytes, chunkData]));
+
+  if (storedCrc !== computedCrc) {
+    return `invalid PNG CRC for chunk ${type}`;
+  }
+
+  return {
+    chunk: { typeBytes, type, data: chunkData },
+    nextOffset,
+  };
+}
+
+function validatePngHeaderChunk(
+  state: PngValidationState,
+  chunk: PngChunk,
+): string | null {
+  if (state.sawIHDR || state.sawIDAT || chunk.data.length !== 13) {
+    return "invalid IHDR chunk";
+  }
+
+  const compressionMethod = chunk.data[10] ?? 0;
+  const filterMethod = chunk.data[11] ?? 0;
+  const interlaceMethod = chunk.data[12] ?? 0;
+
+  state.sawIHDR = true;
+  state.width = chunk.data.readUInt32BE(0);
+  state.height = chunk.data.readUInt32BE(4);
+  state.bitDepth = chunk.data[8] ?? 0;
+  state.colorType = chunk.data[9] ?? 0;
+  state.interlaceMethod = interlaceMethod;
+
+  if (state.width === 0 || state.height === 0) {
+    return "invalid PNG image size";
+  }
+  if (!isValidPngColorFormat(state.bitDepth, state.colorType)) {
+    return "unsupported PNG color format";
+  }
+  if (compressionMethod !== 0 || filterMethod !== 0) {
+    return "unsupported PNG header values";
+  }
+  if (interlaceMethod !== 0 && interlaceMethod !== 1) {
+    return "unsupported PNG interlace method";
+  }
+
+  return null;
+}
+
+function applyPngChunk(
+  state: PngValidationState,
+  chunk: PngChunk,
+  nextOffset: number,
+  totalLength: number,
+): string | null {
+  if (chunk.type === "IHDR") {
+    return validatePngHeaderChunk(state, chunk);
+  }
+
+  if (!state.sawIHDR) {
+    return "missing IHDR chunk";
+  }
+
+  if (chunk.type === "IDAT") {
+    if (state.sawIEND) {
+      return "invalid PNG chunk order";
+    }
+    state.sawIDAT = true;
+    state.compressedParts.push(chunk.data);
+    return null;
+  }
+
+  if (chunk.type !== "IEND") {
+    return null;
+  }
+
+  if (!state.sawIDAT) {
+    return "missing IDAT chunk";
+  }
+  if (chunk.data.length !== 0) {
+    return "invalid IEND chunk length";
+  }
+
+  state.sawIEND = true;
+  if (nextOffset !== totalLength) {
+    return "unexpected trailing data after IEND chunk";
+  }
+
+  return null;
+}
+
+function validateInflatedPngData(state: PngValidationState): string | null {
+  try {
+    const inflated = inflateSync(Buffer.concat(state.compressedParts));
+    if (state.interlaceMethod !== 0) {
+      return null;
+    }
+
+    const expectedLength =
+      state.height *
+      (1 +
+        getPngScanlineByteLength(state.width, state.bitDepth, state.colorType));
+    if (inflated.length !== expectedLength) {
+      return "decoded PNG payload does not match image dimensions";
+    }
+    return null;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `corrupt PNG image data: ${message}`;
+  }
+}
+
+function validatePngImageData(data: Buffer): string | null {
+  if (
+    data.length < PNG_SIGNATURE.length ||
+    !data.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)
+  ) {
+    return "invalid PNG signature";
+  }
+
+  const state = createPngValidationState();
+  let offset = PNG_SIGNATURE.length;
+
+  while (offset < data.length) {
+    const parsedChunk = readPngChunk(data, offset);
+    if (typeof parsedChunk === "string") {
+      return parsedChunk;
+    }
+
+    const chunkError = applyPngChunk(
+      state,
+      parsedChunk.chunk,
+      parsedChunk.nextOffset,
+      data.length,
+    );
+    if (chunkError) {
+      return chunkError;
+    }
+
+    offset = parsedChunk.nextOffset;
+  }
+
+  if (!state.sawIHDR) {
+    return "missing IHDR chunk";
+  }
+  if (!state.sawIDAT) {
+    return "missing IDAT chunk";
+  }
+  if (!state.sawIEND) {
+    return "missing IEND chunk";
+  }
+
+  return validateInflatedPngData(state);
+}
+
+function validateJpegImageData(data: Buffer): string | null {
+  if (
+    data.length < 4 ||
+    !data.subarray(0, JPEG_SIGNATURE.length).equals(JPEG_SIGNATURE) ||
+    data.at(-2) !== 0xff ||
+    data.at(-1) !== 0xd9
+  ) {
+    return "invalid JPEG markers";
+  }
+  return null;
+}
+
+function validateGifImageData(data: Buffer): string | null {
+  if (data.length < 14) {
+    return "truncated GIF file";
+  }
+
+  const header = data.subarray(0, 6).toString("ascii");
+  if (!GIF_SIGNATURES.includes(header)) {
+    return "invalid GIF signature";
+  }
+  if (data.at(-1) !== 0x3b) {
+    return "missing GIF trailer";
+  }
+  return null;
+}
+
+function validateWebpImageData(data: Buffer): string | null {
+  if (data.length < 16) {
+    return "truncated WebP file";
+  }
+
+  if (
+    data.subarray(0, 4).toString("ascii") !== WEBP_RIFF_SIGNATURE ||
+    data.subarray(8, 12).toString("ascii") !== WEBP_FILE_SIGNATURE
+  ) {
+    return "invalid WebP signature";
+  }
+
+  const riffSize = data.readUInt32LE(4);
+  if (riffSize + 8 > data.length) {
+    return "truncated WebP file";
+  }
+
+  return null;
+}
+
+function validateImageData(mimeType: string, data: Buffer): string | null {
+  switch (mimeType) {
+    case "image/png":
+      return validatePngImageData(data);
+    case "image/jpeg":
+      return validateJpegImageData(data);
+    case "image/gif":
+      return validateGifImageData(data);
+    case "image/webp":
+      return validateWebpImageData(data);
+    default:
+      return `unsupported image MIME type ${mimeType}`;
+  }
+}
+
 const readImageToolParameters = Type.Object({
   path: Type.String({
     description: "File path (absolute or relative to cwd)",
@@ -744,10 +1063,16 @@ export function executeReadImage(
 
   try {
     const data = readFileSync(filePath);
-    const base64 = Buffer.from(data).toString("base64");
+    const validationError = validateImageData(mimeType, data);
+    if (validationError) {
+      return textResult(
+        `Invalid image file ${args.path}: ${validationError}`,
+        true,
+      );
+    }
 
     return {
-      content: [{ type: "image", data: base64, mimeType }],
+      content: [{ type: "image", data: data.toString("base64"), mimeType }],
       isError: false,
     };
   } catch (error) {

package/src/ui/agent.ts

@@ -221,6 +221,9 @@ export function createUiAgentController(
           runtime.requestRender("normal");
         }
         return;
+      case "context_compacted":
+        runtime.requestRender("normal");
+        return;
       case "tool_start":
         return;
     }

package/src/ui/commands.test.ts

@@ -6,7 +6,7 @@ import type { ContainerNode } from "@cel-tui/types";
 import { registerFauxProvider, Type } from "@mariozechner/pi-ai";
 import { type AppState, buildToolList } from "../index.ts";
 import {
-  computeContextTokens,
+  computeSessionContextTokens,
   createSession,
   loadMessages,
   openDatabase,
@@ -61,6 +61,9 @@ function createTestState(): AppState {
     skills: [],
     theme: DEFAULT_THEME,
     git: null,
+    delegationDepth: 0,
+    delegationBudgetLimit: 4,
+    delegationBudgetRemaining: 4,
     providers: new Map(),
     oauthCredentials: {},
     settings: {},
@@ -152,8 +155,47 @@ describe("ui/commands", () => {
         now + 1,
       ],
     );
+    const messageRows = state.db
+      .query<
+        { id: number },
+        [string]
+      >("SELECT id FROM messages WHERE session_id = ? ORDER BY id")
+      .all(session.id);
+    state.db.run(
+      "INSERT INTO session_compactions (session_id, message_end_id, summary_data, usage_data, created_at) VALUES (?, ?, ?, ?, ?)",
+      [
+        session.id,
+        messageRows[1]!.id,
+        JSON.stringify({
+          role: "user",
+          content: [
+            "summary of the earlier turn",
+            "",
+            "<system-message>",
+            "Read the originals from the SQLite DB if needed.",
+            "</system-message>",
+          ].join("\n"),
+          timestamp: now + 2,
+        }),
+        JSON.stringify({
+          input: 12,
+          output: 3,
+          cacheRead: 0,
+          cacheWrite: 0,
+          totalTokens: 15,
+          cost: {
+            input: 0.01,
+            output: 0.02,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: 0.03,
+          },
+        }),
+        now + 2,
+      ],
+    );
     state.db.run("UPDATE sessions SET updated_at = ? WHERE id = ?", [
-      now + 1,
+      now + 2,
       session.id,
     ]);
 
@@ -173,11 +215,13 @@ describe("ui/commands", () => {
         "assistant",
       ]);
       expect(state.stats).toEqual({
-        totalInput: 0,
-        totalOutput: 0,
-        totalCost: 0,
+        totalInput: 12,
+        totalOutput: 3,
+        totalCost: 0.03,
       });
-      expect(state.contextTokens).toBe(computeContextTokens(state.messages));
+      expect(state.contextTokens).toBe(
+        computeSessionContextTokens(state.db, session.id),
+      );
       expect(state.queuedUserMessages).toEqual([]);
     } finally {
       state.db.close();