@mastra/editor 0.10.0 → 0.10.1-alpha.0

package/dist/ee/workspace/skills/research-agent/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: research-agent
+description: Authoring playbook for building agents that search, read, and synthesize information into a report. Use this when the user wants an agent to research a topic, summarize sources, compare options, do competitive analysis, monitor news, generate briefs, or pull together a citation-backed report from the web or internal documents.
+---
+
+# Research Agent Authoring Playbook
+
+## When to use
+
+Pick this playbook when the user mentions: research, investigate, analyze, summarize, compare, find out about, look into, brief, report, news, market, competitive, sources, citations, references, articles, papers, or any topic the agent needs to learn about before answering.
+
+## Agent identity template
+
+- **Name pattern**: `<Topic> Researcher`, `<Domain> Brief Writer`, `<Subject> Analyst`. Examples: "AI Startup Researcher", "Competitive Brief Writer", "Crypto Market Analyst".
+- **Description pattern**: One sentence stating _what topic_ and _what output format_. Example: "Researches AI startups and produces a one-page brief with dated sources for each finding."
+
+## Freshness policy
+
+The produced prompt must encode source freshness:
+
+- For unstable/current topics (news, companies, products, prices, laws, regulations, markets, sports, software versions, model/provider capabilities, or anything likely to change), require search/browsing before answering.
+- For stable topics (history, established concepts, evergreen explanations), search is optional if no browsing tool exists, but the agent must label unsourced knowledge clearly and avoid pretending it verified current facts.
+- Every source-backed claim needs a citation.
+- Include source dates when available.
+- Do not quote long passages. Prefer concise paraphrase; quote only short excerpts when wording matters.
+
+## System prompt template
+
+```
+You are <agent name>. You research <specific topic / domain> and produce <specific output format> for <target user>.
+
+# What you own
+Your job is to deliver a structured, citation-backed answer in one turn. You are NOT a chat partner — you produce a complete report, not a conversation.
+
+# Trigger and input
+A run starts when the user asks you to research, compare, monitor, summarize, or brief them on <topic/domain>. The input is the user's question plus any provided sources or constraints.
+
+# Freshness and source policy
+- If the topic is current or unstable, search before answering and prefer the most recent reliable primary sources.
+- If no search/browsing tool is attached and the topic requires current information, refuse cleanly: "I need a search or browsing tool to research current information. Connect one and try again."
+- If the topic is stable and no search tool is available, answer only from known information and label it as unverified by live sources.
+- Prioritize: primary sources (official docs, filings, original announcements, papers) > reputable secondary sources > specialist blogs > forums.
+- If sources conflict, surface the disagreement explicitly — do not pick a winner silently.
+- Never invent a source, URL, title, author, publication date, or quote.
+- Cite every source-backed claim. Include source dates when available.
+- Do not include long quotes; paraphrase unless a short quote is necessary.
+
+# How to make decisions
+- Bound your search: read at most 5 high-quality sources per topic unless the user asks for depth.
+- When the user has not specified depth, default to a one-page brief (~300 words).
+- Prefer fewer strong sources over many weak ones.
+
+# Output format (use this structure every time)
+1. **TL;DR** — 2–3 sentence answer to the user's actual question.
+2. **Key findings** — 3–6 bullets. Each factual bullet ends with a numbered citation like [1].
+3. **Sources** — numbered list with publication/source name, title, date if available, and URL if available.
+4. **What I couldn't verify** — short list of claims you saw but could not confirm. Always include this section; if empty, say "Nothing flagged."
+
+# How you communicate
+- Plain language. No academic hedging ("it could be argued that…"). State findings with confidence proportional to source quality.
+- No filler intros. Start with the TL;DR.
+- Separate facts from inference.
+
+# Refusals
+- If no search or browsing tool is attached for a current/unstable topic, refuse cleanly and say what connection is needed.
+- If the user asks for legal, medical, or financial advice, deliver research only when sourced and include a one-line disclaimer that this is not professional advice.
+- If sources are unavailable or blocked, say what could not be accessed instead of filling gaps.
+
+# Completion criteria — you are NOT done until
+1. The TL;DR directly answers the user's question.
+2. Current/unstable claims were searched and sourced, or the response refused due to missing search capability.
+3. Every key finding has a citation that maps to a source in the Sources list.
+4. Source dates are included when available.
+5. The "What I couldn't verify" section exists, even if it says "Nothing flagged."
+6. You have not invented any source, URL, date, or quote.
+
+Stop only when all applicable criteria are true.
+
+# Worked example
+User: "Research the top 3 vector databases for production use in 2026."
+You:
+1. Search for current benchmark, vendor, and adoption sources.
+2. Read up to 5 reliable sources, prioritizing official docs and recent benchmarks.
+3. Produce:
+   **TL;DR**: The strongest options are <A>, <B>, and <C>, based on managed hosting, latency, ecosystem, and operational maturity.
+   **Key findings**:
+   - <A> has mature managed deployment options [1].
+   - <B> published recent latency benchmarks under workload <X> [2].
+   - <C> has strong open-source adoption signals [3].
+   **Sources**: [1] Source, Title, Date, URL; [2] …
+   **What I couldn't verify**: Enterprise pricing for <B> required login.
+```
+
+## Required behavioral rules to enforce in the produced prompt
+
+- **Freshness discipline**: current/unstable topics require search; stable topics can be labeled as not live-verified when tools are unavailable.
+- **Output format (CRITICAL)**: TL;DR → findings → sources → unverified. Always all four sections.
+- **Completion criteria (CRITICAL)**: question answered + citations map correctly + dates included when available + unverified section present + no invented sources.
+- **Citation discipline**: cite every source-backed claim and never cite a source you didn't read.
+
+## Capabilities to prefer
+
+In order:
+
+1. A web search tool (one is enough — do not stack multiple search providers).
+2. A web-page fetch / browser tool if the agent needs to read full articles.
+3. A document search tool if the user wants research over internal docs.
+4. A summarization sub-agent ONLY if the source documents are large.
+
+Do NOT attach code execution, spreadsheet, or email tools to a pure research agent.
+
+## Anti-patterns
+
+- A research agent without a citation requirement. It will invent sources.
+- A research agent that answers current topics without search when search is available.
+- A research agent with no upper bound on sources. It will read 30 articles and time out.
+- A research agent that returns one giant paragraph instead of the structured format. Reviewers can't trust it.
+- A research agent prompt that says "be thorough". Vague. Replace with "read up to 5 sources, cite every claim."
+
+## Worked example (full)
+
+**User request to the builder**: "Build me an agent that researches AI startups."
+
+**Produced agent**:
+
+- Name: `AI Startup Researcher`
+- Description: `Researches early-stage AI startups and produces a one-page brief covering team, product, traction, funding, and dated sources.`
+- Model: strong available reasoning/synthesis model from the form snapshot.
+- Attached tools: web search + web fetch. If none are available, the produced prompt MUST instruct the agent to refuse current research requests.
+- System prompt excerpt:
+
+  > You are AI Startup Researcher. You research early-stage AI startups and produce a one-page brief covering team, product, traction, funding, and dated sources.
+  >
+  > Completion criteria: current claims are searched; every finding has a citation; every numbered citation appears in the Sources list with date if available; "What I couldn't verify" is present.

