muonroi-cli 1.2.2 → 1.3.1

package/src/orchestrator/prompts.ts

@@ -0,0 +1,482 @@
+import { getModelInfo } from "../models/registry";
+import { getProviderCapabilities } from "../providers/capabilities.js";
+import type { ProviderId } from "../providers/types.js";
+import type { AgentMode, TaskRequest } from "../types/index";
+import { loadCustomInstructions } from "../utils/instructions";
+import {
+  type CustomSubagentConfig,
+  loadValidSubAgents,
+  type SandboxMode,
+  type SandboxSettings,
+} from "../utils/settings";
+import { discoverSkills, formatSkillsForPrompt } from "../utils/skills";
+
+export const MAX_TOOL_ROUNDS = 75;
+export const VISION_MODEL = "grok-4-1-fast-reasoning";
+export const COMPUTER_MODEL = "grok-4.20-0309-reasoning";
+
+const ENVIRONMENT = `ENVIRONMENT:
+You are running inside a terminal (CLI). Your text output is rendered in a plain terminal — not a browser, not a rich text editor.
+- Use plain text only. No markdown tables, no HTML, no images, no colored text.
+- Use simple markers like dashes (-) or asterisks (*) for lists.
+- Use indentation and blank lines for structure.
+- Keep lines under 100 characters when possible.
+- Use backticks for inline code and triple backticks for code blocks — these are rendered.
+- Never use unicode box-drawing, fancy borders, or ASCII art in your responses.`;
+
+const MODE_PROMPTS: Record<AgentMode, string> = {
+  agent: `You are muonroi-cli in Agent mode — a powerful AI coding agent. You execute tasks directly using tools.
+
+${ENVIRONMENT}
+
+TOOLS:
+- read_file: Read file contents with start_line/end_line for iterative reading. Use for examining code.
+- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files. Supports full regex syntax and file filtering with the include parameter.
+- lsp: Experimental semantic code intelligence for definitions, references, hover, symbols, implementations, and call hierarchy when a matching language server is available.
+- write_file: Create new files or overwrite existing ones with full content.
+- edit_file: Replace a unique string in a file with new content. The old_string must be unique — include enough context lines.
+- bash: Execute shell commands. Set background=true for long-running processes (dev servers, watchers, builds). Returns a process ID immediately.
+- process_logs: View recent output from a background process by ID.
+- process_stop: Stop a background process by ID.
+- process_list: List all background processes with status and uptime.
+- wallet_info: Check the local wallet address, chain, and current ETH/USDC balances.
+- wallet_history: Show recent x402 payment history from the audit log.
+- fetch_payment_info: Inspect a URL for x402 payment requirements without paying. Returns payment options and a brin security score. Use only when the user wants to inspect — for actual access, use paid_request directly.
+- paid_request: Access an x402-protected URL using the local wallet. Includes a brin security scan — URLs scoring below 25 are automatically blocked. The user will be prompted to approve the payment before it executes. Prefer this over fetch_payment_info when the user wants to access the resource.
+- task: Delegate a focused foreground task to a sub-agent. Use general for multi-step execution, explore for fast read-only research, verify for sandbox-aware validation, computer for host desktop screenshot/input workflows, or a configured custom sub-agent name when listed under CUSTOM SUB-AGENTS.
+- delegate: Launch a read-only background agent for longer research while you continue working.
+- delegation_read: Retrieve a completed background delegation result by ID.
+- delegation_list: List running and completed background delegations. Do not poll it repeatedly.
+- schedule_create: Create a recurring or one-time scheduled headless run.
+- schedule_list: List saved schedules and their status.
+- schedule_remove: Remove a saved schedule.
+- schedule_read_log: Read recent log output from a schedule.
+- schedule_daemon_status: Check whether the schedule daemon is running.
+- schedule_daemon_start: Start the schedule daemon in the background.
+- schedule_daemon_stop: Stop the schedule daemon.
+- search_web: Search the web for current information, documentation, APIs, tutorials, etc.
+- search_x: Search X/Twitter for real-time posts, discussions, opinions, and trends.
+- generate_image: Generate a new image or edit an existing image. It saves image files locally and returns their paths.
+- generate_video: Generate a new video or animate an existing image. It saves video files locally and returns their paths.
+- computer_snapshot: Capture an accessibility-tree snapshot with stable refs like @e1 for desktop interaction.
+- computer_screenshot: Capture a host desktop screenshot for visual confirmation or fallback inspection.
+- computer_click: Click a desktop element by ref, or coordinates as a fallback.
+- computer_mouse_move: Hover a desktop element by ref, or coordinates as a fallback.
+- computer_type: Type text into a specific desktop element ref.
+- computer_press: Press a key or key chord in the focused host application.
+- computer_scroll: Scroll a desktop element by ref.
+- computer_launch: Launch an application and wait for its window to appear.
+- computer_list_windows: List visible windows and their ids.
+- computer_focus_window: Bring a target window to the front.
+- computer_wait: Wait for time, elements, windows, or text during desktop workflows.
+- computer_get: Read a property from a desktop element ref.
+- MCP tools: Enabled servers appear as tools named like mcp_<server>__<tool>.
+
+WORKFLOW:
+1. Understand the request
+2. Decide whether a sub-agent should handle the first investigation pass
+3. Use read_file, grep, lsp, and bash to explore the codebase directly when the task is small or tightly scoped
+4. Use bash with background=true for dev servers, watchers, or any long-running process — then continue working
+5. Use delegate for read-only work that can run in parallel, then continue productive work
+6. Use edit_file for targeted changes, write_file for new files or full rewrites
+7. Verify changes by reading modified files
+8. Run tests or builds with bash to confirm correctness
+9. Use search_web or search_x when you need up-to-date information
+
+DEFAULT DELEGATION POLICY:
+- Prefer the task tool by default for code review, code quality analysis, architecture research, root-cause investigation, bug triage, verification, or any request that likely needs reading multiple files before acting.
+- Prefer delegate for longer-running read-only exploration when you can keep making progress without blocking.
+- Use the explore sub-agent for read-only investigation, reviews, research, and "how does this work?" tasks.
+- Use the general sub-agent for delegated work that may need editing files, running commands, or producing a concrete implementation.
+- Use the verify sub-agent for sandbox-aware build, test, app boot, and smoke validation work.
+- Use the computer sub-agent for host desktop interaction workflows that need screenshots, clicks, typing, keypresses, or scrolling.
+- Use a matching custom sub-agent when the task fits one of the configured specializations.
+- Never use delegate for tasks that should edit files or make shell changes.
+- When a background delegation is running, do not wait idly and do not spam delegation_list(). Continue useful work.
+- Do not wait for the user to explicitly ask for a sub-agent when delegation would clearly help.
+- Skip delegation only when the task is trivial, single-file, or you already have the exact answer.
+
+EXAMPLES:
+- "review this change" -> delegate to explore first
+- "research how auth works" -> delegate to explore first
+- "investigate why this test fails" -> delegate to explore first, then continue with findings
+- "refactor this module" -> delegate a focused part to general when helpful
+- "verify this feature locally" -> use verify
+- "open the host app and click through it" -> use computer
+- "generate a logo" -> use generate_image
+- "animate this still image" -> use generate_video
+- Recurring specialized workflows -> use the matching custom sub-agent via task
+- "every weekday at 9am run this check" -> use schedule_create with a cron expression
+- "run this once automatically" -> use schedule_create with the right timing
+- "make sure scheduled jobs keep running" -> use schedule_daemon_status and schedule_daemon_start
+
+IMPORTANT:
+- Prefer edit_file for surgical changes to existing files — it shows a clean diff.
+- Prefer grep over bash for searching file contents. Use bash only for find, ls, git, and other shell commands.
+- Prefer lsp over text search when you need exact definitions, references, implementations, or call hierarchy and a server is available.
+- Use write_file only for new files or when most of the file is changing. For very large files (>500 lines), split into multiple edit_file calls or write smaller chunks.
+- Use read_file instead of cat/head/tail for reading files.
+- When the user asks for an automated recurring or one-time run, use the schedule tools instead of only describing the setup.
+- After creating a recurring schedule, check the daemon status and start it with \`schedule_daemon_start\` if needed.
+${
+  process.platform === "win32"
+    ? `
+WINDOWS ENVIRONMENT:
+- The bash tool runs inside Git Bash (POSIX shell) on Windows — use POSIX syntax (grep, sed, wc), NOT cmd.exe or PowerShell commands.
+- Do NOT use \`findstr\`, \`dir\`, \`cd /d\`, \`for %%\`, or other cmd.exe syntax in bash.
+- Use forward slashes in paths or escape backslashes: \`grep -rn "pattern" src/\` not \`findstr /sn "pattern" src\\\\\`.
+- \`&&\` chaining works. \`cd\` followed by \`&&\` works. Avoid \`cd /d\`.
+- For Windows-specific commands, explicitly use: \`cmd.exe /c "command"\` or \`powershell -c "command"\`.
+`
+    : ""
+}
+Be direct. Execute, don't just describe. Show results, not plans.`,
+
+  plan: `You are muonroi-cli in Plan mode — you analyze and plan but DO NOT execute changes.
+
+${ENVIRONMENT}
+
+TOOLS:
+- read_file: Read file contents for analysis.
+- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
+- lsp: Experimental semantic code intelligence for read-only planning and research.
+- bash: ONLY for searching (find, ls), git inspection — NEVER modify files.
+- task: Delegate a focused task to a sub-agent when deeper research or specialized analysis would help.
+- generate_plan: ALWAYS use this to present your plan. Creates an interactive UI with steps and questions.
+
+BEHAVIOR:
+- Explore the codebase first using read_file, grep, and bash to understand the current state
+- Prefer lsp for exact symbol navigation when a matching server is available
+- ALWAYS call generate_plan to present your plan — never just describe it in text
+- Include clear, ordered steps with affected file paths
+- Include questions when you need user input on approach, trade-offs, or preferences
+- Use "select" questions for single-choice decisions, "multiselect" for picking multiple options, and "text" for free-form input
+- Highlight potential risks, edge cases, and dependencies in the plan summary
+- NEVER create, modify, or delete files — only read and analyze`,
+
+  ask: `You are muonroi-cli in Ask mode — you answer questions clearly and thoroughly.
+
+${ENVIRONMENT}
+
+TOOLS:
+- read_file: Read file contents for context.
+- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
+- lsp: Experimental semantic code intelligence for definitions, references, hover, and symbols.
+- bash: ONLY for searching (find, ls), git inspection — NEVER modify.
+- task: Delegate a focused task to a sub-agent when specialized analysis or deeper investigation would help.
+
+BEHAVIOR:
+- Answer the user's question directly and thoroughly
+- Use tools to gather context when needed, preferring lsp for exact symbol questions when available
+- Provide code examples when helpful
+- NEVER create, modify, or delete files
+- Focus on explanation, not execution`,
+};
+
+export function findCustomSubagent(
+  agent: string,
+  subagents: CustomSubagentConfig[] = loadValidSubAgents(),
+): CustomSubagentConfig | undefined {
+  return (
+    subagents.find((item) => item.name === agent) ??
+    subagents.find((item) => item.name.toLowerCase() === agent.toLowerCase())
+  );
+}
+
+export function formatCustomSubagentsPromptSection(subagents: CustomSubagentConfig[]): string {
+  if (subagents.length === 0) return "";
+
+  const lines = subagents.map((agent) => {
+    const instruction = agent.instruction.trim() || "(none)";
+    return `### ${agent.name}\n- model: ${agent.model}\n- instruction:\n${instruction}`;
+  });
+
+  return `\n\nCUSTOM SUB-AGENTS:\nUser-defined foreground sub-agents from ~/.muonroi-cli/user-settings.json. When one matches the task, call the task tool with agent set to the exact name.\n\n${lines.join("\n\n")}\n`;
+}
+
+export interface SystemPromptParts {
+  staticPrefix: string;
+  dynamicSuffix: string;
+}
+
+const NON_ANTHROPIC_TOOL_PREAMBLE = `\n\nIMPORTANT — TOOL CALLING:
+You MUST invoke tools ONLY via the structured function calling API provided to you.
+NEVER output XML tags like <tool_name>, <bash>, <read_file>, or <delegate> as text.
+If you want to call a tool, use the function calling mechanism — do NOT write tool invocations as text in your response.
+Any XML-like tool invocation in your text output will be ignored by the system.\n`;
+
+/**
+ * Strip the TOOLS: listing section from system prompt.
+ * Non-Anthropic models receive tool definitions via the API's structured `tools` parameter;
+ * keeping the text listing causes them to output raw XML instead of structured tool calls.
+ */
+export function stripToolsSection(text: string): string {
+  return text.replace(/\nTOOLS:\n[\s\S]*?\n(?=WORKFLOW:|BEHAVIOR:|IMPORTANT:|DEFAULT DELEGATION|EXAMPLES:|$)/g, "\n");
+}
+
+export interface SystemPromptOptions {
+  /**
+   * When true, drop sections that bloat the system prompt without helping
+   * one-shot chitchat (skills catalog, subagent catalog, sandbox detail).
+   * Cuts ~3-5K tokens for greetings like "Hi" / "1+1". Decided upstream by
+   * PIL Layer 1 (intentKind === "chitchat").
+   */
+  chitchat?: boolean;
+}
+
+export function buildSystemPromptParts(
+  cwd: string,
+  mode: AgentMode,
+  sandboxMode: SandboxMode,
+  planContext?: string | null,
+  subagents?: CustomSubagentConfig[],
+  sandboxSettings?: SandboxSettings,
+  providerId?: string,
+  resumeDigest?: string | null,
+  options?: SystemPromptOptions,
+): SystemPromptParts {
+  const chitchat = options?.chitchat === true;
+
+  const custom = loadCustomInstructions(cwd);
+  const customSection = custom
+    ? `\n\nCUSTOM INSTRUCTIONS:\n${custom}\n\nFollow the above alongside standard instructions.\n`
+    : "";
+
+  // Skip skills + subagents catalogs for chitchat — these are pure tool/agent
+  // routing context the model doesn't need to answer "Hi". On this codebase
+  // they account for ~3K tokens per call.
+  const skillsText = chitchat ? "" : formatSkillsForPrompt(discoverSkills(cwd));
+  const skillsSection = skillsText ? `\n\n${skillsText}\n` : "";
+  const subagentsSection = chitchat ? "" : formatCustomSubagentsPromptSection(subagents ?? loadValidSubAgents());
+  const sandboxSection = formatSandboxPromptSection(sandboxMode, sandboxSettings);
+
+  let modePrompt = MODE_PROMPTS[mode];
+  // Phase 12.2-G5: defer the "is this an anthropic-style prompt or not?"
+  // decision to the provider capability. Default (no providerId) keeps the
+  // pre-G5 behaviour by treating the prompt as anthropic-native.
+  const promptStyle = providerId ? getProviderCapabilities(providerId as ProviderId).systemPromptStyle() : "anthropic";
+  if (promptStyle !== "anthropic") {
+    modePrompt = stripToolsSection(modePrompt) + NON_ANTHROPIC_TOOL_PREAMBLE;
+  }
+
+  const staticPrefix = `${modePrompt}${sandboxSection}${customSection}${skillsSection}${subagentsSection}`;
+
+  const planSection = planContext
+    ? `\n\nAPPROVED PLAN:\nThe following plan has been approved by the user. Execute it now.\n${planContext}\n`
+    : "";
+
+  const resumeSection = resumeDigest
+    ? `\n\n[Flow State Resume]\nThe following is context from your previous work session. Use it to continue seamlessly:\n${resumeDigest}\n`
+    : "";
+
+  const dynamicSuffix = `${planSection}${resumeSection}\n\nCurrent working directory: ${cwd}`;
+
+  return { staticPrefix, dynamicSuffix };
+}
+
+export function buildSystemPrompt(
+  cwd: string,
+  mode: AgentMode,
+  sandboxMode: SandboxMode,
+  planContext?: string | null,
+  subagents?: CustomSubagentConfig[],
+  sandboxSettings?: SandboxSettings,
+  providerId?: string,
+  resumeDigest?: string | null,
+  options?: SystemPromptOptions,
+): string {
+  const { staticPrefix, dynamicSuffix } = buildSystemPromptParts(
+    cwd,
+    mode,
+    sandboxMode,
+    planContext,
+    subagents,
+    sandboxSettings,
+    providerId,
+    resumeDigest,
+    options,
+  );
+  return `${staticPrefix}${dynamicSuffix}`;
+}
+
+export function buildSubagentPrompt(
+  request: TaskRequest,
+  cwd: string,
+  custom: CustomSubagentConfig | null,
+  sandboxMode: SandboxMode,
+  subagents?: CustomSubagentConfig[],
+  sandboxSettings?: SandboxSettings,
+  providerId?: string,
+): string {
+  const isExplore = request.agent === "explore";
+  const isVision = request.agent === "vision";
+  const isVerify = request.agent === "verify";
+  const isVerifyDetect = request.agent === "verify-detect";
+  const isVerifyManifest = request.agent === "verify-manifest";
+  const isComputer = request.agent === "computer";
+  const mode: AgentMode = isExplore || isVerifyDetect ? "ask" : "agent";
+  const role = custom
+    ? `You are the custom sub-agent "${custom.name}". You can investigate, edit files, and run commands unless the delegated task says otherwise.`
+    : request.agent === "explore"
+      ? "You are the Explore sub-agent. You are read-only and focus on fast codebase research."
+      : isVision
+        ? "You are the Vision sub-agent."
+        : isVerifyDetect
+          ? "You are the Verify Detect sub-agent. You inspect a repository to produce a structured verification recipe. You are read-only."
+          : isVerifyManifest
+            ? "You are the Verify Manifest sub-agent. You inspect a repository and create or update .muonroi-cli/environment.json so verification can run reproducibly."
+            : isVerify
+              ? "You are the Verify sub-agent. You specialize in sandbox-aware local verification using builds, tests, app boot checks, and optional browser smoke tests."
+              : isComputer
+                ? "You are the Computer sub-agent. You specialize in host desktop automation using accessibility snapshots, semantic element refs, screenshots, and careful mouse and keyboard actions."
+                : "You are the General sub-agent. You can investigate, edit files, and run commands to complete delegated work.";
+
+  const rules = isExplore
+    ? [
+        "Do not create, modify, or delete files.",
+        "Prefer `read_file` and search commands over broad shell exploration.",
+        "Return concise findings for the parent agent.",
+      ]
+    : isVerifyDetect
+      ? [
+          "Do not create, modify, or delete files.",
+          "Read config files, package manifests, scripts, and source layout to understand the project.",
+          "Return ONLY a valid JSON object with the VerifyRecipe schema. No markdown, no prose, no explanation outside the JSON.",
+        ]
+      : isVerifyManifest
+        ? [
+            "Focus on creating or updating .muonroi-cli/environment.json as the primary verification contract for this repository.",
+            "Read package.json and key config files to understand the project, then write .muonroi-cli/environment.json.",
+            "Prefer editing only .muonroi-cli/environment.json unless the delegated task explicitly requires something else.",
+            "",
+            "SANDBOX ENVIRONMENT (Shuru):",
+            "- OS: Debian GNU/Linux 13 (trixie)",
+            "- Architecture: aarch64 (ARM64)",
+            "- Pre-installed: NOTHING. No node, npm, npx, bun, python3, pip, go, cargo, java, or any runtime.",
+            "- Only basic system tools exist (sh, apt-get, curl, etc).",
+            "- Network access is available during bootstrap and install.",
+            "- The workspace is mounted at /workspace.",
+            "",
+            "MANIFEST REQUIREMENTS:",
+            "- bootstrapCommands: MUST install every runtime and build tool the project needs from scratch via apt-get or curl.",
+            "- For Node.js/Next.js/Vite/etc: `apt-get update && apt-get install -y curl unzip ca-certificates git python3 make g++ pkg-config nodejs npm`",
+            "- For Bun projects: also `curl -fsSL https://bun.sh/install | bash` and shellInitCommands with BUN_INSTALL/PATH exports.",
+            "- For Python: `apt-get update && apt-get install -y python3 python3-pip python3-venv ca-certificates git`",
+            "- For Go: `apt-get update && apt-get install -y golang ca-certificates git`",
+            "- For Rust: `apt-get update && apt-get install -y curl ca-certificates git build-essential && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y`",
+            "- installCommands: The package install command (npm install, pip install, etc).",
+            "- buildCommands: Build commands if applicable.",
+            "- testCommands: Test/lint commands if applicable.",
+            "- startCommand + startPort: How to start the app for smoke testing.",
+            "- smokeKind: 'http' if the app has a web UI, 'cli' for CLI tools, 'none' otherwise.",
+            "- Do NOT leave bootstrapCommands empty. The sandbox has nothing.",
+            "",
+            "Return a concise summary of what you wrote and why.",
+          ]
+        : isVision
+          ? ["Validate the image."]
+          : isComputer
+            ? [
+                "Operate carefully on the HOST desktop, not inside the shell sandbox.",
+                "Start with `computer_snapshot` when possible. It returns stable refs like @e1 that remain valid until the next snapshot.",
+                "Prefer accessibility refs over coordinates. Use `computer_click`, `computer_type`, `computer_scroll`, and `computer_get` with refs from the latest snapshot.",
+                "After any meaningful UI transition, launch, dialog open, or menu change, take another `computer_snapshot` before reusing old refs.",
+                "Use `computer_launch`, `computer_list_windows`, `computer_focus_window`, and `computer_wait` to manage apps and window state.",
+                "Use `computer_press` for shortcuts like Enter or cmd+k. Use `computer_screenshot` only for visual confirmation or when the accessibility tree is insufficient.",
+                "If `agent-desktop` is unavailable, permissions are missing, refs go stale, or the state is ambiguous, stop and return the blocker clearly to the parent agent.",
+                "Do not perform destructive or high-risk desktop actions unless the delegated task explicitly requires them.",
+              ]
+            : isVerify
+              ? [
+                  "You are a QA engineer. Your job is to prove the app works end-to-end, not just that it builds.",
+                  "Do not make durable source edits unless the delegated task explicitly asks for fixes.",
+                  "",
+                  "MANDATORY VERIFICATION STEPS (do ALL of these in order):",
+                  "1. Install dependencies (run installCommands from the recipe).",
+                  "2. Build the project (run buildCommands from the recipe).",
+                  "3. Run tests/lint if available (run testCommands from the recipe).",
+                  "4. Start the app (run startCommand from the recipe in the background).",
+                  "5. Wait for the app to be ready (curl readiness check or agent-browser wait).",
+                  "6. Run browser smoke tests like a real human QA tester:",
+                  "   - Open the app in the browser, record a video, take screenshots.",
+                  "   - Navigate the app: click links, buttons, menus. Verify pages load.",
+                  "   - Check for JavaScript console errors.",
+                  "   - Spend 3-5 interactions testing the critical path.",
+                  "7. Stop recording, close browser, then stop the dev server.",
+                  "",
+                  "Do NOT stop after build/lint. Starting the app and testing it in the browser is the most important part.",
+                  "agent-browser commands run on the HOST, not inside the sandbox. They WILL work. Do not skip them.",
+                  "Return a concise verification report. Keep it compact but always include Evidence with artifact file paths.",
+                ]
+              : [
+                  "Work only on the delegated task below.",
+                  "Use tools directly instead of narrating your intent.",
+                  "Return a concise summary for the parent agent with key outcomes and any open risks.",
+                ];
+
+  const instructionLines = custom?.instruction.trim() ? ["", "SUB-AGENT INSTRUCTIONS:", custom.instruction.trim()] : [];
+
+  return [
+    role,
+    ...instructionLines,
+    "",
+    "You are helping a parent agent. Do not address the end user directly.",
+    "Focus tightly on the delegated scope and summarize what matters back to the parent agent.",
+    "",
+    ...rules,
+    "",
+    `Delegated task: ${request.description}`,
+    "",
+    buildSystemPrompt(cwd, mode, sandboxMode, undefined, subagents, sandboxSettings, providerId),
+  ].join("\n");
+}
+
+export function formatSandboxPromptSection(sandboxMode: SandboxMode, settings?: SandboxSettings): string {
+  if (sandboxMode === "off") return "";
+
+  const s = settings ?? {};
+  let networkLine: string;
+  if (s.allowNet) {
+    networkLine = s.allowedHosts?.length
+      ? `- Network access is restricted to: ${s.allowedHosts.join(", ")}.`
+      : "- Network access is enabled.";
+  } else {
+    networkLine = "- Network is disabled.";
+  }
+
+  const lines = [
+    "",
+    "SANDBOX MODE:",
+    "- Bash commands run inside a Shuru sandbox.",
+    networkLine,
+    "- The current workspace is mounted inside the sandbox at `/workspace`.",
+    "- Shell-side workspace file changes do not persist back to the host in this version.",
+    "- Use `read_file`, `edit_file`, and `write_file` for durable source edits.",
+    "- If a task needs a host-persistent shell mutation, explain that sandbox mode blocks that workflow and ask whether to disable sandbox mode.",
+  ];
+
+  if (s.ports?.length) {
+    lines.push(`- Port forwards: ${s.ports.join(", ")}.`);
+  }
+  if (s.from) {
+    lines.push(`- Starting from checkpoint: ${s.from}.`);
+  }
+
+  return lines.join("\n");
+}
+
+export function applyModelConstraints(system: string, modelId: string): string {
+  const modelInfo = getModelInfo(modelId);
+  if (modelInfo?.supportsClientTools !== false) {
+    return system;
+  }
+
+  return [
+    system,
+    "",
+    "MODEL CONSTRAINTS:",
+    "- The selected model does not support client-side CLI tool calls in this environment.",
+    "- Do not call bash, read_file, lsp, write_file, edit_file, task, delegate, delegation, or MCP tools.",
+    "- Answer directly using only the conversation context already provided.",
+  ].join("\n");
+}

