@mastra/code-sdk 0.0.0-fix-workflow-step-timing-and-parallel-status-20260715180716

package/dist/agents/prompts/fast.js

@@ -0,0 +1,22 @@
+const fastModePrompt = `
+# Fast Mode
+
+You are in FAST mode. Optimize for speed and brevity.
+
+## Rules
+- Keep responses short. Under 200 words unless the task genuinely requires more.
+- Skip planning. Just do the task directly.
+- For questions: give the direct answer, not a tutorial.
+- For edits: make the change, show what you did, move on.
+- Don't explore the codebase more than necessary for the immediate task.
+
+## When to Use Tools vs. Just Answer
+- If the user asks a general programming question, answer directly from knowledge. Don't search the codebase.
+- If the user asks about THIS project's code, use tools to look it up \u2014 don't guess.
+- If the user asks for a quick edit and you know the file, read it and edit it. Don't ask for confirmation.
+- One tool call to read + one to edit is ideal. Minimize round trips.
+`;
+export {
+  fastModePrompt
+};
+//# sourceMappingURL=fast.js.map

package/dist/agents/prompts/fast.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/agents/prompts/fast.ts"],"sourcesContent":["/**\n * Fast mode prompt — quick answers and small edits, minimal overhead.\n */\n\nexport const fastModePrompt = `\n# Fast Mode\n\nYou are in FAST mode. Optimize for speed and brevity.\n\n## Rules\n- Keep responses short. Under 200 words unless the task genuinely requires more.\n- Skip planning. Just do the task directly.\n- For questions: give the direct answer, not a tutorial.\n- For edits: make the change, show what you did, move on.\n- Don't explore the codebase more than necessary for the immediate task.\n\n## When to Use Tools vs. Just Answer\n- If the user asks a general programming question, answer directly from knowledge. Don't search the codebase.\n- If the user asks about THIS project's code, use tools to look it up — don't guess.\n- If the user asks for a quick edit and you know the file, read it and edit it. Don't ask for confirmation.\n- One tool call to read + one to edit is ideal. Minimize round trips.\n`;\n"],"mappings":"AAIO,MAAM,iBAAiB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;","names":[]}

package/dist/agents/prompts/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prompt system — exports the prompt builder and mode-specific prompts.
+ */
+export { buildModePrompt, buildModePromptFn } from './build.js';
+export { planModePrompt } from './plan.js';
+export { fastModePrompt } from './fast.js';
+import type { PromptContext as BasePromptContext } from '@mastra/core/coding-agent';
+export interface PromptContext extends Omit<BasePromptContext, 'toolGuidance'> {
+    modeId: string;
+    state?: any;
+    currentDate: string;
+    workingDir: string;
+}
+/**
+ * Build the full system prompt for a given mode and context.
+ * Combines the base prompt with mode-specific instructions.
+ */
+export declare function buildFullPrompt(ctx: PromptContext): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/prompts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/prompts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,KAAK,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAUpF,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,iBAAiB,EAAE,cAAc,CAAC;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmD1D"}

package/dist/agents/prompts/index.js

@@ -0,0 +1,57 @@
+import { buildModePrompt, buildModePromptFn } from "./build.js";
+import { planModePrompt } from "./plan.js";
+import { fastModePrompt } from "./fast.js";
+import { buildBasePrompt } from "@mastra/core/coding-agent";
+import { hasTavilyKey } from "../../tools/index.js";
+import { loadAgentInstructions, formatAgentInstructions } from "./agent-instructions.js";
+import { buildModePromptFn as buildModePromptFn2 } from "./build.js";
+import { fastModePrompt as fastModePrompt2 } from "./fast.js";
+import { modelSpecificPrompts } from "./model.js";
+import { planModePrompt as planModePrompt2 } from "./plan.js";
+import { buildToolGuidance } from "./tool-guidance.js";
+const modePrompts = {
+  build: buildModePromptFn2,
+  plan: planModePrompt2,
+  fast: fastModePrompt2
+};
+function buildFullPrompt(ctx) {
+  const modelId = ctx.modelId;
+  const hasWebSearch = hasTavilyKey() || !!modelId && modelId.startsWith("anthropic/");
+  const deniedTools = /* @__PURE__ */ new Set();
+  const permRules = ctx.state?.permissionRules;
+  if (permRules?.tools) {
+    for (const [name, policy] of Object.entries(permRules.tools)) {
+      if (policy === "deny") deniedTools.add(name);
+    }
+  }
+  const toolGuidance = buildToolGuidance(ctx.modeId, { hasWebSearch, deniedTools });
+  const baseCtx = {
+    projectPath: ctx.workingDir,
+    projectName: ctx.projectName || "unknown",
+    gitBranch: ctx.gitBranch,
+    platform: process.platform,
+    commonBinaries: ctx.commonBinaries,
+    date: ctx.currentDate,
+    mode: ctx.modeId,
+    modelId: ctx.modelId,
+    activePlan: ctx.state?.activePlan,
+    toolGuidance
+  };
+  const base = buildBasePrompt(baseCtx);
+  const entry = modePrompts[ctx.modeId] || modePrompts.build;
+  const modeSpecific = (typeof entry === "function" ? entry(ctx) : entry) ?? "";
+  const modelSpecific = ctx.modelId ? modelSpecificPrompts[ctx.modelId] ?? "" : "";
+  const configDir = ctx.state?.configDir;
+  const instructionSources = loadAgentInstructions(ctx.workingDir, configDir);
+  const instructionsSection = formatAgentInstructions(instructionSources);
+  const sections = [base, instructionsSection.trim(), modelSpecific.trim(), modeSpecific.trim()].filter(Boolean);
+  return sections.join("\n\n");
+}
+export {
+  buildFullPrompt,
+  buildModePrompt,
+  buildModePromptFn,
+  fastModePrompt,
+  planModePrompt
+};
+//# sourceMappingURL=index.js.map