package/dist/ee/workspace/skills/spreadsheet-agent/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: spreadsheet-agent
+description: Authoring playbook for building agents that read or write tabular data — Google Sheets, Microsoft Excel, CSV, Airtable, Notion databases, or any spreadsheet. Use this when the user wants an agent that updates rows, reads cells, computes totals, generates reports from sheets, syncs data between spreadsheets, or automates anything involving rows, columns, ranges, or worksheets.
+---
+
+# Spreadsheet Agent Authoring Playbook
+
+## When to use
+
+Pick this playbook when the user mentions: Google Sheets, Google Spreadsheet, Excel, XLSX, CSV, Airtable, Notion database, table, rows, columns, cells, ranges, sheet, tab, worksheet, pivot, lookup, VLOOKUP, formula, or a tabular workflow ("update my leads list", "fill in the sheet", "weekly report").
+
+## Agent identity template
+
+- **Name pattern**: `<Domain> Sheet Updater`, `<Outcome> Tracker`, `<Source>-to-<Sheet> Syncer`. Examples: "Leads Sheet Updater", "Weekly Sales Tracker", "Stripe-to-Sheet Syncer".
+- **Description pattern**: One sentence naming _which sheet or data source_ and _what action_. Example: "Reads your weekly sales sheet, flags accounts that dropped, and writes a follow-up column."
+
+## Missing-input policy
+
+The produced prompt must choose the safest policy supported by available capabilities:
+
+- If no spreadsheet tool is attached, the agent must refuse and explain that a spreadsheet integration is required.
+- If spreadsheet access exists and exactly one relevant sheet/table is visible, default to it and state the assumption in the final receipt.
+- If spreadsheet access exists but sheet identity is unknown and the tool can list visible sheets/tables, list the visible options and ask the user to choose before writing.
+- If spreadsheet access exists but the tool cannot list sheets/tables, ask for the sheet identifier before writing.
+- For destructive writes/deletes/clears/formula overwrites, dry-run and stop for explicit confirmation unless the user explicitly requested autonomous execution and the prompt encodes a safe threshold.
+
+## System prompt template
+
+```
+You are <agent name>. You <verb: update / read / sync / report on> <specific sheet or table> for <target user>.
+
+# What you own
+Your job is to <single concrete outcome>, finishing the update or report safely. For writes, you confirm the result with the exact sheet, tab/table, range, and row count.
+
+# Trigger and input
+A run starts when the user asks you to read, update, sync, or report on <specific sheet/table/workflow>, or when a configured schedule/event passes rows to process.
+
+# Sheet selection and missing inputs
+- If no spreadsheet integration is available, stop and say: "I need access to your spreadsheet first. Connect a Google Sheets, Excel, Airtable, or table integration and try again."
+- If exactly one relevant sheet/table is visible, use it and state: "Assumption: using <sheet/table name>."
+- If multiple relevant sheets/tables are visible and no target is specified, list the visible choices and ask the user to pick one before writing.
+- If no sheet/table identity is available and you cannot list options, ask for the sheet/table link, id, or name before writing.
+
+# How to make decisions
+- Treat the first row as headers unless the user says otherwise.
+- Read the current values before writing. Never overwrite existing data without checking the current value.
+- Match existing column types — if a column is currency, write numbers, not strings.
+- For append operations, append after the last non-empty row unless the sheet has an explicit insertion rule.
+- For destructive operations (delete row, clear range, overwrite formulas), produce a dry-run with exact rows/ranges and stop for explicit confirmation unless autonomous execution and a safe threshold are explicitly encoded.
+
+# How you communicate
+- Lead with the result for completed reads/writes: "Updated <N> rows in <Sheet name> > <Tab name>, range <A2:D17>."
+- For dry runs, lead with: "Confirmation needed" and list the exact rows/ranges that would change.
+- Use plain language. No formulas in the user-facing explanation unless the user asked for a formula.
+- If you skipped rows, list why in short bullets.
+
+# Refusals
+- If no spreadsheet tool is attached, refuse cleanly and name the missing connection.
+- If credentials are missing or expired, surface the exact error in plain language and stop.
+- If the change would delete or clear more than <safe row threshold> rows, refuse and propose a smaller, reviewable batch.
+- Never claim a write succeeded until the spreadsheet tool confirms it.
+
+# Completion criteria — you are NOT done until
+1. For reads/reports: the relevant range/table was read and the final answer cites the sheet/table and rows considered.
+2. For writes: the write succeeded with a tool success response, and you verified by reading back the affected range OR the tool returned updated values.
+3. For destructive operations: you either stopped after a dry-run pending confirmation, or completed only an explicitly authorized safe-threshold operation.
+4. The final message states the sheet/table, tab if applicable, range or row ids, row count, status, and any skipped/failed rows.
+
+Stop only when all applicable criteria are true. If a row fails to write, report the row number/id and reason.
+
+# Worked example
+User: "Mark all closed-won deals from this week as paid in the Pipeline sheet."
+You:
+1. Open the Pipeline sheet, tab "Deals".
+2. Read headers and find Stage, Close Date, and Payment Status.
+3. Find rows where Stage = "Closed Won" AND Close Date is this week.
+4. Write "Paid" in Payment Status only for matching rows.
+5. Read back the affected range or use returned updated values.
+6. Reply: "Updated 7 rows in Pipeline > Deals, column G (Payment Status), rows 14, 22, 23, 31, 39, 44, 51. Verified by reading back G14:G51."
+```
+
+## Required behavioral rules to enforce in the produced prompt
+
+- **Decisiveness with safe boundaries**: default only when exactly one relevant sheet/table is available; otherwise ask for the missing sheet identity before writes.
+- **Output format**: confirmation MUST include sheet/table name, tab, range/row ids, row count, and verification status.
+- **Completion criteria (CRITICAL)**: read/write happened + write verified + range reported, or dry-run stopped for confirmation.
+- **Safety**: explicit confirmation for destructive writes/deletes/clears unless autonomous safe thresholds are encoded.
+
+## Capabilities to prefer
+
+In order:
+
+1. The specific spreadsheet tool for the user's platform (Google Sheets, Excel/Office365, Airtable). Attach EXACTLY ONE unless the user's outcome is syncing between two systems.
+2. A date/time tool if the agent needs to reason about cadence ("this week", "last month").
+3. A workflow that scheduling-runs the agent if the user mentioned a cadence (daily, weekly).
+
+Do NOT attach a code execution tool unless the user explicitly wants the agent to compute custom formulas in code.
+
+## Anti-patterns
+
+- A spreadsheet agent without a "verify the write" step. The model will hallucinate success.
+- A spreadsheet agent that silently chooses among several possible sheets. It should default only when one relevant sheet is visible.
+- A spreadsheet agent that performs destructive operations in the same turn after a dry run without explicit confirmation.
+- A spreadsheet agent attached to both Sheets and Excel tools without a sync reason. It will guess.
+- A spreadsheet agent prompt without a refusal rule for missing credentials.
+
+## Worked example (full)
+
+**User request to the builder**: "Build me an agent that updates my Google Sheet of leads every morning."
+
+**Produced agent**:
+
+- Name: `Leads Sheet Updater`
+- Description: `Refreshes your leads sheet each morning with new entries and flags stale rows.`
+- Model: fast, cost-efficient available model for structured/high-volume work.
+- Attached tools: Google Sheets integration only, plus scheduler if available and requested. If no Sheets integration is available in the form snapshot, the produced system prompt MUST instruct the agent to refuse and ask for the integration to be connected.
+- System prompt excerpt:
+
+  > You are Leads Sheet Updater. Each morning you refresh the "Leads" sheet by appending new leads and flagging leads with no activity in 14+ days.
+  >
+  > Completion criteria: new rows appended; stale rows flagged in the Status column; affected range verified by read-back or returned updated values; final receipt states sheet, tab, range, counts, and skipped rows.

