@mindstudio-ai/agent 0.1.99 → 0.1.100

package/dist/index.js

@@ -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;
     }