@mindstudio-ai/remy 0.1.276 → 0.1.278

package/dist/prompt/skills/taskAgents.md

@@ -1,6 +1,6 @@
 ---
 name: Task Agents
-what: A full autonomous agent loop callable from any method. Give it a prompt, a set of tools, and an example of the output shape; the platform runs the model until it produces that shape — searching, scraping, generating images, retrying approaches that failed, and calling your app's own methods to read and write data as it goes. Tools can be any of the 1000+ SDK actions and your own methods in any combination, which is what makes it part of the app rather than a detached research bot. This is the difference between a feature that saves what the user typed and one that researches, enriches, and creates on their behalf, and it is one of the most powerful things the platform can do. Consider it whenever a feature would be dramatically more compelling if the app could do real work autonomously.
+what: A full autonomous agent loop callable from any method. Give it a prompt, a set of tools, and a JSON Schema for the output shape; the platform runs the model until it produces validated output matching that schema — searching, scraping, generating images, retrying approaches that failed, and calling your app's own methods to read and write data as it goes. Tools can be any of the 1000+ SDK actions and your own methods in any combination, which is what makes it part of the app rather than a detached research bot. This is the difference between a feature that saves what the user typed and one that researches, enriches, and creates on their behalf, and it is one of the most powerful things the platform can do. Consider it whenever a feature would be dramatically more compelling if the app could do real work autonomously.
 when: Before writing any `mindstudio.runTask()` call — background enrichment, research-and-generate, anything where the model decides its own next step.
 ---
 
@@ -8,7 +8,7 @@ when: Before writing any `mindstudio.runTask()` call — background enrichment,
 
 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 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 a JSON Schema for the structured output you want (`outputSchema`). The platform runs the loop (calling the model, executing tool calls, feeding results back) until the model produces JSON conforming to your schema — validated every turn, with automatic repair when it doesn't. `result.output` is typed by inference from the schema: no generic argument, no manual validation. 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.
 
@@ -38,12 +38,7 @@ Run tasks in the background — depending on complexity they can take time to co
 ```typescript
 import { mindstudio } from '@mindstudio-ai/agent';
 
-const result = await mindstudio.runTask<{
-  name: string;
-  url: string;
-  address: string;
-  photoUrl: string;
-}>({
+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. Save the result before
@@ -61,30 +56,46 @@ const result = await mindstudio.runTask<{
     },
   ],
 
-  structuredOutputExample: {
-    name: 'Tartine Bakery',
-    url: 'https://tartinebakery.com',
-    address: '600 Guerrero St, San Francisco, CA 94110',
-    photoUrl: 'https://cdn.mindstudio.ai/...',
+  outputSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      url: { type: ['string', 'null'] },   // nullable = a type array, never `nullable: true`
+      address: { type: 'string' },
+      photoUrl: { type: 'string' },
+    },
+    required: ['name', 'url', 'address', 'photoUrl'],
   },
 
   model: 'claude-5-sonnet',   // ask askMindStudioSdk — don't copy this one blind
   maxTurns: 15,
 });
 
-// Always validate before using output
-if (!result.parsedSuccessfully) {
-  console.error('Task failed to produce structured output:', result.outputRaw);
-  throw new Error('Task agent failed');
-}
-
-console.log(result.output.name);    // 'Tartine Bakery'
-console.log(result.output.photoUrl); // URL to the generated illustration
+// result.output is typed from the schema — no generic argument, no validation.
+console.log(result.output.name);    // string
+console.log(result.output.url);     // string | null
 ```
 
-## Always Validate Output
+## Output Contracts: `outputSchema` vs `structuredOutputExample`
 