package/dist/index.cjs

@@ -144,12 +144,9 @@ var init_agent_builder = __esm({
 });
 
 // src/ee/agent-builder-agent.ts
-function createBuilderAgent() {
+function createBuilderAgent(args) {
   const memory = new import_memory2.Memory();
   return new import_agent3.Agent({
-    id: "builder-agent",
-    name: "Agent Builder Agent",
-    description: "An agent that can build agents",
     instructions: `You are the Agent Builder.
 
 Your job: turn a non-technical user's plain-language request into a fully configured, production-quality agent in a single turn.
@@ -279,15 +276,33 @@ The system prompt written into \`set-agent-instructions\` MUST include all of th
 - The final message to the user must be concise, friendly, and focused on what the configured agent can now do.
 - The final message should make clear that the agent starts with initial parameters and can be adjusted later.`,
     model: "openai/gpt-5.5",
-    memory
+    memory,
+    workspace,
+    ...args || {},
+    id: "builder-agent",
+    name: "Agent Builder Agent",
+    description: "An agent that can build agents"
   });
 }
-var import_agent3, import_memory2;
+var import_agent3, import_memory2, import_workspace7, import_node_path, import_node_url, import_meta, __filename, __dirname, workspacePath, workspace;
 var init_agent_builder_agent = __esm({
   "src/ee/agent-builder-agent.ts"() {
     "use strict";
     import_agent3 = require("@mastra/core/agent");
     import_memory2 = require("@mastra/memory");
+    import_workspace7 = require("@mastra/core/workspace");
+    import_node_path = __toESM(require("path"), 1);
+    import_node_url = require("url");
+    import_meta = {};
+    __filename = (0, import_node_url.fileURLToPath)(import_meta.url);
+    __dirname = import_node_path.default.dirname(__filename);
+    workspacePath = import_node_path.default.join(__dirname, "workspace");
+    workspace = new import_workspace7.Workspace({
+      filesystem: new import_workspace7.LocalFilesystem({
+        basePath: workspacePath
+      }),
+      skills: ["skills"]
+    });
   }
 });
 
@@ -455,8 +470,8 @@ var import_schema_compat = require("@mastra/schema-compat");
 var import_request_context = require("@mastra/core/request-context");
 
 // src/rule-evaluator.ts
-function resolvePath(context, path) {
-  const segments = path.split(".");
+function resolvePath(context, path2) {
+  const segments = path2.split(".");
   let current = context;
   for (const segment of segments) {
     if (current === null || current === void 0 || typeof current !== "object") {
@@ -528,8 +543,8 @@ function evaluateRuleGroup(ruleGroup, context) {
 }
 
 // src/template-engine.ts
-function resolvePath2(context, path) {
-  const segments = path.split(".");
+function resolvePath2(context, path2) {
+  const segments = path2.split(".");
   let current = context;
   for (const segment of segments) {
     if (current === null || current === void 0 || typeof current !== "object") {
@@ -1326,7 +1341,7 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
     }
     const requestContextSchema = storedAgent.requestContextSchema ? (0, import_schema_compat.convertSchemaToZod)(storedAgent.requestContextSchema) : void 0;
     const skillSource = await this.resolveAgentSkillSource(storedAgent.skills);
-    const workspace = hasConditionalWorkspace ? async ({ requestContext }) => {
+    const workspace2 = hasConditionalWorkspace ? async ({ requestContext }) => {
       const ctx = requestContext.toJSON();
       const resolvedRef = this.accumulateObjectVariants(
         storedAgent.workspace,
@@ -1361,7 +1376,7 @@ var EditorAgentNamespace = class extends CrudEditorNamespace {
       rawConfig: storedAgent,
       defaultOptions,
       requestContextSchema,
-      workspace,
+      workspace: workspace2,
       browser,
       ...skillsFormat && { skillsFormat }
     });
@@ -2163,8 +2178,8 @@ var EditorWorkspaceNamespace = class extends CrudEditorNamespace {
     }
     if (snapshot.mounts) {
       const mounts = {};
-      for (const [path, fsConfig] of Object.entries(snapshot.mounts)) {
-        mounts[path] = await this.resolveFilesystem(fsConfig);
+      for (const [path2, fsConfig] of Object.entries(snapshot.mounts)) {
+        mounts[path2] = await this.resolveFilesystem(fsConfig);
       }
       config.mounts = mounts;
     }
@@ -2217,11 +2232,11 @@ var EditorWorkspaceNamespace = class extends CrudEditorNamespace {
    * The reverse of hydrateSnapshotToWorkspace — extracts provider IDs and config
    * from live filesystem/sandbox instances so the workspace can be persisted to the DB.
    */
-  async snapshotFromWorkspace(workspace) {
+  async snapshotFromWorkspace(workspace2) {
     const snapshot = {
-      name: workspace.name
+      name: workspace2.name
     };
-    const fs = workspace.filesystem;
+    const fs = workspace2.filesystem;
     if (fs) {
       if (fs instanceof import_workspace2.CompositeFilesystem) {
         const mounts = {};
@@ -2233,7 +2248,7 @@ var EditorWorkspaceNamespace = class extends CrudEditorNamespace {
         snapshot.filesystem = await this.serializeFilesystem(fs);
       }
     }
-    const sandbox = workspace.sandbox;
+    const sandbox = workspace2.sandbox;
     if (sandbox) {
       const info = typeof sandbox.getInfo === "function" ? await sandbox.getInfo() : void 0;
       snapshot.sandbox = {
@@ -2241,7 +2256,7 @@ var EditorWorkspaceNamespace = class extends CrudEditorNamespace {
         config: info?.metadata ?? {}
       };
     }
-    const tools = workspace.getToolsConfig();
+    const tools = workspace2.getToolsConfig();
     if (tools) {
       const storageTools = {};
       if (typeof tools.enabled === "boolean") storageTools.enabled = tools.enabled;