@mindstudio-ai/remy 0.1.249 → 0.1.250

package/dist/prompt/compiled/agent-interfaces.md

@@ -30,6 +30,8 @@ The system prompt says *who* the agent is. The tool descriptions say *what it ca
 - **Parameter guidance** beyond the schema — what makes a good value, when to include optional fields, what to skip
 - **Return value** and how to present results to the user
 
+Note: Task agents (`runTask`) can also expose app methods as tools, but their descriptions are written **inline at the call site**, not compiled here. The two are deliberately different: an agent interface is one long-lived persona whose tools are a stable capability surface, so each method earns one carefully-written description in `tools/*.md`. A task agent is narrow and single-purpose, and the same method gets framed differently depending on the job — so its description belongs with the task, not the method.
+
 ### Not every method should be a tool
 
 Expose methods that serve the conversational flow. Internal helpers, admin-only methods, and batch operations often don't belong in the agent's toolset. A focused set of well-described tools performs better than many underdocumented ones.

package/dist/prompt/compiled/sdk-actions.md

@@ -154,4 +154,4 @@ Consider the ways in which AI can be incorporated into backend methods to solve
 
 ### Task Agents
 
-For multi-step tasks where the model needs to autonomously compose actions (research + scrape + generate, enrichment pipelines, content creation), use `runTask()` instead of chaining actions manually. It runs an agent loop with the SDK actions as tools and returns structured JSON. See the task agents reference for full details.
+For multi-step tasks where the model needs to autonomously compose actions (research + scrape + generate, enrichment pipelines, content creation), use `runTask()` instead of chaining actions manually. It runs an agent loop and returns structured JSON. Its tools can include SDK actions as well as your app's own methods, so the agent can read your data to decide what to do next and write results back itself. See the task agents reference for full details.

package/dist/prompt/compiled/task-agents.md

@@ -2,7 +2,9 @@
 
 A user types the name of a restaurant into your app, or uploads a photo of a storefront. The API call returns early, and in the background, a task agent searches Google, finds the official website, scrapes the address, gets the official social media accounts, and generates a stylized watercolor postcard of the exterior from images it found online. The user gets back a rich, illustrated card with the canonical name, website, address, and a custom image. A few tool calls (some in parallel), fully autonomous.
 
-`runTask()` makes this possible. It runs a multi-step, tool-use agent loop: give it a prompt, a set of SDK actions as tools, and an example of the structured output you want. The platform runs the loop (calling the model, executing tool calls, feeding results back) until the model produces JSON matching your output example. The model decides what to do next based on intermediate results — retrying searches with different terms, working around failed tools, batching independent calls in parallel.
+`runTask()` makes this possible. It runs a multi-step, tool-use agent loop: give it a prompt, a set of tools, and an example of the structured output you want. The platform runs the loop (calling the model, executing tool calls, feeding results back) until the model produces JSON matching your output example. The model decides what to do next based on intermediate results — retrying searches with different terms, working around failed tools, batching independent calls in parallel.
+
+Tools are **SDK actions** (`searchGoogle`, `generateImage`, …) and **your own app's methods** (`{ appMethod: 'saveVendor' }`), in any combination. That second half is what makes a task agent part of your app rather than a detached research bot: it can read your tables to decide what to do next, and write results back itself instead of handing them to you to persist.
 
 This is one of the most powerful pieces of the MindStudio SDK and can make turn apps from amazing into truly magical. Use `askMindStudioSdk` to help construct the perfect agent for a task.
 
@@ -16,10 +18,12 @@ Run tasks in the background — depending on complexity they can take time to co
 - **Content creation pipelines:** "Write SEO copy for this product in 3 languages, generate a hero image, extract keywords" — the model calls text generation, image generation, and analysis actions as needed.
 - **Data processing with judgment:** "Given this restaurant name, find the canonical name, website, address, and create a stylized illustration" — the model searches, verifies, generates, and returns clean structured output.
 - **Any multi-step task with branching logic:** If the model might need to retry a search with different terms, try a different approach when one fails, or make decisions based on intermediate results.
+- **Work that depends on app state:** "Check which vendors are missing contact details, research those, and update them" — the agent reads your data with one method, decides what needs doing, and writes back with another.
 
 ## When NOT to Use
 