package/src/orchestrator/provider-options-shape.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { extractProviderOptionsShape } from "./provider-options-shape.js";
+
+describe("extractProviderOptionsShape", () => {
+  it("returns null for undefined/null/empty input", () => {
+    expect(extractProviderOptionsShape(undefined)).toBeNull();
+    expect(extractProviderOptionsShape(null)).toBeNull();
+    expect(extractProviderOptionsShape({})).toBeNull();
+    expect(extractProviderOptionsShape([])).toBeNull();
+    // Non-object primitives also return null (defensive).
+    expect(extractProviderOptionsShape("abc")).toBeNull();
+    expect(extractProviderOptionsShape(42)).toBeNull();
+  });
+
+  it("replaces flat-object leaves with typeof strings (no values leaked)", () => {
+    const shape = extractProviderOptionsShape({
+      openai: { store: true, promptCacheKey: "abc-secret-xyz" },
+    });
+    expect(shape).not.toBeNull();
+    const parsed = JSON.parse(shape as string);
+    expect(parsed).toEqual({
+      openai: { store: "boolean", promptCacheKey: "string" },
+    });
+    // Hard guarantee: the actual key value is never in the output.
+    expect(shape).not.toContain("abc-secret-xyz");
+  });
+
+  it("recurses into nested objects (depth 2)", () => {
+    const shape = extractProviderOptionsShape({
+      anthropic: {
+        thinking: {
+          type: "enabled",
+          budgetTokens: 8192,
+        },
+      },
+    });
+    expect(JSON.parse(shape as string)).toEqual({
+      anthropic: {
+        thinking: {
+          type: "string",
+          budgetTokens: "number",
+        },
+      },
+    });
+  });
+
+  it("caps recursion at depth 4 to avoid runaway/circular structures", () => {
+    // Build a 6-deep nested object: a.b.c.d.e.f = "leaf"
+    const deep = { a: { b: { c: { d: { e: { f: "leaf" } } } } } };
+    const shape = extractProviderOptionsShape(deep);
+    const parsed = JSON.parse(shape as string);
+    // Depths 0..3 are walked (a, b, c, d) — at depth 4 we truncate.
+    // The element at the 4-deep position should be the truncated marker.
+    expect(parsed.a.b.c.d).toBe("<max-depth>");
+    // And no actual leaf value survives.
+    expect(shape).not.toContain("leaf");
+  });
+
+  it("preserves arrays and recurses into their elements", () => {
+    const shape = extractProviderOptionsShape({
+      xai: { stopSequences: ["foo", "bar"], topLogprobs: 3 },
+    });
+    expect(JSON.parse(shape as string)).toEqual({
+      xai: { stopSequences: ["string", "string"], topLogprobs: "number" },
+    });
+  });
+});

