@mindstudio-ai/agent 0.1.99 → 0.1.101

package/dist/index.js

@@ -3134,28 +3134,28 @@ var stepMetadata = {
   "scrapeUrl": {
     stepType: "scrapeUrl",
     description: "Extract text, HTML, or structured content from one or more web pages.",
-    usageNotes: '- Accepts a single URL or multiple URLs (as a JSON array, comma-separated, or newline-separated).\n- Output format controls the result shape: "text" returns markdown, "html" returns raw HTML, "json" returns structured scraper data.\n- Can optionally capture a screenshot of each page.',
-    inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "URL(s) to scrape. Accepts a single URL, JSON array, or comma/newline-separated list" }, "service": { "enum": ["default", "firecrawl"], "type": "string", "description": "Scraping service to use" }, "autoEnhance": { "type": "boolean", "description": "Whether to enable enhanced scraping for social media URLs (e.g. Twitter, LinkedIn)" }, "outputFormat": { "enum": ["text", "json", "html"], "type": "string", "description": "Output format: text returns markdown, html returns raw HTML, json returns structured scraper data" }, "pageOptions": { "type": "object", "properties": { "onlyMainContent": { "type": "boolean", "description": "Whether to extract only the main content of the page, excluding navigation, footers, etc." }, "screenshot": { "type": "boolean", "description": "Whether to capture a screenshot of the page" }, "waitFor": { "type": "number", "description": "Milliseconds to wait before scraping (0 for immediate)" }, "replaceAllPathsWithAbsolutePaths": { "type": "boolean", "description": "Whether to convert relative URLs to absolute URLs in the result" }, "headers": { "type": "object", "properties": {}, "required": [], "description": "Custom HTTP request headers as key-value pairs" }, "removeTags": { "type": "array", "items": { "type": "string" }, "description": "HTML tags to remove from the scraped result" }, "mobile": { "type": "boolean", "description": "Whether to scrape using a mobile user-agent" } }, "required": ["onlyMainContent", "screenshot", "waitFor", "replaceAllPathsWithAbsolutePaths", "headers", "removeTags", "mobile"], "description": "Page-level scraping options (content filtering, screenshots, headers, etc.)" } }, "required": ["url"] },
-    outputSchema: { "type": "object", "properties": { "content": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"] }, { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"] } }] }, "screenshot": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["content"] }
+    usageNotes: '- Accepts a single URL or multiple URLs (as a JSON array, comma-separated, or newline-separated).\n- Output format controls the result shape: "text" returns markdown, "html" returns raw HTML, "json" returns structured scraper data, "summary" returns a model-written summary and requires the "firecrawl" service.\n- Can optionally capture a screenshot of each page.\n- Handles bot protection automatically; no proxy or rendering configuration is needed.',
+    inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "URL(s) to scrape. Accepts a single URL, JSON array, or comma/newline-separated list" }, "service": { "enum": ["default", "firecrawl"], "type": "string", "description": "Scraping service to use" }, "autoEnhance": { "type": "boolean", "description": "No longer selects a provider \u2014 the default service's anti-bot engine decides per request how hard to work. Retained because existing workflows set it and the builder still renders it." }, "outputFormat": { "enum": ["text", "json", "html", "summary"], "type": "string", "description": "Output format: text returns markdown, html returns raw HTML, json returns structured scraper data, summary returns a model-written summary (Firecrawl only)" }, "pageOptions": { "type": "object", "properties": { "onlyMainContent": { "type": "boolean", "description": "Whether to extract only the main content of the page, excluding navigation, footers, etc." }, "screenshot": { "type": "boolean", "description": "Whether to capture a screenshot of the page" }, "waitFor": { "type": "number", "description": "Milliseconds to wait before scraping (0 for immediate)" }, "replaceAllPathsWithAbsolutePaths": { "type": "boolean", "description": "Whether to convert relative URLs to absolute URLs in the result" }, "headers": { "type": "object", "properties": {}, "required": [], "description": "Custom HTTP request headers as key-value pairs" }, "removeTags": { "type": "array", "items": { "type": "string" }, "description": "HTML tags to remove from the scraped result" }, "mobile": { "type": "boolean", "description": "Whether to scrape using a mobile user-agent" } }, "required": ["onlyMainContent", "screenshot", "waitFor", "replaceAllPathsWithAbsolutePaths", "headers", "removeTags", "mobile"], "description": "Page-level scraping options (content filtering, screenshots, headers, etc.)" } }, "required": ["url"] },
+    outputSchema: { "type": "object", "properties": { "content": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." }, "costUnits": { "type": "number", "description": "What the provider actually charged, when it tells us. Scrapfly returns an exact per-request credit total that varies with how hard the target fought back (6 for an unprotected page, 80 for Glassdoor), so billing a flat rate would either overcharge the easy case or eat the hard one. Providers that report nothing leave this undefined and fall back to the route's estimate.\n\nIncludes every attempt made on the caller's behalf, not just the last one." } }, "required": ["text", "html"] }, { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." }, "costUnits": { "type": "number", "description": "What the provider actually charged, when it tells us. Scrapfly returns an exact per-request credit total that varies with how hard the target fought back (6 for an unprotected page, 80 for Glassdoor), so billing a flat rate would either overcharge the easy case or eat the hard one. Providers that report nothing leave this undefined and fall back to the route's estimate.\n\nIncludes every attempt made on the caller's behalf, not just the last one." } }, "required": ["text", "html"] } }] }, "screenshot": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["content"] }
   },
   "scrapeXPost": {
     stepType: "scrapeXPost",
     description: "Scrape data from a single X (Twitter) post by URL.",
     usageNotes: "- Returns structured post data (text, html, optional json/screenshot/metadata).\n- Optionally saves the text content to a variable.",
     inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "Full URL to the X post (e.g. https://x.com/elonmusk/status/1655608985058267139)" } }, "required": ["url"] },
