@tonyclaw/agent-inspector 3.0.29 → 3.0.30

package/src/mcp/toolHandlers.ts

@@ -36,8 +36,20 @@ import {
 } from "../lib/groupContract";
 import { type CreateInspectorRunInput, type UpdateInspectorRunInput } from "../lib/runContract";
 import { SessionInfoSchema } from "../lib/sessionInfoContract";
+import {
+  ProviderConfigSchema,
+  toRedactedProviderDto,
+  toRedactedProviderDtos,
+} from "../lib/providerContract";
 import { isRecord, textByteLength } from "../lib/unknown";
 import { CapturedLogSchema, type CapturedLog } from "../contracts";
+import {
+  createResourceLimitError,
+  MAX_PROVIDER_MODELS,
+  MAX_SEARCH_PROJECT_CHARS,
+  MAX_SEARCH_QUERY_CHARS,
+  type ResourceLimitErrorInput,
+} from "../lib/resourceLimits";
 import {
   addInspectorGroupSession,
   createInspectorGroup,
@@ -109,6 +121,22 @@ function toolError(message: string): ToolResult {
   return { content: [{ type: "text", text: message }], isError: true };
 }
 
+function resourceLimitToolError(input: ResourceLimitErrorInput): ToolResult {
+  return toolError(JSON.stringify(createResourceLimitError(input), null, 2));
+}
+
+function redactedProviderResult(value: unknown): ToolResult {
+  const parsed = ProviderConfigSchema.safeParse(value);
+  if (!parsed.success) return toolError("Provider API returned an invalid provider response");
+  return textJson(toRedactedProviderDto(parsed.data));
+}
+
+function redactedProvidersResult(value: unknown): ToolResult {
+  const parsed = ProviderConfigSchema.array().safeParse(value);
+  if (!parsed.success) return toolError("Provider API returned an invalid providers response");
+  return textJson(toRedactedProviderDtos(parsed.data));
+}
+
 function inspectorBaseUrl(): string {
   return `http://127.0.0.1:${String(getCurrentPort())}`;
 }
@@ -327,6 +355,19 @@ export type ListLogsArgs = {
 };
 
 export async function listLogsImpl(callApi: CallApiFn, args: ListLogsArgs): Promise<ToolResult> {
+  if (
+    args.limit !== undefined &&
+    (!Number.isSafeInteger(args.limit) || args.limit < 1 || args.limit > LIMIT_HARD_CAP)
+  ) {
+    return resourceLimitToolError({
+      error: `MCP log pages may contain at most ${String(LIMIT_HARD_CAP)} entries.`,
+      code: "invalid-page-request",
+      status: 400,
+      resource: "mcp-log-page-size",
+      limit: LIMIT_HARD_CAP,
+      retryable: false,
+    });
+  }
   const offset = args.offset ?? PAGINATION_DEFAULTS.offset;
   const limit = clampLimit(args.limit);
   const params = new URLSearchParams({
@@ -366,6 +407,42 @@ export async function searchLogsImpl(
   callApi: CallApiFn,
   args: SearchLogsArgs,
 ): Promise<ToolResult> {
+  if ((args.query ?? "").length > MAX_SEARCH_QUERY_CHARS) {
+    return resourceLimitToolError({
+      error: `MCP search queries may contain at most ${String(MAX_SEARCH_QUERY_CHARS)} characters.`,
+      code: "search-limit-exceeded",
+      status: 400,
+      resource: "mcp-log-search-query",
+      limit: MAX_SEARCH_QUERY_CHARS,
+      retryable: false,
+    });
+  }
+  if (
+    args.limit !== undefined &&
+    (!Number.isSafeInteger(args.limit) || args.limit < 1 || args.limit > LIMIT_HARD_CAP)
+  ) {
+    return resourceLimitToolError({
+      error: `MCP search pages may contain at most ${String(LIMIT_HARD_CAP)} entries.`,
+      code: "invalid-page-request",
+      status: 400,
+      resource: "mcp-log-search-page-size",
+      limit: LIMIT_HARD_CAP,
+      retryable: false,
+    });
+  }
+  if (
+    args.scanLimit !== undefined &&
+    (!Number.isSafeInteger(args.scanLimit) || args.scanLimit < 1 || args.scanLimit > 1_000)
+  ) {
+    return resourceLimitToolError({
+      error: "MCP log searches may scan at most 1000 entries.",
+      code: "search-limit-exceeded",
+      status: 400,
+      resource: "mcp-log-search-scan-size",
+      limit: 1_000,
+      retryable: false,
+    });
+  }
   const offset = args.offset ?? PAGINATION_DEFAULTS.offset;
   const limit = clampLimit(args.limit);
   const params = new URLSearchParams({
@@ -1060,13 +1137,13 @@ export async function listModelsImpl(callApi: CallApiFn): Promise<ToolResult> {
 export async function listProvidersImpl(callApi: CallApiFn): Promise<ToolResult> {
   const res = await callApi("/api/providers");
   if (!res.ok) return toolError(`GET /api/providers returned ${res.status}`);
-  return textJson(await res.json());
+  return redactedProvidersResult(await res.json());
 }
 
 export async function getProviderImpl(callApi: CallApiFn, id: string): Promise<ToolResult> {
   const res = await callApi(`/api/providers/${encodeURIComponent(id)}`);
   if (!res.ok) return toolError(`GET /api/providers/${id} returned ${res.status}`);
-  return textJson(await res.json());
+  return redactedProviderResult(await res.json());
 }
 
 export type ReplayLogArgs = { id: number };
@@ -1118,13 +1195,23 @@ export async function addProviderImpl(
   provider: AddProviderInput,
 ): Promise<ToolResult> {
   const models = normalizedProviderModels(provider);
+  if (models.length > MAX_PROVIDER_MODELS) {
+    return resourceLimitToolError({
+      error: `Provider model lists may contain at most ${String(MAX_PROVIDER_MODELS)} entries.`,
+      code: "provider-model-limit-exceeded",
+      status: 413,
+      resource: "provider-models",
+      limit: MAX_PROVIDER_MODELS,
+      retryable: false,
+    });
+  }
   const res = await callApi("/api/providers", {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ ...provider, models }),
   });
   if (!res.ok) return toolError(`POST /api/providers returned ${res.status}`);
-  return textJson(await res.json());
+  return redactedProviderResult(await res.json());
 }
 
 export type UpdateProviderInput = {
@@ -1151,6 +1238,16 @@ export async function updateProviderImpl(
     patch.models !== undefined || patch.model !== undefined
       ? normalizedProviderModels(patch)
       : undefined;
+  if (models !== undefined && models.length > MAX_PROVIDER_MODELS) {
+    return resourceLimitToolError({
+      error: `Provider model lists may contain at most ${String(MAX_PROVIDER_MODELS)} entries.`,
+      code: "provider-model-limit-exceeded",
+      status: 413,
+      resource: "provider-models",
+      limit: MAX_PROVIDER_MODELS,
+      retryable: false,
+    });
+  }
   const body = models === undefined ? patch : { ...patch, models };
   const res = await callApi(`/api/providers/${encodeURIComponent(id)}`, {
     method: "PUT",
@@ -1158,7 +1255,7 @@ export async function updateProviderImpl(
     body: JSON.stringify(body),
   });
   if (!res.ok) return toolError(`PUT /api/providers/${id} returned ${res.status}`);
-  return textJson(await res.json());
+  return redactedProviderResult(await res.json());
 }
 
 export async function testProviderImpl(callApi: CallApiFn, id: string): Promise<ToolResult> {
@@ -1365,6 +1462,26 @@ export async function searchKnowledgeImpl(
   callApi: CallApiFn,
   args: SearchKnowledgeArgs,
 ): Promise<ToolResult> {
+  if (args.query.length > MAX_SEARCH_QUERY_CHARS) {
+    return resourceLimitToolError({
+      error: `MCP search queries may contain at most ${String(MAX_SEARCH_QUERY_CHARS)} characters.`,
+      code: "search-limit-exceeded",
+      status: 400,
+      resource: "mcp-knowledge-search-query",
+      limit: MAX_SEARCH_QUERY_CHARS,
+      retryable: false,
+    });
+  }
+  if (args.project !== undefined && args.project.length > MAX_SEARCH_PROJECT_CHARS) {
+    return resourceLimitToolError({
+      error: `MCP search project filters may contain at most ${String(MAX_SEARCH_PROJECT_CHARS)} characters.`,
+      code: "search-limit-exceeded",
+      status: 400,
+      resource: "mcp-knowledge-search-project",
+      limit: MAX_SEARCH_PROJECT_CHARS,
+      retryable: false,
+    });
+  }
   const params = new URLSearchParams({ q: args.query });
   if (args.project !== undefined && args.project.length > 0) {
     params.set("project", args.project);
@@ -1382,6 +1499,16 @@ export async function getProjectContextImpl(
   callApi: CallApiFn,
   args: GetProjectContextArgs,
 ): Promise<ToolResult> {
+  if (args.project.length > MAX_SEARCH_PROJECT_CHARS) {
+    return resourceLimitToolError({
+      error: `MCP search project filters may contain at most ${String(MAX_SEARCH_PROJECT_CHARS)} characters.`,
+      code: "search-limit-exceeded",
+      status: 400,
+      resource: "mcp-knowledge-search-project",
+      limit: MAX_SEARCH_PROJECT_CHARS,
+      retryable: false,
+    });
+  }
   const params = new URLSearchParams({ project: args.project });
   const res = await callApi(`/api/knowledge/project-context?${params.toString()}`);
   if (!res.ok) return toolError(`GET /api/knowledge/project-context returned ${res.status}`);

package/src/proxy/chunkStorage.ts

@@ -1,6 +1,5 @@
 import {
   writeFileSync,
-  mkdirSync,
   readFileSync,
   unlinkSync,
   existsSync,
@@ -12,6 +11,11 @@ import { logger } from "./logger";
 import { z } from "zod";
 import { JsonValueSchema, type StreamingChunk } from "./schemas";
 import { getDataDir } from "./dataDir";
+import {
+  ensurePrivateDirectorySync,
+  PRIVATE_FILE_MODE,
+  securePrivateFileSync,
+} from "./privateDataPath";
 
 export type StreamingChunksData = {
   chunks: StreamingChunk[];
@@ -56,17 +60,24 @@ export function writeChunks(logId: number, chunks: StreamingChunk[], truncated?:
   const tempPath = getTempFilePath(logId);
 
   // Ensure directory exists
-  try {
-    mkdirSync(dir, { recursive: true });
-  } catch (err) {
-    logger.error("[chunkStorage] Failed to create chunks directory:", String(err));
+  if (!ensurePrivateDirectorySync(dir)) {
+    logger.error("[chunkStorage] Failed to secure chunks directory:", dir);
+    return targetPath;
   }
 
   const data: StreamingChunksData = { chunks, truncated };
 
   // Write to temp file first
   try {
-    writeFileSync(tempPath, JSON.stringify(data), "utf-8");
+    writeFileSync(tempPath, JSON.stringify(data), {
+      encoding: "utf-8",
+      mode: PRIVATE_FILE_MODE,
+    });
+    if (!securePrivateFileSync(tempPath)) {
+      unlinkSync(tempPath);
+      logger.error("[chunkStorage] Failed to secure chunks temp file:", tempPath);
+      return targetPath;
+    }
   } catch (err) {
     logger.error("[chunkStorage] Failed to write chunks temp file:", String(err));
     return targetPath;
@@ -80,6 +91,9 @@ export function writeChunks(logId: number, chunks: StreamingChunk[], truncated?:
     // If rename fails, try copy + delete
     try {
       copyFileSync(tempPath, targetPath);
+      if (!securePrivateFileSync(targetPath)) {
+        logger.error("[chunkStorage] Failed to secure chunks file:", targetPath);
+      }
       unlinkSync(tempPath);
     } catch (copyErr) {
       logger.error("[chunkStorage] Failed to copy chunks file:", String(copyErr));

package/src/proxy/config.ts

@@ -1,6 +1,5 @@
 import {
   writeFileSync,
-  mkdirSync,
   readFileSync,
   unlinkSync,
   existsSync,
@@ -10,6 +9,11 @@ import {
 import { join } from "node:path";
 import { logger } from "./logger";
 import { getDataDir } from "./dataDir";
+import {
+  ensurePrivateDirectorySync,
+  PRIVATE_FILE_MODE,
+  securePrivateFileSync,
+} from "./privateDataPath";
 import {
   CaptureModeSchema,
   DEFAULT_CAPTURE_MODE,
@@ -168,15 +172,21 @@ function persistConfig(value: RuntimeConfig): boolean {
   const targetPath = getConfigFilePath();
   const tempPath = getConfigTempPath();
 
-  try {
-    mkdirSync(dir, { recursive: true });
-  } catch (err) {
-    logger.error(`[config] Failed to create data directory ${dir}: ${String(err)}`);
+  if (!ensurePrivateDirectorySync(dir)) {
+    logger.error(`[config] Failed to secure data directory ${dir}`);
     return false;
   }
 
   try {
-    writeFileSync(tempPath, JSON.stringify(toPersistedConfig(value)), "utf-8");
+    writeFileSync(tempPath, JSON.stringify(toPersistedConfig(value)), {
+      encoding: "utf-8",
+      mode: PRIVATE_FILE_MODE,
+    });
+    if (!securePrivateFileSync(tempPath)) {
+      unlinkSync(tempPath);
+      logger.error(`[config] Failed to secure config temp file ${tempPath}`);
+      return false;
+    }
   } catch (err) {
     logger.error(`[config] Failed to write config temp file: ${String(err)}`);
     return false;
@@ -189,6 +199,10 @@ function persistConfig(value: RuntimeConfig): boolean {
     logger.warn(`[config] Rename failed, falling back to copy+delete: ${String(err)}`);
     try {
       copyFileSync(tempPath, targetPath);
+      if (!securePrivateFileSync(targetPath)) {
+        logger.error(`[config] Failed to secure config file ${targetPath}`);
+        return false;
+      }
       unlinkSync(tempPath);
       return true;
     } catch (copyErr) {

package/src/proxy/dataDir.ts

@@ -1,5 +1,6 @@
 import { cpSync, existsSync, rmSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
+import { ensurePrivateDirectorySync, securePrivateTreeSync } from "./privateDataPath";
 
 const CURRENT_DATA_DIR_NAME = ".agent-inspector";
 const LEGACY_DATA_DIR_NAMES = [".llm-inspector", ".llm-agent"];
@@ -98,7 +99,9 @@ export function migrateLegacyDataDirs(): void {
     if (!existsSync(legacyDir)) continue;
 
     try {
+      if (!ensurePrivateDirectorySync(currentDir)) return;
       cpSync(legacyDir, currentDir, { recursive: true, force: true });
+      if (!securePrivateTreeSync(currentDir)) return;
       rmSync(legacyDir, { recursive: true, force: true });
     } catch {
       // Best-effort migration: startup must continue even when the old

package/src/proxy/ecosystemExecutionConfirmation.ts

@@ -0,0 +1,114 @@
+import { randomUUID } from "node:crypto";
+import {
+  ECOSYSTEM_EXECUTION_CONFIRMATION_PHRASE,
+  type EcosystemExecutionConfirmation,
+  type EcosystemExecutionPlan,
+  type EcosystemTaskAction,
+} from "../lib/ecosystemContract";
+import { logger } from "./logger";
+
+const CONFIRMATION_TTL_MS = 2 * 60 * 1000;
+const MAX_PENDING_CONFIRMATIONS = 100;
+
+type ConfirmationRecord = {
+  confirmation: EcosystemExecutionConfirmation;
+  expiresAtMs: number;
+};
+
+type ConfirmationFailureReason =
+  | "missing_or_invalid_confirmation"
+  | "expired_confirmation"
+  | "mismatched_confirmation";
+
+type ConsumeEcosystemConfirmationResult =
+  | { ok: true; plan: EcosystemExecutionPlan }
+  | { ok: false; reason: ConfirmationFailureReason };
+
+type EcosystemAuditEvent = "confirmation_issued" | "confirmation_rejected" | "execution_started";
+type EcosystemAuditReason =
+  | "none"
+  | "invalid_request"
+  | "unknown_target"
+  | "missing_or_invalid_confirmation"
+  | "expired_confirmation"
+  | "mismatched_confirmation"
+  | "task_unavailable";
+
+const confirmations = new Map<string, ConfirmationRecord>();
+
+function pruneConfirmations(nowMs: number): void {
+  for (const [nonce, record] of confirmations) {
+    if (record.expiresAtMs <= nowMs) confirmations.delete(nonce);
+  }
+  while (confirmations.size >= MAX_PENDING_CONFIRMATIONS) {
+    const oldestNonce = confirmations.keys().next().value;
+    if (typeof oldestNonce !== "string") return;
+    confirmations.delete(oldestNonce);
+  }
+}
+
+function safeAuditTarget(targetId: string | null): string {
+  if (targetId === null || !/^[a-z0-9-]{1,64}$/.test(targetId)) return "unrecognized";
+  return targetId;
+}
+
+export function auditEcosystemExecution(
+  event: EcosystemAuditEvent,
+  action: EcosystemTaskAction,
+  targetId: string | null,
+  reason: EcosystemAuditReason,
+): void {
+  logger.info(
+    `[security-audit] event=${event} action=${action} target=${safeAuditTarget(targetId)} reason=${reason}`,
+  );
+}
+
+export function createEcosystemExecutionConfirmation(
+  plan: EcosystemExecutionPlan,
+  nowMs = Date.now(),
+): EcosystemExecutionConfirmation {
+  pruneConfirmations(nowMs);
+  const expiresAtMs = nowMs + CONFIRMATION_TTL_MS;
+  const confirmation: EcosystemExecutionConfirmation = {
+    nonce: randomUUID(),
+    phrase: ECOSYSTEM_EXECUTION_CONFIRMATION_PHRASE,
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    plan,
+  };
+  confirmations.set(confirmation.nonce, { confirmation, expiresAtMs });
+  return confirmation;
+}
+
+export function consumeEcosystemExecutionConfirmation(
+  nonce: string,
+  phrase: string,
+  expectedPlan: EcosystemExecutionPlan,
+  nowMs = Date.now(),
+): ConsumeEcosystemConfirmationResult {
+  const record = confirmations.get(nonce);
+  if (record === undefined) {
+    return { ok: false, reason: "missing_or_invalid_confirmation" };
+  }
+
+  confirmations.delete(nonce);
+  if (record.expiresAtMs <= nowMs) return { ok: false, reason: "expired_confirmation" };
+  const reviewedPlan = record.confirmation.plan;
+  if (
+    phrase !== ECOSYSTEM_EXECUTION_CONFIRMATION_PHRASE ||
+    reviewedPlan.action !== expectedPlan.action ||
+    reviewedPlan.targetId !== expectedPlan.targetId ||
+    reviewedPlan.targetName !== expectedPlan.targetName ||
+    reviewedPlan.command !== expectedPlan.command ||
+    reviewedPlan.source !== expectedPlan.source ||
+    reviewedPlan.timeoutMs !== expectedPlan.timeoutMs ||
+    reviewedPlan.scope !== expectedPlan.scope
+  ) {
+    return { ok: false, reason: "mismatched_confirmation" };
+  }
+
+  return { ok: true, plan: reviewedPlan };
+}
+
+export function resetEcosystemExecutionConfirmationsForTests(): void {
+  confirmations.clear();
+}

package/src/proxy/ecosystemExecutionRoute.ts

@@ -0,0 +1,116 @@
+import {
+  EcosystemExecutionRequestSchema,
+  type EcosystemTask,
+  type EcosystemTaskAction,
+} from "../lib/ecosystemContract";
+import {
+  auditEcosystemExecution,
+  consumeEcosystemExecutionConfirmation,
+  createEcosystemExecutionConfirmation,
+} from "./ecosystemExecutionConfirmation";
+import {
+  getEcosystemPackageExecutionPlan,
+  getEcosystemRecipeExecutionPlan,
+  startEcosystemRecipeTask,
+  startEcosystemTask,
+} from "./ecosystemTasks";
+
+const NO_STORE_HEADERS = { "Cache-Control": "no-store" };
+
+type StartPackageTask = (packageId: string, action: EcosystemTaskAction) => EcosystemTask | null;
+type StartRecipeTask = (recipeId: string) => EcosystemTask | null;
+
+function noStoreJson(body: unknown, status = 200): Response {
+  return Response.json(body, { status, headers: NO_STORE_HEADERS });
+}
+
+async function readExecutionRequest(request: Request) {
+  const body: unknown = await request.json().catch(() => null);
+  return EcosystemExecutionRequestSchema.safeParse(body);
+}
+
+export async function handleEcosystemPackageExecution(
+  request: Request,
+  packageId: string,
+  action: Exclude<EcosystemTaskAction, "recipe">,
+  startTask: StartPackageTask = startEcosystemTask,
+): Promise<Response> {
+  const parsed = await readExecutionRequest(request);
+  if (!parsed.success) {
+    auditEcosystemExecution("confirmation_rejected", action, null, "invalid_request");
+    return noStoreJson({ error: "Explicit local command confirmation is required" }, 400);
+  }
+
+  const plan = getEcosystemPackageExecutionPlan(packageId, action);
+  if (plan === null) {
+    auditEcosystemExecution("confirmation_rejected", action, null, "unknown_target");
+    return noStoreJson({ error: "Unknown or unavailable ecosystem action" }, 404);
+  }
+
+  if (parsed.data.intent === "prepare") {
+    const confirmation = createEcosystemExecutionConfirmation(plan);
+    auditEcosystemExecution("confirmation_issued", action, plan.targetId, "none");
+    return noStoreJson({ confirmation });
+  }
+
+  const consumed = consumeEcosystemExecutionConfirmation(
+    parsed.data.nonce,
+    parsed.data.confirmation,
+    plan,
+  );
+  if (!consumed.ok) {
+    auditEcosystemExecution("confirmation_rejected", action, plan.targetId, consumed.reason);
+    return noStoreJson({ error: "Confirmation is invalid, expired, or already used" }, 409);
+  }
+
+  const task = startTask(packageId, action);
+  if (task === null) {
+    auditEcosystemExecution("confirmation_rejected", action, plan.targetId, "task_unavailable");
+    return noStoreJson({ error: "Ecosystem action is no longer available" }, 409);
+  }
+  auditEcosystemExecution("execution_started", action, plan.targetId, "none");
+  return noStoreJson({ task });
+}
+
+export async function handleEcosystemRecipeExecution(
+  request: Request,
+  recipeId: string,
+  startTask: StartRecipeTask = startEcosystemRecipeTask,
+): Promise<Response> {
+  const action = "recipe";
+  const parsed = await readExecutionRequest(request);
+  if (!parsed.success) {
+    auditEcosystemExecution("confirmation_rejected", action, null, "invalid_request");
+    return noStoreJson({ error: "Explicit local command confirmation is required" }, 400);
+  }
+
+  const plan = getEcosystemRecipeExecutionPlan(recipeId);
+  if (plan === null) {
+    auditEcosystemExecution("confirmation_rejected", action, null, "unknown_target");
+    return noStoreJson({ error: "Unknown or unavailable ecosystem recipe" }, 404);
+  }
+
+  if (parsed.data.intent === "prepare") {
+    const confirmation = createEcosystemExecutionConfirmation(plan);
+    auditEcosystemExecution("confirmation_issued", action, plan.targetId, "none");
+    return noStoreJson({ confirmation });
+  }
+
+  const consumed = consumeEcosystemExecutionConfirmation(
+    parsed.data.nonce,
+    parsed.data.confirmation,
+    plan,
+  );
+  if (!consumed.ok) {
+    auditEcosystemExecution("confirmation_rejected", action, plan.targetId, consumed.reason);
+    return noStoreJson({ error: "Confirmation is invalid, expired, or already used" }, 409);
+  }
+
+  const task = startTask(recipeId);
+  if (task === null) {
+    auditEcosystemExecution("confirmation_rejected", action, plan.targetId, "task_unavailable");
+    return noStoreJson({ error: "Ecosystem recipe is no longer available" }, 409);
+  }
+  auditEcosystemExecution("execution_started", action, plan.targetId, "none");
+  return noStoreJson({ task });
+}

package/src/proxy/ecosystemTasks.ts

@@ -2,6 +2,7 @@ import { Buffer } from "node:buffer";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import type {
+  EcosystemExecutionPlan,
   EcosystemTask,
   EcosystemTaskAction,
   EcosystemTaskStatus,
@@ -93,6 +94,52 @@ function taskCommand(args: readonly string[]): string {
   return `${npmCommand()} ${args.join(" ")}`;
 }
 
+export function getEcosystemPackageExecutionPlan(
+  packageId: string,
+  action: EcosystemTaskAction,
+): EcosystemExecutionPlan | null {
+  if (action === "recipe") return null;
+  const definition =
+    action === "runner-presets"
+      ? findEcosystemPackage("eval-harness")
+      : findEcosystemPackage(packageId);
+  if (definition === null) return null;
+  if (action === "runner-presets" && packageId !== "eval-harness") return null;
+
+  const args = packageActionArgs(action, definition.npmName);
+  const mutatesGlobalPackages = action === "install" || action === "upgrade";
+  return {
+    action,
+    targetId: definition.id,
+    targetName: definition.name,
+    command: taskCommand(args),
+    source: `npm registry: ${definition.npmName}`,
+    timeoutMs: packageActionTimeout(action),
+    scope: mutatesGlobalPackages
+      ? "Global npm package installation"
+      : "Ephemeral npm exec process in the Inspector service account",
+  };
+}
+
+export function getEcosystemRecipeExecutionPlan(recipeId: string): EcosystemExecutionPlan | null {
+  const recipe = findEcosystemRecipe(recipeId);
+  if (recipe === null || !recipe.runnable) return null;
+  const definition = findEcosystemPackage(recipe.packageId);
+  if (definition === null) return null;
+  const args = recipeActionArgs(recipe.id);
+  if (args === null) return null;
+
+  return {
+    action: "recipe",
+    targetId: recipe.id,
+    targetName: recipe.title,
+    command: taskCommand(args),
+    source: `Built-in allowlisted recipe using ${definition.npmName}`,
+    timeoutMs: RECIPE_TIMEOUT_MS,
+    scope: "Ephemeral npm exec process in the Inspector service account",
+  };
+}
+
 function completeTask(
   task: EcosystemTask,
   status: Exclude<EcosystemTaskStatus, "queued" | "running">,
@@ -117,6 +164,7 @@ export function startEcosystemTask(
   packageId: string,
   action: EcosystemTaskAction,
 ): EcosystemTask | null {
+  if (action === "recipe") return null;
   const definition =
     action === "runner-presets"
       ? findEcosystemPackage("eval-harness")