@oddington/sdk 0.1.35 → 0.1.36

package/README.md

@@ -79,6 +79,21 @@ declared `review` handler crosses the Inbox publication seam as `review`; Inbox
 retains the canonical `invoice-import` routine identity separately, without
 deploying or executing that handler.
 
+With `access: { ai: true }`, `os.ai.generateText` returns non-empty `{ text }`.
+`os.ai.generateObject` returns `{ object }` validated against the requested
+`schema`, with its inferred type. An invalid answer throws `RoutineAIError`
+with code `invalid_output`, a clear bounded `detail`, and the original final
+answer as optional `text` for routine-owned recovery. The text is bounded at
+256 KiB and excluded from the error message and ordinary JSON serialization.
+The routine can inspect it explicitly, apply its own recovery rules, report
+an item failure and continue; it must not cast a rejected answer to the promised
+type. OS does not coerce, drop fields, repair or retry automatically.
+
+An AI call failure can be caught and handled without automatically failing the
+Run. Uncaught routine or step exceptions still fail execution, and outstanding
+AI calls drain before completion. The host retains authority, isolation,
+cancellation and byte limits. Local and remote Runs use the same API.
+
 The bounded grammar supports closed objects with required properties, arrays with
 an explicit `maxItems` from 1 to 64, booleans, strings (at most 4096 code points),
 finite numbers and safe integers with optional inclusive bounds, and Files.

package/dist/browser.js

@@ -221,32 +221,45 @@ function jsonData(value, ancestors = /* @__PURE__ */ new Set()) {
     ancestors.delete(value);
   }
 }