-    outputSchema: { "type": "object", "properties": { "post": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"], "description": "Scraped post data including text, HTML, and optional structured JSON" } }, "required": ["post"] }
+    outputSchema: { "type": "object", "properties": { "post": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." }, "costUnits": { "type": "number", "description": "What the provider actually charged, when it tells us. Scrapfly returns an exact per-request credit total that varies with how hard the target fought back (6 for an unprotected page, 80 for Glassdoor), so billing a flat rate would either overcharge the easy case or eat the hard one. Providers that report nothing leave this undefined and fall back to the route's estimate.\n\nIncludes every attempt made on the caller's behalf, not just the last one." } }, "required": ["text", "html"], "description": "Scraped post data including text, HTML, and optional structured JSON" } }, "required": ["post"] }
   },
   "scrapeXProfile": {
     stepType: "scrapeXProfile",
     description: "Scrape public profile data from an X (Twitter) account by URL.",
     usageNotes: "- Returns structured profile data.\n- Optionally saves the result to a variable.",
     inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "Full URL or username for the X profile (e.g. https://x.com/elonmusk)" } }, "required": ["url"] },
-    outputSchema: { "type": "object", "properties": { "profile": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"], "description": "Scraped profile data including text, HTML, and optional structured JSON" } }, "required": ["profile"] }
+    outputSchema: { "type": "object", "properties": { "profile": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." }, "costUnits": { "type": "number", "description": "What the provider actually charged, when it tells us. Scrapfly returns an exact per-request credit total that varies with how hard the target fought back (6 for an unprotected page, 80 for Glassdoor), so billing a flat rate would either overcharge the easy case or eat the hard one. Providers that report nothing leave this undefined and fall back to the route's estimate.\n\nIncludes every attempt made on the caller's behalf, not just the last one." } }, "required": ["text", "html"], "description": "Scraped profile data including text, HTML, and optional structured JSON" } }, "required": ["profile"] }
   },
   "screenshotUrl": {
     stepType: "screenshotUrl",
     description: "Capture a screenshot of a web page as a PNG image.",
-    usageNotes: "- Takes a viewport or full-page screenshot of the given URL.\n- Returns a CDN-hosted PNG image URL.\n- Viewport mode captures only the visible area; fullPage captures the entire scrollable page.\n- You can customize viewport width/height, add a delay, or wait for a CSS selector before capturing.",
+    usageNotes: "- Takes a viewport or full-page screenshot of the given URL.\n- Returns a CDN-hosted PNG image URL.\n- Viewport mode captures only the visible area; fullPage captures the entire scrollable page, scrolling it first so lazy-loaded content is included.\n- Works on sites behind bot protection (Cloudflare and similar).\n- Cookie-consent banners and similar overlays are suppressed automatically.\n- `width` and `height` are the exact output pixel dimensions.\n- You can add a delay or wait for a CSS selector before capturing. A selector that never appears fails the step rather than capturing early.",
     inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "URL to screenshot" }, "mode": { "enum": ["viewport", "fullPage"], "type": "string", "description": "Screenshot mode: viewport captures visible area, fullPage captures entire page" }, "width": { "type": "number", "description": "Viewport width in pixels (default: 1280)" }, "height": { "type": "number", "description": "Viewport height in pixels (default: 800, ignored for fullPage mode)" }, "delay": { "type": "number", "description": "Milliseconds to wait before capturing (default: 0)" }, "waitFor": { "type": "string", "description": "CSS selector to wait for before capturing" } }, "required": ["url"] },
     outputSchema: { "type": "object", "properties": { "screenshotUrl": { "type": "string" } }, "required": ["screenshotUrl"] }
   },
@@ -3525,6 +3525,178 @@ var stepMetadata = {
   }
 };
 