-`runTask()` can return successfully with garbage output — fields null, data echoed back, or raw text instead of JSON. The result includes `parsedSuccessfully` to make this explicit. Always check it before using the output:
+**With `outputSchema` (use this):** validation is built in. The schema is plain JSON Schema in the tool-definition dialect — `type`, `properties`, `required`, `enum`, `items`, nullability via type arrays like `['string', 'null']`. No `oneOf`/`anyOf`/`$ref`, no `nullable: true` — out-of-dialect schemas are rejected up front with `task_output_schema_unsupported`. Output is validated every turn and repaired automatically; `runTask()` either returns schema-conforming typed output or throws a `MindStudioError` with `code === 'task_output_schema_mismatch'` (raw text and validation errors in `err.details`). It never resolves with garbage, so use `result.output` directly and validate only domain invariants the schema can't express. For dynamic value sets, build the schema at runtime and put the set in an `enum` — the value is checked at runtime even though the type widens to `string`:
+
+```typescript
+import type { JsonObjectSchema } from '@mindstudio-ai/agent';
+
+const services = [...new Set(rows.map((r) => r.service))];
+const result = await mindstudio.runTask({
+  // ...
+  outputSchema: {
+    type: 'object',
+    properties: { service: { enum: services } },
+    required: ['service'],
+  } as const satisfies JsonObjectSchema, // needed when the schema lives in a variable
+  // ...
+});
+```
+
+**With `structuredOutputExample` (legacy):** the output shape is suggested by example only, `output` is typed by your generic argument, and `runTask()` can return successfully with garbage — fields null, data echoed back, or raw text instead of JSON. Always check `parsedSuccessfully` before using the output:
 
 ```typescript
 const result = await mindstudio.runTask<MyType>({ ... });
@@ -151,7 +162,8 @@ When a task agent produces user-facing text, the prompt must state the voice and
 | `prompt` | Yes | — | System prompt defining the agent's behavior |
 | `input` | Yes | — | Structured input (passed as user message) |
 | `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'` |
+| `outputSchema` | One of these two | — | Plain JSON Schema for the output (`type`/`properties`/`required`/`enum`/`items`; nullable via type arrays, never `nullable: true`; no `oneOf`/`$ref`). Validated every turn with automatic repair; `result.output` typed from the schema. Use this |
+| `structuredOutputExample` | One of these two | — | Legacy: object or JSON string showing expected output shape, unvalidated. Use realistic example values, not placeholders like `'string'`, and always check `parsedSuccessfully` |
 | `model` | Yes | — | Model ID (must support tool use). Ask `askMindStudioSdk` for the right one — MindStudio's ids don't match vendor ids, so a plausible-looking guess is usually wrong |
 | `maxTurns` | No | 20 | Max loop iterations (capped at 100) |
 | `onEvent` | No | — | SSE event callback for real-time streaming |
@@ -160,9 +172,9 @@ When a task agent produces user-facing text, the prompt must state the voice and
 
 ```typescript
 interface RunTaskResult<T> {
-  output: T;                // Parsed structured output matching your example
+  output: T;                // With outputSchema: validated, typed from the schema. With an example: whatever parsed
   outputRaw: string;        // Raw model text before JSON parse
-  parsedSuccessfully: boolean; // Whether output was valid JSON
+  parsedSuccessfully: boolean; // Example mode only — always true in schema mode (a failure throws instead)
   turns: number;            // Number of loop iterations used
   usage: {
     inputTokens: number;
@@ -201,22 +213,23 @@ Without `onEvent`, the SDK uses async polling (returns silently when complete).
 ## Error Handling
 
 - Model produces non-JSON output: retried automatically if turns remain
+- With `outputSchema`, JSON that doesn't conform: the validation errors go back to the model as a repair turn (up to 3), then the call throws
 - 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`
+- Exhausted with nonconforming output: schema mode **throws** `task_output_schema_mismatch` (raw text and errors in `err.details`); example mode resolves with `parsedSuccessfully: false` and raw text in `outputRaw`
 
 ```typescript
 try {
-  const result = await mindstudio.runTask({ ... });
-  if (!result.parsedSuccessfully) {
-    // Task completed but output wasn't valid JSON
-    console.error('Raw output:', result.outputRaw);
-    console.error('Tool calls:', result.toolCalls);
-  }
+  const result = await mindstudio.runTask({ ...with outputSchema... });
+  // Conforming, typed output — use it directly.
+  await Table.update(id, result.output);
 } catch (err) {
   if (err instanceof MindStudioError) {
-    // err.code: 'task_execution_error' | 'poll_token_expired' | 'stream_error'
+    // err.code: 'task_output_schema_mismatch' (couldn't produce conforming output;
+    //   err.details has outputRaw + validation errors + toolCalls)
+    // | 'task_output_schema_unsupported' (schema uses out-of-dialect keywords)
+    // | 'task_execution_error' | 'poll_token_expired' | 'stream_error'
   }
 }
 ```