-- **Simple linear pipelines (2-3 steps, no branching):** Just call the SDK actions directly in sequence. `runTask()` adds overhead from the model reasoning about what to do next.
+- **Simple linear pipelines (2-3 steps, no branching):** Just call the SDK actions or your methods directly in sequence. `runTask()` adds overhead from the model reasoning about what to do next.
+- **Anything with a deterministic answer:** If you know exactly which methods to call and in what order, call them. Handing a fixed sequence to a model buys nothing and can go wrong.
 - **Chat/conversation:** Use an Agent interface instead. Task agents are single-shot, no persistent conversation history.
 - **One-off text generation:** Just use `generateText()` directly.
 
@@ -36,7 +40,8 @@ const result = await mindstudio.runTask<{
 }>({
   prompt: `You are a restaurant research assistant. Given a restaurant name,
     find its canonical name, website URL, full address, and create a stylized
-    watercolor illustration of the restaurant exterior.`,
+    watercolor illustration of the restaurant exterior. Save the result before
+    you finish.`,
 
   input: { restaurantName: 'Tartine Bakery SF' },
 
@@ -44,6 +49,10 @@ const result = await mindstudio.runTask<{
     'searchGoogle',
     'fetchUrl',
     { method: 'generateImage', defaults: { imageModelOverride: { model: 'seedream-4.5' } } },
+    {
+      appMethod: 'saveRestaurant',
+      description: 'Persist a researched restaurant. Call once, at the end, when you have the canonical name, address and illustration.',
+    },
   ],
 
   structuredOutputExample: {
@@ -85,24 +94,45 @@ await Table.update(id, result.output);
 
 ## Tool Configuration
 
-Tools are SDK action names. The model gets the full input schema for each tool so it knows what parameters to pass. Only include tools the task actually needs — the model may use extra tools unnecessarily.
+The model gets the full input schema for each tool so it knows what parameters to pass. Only include tools the task actually needs — the model may use extra tools unnecessarily.
 
 Use tool defaults for model/config choices. Use the prompt for task-level instructions.
 
 ```typescript
 tools: [
-  // Simple — just the action name
+  // SDK action — just the action name
   'searchGoogle',
   'fetchUrl',
   'scrapeUrl',
 
-  // With defaults — override specific input fields while letting the model control the rest
+  // SDK action with defaults — override specific input fields while letting the model control the rest
   { method: 'generateImage', defaults: { imageModelOverride: { model: 'seedream-4.5' } } },
   { method: 'analyzeImage', defaults: { visionModelOverride: { model: 'gemini-3-flash' } } },
+
+  // One of your app's own methods — note `appMethod`, not `method`
+  { appMethod: 'listVendorsMissingContacts', description: 'Vendors with no email on file. Call this first to decide what needs researching.' },
+  { appMethod: 'updateVendor', description: 'Write researched contact details back. One call per vendor.' },
 ]
 ```
 
-When the model calls a tool, the platform deep-merges the model's arguments with the developer's defaults. The model decides what to do (prompt, query, parameters), the developer controls which model/config to use. If the model needs to search and generate an image and those are independent, it will call both tools in the same turn (parallel execution server-side).
+When the model calls a tool, the platform deep-merges your defaults over the model's arguments. **Defaults win** — any field set in `defaults` overrides whatever the model passed for it, including nested fields, so the model can't talk its way out of a pinned model or config. The model decides what to do (prompt, query, parameters), you control which model/config it uses. If the model needs to search and generate an image and those are independent, it will call both tools in the same turn (parallel execution server-side).
+
+### App methods as tools
+
+`{ appMethod: 'methodId' }` exposes one of your app's methods. Use `appMethod`, not `method` — `method` means an SDK action, and the two are different namespaces.
+
+**Write the description.** Unlike agent interfaces, where each method gets one compiled description, a task agent's tool descriptions are written inline, per task. This is deliberate: the same method serves different purposes in different tasks. `getVendor` called by an enrichment task and `getVendor` called by a reporting task want different framing — when to call it, what to do with the result, whether to call it once or per item. The method's own description is only a fallback.
+
+Keep them short and task-specific. Say when to reach for it and when not to, since the model is choosing from a small flat list.
+
+**Authorization is automatic.** The method runs as the user who invoked the method that started the task, with their roles. A method gated on a role they lack is rejected at runtime, exactly as if they'd called it themselves. The agent cannot reach anything the user couldn't — but that also means a task started from a background context (cron, webhook) runs with the `system` role, so gate accordingly.
+
+**Constraints worth knowing:**
+
+- A method invoked as a task tool **cannot start another task agent**. Decompose differently if you're reaching for that.
+- A method id that collides with an SDK action name is rejected — the model sees one flat tool namespace. Rename the method.
+- Method calls run in parallel with everything else in the turn, so don't expose two methods that would conflict if called simultaneously.
+- Cost from inside a method (its own model calls) doesn't appear in the task's `usage.totalBillingCost`. It's billed and attributed to that method, just not rolled into the task total.
 
 ## Voice & Tone in Prompts
 
@@ -114,10 +144,10 @@ When a task agent produces user-facing text, the prompt must include a note voic
 |-------|----------|---------|-------------|
 | `prompt` | Yes | — | System prompt defining the agent's behavior |
 | `input` | Yes | — | Structured input (passed as user message) |
-| `tools` | Yes | — | SDK action names with optional defaults |
+| `tools` | Yes | — | SDK action names and/or `{ appMethod, description }` entries, each with optional `defaults` |
 | `structuredOutputExample` | Yes | — | Object or JSON string showing expected output shape. Use realistic example values, not placeholders like `'string'` |
 | `model` | Yes | — | Model ID (must support tool use) |
-| `maxTurns` | No | 10 | Max loop iterations (capped at 25) |
+| `maxTurns` | No | 20 | Max loop iterations (capped at 100) |
 | `onEvent` | No | — | SSE event callback for real-time streaming |
 
 ## Models
@@ -170,6 +200,7 @@ Without `onEvent`, the SDK uses async polling (returns silently when complete).
 
 - Model produces non-JSON output: retried automatically if turns remain
 - Tool execution fails: error fed back to model, it can retry or work around it
+- An app method that throws: its actual error message goes back to the model, so a `MindStudioError` you throw deliberately ("vendor not found", "missing required field") is usable guidance the agent can act on. Worth throwing informative errors in methods you expose as tools
 - Max turns exceeded: one final forced output attempt with tools disabled
 - If output still can't be parsed: `parsedSuccessfully` will be `false`, raw text available in `outputRaw`
 

package/dist/prompt/static/coding.md

@@ -28,7 +28,7 @@ Process logs are available at .logs/ in NDJSON format (one JSON object per line)
 ### MindStudio SDK
 For any work involving AI models, external actions (web scraping, email, SMS), or third-party API/OAuth connections, prefer the `@mindstudio-ai/agent` SDK. It removes the need to research API methods, configure keys and tokens, or require the user to set up developer accounts.
 
-For multi-step tasks with branching logic (research, enrichment, content pipelines), use `runTask()` instead of manually chaining SDK actions. It runs an autonomous agent loop that composes actions, retries on failure, and returns structured JSON. See the task agents reference for details.
+For multi-step tasks with branching logic (research, enrichment, content pipelines), use `runTask()` instead of manually chaining SDK actions. It runs an autonomous agent loop that composes tools, retries on failure, and returns structured JSON. Tools are SDK actions and your own app methods — the agent can read app state to decide what to do next and persist results itself. See the task agents reference for details.
 
 For methods that take more than a few seconds, use `stream()` from `@mindstudio-ai/agent` to push real-time progress to the frontend. Pipe `onLog` from SDK actions through `stream()` so users see what's happening. The frontend calls the method with `stream: true` and gets updates via `onToken`. See the methods reference for the full pattern.
 

package/dist/prompt/static/intake.md

@@ -10,7 +10,7 @@ Remy apps are full-stack TypeScript projects. You have a lot to work with:
 
 - **Backend (Methods):** TypeScript in a sandboxed runtime. Any npm package. Managed SQLite database with typed schemas and automatic migrations. Built-in app-managed auth with email/SMS verification, cookie sessions, and role enforcement. None of these are required — use what the app needs.
 - **Frontend (Web Interface):** Starts as Vite + React, but any TypeScript project with a build command works. Any framework, any library, or no framework at all.
-- **AI & integrations:** The `@mindstudio-ai/agent` SDK gives access to 200+ AI models (OpenAI, Anthropic, Google, Meta, Mistral, and more) and 1000+ integrations (email, SMS, Slack, HubSpot, Google Workspace, web scraping, image/video generation, media processing) with zero configuration — credentials are handled automatically. No API keys needed. Beyond individual actions, `runTask()` lets you spin up lightweight autonomous task agents that chain these actions together with judgment — e.g., a user types a restaurant name and the backend autonomously researches it in the background, finds the address, and generates a custom illustration. Think about where this kind of enrichment would make a feature go from functional to magical.
+- **AI & integrations:** The `@mindstudio-ai/agent` SDK gives access to 200+ AI models (OpenAI, Anthropic, Google, Meta, Mistral, and more) and 1000+ integrations (email, SMS, Slack, HubSpot, Google Workspace, web scraping, image/video generation, media processing) with zero configuration — credentials are handled automatically. No API keys needed. Beyond individual actions, `runTask()` lets you spin up lightweight autonomous task agents that chain these actions together with judgment — e.g., a user types a restaurant name and the backend autonomously researches it in the background, finds the address, generates a custom illustration, and saves the finished record itself. These agents can call the app's own methods too, so they can read existing data to decide what needs doing and write results straight back. Think about where this kind of enrichment would make a feature go from functional to magical.
 - **Interfaces:** Web UI, REST API, cron jobs, webhooks, MCP tool servers, email processors, conversational AI agents — all backed by the same methods. An app can use any combination.
 
 This is a capable, stable platform. Build with confidence; you're building production-grade apps, not fragile prototypes.

package/dist/subagents/codeSanityCheck/prompt.md

@@ -65,7 +65,15 @@ When a plan includes multiple screens/API calls, always note this item for the d
 
 - **Auth state read once instead of subscribed.** If the plan reads `auth.currentUser` or `auth.getCurrentUser()` in a `useState` initializer, at component top-level, or in a one-time check, the UI won't update after login/logout. The correct pattern is `auth.onAuthStateChanged(cb)` which fires immediately and on every auth transition. Flag if you see auth state read without a subscription.
 
-- **Manual multi-step MindStudio SDK action chains that should be `runTask()`.** If a method chains AI-driven SDK actions with branching logic (search, then scrape based on results, then generate based on what was scraped), that's a `runTask()` use case. `runTask()` runs an agent loop that autonomously calls SDK actions as tools and returns structured JSON. The developer writes a prompt and an output example instead of imperative code. Flag when you see methods with complex sequential/branching SDK action chains — especially research, enrichment, or content generation pipelines. Similarly, flag opportunities where the developer might not have realized they could get better and richer data via runTask - it's a really powerful lever for working with data (e.g., user provides some fragment and agent task goes off and enriches it) that the developer might not have remembered when planning their work.
+- **Manual multi-step chains that should be `runTask()`.** If a method chains AI-driven work with branching logic (search, then scrape based on results, then generate based on what was scraped), that's a `runTask()` use case. `runTask()` runs an agent loop that autonomously calls tools and returns structured JSON. The developer writes a prompt and an output example instead of imperative code. Flag when you see methods with complex sequential/branching chains — especially research, enrichment, or content generation pipelines. Similarly, flag opportunities where the developer might not have realized they could get better and richer data via runTask - it's a really powerful lever for working with data (e.g., user provides some fragment and agent task goes off and enriches it) that the developer might not have remembered when planning their work.
+
+  Tools are SDK actions **and the app's own methods** (`{ appMethod: 'saveVendor', description: '...' }`), which widens this considerably. The pattern most worth looking for: work that needs to *read* app state to decide what to do next (fetch rows, loop, research each, update each) hand-rolled as a loop, when the agent could take a read method and a write method and exercise the judgment itself. App methods run as the invoking user with their roles, so authorization is unchanged.
+
+  Two things NOT to flag. A deterministic sequence that happens to touch several methods — if the order is known up front and no judgment is involved, imperative code is correct and cheaper. And the fire-and-forget background pattern, where a method kicks off `runTask()` and writes the result back in `.then()`: that write-back is doing status management around `parsedSuccessfully`, which the agent can't do for itself because it doesn't know when its own output is garbage. That one is the recommended pattern, not a smell.
+
+- **Task agent tool descriptions missing or recycled.** When a plan exposes app methods to `runTask()`, each entry should carry an inline `description` written for *that* task — when to call it, when not to, what to do with the result. Falling back to the method's own description is allowed but usually too generic, and the description is the main thing determining whether the agent uses the tool correctly. Flag entries with no description, or the same description pasted across different tasks.
+
+- **A method exposed as a task tool that itself calls `runTask()`.** Task agents can't nest — the inner call is rejected at runtime. Flag it and suggest flattening the decomposition.
 
 - **MindStudio SDK `runTask()` output used without validation.** `runTask()` can return successfully with garbage output (null fields, echoed input, raw text). The result includes `parsedSuccessfully` — if the plan uses `result.output` without checking `result.parsedSuccessfully` first, flag it. This is the #1 footgun with task agents.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.249",
+  "version": "0.1.250",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",