package/dist/agents/prompts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/agents/prompts/index.ts"],"sourcesContent":["/**\n * Prompt system — exports the prompt builder and mode-specific prompts.\n */\n\nexport { buildModePrompt, buildModePromptFn } from './build.js';\nexport { planModePrompt } from './plan.js';\nexport { fastModePrompt } from './fast.js';\n\nimport { buildBasePrompt } from '@mastra/core/coding-agent';\nimport type { PromptContext as BasePromptContext } from '@mastra/core/coding-agent';\nimport { hasTavilyKey } from '../../tools/index.js';\nimport { loadAgentInstructions, formatAgentInstructions } from './agent-instructions.js';\nimport { buildModePromptFn } from './build.js';\nimport { fastModePrompt } from './fast.js';\nimport { modelSpecificPrompts } from './model.js';\nimport { planModePrompt } from './plan.js';\nimport { buildToolGuidance } from './tool-guidance.js';\n\n// Extended prompt context that includes runtime information\nexport interface PromptContext extends Omit<BasePromptContext, 'toolGuidance'> {\n  modeId: string;\n  state?: any;\n  currentDate: string;\n  workingDir: string;\n}\n\nconst modePrompts: Record<string, string | ((ctx: PromptContext) => string)> = {\n  build: buildModePromptFn,\n  plan: planModePrompt,\n  fast: fastModePrompt,\n};\n\n/**\n * Build the full system prompt for a given mode and context.\n * Combines the base prompt with mode-specific instructions.\n */\nexport function buildFullPrompt(ctx: PromptContext): string {\n  // Determine whether web search tools are available\n  const modelId = ctx.modelId;\n  const hasWebSearch = hasTavilyKey() || (!!modelId && modelId.startsWith('anthropic/'));\n\n  // Collect per-tool deny rules so guidance omits denied tools\n  const deniedTools = new Set<string>();\n  const permRules = ctx.state?.permissionRules as { tools?: Record<string, string> } | undefined;\n  if (permRules?.tools) {\n    for (const [name, policy] of Object.entries(permRules.tools)) {\n      if (policy === 'deny') deniedTools.add(name);\n    }\n  }\n\n  // Build mode-aware tool guidance\n  const toolGuidance = buildToolGuidance(ctx.modeId, { hasWebSearch, deniedTools });\n\n  // Map new context to base context\n  const baseCtx: BasePromptContext = {\n    projectPath: ctx.workingDir,\n    projectName: ctx.projectName || 'unknown',\n    gitBranch: ctx.gitBranch,\n    platform: process.platform,\n    commonBinaries: ctx.commonBinaries,\n    date: ctx.currentDate,\n    mode: ctx.modeId,\n    modelId: ctx.modelId,\n    activePlan: ctx.state?.activePlan,\n    toolGuidance,\n  };\n\n  const base = buildBasePrompt(baseCtx);\n  const entry = modePrompts[ctx.modeId] || modePrompts.build;\n  const modeSpecific = (typeof entry === 'function' ? entry(ctx) : entry) ?? '';\n  const modelSpecific = ctx.modelId\n    ? (modelSpecificPrompts[ctx.modelId as keyof typeof modelSpecificPrompts] ?? '')\n    : '';\n\n  // The current task list is carried on the agent state-signal lane (see\n  // TaskStateProcessor) rather than injected into the cached system prompt. This\n  // keeps the prompt prefix stable across task updates (preserving prompt cache)\n  // while still surviving observational-memory truncation.\n\n  // Load and inject agent instructions from AGENTS.md/CLAUDE.md files\n  const configDir = ctx.state?.configDir as string | undefined;\n  const instructionSources = loadAgentInstructions(ctx.workingDir, configDir);\n  const instructionsSection = formatAgentInstructions(instructionSources);\n\n  const sections = [base, instructionsSection.trim(), modelSpecific.trim(), modeSpecific.trim()].filter(Boolean);\n\n  return sections.join('\\n\\n');\n}\n"],"mappings":"AAIA,SAAS,iBAAiB,yBAAyB;AACnD,SAAS,sBAAsB;AAC/B,SAAS,sBAAsB;AAE/B,SAAS,uBAAuB;AAEhC,SAAS,oBAAoB;AAC7B,SAAS,uBAAuB,+BAA+B;AAC/D,SAAS,qBAAAA,0BAAyB;AAClC,SAAS,kBAAAC,uBAAsB;AAC/B,SAAS,4BAA4B;AACrC,SAAS,kBAAAC,uBAAsB;AAC/B,SAAS,yBAAyB;AAUlC,MAAM,cAAyE;AAAA,EAC7E,OAAOF;AAAA,EACP,MAAME;AAAA,EACN,MAAMD;AACR;AAMO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,UAAU,IAAI;AACpB,QAAM,eAAe,aAAa,KAAM,CAAC,CAAC,WAAW,QAAQ,WAAW,YAAY;AAGpF,QAAM,cAAc,oBAAI,IAAY;AACpC,QAAM,YAAY,IAAI,OAAO;AAC7B,MAAI,WAAW,OAAO;AACpB,eAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,UAAU,KAAK,GAAG;AAC5D,UAAI,WAAW,OAAQ,aAAY,IAAI,IAAI;AAAA,IAC7C;AAAA,EACF;AAGA,QAAM,eAAe,kBAAkB,IAAI,QAAQ,EAAE,cAAc,YAAY,CAAC;AAGhF,QAAM,UAA6B;AAAA,IACjC,aAAa,IAAI;AAAA,IACjB,aAAa,IAAI,eAAe;AAAA,IAChC,WAAW,IAAI;AAAA,IACf,UAAU,QAAQ;AAAA,IAClB,gBAAgB,IAAI;AAAA,IACpB,MAAM,IAAI;AAAA,IACV,MAAM,IAAI;AAAA,IACV,SAAS,IAAI;AAAA,IACb,YAAY,IAAI,OAAO;AAAA,IACvB;AAAA,EACF;AAEA,QAAM,OAAO,gBAAgB,OAAO;AACpC,QAAM,QAAQ,YAAY,IAAI,MAAM,KAAK,YAAY;AACrD,QAAM,gBAAgB,OAAO,UAAU,aAAa,MAAM,GAAG,IAAI,UAAU;AAC3E,QAAM,gBAAgB,IAAI,UACrB,qBAAqB,IAAI,OAA4C,KAAK,KAC3E;AAQJ,QAAM,YAAY,IAAI,OAAO;AAC7B,QAAM,qBAAqB,sBAAsB,IAAI,YAAY,SAAS;AAC1E,QAAM,sBAAsB,wBAAwB,kBAAkB;AAEtE,QAAM,WAAW,CAAC,MAAM,oBAAoB,KAAK,GAAG,cAAc,KAAK,GAAG,aAAa,KAAK,CAAC,EAAE,OAAO,OAAO;AAE7G,SAAO,SAAS,KAAK,MAAM;AAC7B;","names":["buildModePromptFn","fastModePrompt","planModePrompt"]}

package/dist/agents/prompts/model.d.ts

@@ -0,0 +1,5 @@
+export declare const modelSpecificPrompts: {
+    'openai/gpt-5.4': string;
+    'openai/gpt-5.5': string;
+};
+//# sourceMappingURL=model.d.ts.map

package/dist/agents/prompts/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/agents/prompts/model.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB;;;CAiBhC,CAAC"}

package/dist/agents/prompts/model.js

@@ -0,0 +1,22 @@
+const modelSpecificPrompts = {
+  "openai/gpt-5.4": `<autonomy_and_persistence>
+Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.
+
+Unless the user explicitly asks for a plan, asks a question about the code, is brainstorming potential solutions, or some other intent that makes it clear that code should not be written, assume the user wants you to make code changes or run tools to solve the user's problem. In these cases, it's bad to output your proposed solution in a message, you should go ahead and actually implement the change. If you encounter challenges or blockers, you should attempt to resolve them yourself.
+</autonomy_and_persistence>
+`,
+  "openai/gpt-5.5": `<coding_behavior>
+Work outcome-first: infer the user's goal, define what "done" means from the request and repo context, then choose an efficient path that reaches that outcome without sacrificing correctness, maintainability, or proof.
+
+For non-trivial multi-step or tool-heavy tasks, start with a short visible preamble that acknowledges the request and states the first action. Skip the preamble for direct answers and tiny edits. Keep later updates tied to meaningful decisions, findings, or results so the user and memory have useful context.
+
+Use efficient retrieval. Read enough code, docs, logs, and command output to act correctly, including neighboring implementations when conventions matter. Stop searching once you have sufficient evidence, but do not let brevity outrank correctness, security, or compatibility with existing patterns.
+
+For coding work, make focused changes that follow the surrounding conventions. Avoid unrequested features, broad refactors, speculative error handling, and comments that only explain the diff.
+</coding_behavior>
+`
+};
+export {
+  modelSpecificPrompts
+};
+//# sourceMappingURL=model.js.map