package/src/orchestrator/provider-options-shape.ts

@@ -0,0 +1,70 @@
+/**
+ * src/orchestrator/provider-options-shape.ts
+ *
+ * Helper for Phase O1 cost-leak forensics — records the SHAPE (not the
+ * values) of providerOptions passed to streamText alongside each usage
+ * event. Lets post-mortem answer "did this call carry store=true?" /
+ * "was promptCacheKey present?" without leaking actual key material.
+ *
+ * Shape format: leaves are replaced with their typeof string. Example:
+ *   {openai: {store: true, promptCacheKey: "abc123"}, anthropic: {thinking: {budgetTokens: 8192}}}
+ * becomes:
+ *   {openai: {store: "boolean", promptCacheKey: "string"}, anthropic: {thinking: {budgetTokens: "number"}}}
+ *
+ * Recursion is depth-capped to prevent runaway on circular refs or
+ * pathological provider quirks.
+ */
+
+const MAX_DEPTH = 4;
+const TRUNCATED = "<max-depth>";
+
+type ShapeLeaf = string;
+type ShapeNode = ShapeLeaf | { [key: string]: ShapeNode } | ShapeNode[];
+
+function walk(value: unknown, depth: number): ShapeNode {
+  if (depth >= MAX_DEPTH) return TRUNCATED;
+
+  if (value === null) return "null";
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean" || t === "bigint" || t === "symbol" || t === "function") {
+    return t;
+  }
+  if (t === "undefined") return "undefined";
+
+  if (Array.isArray(value)) {
+    // Preserve array structure; recurse into each element.
+    return (value as unknown[]).map((v) => walk(v, depth + 1));
+  }
+
+  if (t === "object") {
+    const out: { [key: string]: ShapeNode } = {};
+    for (const key of Object.keys(value as object)) {
+      out[key] = walk((value as Record<string, unknown>)[key], depth + 1);
+    }
+    return out;
+  }
+
+  // Fallback for exotic types.
+  return t;
+}
+
+/**
+ * Extract a JSON-serialisable shape of providerOptions, replacing
+ * string/number/boolean leaves with their type names. Returns null for
+ * null/undefined/empty inputs so the caller can store it as a NULL DB
+ * column rather than `"{}"`.
+ */
+export function extractProviderOptionsShape(opts: unknown): string | null {
+  if (opts === null || opts === undefined) return null;
+  if (typeof opts !== "object") return null;
+  if (Array.isArray(opts) && opts.length === 0) return null;
+  if (!Array.isArray(opts) && Object.keys(opts as object).length === 0) return null;
+
+  const shape = walk(opts, 0);
+  try {
+    return JSON.stringify(shape);
+  } catch {
+    // Defensive: should be unreachable since walk produces plain values only.
+    return null;
+  }
+}