-function validateRoutineSchemaValue(schema2, value) {
-  switch (schema2.type) {
-    case "object":
-      if (!record(value) || (schema2.required ?? []).some((key) => !owns(value, key)) || Object.keys(value).some((key) => !owns(schema2.properties, key))) return invalidValue();
-      for (let [key, child] of Object.entries(value)) validateRoutineSchemaValue(schema2.properties[key], child);
-      return;
-    case "array":
-      if (!denseArray(value) || value.length > schema2.maxItems) return invalidValue();
-      for (let child of value) validateRoutineSchemaValue(schema2.items, child);
-      return;
-    case "boolean":
-      return typeof value != "boolean" ? invalidValue() : void 0;
-    case "string":
-      return typeof value != "string" || Array.from(value).length > (schema2.maxLength ?? 4096) ? invalidValue() : void 0;
-    case "integer":
-    case "number":
-      return typeof value != "number" || !(schema2.type === "integer" ? Number.isSafeInteger(value) : Number.isFinite(value)) || schema2.minimum !== void 0 && value < schema2.minimum || schema2.maximum !== void 0 && value > schema2.maximum ? invalidValue() : void 0;
-    case "file":
-      try {
-        jsonData(value);
-        let file2 = parseFileDescriptor(value);
-        if (schema2.path !== void 0 && file2.path !== schema2.path) return invalidValue();
-      } catch {
-        return invalidValue();
+function validateRoutineSchemaValue(schema2, value, rejected) {
+  let type = (value2) => value2 === null ? "null" : Array.isArray(value2) ? "array" : ["object", "boolean", "string", "number"].includes(typeof value2) ? typeof value2 : "other";
+  function check(schema3, value2, path) {
+    let fail4 = (reason, extra = {}) => (rejected?.({ reason, path: path.length <= 256 ? path : "$", expected: schema3.type, received: type(value2), ...extra }), invalidValue());
+    switch (schema3.type) {
+      case "object":
+        if (!record(value2)) return fail4("wrong_type");
+        for (let key of schema3.required ?? []) if (!owns(value2, key)) return fail4("missing_field", {
+          path: `${path}.${key}`.length <= 256 ? `${path}.${key}` : "$",
+          expected: schema3.properties[key].type,
+          received: "missing"
+        });
+        if (Object.keys(value2).some((key) => !owns(schema3.properties, key))) return fail4("unexpected_field");
+        for (let [key, child] of Object.entries(value2)) check(schema3.properties[key], child, `${path}.${key}`);
+        return;
+      case "array":
+        if (!denseArray(value2)) return fail4("wrong_type");
+        if (value2.length > schema3.maxItems) return fail4("out_of_bounds", { constraint: "maxItems", limit: schema3.maxItems });
+        value2.forEach((child, index) => check(schema3.items, child, `${path}[${index}]`));
+        return;
+      case "boolean":
+        return typeof value2 != "boolean" ? fail4("wrong_type") : void 0;
+      case "string":
+        return typeof value2 != "string" ? fail4("wrong_type") : Array.from(value2).length > (schema3.maxLength ?? 4096) ? fail4("out_of_bounds", { constraint: "maxLength", limit: schema3.maxLength ?? 4096 }) : void 0;
+      case "integer":
+      case "number":
+        return typeof value2 != "number" || !(schema3.type === "integer" ? Number.isSafeInteger(value2) : Number.isFinite(value2)) ? fail4("wrong_type") : schema3.minimum !== void 0 && value2 < schema3.minimum ? fail4("out_of_bounds", { constraint: "minimum", limit: schema3.minimum }) : schema3.maximum !== void 0 && value2 > schema3.maximum ? fail4("out_of_bounds", { constraint: "maximum", limit: schema3.maximum }) : void 0;
+      case "file": {
+        let file2;
+        try {
+          jsonData(value2), file2 = parseFileDescriptor(value2);
+        } catch {
+          return fail4("invalid_file");
+        }
+        if (schema3.path !== void 0 && file2.path !== schema3.path) return fail4("invalid_file");
       }
+    }
   }
+  check(schema2, value, "$");
 }
 
 var InboxContractError = class extends Error {
@@ -695,20 +708,82 @@ function parseRoutineAccess(value) {
   }
 }
 
-var ROUTINE_AI_VALUE_BYTES = 256 * 1024, ROUTINE_AI_EVIDENCE_BYTES = 4 * 1024;
+function parseRoutineAIOutputIssue(value) {
+  if (!value || typeof value != "object" || Array.isArray(value)) return;
+  let v = value;
+  if (["invalid_json", "invalid_response", "empty_text"].includes(String(v.reason)))
+    return Object.keys(v).join(",") === "reason" ? { reason: v.reason } : void 0;
+  if (!(!["missing_field", "unexpected_field", "wrong_type", "out_of_bounds", "invalid_file"].includes(String(v.reason)) || typeof v.path != "string" || v.path.length > 256 || !/^\$(?:\.[a-z][A-Za-z0-9]*|\[(?:0|[1-9][0-9]*)\])*$/.test(v.path) || !["object", "array", "boolean", "string", "integer", "number", "file"].includes(String(v.expected)) || !["missing", "null", "object", "array", "boolean", "string", "number", "other"].includes(String(v.received)) || Object.keys(v).some((key) => !["reason", "path", "expected", "received", "constraint", "limit"].includes(key)))) {
+    if (v.reason === "out_of_bounds") {
+      if (!["maxLength", "maxItems", "minimum", "maximum"].includes(String(v.constraint)) || typeof v.limit != "number" || !Number.isFinite(v.limit)) return;
+    } else if (Object.hasOwn(v, "constraint") || Object.hasOwn(v, "limit")) return;
+    return {
+      reason: v.reason,
+      path: v.path,
+      expected: v.expected,
+      received: v.received,
+      ...v.reason === "out_of_bounds" ? { constraint: v.constraint, limit: v.limit } : {}
+    };
+  }
+}
+function routineAIOutputMessage(issue) {
+  if (issue.reason === "invalid_json") return "AI replied, but its answer could not be read as JSON.";
+  if (issue.reason === "invalid_response") return "AI returned a response OS could not read.";
+  if (issue.reason === "empty_text") return "AI returned an empty answer.";
+  let field = issue.path === "$" ? "response" : issue.path.slice(issue.path.startsWith("$.") ? 2 : 1), expected = {
+    object: "an object",
+    array: "a list",
+    boolean: "true or false",
+    string: "text",
+    integer: "a whole number",
+    number: "a number",
+    file: "a File"
+  }[issue.expected], received = {
+    missing: "a missing field",
+    null: "null",
+    object: "an object",
+    array: "a list",
+    boolean: "true or false",
+    string: "text",
+    number: "a number",
+    other: "an unsupported value"
+  }[issue.received];
+  if (issue.reason === "missing_field") return `AI response is missing a required field.
+  ${field}: expected ${expected}; the field was missing.`;
+  if (issue.reason === "unexpected_field") return `AI response includes an unexpected field.
+  ${field}: only the fields declared by the routine are allowed.`;
+  if (issue.reason === "invalid_file") return `AI response contains an invalid File.
+  ${field}: expected a valid File matching the routine's requirements.`;
+  if (issue.reason === "out_of_bounds") {
+    let constraint = {
+      maxLength: `at most ${issue.limit} characters`,
+      maxItems: `at most ${issue.limit} items`,
+      minimum: `a value of at least ${issue.limit}`,
+      maximum: `a value of at most ${issue.limit}`
+    }[issue.constraint];
+    return `AI response is outside a permitted limit.
+  ${field}: expected ${constraint}.`;
+  }
+  return `AI response has the wrong type.
+  ${field}: expected ${expected}; received ${received}.`;
+}
+
+var ROUTINE_AI_VALUE_BYTES = 256 * 1024, ROUTINE_AI_RESULT_BYTES = 6 * ROUTINE_AI_VALUE_BYTES + 1024, ROUTINE_AI_EVIDENCE_BYTES = 4 * 1024;
 var RoutineAIError = class extends Error {
-  constructor(code) {
-    super(code);
+  constructor(code, options = {}) {
+    let detail = code === "invalid_output" ? parseRoutineAIOutputIssue(options.detail) : void 0;
+    super(detail ? routineAIOutputMessage(detail) : code);
     this.code = code;
-    this.name = "RoutineAIError";
+    this.name = "RoutineAIError", detail && (this.detail = Object.freeze(detail)), code === "invalid_output" && typeof options.text == "string" && new TextEncoder().encode(options.text).byteLength <= ROUTINE_AI_VALUE_BYTES && Object.defineProperty(this, "text", { value: options.text });
   }
   code;
+  detail;
 };
-function capture(value, invalid9, oversized) {
+function capture(value, invalid9, oversized, limit = ROUTINE_AI_VALUE_BYTES) {
   try {
     assertRoutineJson(value);
     let encoded = JSON.stringify(value);
-    if (new TextEncoder().encode(encoded).byteLength > ROUTINE_AI_VALUE_BYTES) throw new RoutineAIError(oversized);
+    if (new TextEncoder().encode(encoded).byteLength > limit) throw new RoutineAIError(oversized);
     return freezeRoutineMetadata(JSON.parse(encoded));
   } catch (error) {
     throw error instanceof RoutineAIError ? error : new RoutineAIError(invalid9);
@@ -727,18 +802,46 @@ function parseRoutineAIRequest(value) {
   }
 }
 function parseRoutineAIResult(request2, value) {
-  let v = capture(value, "invalid_output", "output_too_large");
+  let v;
   try {
-    if (request2.kind === "generateText") {
-      if (assertRoutineFields(v, ["text"]), typeof v.text != "string" || !v.text.trim()) throw new Error();
-      return freezeRoutineMetadata({ text: v.text });
-    } else {
-      if (assertRoutineFields(v, ["object"]), !Object.hasOwn(v, "object")) throw new Error();
-      return validateRoutineSchemaValue(request2.schema, v.object), freezeRoutineMetadata({ object: v.object });
+    if (v = capture(
+      value,
+      "invalid_output",
+      "output_too_large",
+      request2.kind === "generateText" ? ROUTINE_AI_RESULT_BYTES : ROUTINE_AI_VALUE_BYTES
+    ), assertRoutineFields(v, request2.kind === "generateText" ? ["text"] : ["object"]), request2.kind === "generateText") {
+      if (typeof v.text != "string") throw new Error();
+      return acceptText(request2, v.text);
     }
+    if (!Object.hasOwn(v, "object")) throw new Error();
+  } catch (error) {
+    throw error instanceof RoutineAIError ? error : new RoutineAIError("invalid_output", { detail: { reason: "invalid_response" } });
+  }
+  return validateObject(request2.schema, v.object), freezeRoutineMetadata({ object: v.object });
+}
+function validateObject(schema2, object5, text5) {
+  let detail = { reason: "invalid_response" };
+  try {
+    validateRoutineSchemaValue(schema2, object5, (issue) => {
+      detail = issue;
+    });
+  } catch {
+    throw new RoutineAIError("invalid_output", { ...text5 === void 0 ? {} : { text: text5 }, detail });
+  }
+}
+function acceptText(request2, text5) {
+  if (new TextEncoder().encode(text5).byteLength > ROUTINE_AI_VALUE_BYTES) throw new RoutineAIError("output_too_large");
+  if (request2.kind === "generateText") {
+    if (!text5.trim()) throw new RoutineAIError("invalid_output", { text: text5, detail: { reason: "empty_text" } });
+    return freezeRoutineMetadata({ text: text5 });
+  }
+  let object5;
+  try {
+    object5 = JSON.parse(text5);
   } catch {
-    throw new RoutineAIError("invalid_output");
+    throw new RoutineAIError("invalid_output", { text: text5, detail: { reason: "invalid_json" } });
   }
+  return validateObject(request2.schema, object5, text5), capture({ object: object5 }, "invalid_output", "output_too_large");
 }
 
 var LIMIT = 256 * 1024, invalid3 = () => {
@@ -865,7 +968,7 @@ function captureRoutineInput(definition, input) {
   return capture2(contract.input, input === void 0 && Object.hasOwn(contract, "inputDefault") ? contract.inputDefault : input);
 }
 async function executeRoutineDefinition(definition, input, runtime) {
-  let captured = captureRoutineInput(definition, input), { contract, steps, run } = definitions.get(definition), active2 = !0, accepting = !0, broken = !1, work = Promise.resolve(), aiFailure, aiWork = /* @__PURE__ */ new Set(), generate = (kind, value) => {
+  let captured = captureRoutineInput(definition, input), { contract, steps, run } = definitions.get(definition), active2 = !0, accepting = !0, broken = !1, work = Promise.resolve(), aiWork = /* @__PURE__ */ new Set(), generate = (kind, value) => {
     let operation2 = (async () => {
       if (!active2 || broken || contract.access.ai !== !0) throw new RoutineAIError("access_denied");
       if (!runtime.ai) throw new RoutineAIError("capability_unavailable");
@@ -884,9 +987,7 @@ async function executeRoutineDefinition(definition, input, runtime) {
       if (!active2 || broken) throw new RoutineAIError("access_denied");
       return parseRoutineAIResult(request2, result3);
     })();
-    return aiWork.add(operation2), operation2.then(() => aiWork.delete(operation2), (error) => {
-      aiFailure ??= error, broken = !0, aiWork.delete(operation2);
-    }), operation2;
+    return aiWork.add(operation2), operation2.then(() => aiWork.delete(operation2), () => aiWork.delete(operation2)), operation2;
   }, called = /* @__PURE__ */ new Set(), reached = /* @__PURE__ */ new Set(), guarded = (value, receiver) => typeof value == "function" ? (...args) => {
     if (!active2 || broken) throw new Error("Run authority ended");
     return guarded(Reflect.apply(value, receiver, args));
@@ -950,7 +1051,7 @@ async function executeRoutineDefinition(definition, input, runtime) {
   for (accepting = !1, await work; aiWork.size; ) await Promise.allSettled([...aiWork]);
   active2 = !1;
   for (let step of contract.steps) reached.has(step.id) || await runtime.step(step.id, { status: "skipped" });
-  if (broken) throw failure ?? aiFailure ?? new AppRoutineContractError("invalid_value");
+  if (broken) throw failure ?? new AppRoutineContractError("invalid_value");
   if (contract.result !== void 0) return capture2(contract.result, result2);
   if (result2 !== void 0) return invalid3();
 }
@@ -4016,6 +4117,7 @@ export {
   FileOperationError,
   InboxContractError,
   InboxOperationError,
+  RoutineAIError,
   app,
   asksBlock,
   auth,