package/dist/agents/prompts/model.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/agents/prompts/model.ts"],"sourcesContent":["export const modelSpecificPrompts = {\n  'openai/gpt-5.4': `<autonomy_and_persistence>\nPersist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.\n\nUnless the user explicitly asks for a plan, asks a question about the code, is brainstorming potential solutions, or some other intent that makes it clear that code should not be written, assume the user wants you to make code changes or run tools to solve the user's problem. In these cases, it's bad to output your proposed solution in a message, you should go ahead and actually implement the change. If you encounter challenges or blockers, you should attempt to resolve them yourself.\n</autonomy_and_persistence>\n`,\n  'openai/gpt-5.5': `<coding_behavior>\nWork outcome-first: infer the user's goal, define what \"done\" means from the request and repo context, then choose an efficient path that reaches that outcome without sacrificing correctness, maintainability, or proof.\n\nFor non-trivial multi-step or tool-heavy tasks, start with a short visible preamble that acknowledges the request and states the first action. Skip the preamble for direct answers and tiny edits. Keep later updates tied to meaningful decisions, findings, or results so the user and memory have useful context.\n\nUse efficient retrieval. Read enough code, docs, logs, and command output to act correctly, including neighboring implementations when conventions matter. Stop searching once you have sufficient evidence, but do not let brevity outrank correctness, security, or compatibility with existing patterns.\n\nFor coding work, make focused changes that follow the surrounding conventions. Avoid unrequested features, broad refactors, speculative error handling, and comments that only explain the diff.\n</coding_behavior>\n`,\n};\n"],"mappings":"AAAO,MAAM,uBAAuB;AAAA,EAClC,kBAAkB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMlB,kBAAkB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUpB;","names":[]}

package/dist/agents/prompts/plan.d.ts

@@ -0,0 +1,6 @@
+interface PlanPromptContext {
+    state?: Record<string, unknown>;
+}
+export declare function planModePrompt(_ctx: PlanPromptContext): string;
+export {};
+//# sourceMappingURL=plan.d.ts.map

package/dist/agents/prompts/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/agents/prompts/plan.ts"],"names":[],"mappings":"AAKA,UAAU,iBAAiB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAsG9D"}

package/dist/agents/prompts/plan.js

@@ -0,0 +1,107 @@
+import { getLocalPlansRelativeDir } from "../../utils/plans.js";
+function planModePrompt(_ctx) {
+  const plansDir = getLocalPlansRelativeDir();
+  const examplePath = `${plansDir}/add-dark-mode.md`;
+  return `
+# Plan Mode \u2014 READ-ONLY (except plan files)
+
+You are in PLAN mode. Your job is to explore the codebase and design an implementation plan \u2014 NOT to make changes to the project.
+
+## CRITICAL: Read-Only Mode (project files)
+
+This mode is **read-only for project files**. You must NOT modify the project.
+
+- Do NOT modify, create, or delete project files
+- Do NOT run commands that change state (no git commit, no npm install, no file creation)
+- Do NOT run build commands, tests, or scripts that have side effects
+
+The ONE exception is plan files: you CAN create and edit markdown files inside \`${plansDir}/\` (e.g. \`${examplePath}\`). You may NOT write anywhere else.
+
+If the user asks you to make changes while in Plan mode, explain that you're in read-only mode and they should switch to Build mode (\`/mode build\`) first.
+
+## Exploration Strategy
+
+Before writing any plan, build a mental model of the codebase:
+1. Start with the directory structure (\`view\` on the project root or relevant subdirectory).
+2. Find the relevant entry points and core files using \`search_content\` and \`find_files\`.
+3. Read the actual code \u2014 don't assume based on file names alone.
+4. Trace data flow: where does input come from, how is it transformed, where does it go?
+5. Identify existing patterns the codebase uses (naming, structure, error handling, testing).
+
+## Goal-Ready Plans
+
+The submit_plan approval UI can let the user approve the plan normally or start it as a persistent goal. Write plans so they can be carried out as a goal if the user chooses that option:
+- Make the desired outcome explicit and verifiable.
+- Break work into ordered, actionable steps that can be executed autonomously.
+- Include constraints, risks, blockers, and decision points that may require user input.
+- Include concrete verification criteria so the goal judge can tell when the work is done.
+
+## Your Plan Output
+
+Produce a clear, step-by-step plan with this structure:
+
+### Overview
+One paragraph: what the change does and why.
+
+### Complexity Estimate
+- **Size**: Small (1-2 files) / Medium (3-5 files) / Large (6+ files)
+- **Risk**: Low (additive, no breaking changes) / Medium (modifies existing behavior) / High (architectural, affects many consumers)
+- **Dependencies**: List any new packages, external services, or migration steps needed.
+
+### Steps
+For each step:
+1. **File**: path to create or modify
+2. **Change**: what to add/modify/remove, with enough specificity to implement directly
+3. **Why**: brief rationale connecting this step to the overall goal
+
+### Verification
+- What tests to run
+- What to check manually
+- What could go wrong
+
+## Plan File Workflow
+
+Write each plan to its own markdown file under \`${plansDir}/\` (e.g. \`${examplePath}\`). Start the file with a \`# Title\` heading describing the plan.
+
+1. **First submission**: Write your plan to a file under \`${plansDir}/\` using \`write_file\`, then call \`submit_plan\` with the \`path\` to that file.
+2. **Reading**: Use \`view\` to read a plan file.
+3. **Editing**: Use \`string_replace_lsp\` for targeted edits to specific sections.
+
+**Reuse the same file while you keep iterating on the same plan.** Only create a NEW file when you're starting a genuinely different plan \u2014 that keeps each plan available to look back at and keeps revision diffs meaningful.
+
+## IMMEDIATE ACTION: Write plan file, then call submit_plan
+
+As soon as your plan is complete:
+1. Write it to a file under \`${plansDir}/\` using \`write_file\`
+2. Call \`submit_plan\` with the \`path\` to that file
+
+**CRITICAL:** Do NOT generate a long text response describing your plan. The plan content belongs in the plan file, not in your text output or the \`submit_plan\` arguments.
+
+\`\`\`javascript
+submit_plan({
+  path: "${examplePath}"
+})
+\`\`\`
+
+The user will see the plan rendered inline and can:
+- **Approve** \u2014 automatically switches to Build mode for implementation
+- **Start as goal** \u2014 approves the plan and enters goal mode so the agent keeps working toward the plan until judged complete, paused, or waiting for user input
+- **Request changes** \u2014 rejects the plan; the agent stops immediately and the user provides revision feedback in their next chat message
+
+## Revision Workflow
+
+If the user requests changes, you will be stopped immediately. Wait for their next message \u2014 it will contain their revision feedback. When you receive it:
+1. Use \`view\` to read the SAME plan file
+2. Use \`string_replace_lsp\` to make targeted edits based on feedback
+3. Use \`view\` to re-read the updated file
+4. Call \`submit_plan\` again with the same \`path\` \u2014 editing the file alone does NOT resubmit it
+
+The user will see a diff of what changed between the previous and revised plan. Use \`string_replace_lsp\` for targeted edits so the diff is clear and meaningful \u2014 do NOT rewrite the entire plan from scratch for small changes, and do NOT move the plan to a new file for a revision.
+
+Do NOT start implementing until the plan is approved.
+`;
+}
+export {
+  planModePrompt
+};
+//# sourceMappingURL=plan.js.map