+// src/task/schema.ts
+function describe(value) {
+  if (value === void 0) return "undefined";
+  const json = JSON.stringify(value);
+  if (json === void 0) return String(value);
+  return json.length > 60 ? `${json.slice(0, 57)}...` : json;
+}
+function matchesTypeName(value, name) {
+  switch (name) {
+    case "null":
+      return value === null;
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+}
+function validateAgainstSchema(value, schema) {
+  const errors = [];
+  walk(value, schema, "$", errors);
+  return errors;
+}
+function walk(value, schema, path, errors) {
+  if (schema.const !== void 0) {
+    if (value !== schema.const) {
+      errors.push({
+        path,
+        message: `expected the constant ${describe(schema.const)}, got ${describe(value)}`
+      });
+    }
+    return;
+  }
+  if (schema.enum !== void 0) {
+    if (!schema.enum.includes(value)) {
+      errors.push({
+        path,
+        message: `expected one of ${schema.enum.map(describe).join(" | ")}, got ${describe(value)}`
+      });
+    }
+    return;
+  }
+  if (schema.type !== void 0) {
+    const names = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!names.some((name) => matchesTypeName(value, name))) {
+      errors.push({
+        path,
+        message: `expected type ${names.join(" | ")}, got ${describe(value)}`
+      });
+      return;
+    }
+  }
+  if (matchesTypeName(value, "object")) {
+    const record = value;
+    if (schema.required) {
+      for (const key of schema.required) {
+        if (!(key in record) || record[key] === void 0) {
+          errors.push({
+            path,
+            message: `missing required property "${key}"`
+          });
+        }
+      }
+    }
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in record && record[key] !== void 0) {
+          walk(record[key], propSchema, `${path}.${key}`, errors);
+        }
+      }
+      if (schema.additionalProperties === false) {
+        for (const key of Object.keys(record)) {
+          if (!(key in schema.properties)) {
+            errors.push({
+              path,
+              message: `unexpected property "${key}" (additionalProperties is false)`
+            });
+          }
+        }
+      }
+    }
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, index) => {
+      walk(item, schema.items, `${path}[${index}]`, errors);
+    });
+  }
+}
+function formatValidationErrors(errors) {
+  return errors.map((e) => `- at ${e.path}: ${e.message}`).join("\n");
+}
+var SUPPORTED_KEYWORDS = /* @__PURE__ */ new Set([
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "enum",
+  "const",
+  // Harmless annotations — ignored by the validator, allowed to pass through.
+  "description",
+  "title",
+  "examples",
+  "default"
+]);
+function assertSupportedSchema(schema) {
+  assertSupportedNode(schema, "$");
+}
+function assertSupportedNode(schema, path) {
+  for (const key of Object.keys(schema)) {
+    if (SUPPORTED_KEYWORDS.has(key)) continue;
+    const hint = key === "nullable" ? ' Use a type array instead: type: ["string", "null"].' : key === "oneOf" || key === "anyOf" || key === "allOf" ? " Model alternatives with an enum, a type array, or a discriminating property instead." : "";
+    throw new MindStudioError(
+      `[task] Unsupported JSON Schema keyword "${key}" at ${path} in outputSchema. Supported: type, properties, required, additionalProperties, items, enum, const.${hint}`,
+      "task_output_schema_unsupported",
+      400
+    );
+  }
+  if (schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      assertSupportedNode(propSchema, `${path}.${key}`);
+    }
+  }
+  if (schema.items) {
+    assertSupportedNode(schema.items, `${path}[]`);
+  }
+}
+function buildExampleFromSchema(schema) {
+  if (schema.const !== void 0) return schema.const;
+  if (schema.enum !== void 0 && schema.enum.length > 0)
+    return schema.enum[0];
+  const names = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  const name = names.find((n) => n !== "null") ?? names[0];
+  switch (name) {
+    case "object": {
+      const example = {};
+      for (const [key, propSchema] of Object.entries(
+        schema.properties ?? {}
+      )) {
+        example[key] = buildExampleFromSchema(propSchema);
+      }
+      return example;
+    }
+    case "array":
+      return schema.items ? [buildExampleFromSchema(schema.items)] : [];
+    case "string":
+      return "...";
+    case "number":
+    case "integer":
+      return 0;
+    case "boolean":
+      return true;
+    case "null":
+      return null;
+    default:
+      return null;
+  }
+}
+function stripCodeFences(text) {
+  const match = /^```[a-zA-Z]*[ \t]*\r?\n([\s\S]*?)\r?\n?```$/.exec(
+    text.trim()
+  );
+  return match ? match[1] : text;
+}
+
 // src/task/index.ts
 function resolveStepType(name) {
   const meta = stepMetadata[name];
@@ -3550,7 +3722,11 @@ function buildTaskRequestBody(options) {
     prompt: options.prompt,
     input: options.input,
     tools: mapTools(options.tools),
-    structuredOutputExample: typeof options.structuredOutputExample === "string" ? options.structuredOutputExample : JSON.stringify(options.structuredOutputExample),
+    // The legacy whole-task route requires structuredOutputExample and
+    // composes its own prompt server-side, so in schema mode we synthesize a
+    // skeleton example from the schema. Validation still happens client-side
+    // after the result comes back (see _runTaskInner).
+    structuredOutputExample: options.outputSchema ? JSON.stringify(buildExampleFromSchema(options.outputSchema)) : typeof options.structuredOutputExample === "string" ? options.structuredOutputExample : JSON.stringify(options.structuredOutputExample),
     model: options.model,
     ...options.maxTurns != null && { maxTurns: options.maxTurns },
     ...options.appId != null && { appId: options.appId },
@@ -3751,6 +3927,7 @@ async function runTaskStream(httpConfig, body, onEvent) {
 // src/task/local.ts
 var DEFAULT_MAX_TURNS = 20;
 var MAX_TURNS_LIMIT = 100;
+var MAX_SCHEMA_REPAIR_ATTEMPTS = 3;
 var MAX_TOOL_OUTPUT_CHARS = 5e4;
 var MAX_TURN_ATTEMPTS = 5;
 var INITIAL_BACKOFF_MS = 1e3;
@@ -3946,12 +4123,23 @@ async function runTurnWithRetry(httpConfig, body) {
 async function runTaskLocal(deps, options) {
   const { httpConfig } = deps;
   const onEvent = options.onEvent;
-  const structuredOutputExample = typeof options.structuredOutputExample === "string" ? options.structuredOutputExample : JSON.stringify(options.structuredOutputExample);
-  const system = `${options.prompt}
+  const outputSchema = options.outputSchema;
+  if (outputSchema) assertSupportedSchema(outputSchema);
+  let system;
+  if (outputSchema) {
+    system = `${options.prompt}
+
+When you have completed the task, respond with your final output as a single JSON object that conforms to this JSON Schema. Respond with the JSON object itself \u2014 NOT the schema, no prose, no code fences:
+${JSON.stringify(outputSchema)}
+<!-- cache_breakpoint -->`;
+  } else {
+    const structuredOutputExample = typeof options.structuredOutputExample === "string" ? options.structuredOutputExample : JSON.stringify(options.structuredOutputExample);
+    system = `${options.prompt}
 
 When you have completed the task, respond with your final output as JSON matching this example:
 ${structuredOutputExample}
 <!-- cache_breakpoint -->`;
+  }
   const wireTools = mapTools(options.tools);
   const toolKinds = /* @__PURE__ */ new Map();
   const toolDefaults = /* @__PURE__ */ new Map();
@@ -3972,6 +4160,7 @@ ${structuredOutputExample}
     { role: "user", content: JSON.stringify(options.input) }
   ];
   let loopCount = 0;
+  let schemaRepairCount = 0;
   const toolCallLog = [];
   const totalUsage = {
     inputTokens: 0,
@@ -4003,11 +4192,38 @@ ${structuredOutputExample}
     logTaskResult(result);
     return result;
   };
+  const schemaMismatch = (outputRaw, errors) => {
+    onEvent?.({
+      type: "error",
+      error: "Output did not conform to outputSchema.",
+      errors
+    });
+    return new MindStudioError(
+      "[task] Output did not conform to outputSchema after all repair attempts.",
+      "task_output_schema_mismatch",
+      422,
+      {
+        outputRaw,
+        errors,
+        turns: loopCount,
+        usage: totalUsage,
+        toolCalls: toolCallLog
+      }
+    );
+  };
   const turnFailure = (err) => {
     if (err instanceof TurnError && err.phase === "model") {
       if (isDevMode()) {
         console.error(`[task] Model call failed: ${err.message}`);
       }
+      if (outputSchema) {
+        throw new MindStudioError(
+          `[task] ${err.message}`,
+          "task_execution_error",
+          500,
+          { turns: loopCount, usage: totalUsage, toolCalls: toolCallLog }
+        );
+      }
       return finish(buildResult(null, "", false, loopCount));
     }
     if (err instanceof TurnError) {
@@ -4066,11 +4282,11 @@ ${structuredOutputExample}
           return { toolCall, ...result };
         })
       );
-      for (const { toolCall, output: output2, billingCost, isError } of results) {
+      for (const { toolCall, output: output3, billingCost, isError } of results) {
         if (billingCost) {
           totalUsage.totalBillingCost += billingCost;
         }
-        const truncated = truncateToolOutput(output2);
+        const truncated = truncateToolOutput(output3);
         messages.push({
           role: "user",
           content: JSON.stringify(truncated),
@@ -4089,17 +4305,43 @@ ${structuredOutputExample}
       continue;
     }
     messages.push({ role: "assistant", content: turn.text });
+    let output2;
+    let parseOk = true;
     try {
-      const output2 = JSON.parse(turn.text);
-      return finish(buildResult(output2, turn.text, true, loopCount));
+      output2 = JSON.parse(outputSchema ? stripCodeFences(turn.text) : turn.text);
     } catch {
-      if (loopCount < maxTurns) {
+      parseOk = false;
+    }
+    if (parseOk) {
+      if (!outputSchema) {
+        return finish(buildResult(output2, turn.text, true, loopCount));
+      }
+      const errors = validateAgainstSchema(output2, outputSchema);
+      if (errors.length === 0) {
+        return finish(buildResult(output2, turn.text, true, loopCount));
+      }
+      if (loopCount < maxTurns && schemaRepairCount < MAX_SCHEMA_REPAIR_ATTEMPTS) {
+        schemaRepairCount++;
         messages.push({
           role: "user",
-          content: "Your response was not valid JSON. Please respond with ONLY the JSON output, no other text."
+          content: `Your JSON output did not conform to the required schema. Fix these problems and respond again with ONLY the corrected JSON:
+${formatValidationErrors(errors)}`
         });
         continue;
       }
+      throw schemaMismatch(turn.text, errors);
+    }
+    if (loopCount < maxTurns) {
+      messages.push({
+        role: "user",
+        content: "Your response was not valid JSON. Please respond with ONLY the JSON output, no other text."
+      });
+      continue;
+    }
+    if (outputSchema) {
+      throw schemaMismatch(turn.text, [
+        { path: "$", message: "output was not valid JSON" }
+      ]);
     }
     return finish(buildResult(turn.text, turn.text, false, loopCount));
   }
@@ -4129,11 +4371,22 @@ ${structuredOutputExample}
   let parsedSuccessfully = true;
   let output;
   try {
-    output = JSON.parse(finalText);
+    output = JSON.parse(outputSchema ? stripCodeFences(finalText) : finalText);
   } catch {
     output = finalText;
     parsedSuccessfully = false;
   }
+  if (outputSchema) {
+    if (!parsedSuccessfully) {
+      throw schemaMismatch(finalText, [
+        { path: "$", message: "output was not valid JSON" }
+      ]);
+    }
+    const errors = validateAgainstSchema(output, outputSchema);
+    if (errors.length > 0) {
+      throw schemaMismatch(finalText, errors);
+    }
+  }
   return finish(
     buildResult(output, finalText, parsedSuccessfully, loopCount + 1)
   );
@@ -5150,29 +5403,6 @@ var MindStudioAgent = class {
       };
     }
   }
-  /**
-   * Run a task agent — a multi-step tool-use loop that composes SDK actions
-   * to produce structured output. The model receives the prompt and tools,
-   * calls actions as needed, and returns JSON matching the output example.
-   *
-   * Tools can be SDK actions, your own app's methods, or both. App methods run
-   * as the user who invoked the method that started the task, with their roles.
-   *
-   * ```ts
-   * const result = await agent.runTask<{ name: string; url: string }>({
-   *   prompt: 'Find canonical info for this restaurant, then save it.',
-   *   input: { restaurantName: 'Tartine Bakery SF' },
-   *   tools: [
-   *     'searchGoogle',
-   *     'fetchUrl',
-   *     { appMethod: 'saveRestaurant', description: 'Persist the researched restaurant.' },
-   *   ],
-   *   structuredOutputExample: JSON.stringify({ name: 'Tartine Bakery', url: 'https://tartinebakery.com' }),
-   *   model: 'claude-4-6-sonnet',
-   * });
-   * console.log(result.output.name); // 'Tartine Bakery'
-   * ```
-   */
   async runTask(options) {
     const taskPromise = this._runTaskInner(options);
     const hook = globalThis.__msWaitUntil;
@@ -5296,10 +5526,25 @@ var MindStudioAgent = class {
     } catch (err) {
       if (err instanceof MindStudioError && err.code === TURN_UNAVAILABLE_CODE) {
         const body = buildTaskRequestBody(options);
-        if (options.onEvent) {
-          return runTaskStream(httpConfig, body, options.onEvent);
+        const result = options.onEvent ? await runTaskStream(httpConfig, body, options.onEvent) : await runTaskPoll(httpConfig, body);
+        if (options.outputSchema) {
+          const errors = result.parsedSuccessfully ? validateAgainstSchema(result.output, options.outputSchema) : [{ path: "$", message: "output was not valid JSON" }];
+          if (errors.length > 0) {
+            throw new MindStudioError(
+              "[task] Output did not conform to outputSchema (legacy task route, no repair turns).",
+              "task_output_schema_mismatch",
+              422,
+              {
+                outputRaw: result.outputRaw,
+                errors,
+                turns: result.turns,
+                usage: result.usage,
+                toolCalls: result.toolCalls
+              }
+            );
+          }
         }
-        return runTaskPoll(httpConfig, body);
+        return result;
       }
       throw err;
     }
@@ -5713,6 +5958,79 @@ var MindStudioAgent = class {
   get files() {
     return this._files ??= createFiles(this._filesRequest.bind(this));
   }
+  /**
+   * Jewel surfaces: arrival-shaped triggers (`propose`) and the app-native
+   * approval queue (`queue.list` / `queue.resolve`). See {@link JewelsApi}.
+   */
+  get jewels() {
+    return {
+      propose: (methodId, subject, opts) => {
+        if (!methodId || typeof methodId !== "string") {
+          throw new MindStudioError(
+            "methodId is required",
+            "missing_method_id",
+            400
+          );
+        }
+        return this._jewelsRequest("propose", {
+          methodId,
+          subject,
+          ...opts?.idempotencyKey !== void 0 && {
+            idempotencyKey: opts.idempotencyKey
+          }
+        });
+      },
+      queue: {
+        list: (opts) => this._jewelsRequest("queue/list", {
+          ...opts?.methodId !== void 0 && { methodId: opts.methodId },
+          ...opts?.limit !== void 0 && { limit: opts.limit }
+        }),
+        resolve: (itemId, opts) => this._jewelsRequest("queue/resolve", {
+          itemId,
+          action: opts.action,
+          ...opts.input !== void 0 && { input: opts.input }
+        })
+      }
+    };
+  }
+  /**
+   * Raw hook-token call shared by the jewels surfaces (mirrors reportIssue).
+   * No retries: propose holds the request for the jewel run and is idempotent
+   * by key anyway; resolve applies a method and must never double-fire.
+   */
+  async _jewelsRequest(path, body) {
+    const rctx = getRequestContext();
+    if (this._authType !== "internal" && !rctx?.callbackToken) {
+      throw new MindStudioError(
+        `jewels.${path.replace("/", ".")} requires an app execution context (hook token) \u2014 it cannot be called with an API key.`,
+        "jewels_requires_app_context",
+        400
+      );
+    }
+    const url = `${this._currentHttpConfig.baseUrl}/_internal/v2/jewels/${path}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: this._token
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let code = "jewels_error";
+      let message = `jewels.${path.replace("/", ".")} failed: ${res.status} ${res.statusText}`;
+      let details;
+      try {
+        const errBody = await res.json();
+        details = errBody;
+        if (typeof errBody.errorString === "string") code = errBody.errorString;
+        message = typeof errBody.errorMessage === "string" && errBody.errorMessage || typeof errBody.errorString === "string" && errBody.errorString || message;
+      } catch {
+      }
+      throw new MindStudioError(message, code, res.status, details);
+    }
+    return await res.json();
+  }
   /**
    * Searchable document corpora.
    *
@@ -6274,6 +6592,124 @@ function resolveToken(provided, config) {
   );
 }
 
+// src/jewel/index.ts
+function errorInfo(e) {
+  if (e instanceof Error) return { message: e.message, stack: e.stack };
+  return { message: String(e) };
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+    return false;
+  }
+  const aIsArray = Array.isArray(a);
+  if (aIsArray !== Array.isArray(b)) return false;
+  if (aIsArray) {
+    const aa = a;
+    const ba = b;
+    return aa.length === ba.length && aa.every((v, i) => deepEqual(v, ba[i]));
+  }
+  const ao = a;
+  const bo = b;
+  const aKeys = Object.keys(ao).filter((k) => ao[k] !== void 0);
+  const bKeys = Object.keys(bo).filter((k) => bo[k] !== void 0);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((k) => deepEqual(ao[k], bo[k]));
+}
+var VERDICTS = /* @__PURE__ */ new Set(["agree", "disagree", "skip"]);
+function normalizeVerdict(v) {
+  if (!v || !VERDICTS.has(v.verdict)) {
+    return {
+      verdict: "skip",
+      notes: `grade returned invalid verdict: ${JSON.stringify(v)}`
+    };
+  }
+  return v.notes === void 0 ? { verdict: v.verdict } : { verdict: v.verdict, notes: v.notes };
+}
+function defineJewel(method, config) {
+  const runGrade = async (proposed, actual) => {
+    if (config.grade) {
+      try {
+        return normalizeVerdict(await config.grade({ proposed, actual }));
+      } catch (e) {
+        return { verdict: "skip", notes: `grade threw: ${errorInfo(e).message}` };
+      }
+    }
+    return deepEqual(proposed, actual) ? { verdict: "agree" } : { verdict: "disagree" };
+  };
+  const run = async (params) => {
+    const startedAt = Date.now();
+    const customGrade = config.grade !== void 0;
+    const done = (rest) => ({
+      v: 1,
+      customGrade,
+      startedAt,
+      durationMs: Date.now() - startedAt,
+      ...rest
+    });
+    if (Object.prototype.hasOwnProperty.call(params, "grade")) {
+      const ctx = params.grade;
+      const verdict2 = await runGrade(ctx.proposed, ctx.actual);
+      return done({
+        mode: "grade",
+        proposed: ctx.proposed,
+        actual: ctx.actual,
+        verdict: verdict2.verdict,
+        ...verdict2.notes !== void 0 ? { notes: verdict2.notes } : {}
+      });
+    }
+    const isShadow = Object.prototype.hasOwnProperty.call(params, "humanInput");
+    const mode = isShadow ? "shadow" : "eval";
+    const actual = isShadow ? params.humanInput : void 0;
+    let subject;
+    if (isShadow) {
+      try {
+        subject = config.subject(actual);
+      } catch (e) {
+        return done({ mode, actual, error: { phase: "subject", ...errorInfo(e) } });
+      }
+    } else {
+      subject = params.subject;
+    }
+    let proposal;
+    try {
+      proposal = await config.propose(subject);
+    } catch (e) {
+      return done({
+        mode,
+        subject,
+        actual,
+        error: { phase: "propose", ...errorInfo(e) }
+      });
+    }
+    if (!isShadow) {
+      return done({
+        mode,
+        subject,
+        proposed: proposal.input,
+        reasoning: proposal.reasoning
+      });
+    }
+    const verdict = await runGrade(proposal.input, actual);
+    return done({
+      mode,
+      subject,
+      proposed: proposal.input,
+      reasoning: proposal.reasoning,
+      actual,
+      verdict: verdict.verdict,
+      ...verdict.notes !== void 0 ? { notes: verdict.notes } : {}
+    });
+  };
+  return Object.assign(run, {
+    kind: "jewel",
+    method,
+    subject: config.subject,
+    propose: config.propose,
+    grade: config.grade
+  });
+}
+
 // src/generated/snippets.ts
 var monacoSnippets = {
   "activeCampaignAddNote": { fields: [["contactId", "string"], ["note", "string"]], outputKeys: [] },
@@ -6525,6 +6961,7 @@ export {
   dataSources,
   db,
   index_default as default,
+  defineJewel,
   files,
   getRequestContext,
   mindstudio,