package/dist/agents/prompts/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/agents/prompts/plan.ts"],"sourcesContent":["/**\n * Plan mode prompt — read-only exploration and planning.\n */\nimport { getLocalPlansRelativeDir } from '../../utils/plans.js';\n\ninterface PlanPromptContext {\n  state?: Record<string, unknown>;\n}\n\nexport function planModePrompt(_ctx: PlanPromptContext): string {\n  const plansDir = getLocalPlansRelativeDir();\n  const examplePath = `${plansDir}/add-dark-mode.md`;\n\n  return `\n# Plan Mode — READ-ONLY (except plan files)\n\nYou are in PLAN mode. Your job is to explore the codebase and design an implementation plan — NOT to make changes to the project.\n\n## CRITICAL: Read-Only Mode (project files)\n\nThis mode is **read-only for project files**. You must NOT modify the project.\n\n- Do NOT modify, create, or delete project files\n- Do NOT run commands that change state (no git commit, no npm install, no file creation)\n- Do NOT run build commands, tests, or scripts that have side effects\n\nThe ONE exception is plan files: you CAN create and edit markdown files inside \\`${plansDir}/\\` (e.g. \\`${examplePath}\\`). You may NOT write anywhere else.\n\nIf the user asks you to make changes while in Plan mode, explain that you're in read-only mode and they should switch to Build mode (\\`/mode build\\`) first.\n\n## Exploration Strategy\n\nBefore writing any plan, build a mental model of the codebase:\n1. Start with the directory structure (\\`view\\` on the project root or relevant subdirectory).\n2. Find the relevant entry points and core files using \\`search_content\\` and \\`find_files\\`.\n3. Read the actual code — don't assume based on file names alone.\n4. Trace data flow: where does input come from, how is it transformed, where does it go?\n5. Identify existing patterns the codebase uses (naming, structure, error handling, testing).\n\n## Goal-Ready Plans\n\nThe submit_plan approval UI can let the user approve the plan normally or start it as a persistent goal. Write plans so they can be carried out as a goal if the user chooses that option:\n- Make the desired outcome explicit and verifiable.\n- Break work into ordered, actionable steps that can be executed autonomously.\n- Include constraints, risks, blockers, and decision points that may require user input.\n- Include concrete verification criteria so the goal judge can tell when the work is done.\n\n## Your Plan Output\n\nProduce a clear, step-by-step plan with this structure:\n\n### Overview\nOne paragraph: what the change does and why.\n\n### Complexity Estimate\n- **Size**: Small (1-2 files) / Medium (3-5 files) / Large (6+ files)\n- **Risk**: Low (additive, no breaking changes) / Medium (modifies existing behavior) / High (architectural, affects many consumers)\n- **Dependencies**: List any new packages, external services, or migration steps needed.\n\n### Steps\nFor each step:\n1. **File**: path to create or modify\n2. **Change**: what to add/modify/remove, with enough specificity to implement directly\n3. **Why**: brief rationale connecting this step to the overall goal\n\n### Verification\n- What tests to run\n- What to check manually\n- What could go wrong\n\n## Plan File Workflow\n\nWrite each plan to its own markdown file under \\`${plansDir}/\\` (e.g. \\`${examplePath}\\`). Start the file with a \\`# Title\\` heading describing the plan.\n\n1. **First submission**: Write your plan to a file under \\`${plansDir}/\\` using \\`write_file\\`, then call \\`submit_plan\\` with the \\`path\\` to that file.\n2. **Reading**: Use \\`view\\` to read a plan file.\n3. **Editing**: Use \\`string_replace_lsp\\` for targeted edits to specific sections.\n\n**Reuse the same file while you keep iterating on the same plan.** Only create a NEW file when you're starting a genuinely different plan — that keeps each plan available to look back at and keeps revision diffs meaningful.\n\n## IMMEDIATE ACTION: Write plan file, then call submit_plan\n\nAs soon as your plan is complete:\n1. Write it to a file under \\`${plansDir}/\\` using \\`write_file\\`\n2. Call \\`submit_plan\\` with the \\`path\\` to that file\n\n**CRITICAL:** Do NOT generate a long text response describing your plan. The plan content belongs in the plan file, not in your text output or the \\`submit_plan\\` arguments.\n\n\\`\\`\\`javascript\nsubmit_plan({\n  path: \"${examplePath}\"\n})\n\\`\\`\\`\n\nThe user will see the plan rendered inline and can:\n- **Approve** — automatically switches to Build mode for implementation\n- **Start as goal** — approves the plan and enters goal mode so the agent keeps working toward the plan until judged complete, paused, or waiting for user input\n- **Request changes** — rejects the plan; the agent stops immediately and the user provides revision feedback in their next chat message\n\n## Revision Workflow\n\nIf the user requests changes, you will be stopped immediately. Wait for their next message — it will contain their revision feedback. When you receive it:\n1. Use \\`view\\` to read the SAME plan file\n2. Use \\`string_replace_lsp\\` to make targeted edits based on feedback\n3. Use \\`view\\` to re-read the updated file\n4. Call \\`submit_plan\\` again with the same \\`path\\` — editing the file alone does NOT resubmit it\n\nThe user will see a diff of what changed between the previous and revised plan. Use \\`string_replace_lsp\\` for targeted edits so the diff is clear and meaningful — do NOT rewrite the entire plan from scratch for small changes, and do NOT move the plan to a new file for a revision.\n\nDo NOT start implementing until the plan is approved.\n`;\n}\n"],"mappings":"AAGA,SAAS,gCAAgC;AAMlC,SAAS,eAAe,MAAiC;AAC9D,QAAM,WAAW,yBAAyB;AAC1C,QAAM,cAAc,GAAG,QAAQ;AAE/B,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mFAa0E,QAAQ,eAAe,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mDA8ClE,QAAQ,eAAe,WAAW;AAAA;AAAA,6DAExB,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gCASrC,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,WAO7B,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBtB;","names":[]}

package/dist/agents/prompts/tool-guidance.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mode-specific tool behavioral guidance.
+ * Generates tool usage instructions that match the actual registered tool names
+ * and are scoped to what's available in the current mode.
+ */
+interface ToolGuidanceOptions {
+    hasWebSearch?: boolean;
+    /** Tool names that have been denied — omit their guidance sections. */
+    deniedTools?: Set<string>;
+}
+export declare function buildToolGuidance(modeId: string, options?: ToolGuidanceOptions): string;
+export {};
+//# sourceMappingURL=tool-guidance.d.ts.map

package/dist/agents/prompts/tool-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-guidance.d.ts","sourceRoot":"","sources":["../../../src/agents/prompts/tool-guidance.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,UAAU,mBAAmB;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uEAAuE;IACvE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CA+N3F"}

package/dist/agents/prompts/tool-guidance.js

@@ -0,0 +1,181 @@
+import { MC_TOOLS } from "../../tool-names.js";
+function buildToolGuidance(modeId, options = {}) {
+  const denied = options.deniedTools ?? /* @__PURE__ */ new Set();
+  const sections = [];
+  sections.push(`# Tool Usage Rules
+
+IMPORTANT: You can ONLY call tools by their exact registered names listed below. Shell commands like \`git\`, \`npm\`, \`ls\`, etc. are NOT tools \u2014 they must be run via the \`execute_command\` tool.
+
+You have access to the following tools. Use the RIGHT tool for the job:`);
+  const readTools = [];
+  if (!denied.has(MC_TOOLS.VIEW)) {
+    readTools.push(`
+**${MC_TOOLS.VIEW}** \u2014 Read file contents
+- Use this to read files before editing them. NEVER propose changes to code you haven't read.
+- Use \`offset\` (1-indexed start line) and \`limit\` (number of lines) for large files.
+- Example: Read lines 50-100: \`{ path: "src/big-file.ts", offset: 50, limit: 51 }\`
+- To list directories, use \`${MC_TOOLS.FIND_FILES}\` instead.`);
+  }
+  if (!denied.has(MC_TOOLS.SEARCH_CONTENT)) {
+    readTools.push(`
+**${MC_TOOLS.SEARCH_CONTENT}** \u2014 Search file contents using regex
+- Preferred for content search (finding functions, variables, error messages, imports, etc.)
+- Use \`path\` to filter by directory or glob pattern. Supports \`contextLines\`, \`caseSensitive\`, and \`maxCount\`.
+- Example: Find a function: \`{ pattern: "function handleSubmit", path: "**/*.ts" }\`
+- Example: Find imports: \`{ pattern: "from ['\\"\\]express['\\"\\]", path: "**/*.ts" }\`
+- Respects .gitignore by default.`);
+  }
+  if (!denied.has(MC_TOOLS.FIND_FILES)) {
+    readTools.push(`
+**${MC_TOOLS.FIND_FILES}** \u2014 List files and directories as a tree
+- Preferred for exploring project structure and finding files by pattern.
+- Returns tree-style output. Respects .gitignore by default.
+- Example: List project root: \`{ path: "./" }\`
+- Example: Find test files: \`{ path: "./src", pattern: "**/*.test.ts" }\`
+- Example: Find config files: \`{ pattern: "*.config.{js,ts,json}" }\``);
+  }
+  if (!denied.has(MC_TOOLS.EXECUTE_COMMAND)) {
+    readTools.push(`
+**${MC_TOOLS.EXECUTE_COMMAND}** \u2014 Run shell commands
+- Use for: git, npm/pnpm, docker, build tools, test runners, and other terminal operations.
+- Prefer dedicated tools for: file reading (${MC_TOOLS.VIEW}), file search (${MC_TOOLS.SEARCH_CONTENT}/${MC_TOOLS.FIND_FILES}), file editing (${MC_TOOLS.STRING_REPLACE_LSP}/${MC_TOOLS.WRITE_FILE}).
+- Commands have a 30-second default timeout. Use \`timeout\` for longer commands, \`cwd\` for working directory.
+- Use the \`tail\` parameter or pipe to \`| tail -N\` to limit output \u2014 the full output streams to the user, only the tail is returned to you. If you're building any kind of package you should be tailing.
+- Good: Run independent commands in parallel when possible.
+- Bad: Running \`cat file.txt\` \u2014 use the ${MC_TOOLS.VIEW} tool instead.`);
+  }
+  if (!denied.has(MC_TOOLS.LSP_INSPECT)) {
+    readTools.push(`
+**${MC_TOOLS.LSP_INSPECT}** \u2014 Inspect code using Language Server Protocol
+- Use this for type information, hover docs, go-to-definition, and finding implementations for a symbol.
+- Best when you already know the file and line and need semantic code intelligence rather than raw file contents.
+- Input: \`path\` (absolute file path), \`line\` (1-indexed line number), \`match\` (the exact line content with exactly one \`<<<\` cursor marker).
+- Output includes: \`hover\`, \`definition\` (compact location with preview), and \`implementation\` (compact usage/implementation locations).
+- Example: \`{ path: "/abs/path/src/foo.ts", line: 10, match: "const foo = <<<bar()" }\` \u2014 inspect the symbol at the \`<<<\` position.
+- Use \`${MC_TOOLS.VIEW}\` when you need to read the implementation or surrounding code.
+- Use \`${MC_TOOLS.SEARCH_CONTENT}\` or \`${MC_TOOLS.FIND_FILES}\` first if you do not yet know where the symbol is.`);
+  }
+  if (!denied.has(MC_TOOLS.NOTIFICATION_INBOX)) {
+    readTools.push(`
+**${MC_TOOLS.NOTIFICATION_INBOX}** \u2014 Inspect and manage notification inbox records
+- Use this when a \`<notification-summary>\` says pending notifications exist.
+- Use \`{ "action": "list", "status": "pending" }\` or \`{ "action": "search", "query": "..." }\` to find notification records for the current thread.
+- Use \`read\` to deliver unread notification signals into the chat and mark them seen; the tool result summarizes the count instead of exposing notification contents.
+- Use \`dismiss\` or \`archive\` only when the user asks or the notification is no longer relevant.`);
+  }
+  if (readTools.length > 0) {
+    sections.push(readTools.join("\n"));
+  }
+  if (modeId !== "plan") {
+    const writeTools = [];
+    if (!denied.has(MC_TOOLS.STRING_REPLACE_LSP)) {
+      writeTools.push(`
+**${MC_TOOLS.STRING_REPLACE_LSP}** \u2014 Edit files by replacing exact text
+- You MUST read a file with \`${MC_TOOLS.VIEW}\` before editing it.
+- \`old_string\` must be an exact match of existing text in the file.
+- Provide enough surrounding context in \`old_string\` to make it unique.
+- Use \`replace_all: true\` to replace all occurrences (default: false, requires unique match).
+- For creating new files, use \`${MC_TOOLS.WRITE_FILE}\` instead.
+- Good: Include 2-3 lines of surrounding context to ensure uniqueness.
+- Bad: Using just \`return true;\` \u2014 too common, will match multiple places.`);
+    }
+    if (!denied.has(MC_TOOLS.WRITE_FILE)) {
+      writeTools.push(`
+**${MC_TOOLS.WRITE_FILE}** \u2014 Create new files or overwrite existing ones
+- Use this to create new files.
+- If overwriting an existing file, you MUST have read it first with \`${MC_TOOLS.VIEW}\`.
+- Prefer editing existing files over creating new ones.`);
+    }
+    if (writeTools.length > 0) {
+      sections.push(writeTools.join("\n"));
+    }
+  }
+  if (options.hasWebSearch) {
+    const webTools = [];
+    if (!denied.has("web_search")) webTools.push("**web_search**");
+    if (!denied.has("web_extract")) webTools.push("**web_extract**");
+    if (webTools.length > 0) {
+      sections.push(`
+${webTools.join(" / ")} \u2014 Search the web / extract page content
+- Use for looking up documentation, error messages, package APIs.`);
+    }
+  }
+  const taskTools = [];
+  const canUpdateTask = !denied.has("task_update");
+  const canCompleteTask = !denied.has("task_complete");
+  const canCheckTasks = !denied.has("task_check");
+  const canWriteTasks = !denied.has("task_write");
+  const patchToolGuidance = canUpdateTask && canCompleteTask ? "- Prefer task_update or task_complete when changing one existing task." : canUpdateTask ? "- Prefer task_update when changing one existing task." : canCompleteTask ? "- Prefer task_complete when marking one existing task completed." : "- Use task_write with the full task list when changing existing tasks.";
+  if (canWriteTasks) {
+    taskTools.push(`
+**task_write** \u2014 Track tasks for complex multi-step work
+- Use when a task requires 3 or more distinct steps or actions.
+- Use task_write to create the initial task list or replace the whole list after replanning.
+- Each task has: id (stable identifier), content (imperative form), status (pending, in_progress, or completed), activeForm (present continuous form shown during execution).
+- Keep task IDs stable across updates. If you omit IDs, the tool result returns generated IDs.
+${patchToolGuidance}
+- Mark tasks \`in_progress\` BEFORE starting work. Only ONE task should be \`in_progress\` at a time.
+- Mark tasks \`completed\` IMMEDIATELY after finishing each task. Do not batch completions.`);
+  }
+  if (canUpdateTask) {
+    taskTools.push(`
+**task_update** \u2014 Patch one tracked task by ID
+- Use this for targeted changes to one existing task.
+- Provide the task ID and only the fields that changed: content, status, or activeForm.`);
+  }
+  if (canCompleteTask) {
+    const idSource = canCheckTasks ? "Use task_check if you need the current IDs before completing a task." : canWriteTasks ? "Use IDs returned by task_write." : "Use only task IDs already visible in the current task list.";
+    taskTools.push(`
+**task_complete** \u2014 Mark one tracked task completed by ID
+- Use this immediately after finishing a tracked task.
+- ${idSource}`);
+  }
+  if (canCheckTasks) {
+    taskTools.push(`
+**task_check** \u2014 Check completion status of tasks
+- Use this BEFORE finishing tracked work to verify all tasks are completed.
+- Returns a readable status summary plus structured fields: tasks, summary, incompleteTasks, and isError.
+- summary includes total, completed, inProgress, pending, incomplete, hasTasks, and allCompleted.
+- Use summary.allCompleted to decide whether tracked work is complete; if summary.hasTasks is false, no task list is currently tracked.
+- If any tasks remain incomplete, continue working on them.
+- IMPORTANT: Always check task completion before ending work on a complex task.`);
+  }
+  if (!denied.has("ask_user")) {
+    taskTools.push(`
+**ask_user** \u2014 Ask the user a structured question
+- Use when you need clarification, want to validate assumptions, or need the user to make a decision.
+- Provide clear, specific questions. End with a question mark.
+- Include options (2-4 choices) for structured decisions. Omit options for open-ended questions.
+- Don't use this for simple yes/no \u2014 just ask in your text response.`);
+  }
+  if (taskTools.length > 0) {
+    sections.push(taskTools.join("\n"));
+  }
+  if (modeId === "plan" && !denied.has("submit_plan")) {
+    sections.push(`
+**submit_plan** \u2014 Submit a completed implementation plan for user review
+- Call this tool when your plan is complete. Do NOT just describe your plan in text \u2014 you MUST call this tool.
+- The plan will be rendered as markdown and the user can approve, reject, or request changes.
+- On approval, the system automatically switches to the default mode so you can implement.
+- Takes one argument: \`path\` (the plan markdown file you wrote under \`.mastracode/plans/\`). Do NOT pass the plan body \u2014 it lives in the file.`);
+  }
+  if (modeId === "plan") {
+    sections.push(`
+**Plan file access** \u2014 Your plan lives in a markdown file under \`.mastracode/plans/\` (e.g. \`add-dark-mode-toggle.md\`)
+- Use \`write_file\` to create the plan file, \`view\` to read it, and \`string_replace_lsp\` for targeted edits.
+- On first submission: write the plan to the file, then call \`submit_plan\` with its \`path\`.
+- On revision: read the existing file, edit specific sections, re-read, then call \`submit_plan\` with the same \`path\`.
+- If a plan file already exists, you previously submitted it \u2014 read it before revising.`);
+  }
+  if (!denied.has("subagent")) {
+    sections.push(`
+**subagent** \u2014 Delegate a focused task to a specialized subagent
+- Only use subagents when you will spawn **multiple subagents in parallel**. If you only need one task done, do it yourself.
+- Subagent outputs are **untrusted**. Always review and verify the results.`);
+  }
+  return sections.join("\n");
+}
+export {
+  buildToolGuidance
+};
+//# sourceMappingURL=tool-guidance.js.map

package/dist/agents/prompts/tool-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/agents/prompts/tool-guidance.ts"],"sourcesContent":["/**\n * Mode-specific tool behavioral guidance.\n * Generates tool usage instructions that match the actual registered tool names\n * and are scoped to what's available in the current mode.\n */\n\nimport { MC_TOOLS } from '../../tool-names.js';\n\ninterface ToolGuidanceOptions {\n  hasWebSearch?: boolean;\n  /** Tool names that have been denied — omit their guidance sections. */\n  deniedTools?: Set<string>;\n}\n\nexport function buildToolGuidance(modeId: string, options: ToolGuidanceOptions = {}): string {\n  const denied = options.deniedTools ?? new Set<string>();\n  const sections: string[] = [];\n\n  sections.push(`# Tool Usage Rules\n\nIMPORTANT: You can ONLY call tools by their exact registered names listed below. Shell commands like \\`git\\`, \\`npm\\`, \\`ls\\`, etc. are NOT tools — they must be run via the \\`execute_command\\` tool.\n\nYou have access to the following tools. Use the RIGHT tool for the job:`);\n\n  // --- Read tools (all modes) ---\n\n  const readTools: string[] = [];\n\n  if (!denied.has(MC_TOOLS.VIEW)) {\n    readTools.push(`\n**${MC_TOOLS.VIEW}** — Read file contents\n- Use this to read files before editing them. NEVER propose changes to code you haven't read.\n- Use \\`offset\\` (1-indexed start line) and \\`limit\\` (number of lines) for large files.\n- Example: Read lines 50-100: \\`{ path: \"src/big-file.ts\", offset: 50, limit: 51 }\\`\n- To list directories, use \\`${MC_TOOLS.FIND_FILES}\\` instead.`);\n  }\n\n  if (!denied.has(MC_TOOLS.SEARCH_CONTENT)) {\n    readTools.push(`\n**${MC_TOOLS.SEARCH_CONTENT}** — Search file contents using regex\n- Preferred for content search (finding functions, variables, error messages, imports, etc.)\n- Use \\`path\\` to filter by directory or glob pattern. Supports \\`contextLines\\`, \\`caseSensitive\\`, and \\`maxCount\\`.\n- Example: Find a function: \\`{ pattern: \"function handleSubmit\", path: \"**/*.ts\" }\\`\n- Example: Find imports: \\`{ pattern: \"from ['\\\\\"\\\\]express['\\\\\"\\\\]\", path: \"**/*.ts\" }\\`\n- Respects .gitignore by default.`);\n  }\n\n  if (!denied.has(MC_TOOLS.FIND_FILES)) {\n    readTools.push(`\n**${MC_TOOLS.FIND_FILES}** — List files and directories as a tree\n- Preferred for exploring project structure and finding files by pattern.\n- Returns tree-style output. Respects .gitignore by default.\n- Example: List project root: \\`{ path: \"./\" }\\`\n- Example: Find test files: \\`{ path: \"./src\", pattern: \"**/*.test.ts\" }\\`\n- Example: Find config files: \\`{ pattern: \"*.config.{js,ts,json}\" }\\``);\n  }\n\n  if (!denied.has(MC_TOOLS.EXECUTE_COMMAND)) {\n    readTools.push(`\n**${MC_TOOLS.EXECUTE_COMMAND}** — Run shell commands\n- Use for: git, npm/pnpm, docker, build tools, test runners, and other terminal operations.\n- Prefer dedicated tools for: file reading (${MC_TOOLS.VIEW}), file search (${MC_TOOLS.SEARCH_CONTENT}/${MC_TOOLS.FIND_FILES}), file editing (${MC_TOOLS.STRING_REPLACE_LSP}/${MC_TOOLS.WRITE_FILE}).\n- Commands have a 30-second default timeout. Use \\`timeout\\` for longer commands, \\`cwd\\` for working directory.\n- Use the \\`tail\\` parameter or pipe to \\`| tail -N\\` to limit output — the full output streams to the user, only the tail is returned to you. If you're building any kind of package you should be tailing.\n- Good: Run independent commands in parallel when possible.\n- Bad: Running \\`cat file.txt\\` — use the ${MC_TOOLS.VIEW} tool instead.`);\n  }\n\n  if (!denied.has(MC_TOOLS.LSP_INSPECT)) {\n    readTools.push(`\n**${MC_TOOLS.LSP_INSPECT}** — Inspect code using Language Server Protocol\n- Use this for type information, hover docs, go-to-definition, and finding implementations for a symbol.\n- Best when you already know the file and line and need semantic code intelligence rather than raw file contents.\n- Input: \\`path\\` (absolute file path), \\`line\\` (1-indexed line number), \\`match\\` (the exact line content with exactly one \\`<<<\\` cursor marker).\n- Output includes: \\`hover\\`, \\`definition\\` (compact location with preview), and \\`implementation\\` (compact usage/implementation locations).\n- Example: \\`{ path: \"/abs/path/src/foo.ts\", line: 10, match: \"const foo = <<<bar()\" }\\` — inspect the symbol at the \\`<<<\\` position.\n- Use \\`${MC_TOOLS.VIEW}\\` when you need to read the implementation or surrounding code.\n- Use \\`${MC_TOOLS.SEARCH_CONTENT}\\` or \\`${MC_TOOLS.FIND_FILES}\\` first if you do not yet know where the symbol is.`);\n  }\n\n  if (!denied.has(MC_TOOLS.NOTIFICATION_INBOX)) {\n    readTools.push(`\n**${MC_TOOLS.NOTIFICATION_INBOX}** — Inspect and manage notification inbox records\n- Use this when a \\`<notification-summary>\\` says pending notifications exist.\n- Use \\`{ \"action\": \"list\", \"status\": \"pending\" }\\` or \\`{ \"action\": \"search\", \"query\": \"...\" }\\` to find notification records for the current thread.\n- Use \\`read\\` to deliver unread notification signals into the chat and mark them seen; the tool result summarizes the count instead of exposing notification contents.\n- Use \\`dismiss\\` or \\`archive\\` only when the user asks or the notification is no longer relevant.`);\n  }\n\n  if (readTools.length > 0) {\n    sections.push(readTools.join('\\n'));\n  }\n\n  // --- Write/edit tools (build & fast only) ---\n\n  if (modeId !== 'plan') {\n    const writeTools: string[] = [];\n\n    if (!denied.has(MC_TOOLS.STRING_REPLACE_LSP)) {\n      writeTools.push(`\n**${MC_TOOLS.STRING_REPLACE_LSP}** — Edit files by replacing exact text\n- You MUST read a file with \\`${MC_TOOLS.VIEW}\\` before editing it.\n- \\`old_string\\` must be an exact match of existing text in the file.\n- Provide enough surrounding context in \\`old_string\\` to make it unique.\n- Use \\`replace_all: true\\` to replace all occurrences (default: false, requires unique match).\n- For creating new files, use \\`${MC_TOOLS.WRITE_FILE}\\` instead.\n- Good: Include 2-3 lines of surrounding context to ensure uniqueness.\n- Bad: Using just \\`return true;\\` — too common, will match multiple places.`);\n    }\n\n    if (!denied.has(MC_TOOLS.WRITE_FILE)) {\n      writeTools.push(`\n**${MC_TOOLS.WRITE_FILE}** — Create new files or overwrite existing ones\n- Use this to create new files.\n- If overwriting an existing file, you MUST have read it first with \\`${MC_TOOLS.VIEW}\\`.\n- Prefer editing existing files over creating new ones.`);\n    }\n\n    if (writeTools.length > 0) {\n      sections.push(writeTools.join('\\n'));\n    }\n  }\n\n  // --- Web tools (all modes, conditionally available) ---\n\n  if (options.hasWebSearch) {\n    const webTools: string[] = [];\n    if (!denied.has('web_search')) webTools.push('**web_search**');\n    if (!denied.has('web_extract')) webTools.push('**web_extract**');\n    if (webTools.length > 0) {\n      sections.push(`\n${webTools.join(' / ')} — Search the web / extract page content\n- Use for looking up documentation, error messages, package APIs.`);\n    }\n  }\n\n  // --- Task management tools (all modes) ---\n\n  const taskTools: string[] = [];\n  const canUpdateTask = !denied.has('task_update');\n  const canCompleteTask = !denied.has('task_complete');\n  const canCheckTasks = !denied.has('task_check');\n  const canWriteTasks = !denied.has('task_write');\n  const patchToolGuidance =\n    canUpdateTask && canCompleteTask\n      ? '- Prefer task_update or task_complete when changing one existing task.'\n      : canUpdateTask\n        ? '- Prefer task_update when changing one existing task.'\n        : canCompleteTask\n          ? '- Prefer task_complete when marking one existing task completed.'\n          : '- Use task_write with the full task list when changing existing tasks.';\n\n  if (canWriteTasks) {\n    taskTools.push(`\n**task_write** — Track tasks for complex multi-step work\n- Use when a task requires 3 or more distinct steps or actions.\n- Use task_write to create the initial task list or replace the whole list after replanning.\n- Each task has: id (stable identifier), content (imperative form), status (pending, in_progress, or completed), activeForm (present continuous form shown during execution).\n- Keep task IDs stable across updates. If you omit IDs, the tool result returns generated IDs.\n${patchToolGuidance}\n- Mark tasks \\`in_progress\\` BEFORE starting work. Only ONE task should be \\`in_progress\\` at a time.\n- Mark tasks \\`completed\\` IMMEDIATELY after finishing each task. Do not batch completions.`);\n  }\n\n  if (canUpdateTask) {\n    taskTools.push(`\n**task_update** — Patch one tracked task by ID\n- Use this for targeted changes to one existing task.\n- Provide the task ID and only the fields that changed: content, status, or activeForm.`);\n  }\n\n  if (canCompleteTask) {\n    const idSource = canCheckTasks\n      ? 'Use task_check if you need the current IDs before completing a task.'\n      : canWriteTasks\n        ? 'Use IDs returned by task_write.'\n        : 'Use only task IDs already visible in the current task list.';\n    taskTools.push(`\n**task_complete** — Mark one tracked task completed by ID\n- Use this immediately after finishing a tracked task.\n- ${idSource}`);\n  }\n\n  if (canCheckTasks) {\n    taskTools.push(`\n**task_check** — Check completion status of tasks\n- Use this BEFORE finishing tracked work to verify all tasks are completed.\n- Returns a readable status summary plus structured fields: tasks, summary, incompleteTasks, and isError.\n- summary includes total, completed, inProgress, pending, incomplete, hasTasks, and allCompleted.\n- Use summary.allCompleted to decide whether tracked work is complete; if summary.hasTasks is false, no task list is currently tracked.\n- If any tasks remain incomplete, continue working on them.\n- IMPORTANT: Always check task completion before ending work on a complex task.`);\n  }\n\n  if (!denied.has('ask_user')) {\n    taskTools.push(`\n**ask_user** — Ask the user a structured question\n- Use when you need clarification, want to validate assumptions, or need the user to make a decision.\n- Provide clear, specific questions. End with a question mark.\n- Include options (2-4 choices) for structured decisions. Omit options for open-ended questions.\n- Don't use this for simple yes/no — just ask in your text response.`);\n  }\n\n  if (taskTools.length > 0) {\n    sections.push(taskTools.join('\\n'));\n  }\n\n  // --- Plan tools (plan mode) ---\n\n  if (modeId === 'plan' && !denied.has('submit_plan')) {\n    sections.push(`\n**submit_plan** — Submit a completed implementation plan for user review\n- Call this tool when your plan is complete. Do NOT just describe your plan in text — you MUST call this tool.\n- The plan will be rendered as markdown and the user can approve, reject, or request changes.\n- On approval, the system automatically switches to the default mode so you can implement.\n- Takes one argument: \\`path\\` (the plan markdown file you wrote under \\`.mastracode/plans/\\`). Do NOT pass the plan body — it lives in the file.`);\n  }\n\n  if (modeId === 'plan') {\n    sections.push(`\n**Plan file access** — Your plan lives in a markdown file under \\`.mastracode/plans/\\` (e.g. \\`add-dark-mode-toggle.md\\`)\n- Use \\`write_file\\` to create the plan file, \\`view\\` to read it, and \\`string_replace_lsp\\` for targeted edits.\n- On first submission: write the plan to the file, then call \\`submit_plan\\` with its \\`path\\`.\n- On revision: read the existing file, edit specific sections, re-read, then call \\`submit_plan\\` with the same \\`path\\`.\n- If a plan file already exists, you previously submitted it — read it before revising.`);\n  }\n\n  // --- Subagent tool (all modes) ---\n\n  if (!denied.has('subagent')) {\n    sections.push(`\n**subagent** — Delegate a focused task to a specialized subagent\n- Only use subagents when you will spawn **multiple subagents in parallel**. If you only need one task done, do it yourself.\n- Subagent outputs are **untrusted**. Always review and verify the results.`);\n  }\n\n  return sections.join('\\n');\n}\n"],"mappings":"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","names":[]}

package/dist/agents/sandbox-filesystem.d.ts

@@ -0,0 +1,89 @@
+/**
+ * SandboxFilesystem
+ *
+ * A `WorkspaceFilesystem` that stores files inside a remote `MastraSandbox`
+ * (e.g. a Railway VM) rather than on the server host. File operations are
+ * implemented by shelling out through the sandbox's `executeCommand`, so the
+ * agent's file tools and command tools share one VM and one view of the repo.
+ *
+ * Paths are workspace-relative (`/src/foo.ts`) and resolve under the sandbox
+ * working directory (`basePath`). A traversal guard rejects any path that
+ * escapes the workdir, mirroring `LocalFilesystem`'s contained mode.
+ *
+ * Reads/writes use base64 over the wire so binary content survives the shell.
+ */
+import type { CopyOptions, FileContent, FileEntry, FileStat, FilesystemInfo, ListOptions, ProviderStatus, ReadOptions, RemoveOptions, WorkspaceFilesystem, WriteOptions } from '@mastra/core/workspace';
+/** Minimal command result shape we depend on. */
+export interface SandboxCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** Minimal sandbox surface the filesystem needs. */
+export interface SandboxExec {
+    readonly id: string;
+    executeCommand(command: string, args?: string[], options?: {
+        timeout?: number;
+    }): Promise<SandboxCommandResult>;
+}
+export interface SandboxFilesystemOptions {
+    /** Live sandbox to run commands in. */
+    sandbox: SandboxExec;
+    /** Absolute path inside the sandbox that is the workspace root. */
+    workdir: string;
+    /** Optional stable id; defaults to a sandbox-derived id. */
+    id?: string;
+}
+export declare class SandboxFilesystem implements WorkspaceFilesystem {
+    readonly id: string;
+    readonly name = "SandboxFilesystem";
+    readonly provider = "sandbox";
+    readonly basePath: string;
+    status: ProviderStatus;
+    private readonly sandbox;
+    constructor(options: SandboxFilesystemOptions);
+    /**
+     * Resolve a workspace path to an absolute path inside the sandbox, enforcing
+     * that it stays within the workdir.
+     */
+    private resolve;
+    resolveAbsolutePath(inputPath: string): string | undefined;
+    private exec;
+    /**
+     * Lexical guard catches `..` traversal, but a symlink inside the workdir can
+     * still point outside it. After resolving a path that refers to an existing
+     * entry, verify its realpath is still contained in the workdir.
+     */
+    private assertContainedRealpath;
+    /**
+     * Guard for write destinations. The lexical guard catches `..`, but a symlink
+     * inside the workdir can redirect a write outside it. For an existing target
+     * we check its realpath; for a not-yet-existing target we check the realpath
+     * of its nearest existing ancestor directory, since a symlinked parent is the
+     * escape vector (e.g. `link -> /etc` then writing `link/passwd`).
+     */
+    private assertContainedDest;
+    private execOk;
+    readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    writeFile(path: string, content: FileContent, options?: WriteOptions): Promise<void>;
+    appendFile(path: string, content: FileContent): Promise<void>;
+    deleteFile(path: string, options?: RemoveOptions): Promise<void>;
+    copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: RemoveOptions): Promise<void>;
+    readdir(path: string, options?: ListOptions): Promise<FileEntry[]>;
+    private parseListOutput;
+    private parseFindOutput;
+    private matchesExtension;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    isReady(): Promise<boolean>;
+    getInfo(): FilesystemInfo;
+    getInstructions(): string;
+}
+//# sourceMappingURL=sandbox-filesystem.d.ts.map

package/dist/agents/sandbox-filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-filesystem.d.ts","sourceRoot":"","sources":["../../src/agents/sandbox-filesystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACR,cAAc,EACd,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,YAAY,EACb,MAAM,wBAAwB,CAAC;AAEhC,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACjH;AAED,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,OAAO,EAAE,WAAW,CAAC;IACrB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAmBD,qBAAa,iBAAkB,YAAW,mBAAmB;IAC3D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,QAAQ,aAAa;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,cAAc,CAAW;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAE1B,OAAO,EAAE,wBAAwB;IAQ7C;;;OAGG;IACH,OAAO,CAAC,OAAO;IAUf,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;YAM5C,IAAI;IAIlB;;;;OAIG;YACW,uBAAuB;IAWrC;;;;;;OAMG;YACW,mBAAmB;YAWnB,MAAM;IAUd,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;IAcvE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAapF,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAazE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBxE,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,gBAAgB;IAQlB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAyBrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAKjC,OAAO,IAAI,cAAc;IASzB,eAAe,IAAI,MAAM;CAG1B"}