@oddington/sdk 0.1.41 → 0.1.42

package/README.md

@@ -86,6 +86,11 @@ 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.
 
+Long customer computation inside a remote step can report advancing work with
+`await os.run.progress({ completed, total })`. Report progress after meaningful
+batches of work rather than after every individual item. OS capability calls and
+step transitions already count as activity automatically.
+
 Microsoft Connection configuration has a separate, optional `access` description.
 It preserves supplied strings, including existing `read` and `read-write` labels,
 and does not grant or restrict Microsoft permissions. Management results omit
@@ -98,6 +103,13 @@ With `access: { ai: true }`, `os.ai.generateText` returns non-empty `{ text }`.
 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.
+AI failures have plain-language messages and keep their structured `code`.
+Optional `detail` explains a known runner limit, exit, response failure or request
+validation rule. Use these facts rather than parsing messages. A code-only legacy
+failure does not establish a more specific cause or justify a retry. Local Run
+activity and AI inspection preserve these diagnostics even when the routine
+catches the error and continues; no provider logs or private answer text are
+included in the ordinary activity summary.
 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.
@@ -107,6 +119,29 @@ type. OS does not coerce, drop fields, repair or retry automatically.
 extract JSON from explanatory prose or repair the answer. `RoutineAIError`
 remains a compatibility alias of `AIError`, so existing `instanceof` checks work.
 
+For a File that needs local tool-assisted inspection, explicitly enable tools
+on that call:
+
+```ts
+const { object } = await os.ai.generateObject({
+  input: document,
+  instructions: 'Read this document and report only grounded facts.',
+  schema: documentFacts,
+  tools: true,
+});
+```
+
+Omitting `tools` or setting it to `false` keeps the existing tool-free behavior.
+OS supplies and sandboxes the tools; routines do not choose CLI flags or shell
+commands. This first version requires a File input and local macOS execution
+with Claude Code 2.1.285 or newer. Unsupported hosts reject with
+`AIError('capability_unavailable')` rather than silently ignoring the option.
+The original stays read-only, temporary processing is disposable, and tool
+network access is blocked. A tool-assisted answer still has to satisfy the
+requested schema and the routine's own completeness checks.
+Tool-enabled object generation uses the runner's structured final submission;
+OS validates that value without extracting JSON from surrounding commentary.
+
 Preserve safe AI error facts when reporting a per-document failure. Keep the
 original answer (`error.text`) out of step data, business records and logs:
 
@@ -244,7 +279,7 @@ os.init({ auth }); // OS-owned startup, once before app modules run.
 // App code uses the installed capabilities directly.
 const general = data.repository('general');
 try {
-  const selected = await general.records.select({ invoices: { $: { limit: 20 } } });
+  const selected = await general.records.query({ invoices: { $: { limit: 20 } } });
   const found = await general.records.search('acme overdue', {
     collections: ['invoices'], limit: 20,
   });
@@ -473,7 +508,10 @@ and numeric byte counts; its message explains the rejected field or expected
 versus received size. Streaming rejection marks partial received counts with
 `receivedAtLeast: true`. These facts survive local Run summaries and saved
 failure evidence without raw names, keys, file content or provider text. Older
-errors without `detail` remain valid. Reads return the successful Web
+errors without `detail` remain valid. Messages use the known reason in plain
+language; use `code`, `status`, `retryable` and `detail` for programmatic decisions
+rather than parsing the message. Replacement errors explain that `replace`
+expects the current enrichment's SHA-256 value. Reads return the successful Web
 Response without consuming its body. Local transfer is bounded and buffered
 before constructing that Response. Current workspace members can use every File in that workspace. A
 routine's `files: "read"` permits get/read; `files: "read-write"` also permits
@@ -581,12 +619,12 @@ import { data, DataOperationError } from '@oddington/sdk';
 const general = data.repository('general');
 const collections = await general.collections.list();
 const schema = await general.collections.schema('invoices');
-const first = await general.records.select({
+const first = await general.records.query({
   invoices: { $: { limit: 50 }, supplier: { $: { fields: ['name'] } } },
   suppliers: {},
 });
 const next = first.$meta.collections.invoices.next;
-if (next) await general.records.select({
+if (next) await general.records.query({
   invoices: { $: { limit: 50, after: next }, supplier: { $: { fields: ['name'] } } },
 });
 ```
@@ -623,7 +661,7 @@ unedited first-release generated output and preserves every other alias; edited
 or malformed generated files remain protected.
 
 Known repository literals then constrain collection/field/link names and query
-operands and infer projected `select`, `pages` and `all` values from normalized
+operands and infer projected `query`, `pages` and `all` values from normalized
 schemas. Multiple aliases share the root declaration. Refresh explicitly with
 the same CLI command after publishing schema changes; app builds and launches
 never refresh it. Missing metadata and dynamic repository strings retain generic
@@ -651,7 +689,7 @@ Both helpers preserve literal collection arrays and selected-link inference.
 prefetches after a consumer stops. Independent collection cursors pin the first
 snapshot. Completed collections yield empty arrays on later pages and retain
 requested counts. Empty matches yield one versioned page. Helpers own continuation;
-use `select` for a manual `after` cursor or explicit historical selection.
+use `query` for a manual `after` cursor or explicit historical query.
 
 `all` consumes the same iterator and returns only after successful exhaustion.
 Its required positive safe-integer `maxRecords` caps top-level Record occurrences
@@ -661,7 +699,7 @@ or increase `maxRecords`, and rejects with nonretryable `capacity` without a
 partial or truncated result.
 Invalid helper arguments use `invalid_query`; malformed pages, cursor cycles,
 snapshot changes or inconsistent requested counts use nonretryable `unavailable`.
-Selection and authority failures propagate unchanged, with no retry or restart.
+Query and authority failures propagate unchanged, with no retry or restart.
 
 Read known stable refs directly, including refs from different collections:
 
@@ -674,7 +712,7 @@ const batch = await general.records.read(['invoices/one', 'suppliers/acme']);
 
 An array accepts 1–100 distinct valid refs; a one-element array keeps the batch
 shape, and all-missing batches still carry their version. Both forms send one
-bounded operation through the same app/routine authority and snapshot as `select`.
+bounded operation through the same app/routine authority and snapshot as `query`.
 Records include `$ref`, `$version` and all canonical structured fields; links
 remain refs, omitted and null fields stay distinct, and Markdown bodies and
 `$filing` are excluded. Invalid refs, exceeded bounds, denied access and service
@@ -743,7 +781,7 @@ and `$in`, declared one-valued `integer`, `number` and `date` fields accept
 `$gt`, `$gte`, `$lt` and `$lte`:
 
 ```ts
-await general.records.select({ invoices: { $: { where: {
+await general.records.query({ invoices: { $: { where: {
   amount: { $gte: 10, $lte: 20 },
   date: { $gte: '2026-10-01', $lt: '2026-11-01' },
   month: { $gte: '2026-10', $lte: '2026-10' },

package/dist/browser.js

@@ -3,19 +3,27 @@ var fileValidationReasons = {
   invalid_name: "File name must be 1\u2013255 characters, with no reserved names, path separators, control characters or trailing spaces/dots.",
   invalid_path: "File path must contain safe relative folder names and cannot start with .os.",
   invalid_storage: "File storage must be local or remote.",
-  invalid_media_type: "File media type must name one valid type/subtype.",
+  invalid_media_type: "The media type must use a value such as text/markdown or application/json.",
   invalid_size: "File size must be a non-negative safe integer byte count.",
   invalid_request_key: "File request key must contain 1\u2013256 characters, with no surrounding whitespace or control characters.",
-  invalid_enrichment_name: "Enrichment name must be a safe filename and cannot be original or original.*.",
-  invalid_replacement: "Enrichment replacement must be a SHA-256 hash of 64 lowercase hexadecimal characters.",
+  invalid_enrichment_name: "The enrichment name must be a filename without folders, such as read.md. Names such as original and original.pdf are reserved.",
+  invalid_enrichment_request: "The save request has invalid content or metadata.",
+  invalid_replacement: "To replace an enrichment, pass its current SHA-256 value as replace.",
   invalid_bytes: "File content must contain byte chunks.",
   original_changed: "The selected file changed while OS was reading it. Wait for it to finish saving, then try again."
+}, localStorageReasons = {
+  local_storage_legacy: `OS found an older local file storage layout: the internal metadata folder is still named .oddington-files.
+
+Stop any OS routines using this workspace, then rename .oddington-files to .os in the same directory and rerun your command. Keep the folder\u2019s contents intact.`,
+  local_storage_ambiguous: "OS found both .oddington-files and .os metadata folders in local file storage and could not safely choose one. Reconcile their metadata before continuing; do not overwrite either folder. Your stored files have been left in place.",
+  local_storage_unrecognized: "OS could not open its local file storage because the folder contains files but has no recognized metadata. The storage folder needs to be checked before continuing. Your stored files have been left in place.",
+  local_storage_tracked: "OS could not use its local file storage because it contains Git-tracked files. Local file storage must be outside tracked repository content. Your stored files have been left in place."
 };
 function parseFileErrorDetail(value) {
   if (!value || typeof value != "object" || Array.isArray(value)) return;
   let v = value;
   if (typeof v.reason != "string") return;
-  if (Object.hasOwn(fileValidationReasons, v.reason))
+  if (Object.hasOwn(fileValidationReasons, v.reason) || Object.hasOwn(localStorageReasons, v.reason))
     return Object.keys(v).length === 1 ? { reason: v.reason } : void 0;
   if (v.reason !== "size_mismatch" && v.reason !== "size_limit") return;
   let count = v.reason === "size_mismatch" ? "expectedBytes" : "limitBytes";
@@ -28,16 +36,57 @@ function parseFileErrorDetail(value) {
     };
 }
 function fileErrorExplanation(detail) {
-  return detail.reason === "size_mismatch" ? `File byte count mismatch: expected ${detail.expectedBytes} bytes; received ${detail.receivedAtLeast ? "at least " : ""}${detail.receivedBytes} bytes.` : detail.reason === "size_limit" ? `File size exceeds the ${detail.limitBytes}-byte limit; received ${detail.receivedAtLeast ? "at least " : ""}${detail.receivedBytes} bytes.` : fileValidationReasons[detail.reason];
-}
-var FILE_CAPACITY_MESSAGE = "OS reached its file-processing limit. Try again in a moment. If this keeps happening with a large batch, split the files into smaller groups.", FILE_INTEGRITY_MESSAGE = "OS could not verify this File against its saved record. Try again. If the problem continues, add the original file again.", FileOperationError = class extends Error {
+  return detail.reason === "size_mismatch" ? `The request declared ${detail.expectedBytes} bytes, but contained ${detail.receivedAtLeast ? "at least " : ""}${detail.receivedBytes} bytes.` : detail.reason === "size_limit" ? `The file content exceeds the ${fileSizeLabel(detail.limitBytes)} limit; received ${detail.receivedAtLeast ? "at least " : ""}${fileSizeLabel(detail.receivedBytes)}.` : Object.hasOwn(localStorageReasons, detail.reason) ? localStorageReasons[detail.reason] : fileValidationReasons[detail.reason];
+}
+function fileSizeLabel(bytes) {
+  for (let [unit, size] of [["GiB", 1024 ** 3], ["MiB", 1024 ** 2], ["KiB", 1024]])
+    if (bytes >= size && bytes % size === 0) return `${bytes / size} ${unit}`;
+  return `${bytes} bytes`;
+}
+function fileErrorDetailForCode(code, detail) {
+  let parsed = parseFileErrorDetail(detail);
+  if (!parsed) return;
+  if (Object.hasOwn(localStorageReasons, parsed.reason) ? code === "unavailable" : ["invalid_input", "request_too_large"].includes(code)) return parsed;
+}
+var FILE_CAPACITY_MESSAGE = "OS reached its file-processing limit. Try again in a moment. If this keeps happening with a large batch, split the files into smaller groups.", FILE_INTEGRITY_MESSAGE = "OS could not verify this File against its saved record. Try again. If the problem continues, add the original file again.";
+function fileErrorMessage(error) {
+  let detail = fileErrorDetailForCode(error.code, error.detail);
+  if (detail)
+    return `${["invalid_enrichment_name", "invalid_enrichment_request", "invalid_replacement"].includes(detail.reason) ? `Couldn\u2019t save the file\u2019s enrichment.
+` : ""}${fileErrorExplanation(detail)}`;
+  switch (error.code) {
+    case "invalid_input":
+      return "The file request is invalid.";
+    case "unsupported_context":
+      return "This environment does not support this file operation.";
+    case "unauthenticated":
+      return "Sign in to OS before accessing files.";
+    case "access_denied":
+      return "You don\u2019t have access to this file operation.";
+    case "request_too_large":
+      return "The file request exceeds the size limit.";
+    case "conflict":
+      return "The saved file or enrichment doesn\u2019t match this request. Reload it before trying again.";
+    case "local_only":
+      return "This file is stored on a computer and isn\u2019t available through remote storage.";
+    case "integrity":
+      return FILE_INTEGRITY_MESSAGE;
+    case "capacity":
+      return FILE_CAPACITY_MESSAGE;
+    case "method_not_allowed":
+      return "This request uses an unsupported file operation.";
+    case "unavailable":
+      return `OS couldn\u2019t complete the file operation.${error.retryable ? " Try again." : ""}`;
+  }
+}
+var FileOperationError = class extends Error {
   constructor(code, status, retryable = !1, detail) {
-    let safe = ["invalid_input", "request_too_large"].includes(code) ? parseFileErrorDetail(detail) : void 0;
-    super(safe ? `${code}: ${fileErrorExplanation(safe)}` : code === "capacity" ? FILE_CAPACITY_MESSAGE : code === "integrity" ? FILE_INTEGRITY_MESSAGE : code);
+    let safe = fileErrorDetailForCode(code, detail);
+    super(fileErrorMessage({ code, retryable, detail: safe }));
     this.code = code;
     this.status = status;
     this.retryable = retryable;
-    safe && (this.detail = Object.freeze(safe));
+    safe && (this.detail = Object.freeze(safe)), safe && Object.hasOwn(localStorageReasons, safe.reason) && (this.retryable = !1);
   }
   code;
   status;
@@ -666,7 +715,7 @@ function parseRoutineDeclaration(value) {
     (!routineAlias(key) || !["read", "write"].includes(repositories[key])) && invalid(`access.repositories.${key}`), grants[key] = repositories[key];
   access.files !== void 0 && !["read", "read-write"].includes(access.files) && invalid("access.files");
   let runtime = object2(v.runtime === void 0 ? {} : v.runtime, ["features", "resources", "maxDuration"], "runtime");
-  runtime.features !== void 0 && (!Array.isArray(runtime.features) || runtime.features.length !== 0) && invalid("runtime.features"), runtime.resources !== void 0 && runtime.resources !== "standard" && invalid("runtime.resources"), runtime.maxDuration !== void 0 && runtime.maxDuration !== "15m" && invalid("runtime.maxDuration");
+  runtime.features !== void 0 && (!Array.isArray(runtime.features) || runtime.features.length !== 0) && invalid("runtime.features"), runtime.resources !== void 0 && runtime.resources !== "standard" && invalid("runtime.resources"), runtime.maxDuration !== void 0 && !["15m", "60m"].includes(runtime.maxDuration) && invalid("runtime.maxDuration");
   let retry = object2(v.retry === void 0 ? {} : v.retry, ["maxAttempts"], "retry");
   retry.maxAttempts !== void 0 && retry.maxAttempts !== 1 && invalid("retry.maxAttempts");
   let assets = v.assets === void 0 ? [] : v.assets;
@@ -679,7 +728,11 @@ function parseRoutineDeclaration(value) {
       ...access.files === void 0 ? {} : { files: access.files },
       publish: list(access.publish, "access.publish", ["asks", "digests"])
     },
-    runtime: { features: [], resources: "standard", maxDuration: "15m" },
+    runtime: {
+      features: [],
+      resources: "standard",
+      maxDuration: runtime.maxDuration ?? "60m"
+    },
     retry: { maxAttempts: 1 },
     assets: [...assets].sort()
   };
@@ -732,7 +785,7 @@ function parseRoutineAccess(value) {
 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)))
+  if (["invalid_json", "invalid_response", "empty_text", "structured_output_limit"].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") {
@@ -748,6 +801,7 @@ function parseRoutineAIOutputIssue(value) {
   }
 }
 function routineAIOutputMessage(issue) {
+  if (issue.reason === "structured_output_limit") return "AI couldn\u2019t produce an answer matching the requested format within its submission limit.";
   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.";
@@ -789,11 +843,83 @@ function routineAIOutputMessage(issue) {
   ${field}: expected ${expected}; received ${received}.`;
 }
 
+function parseRoutineAIErrorDetail(code, value) {
+  if (code === "invalid_output") return parseRoutineAIOutputIssue(value);
+  if (!value || typeof value != "object" || Array.isArray(value)) return;
+  let v = value, only2 = (...keys4) => Object.keys(v).every((key) => ["reason", ...keys4].includes(key));
+  if (code === "provider_failure") {
+    if (v.reason === "turn_limit" && only2("limit") && Number.isSafeInteger(v.limit) && Number(v.limit) >= 1 && Number(v.limit) <= 1024)
+      return { reason: "turn_limit", limit: v.limit };
+    if (v.reason === "runner_exit" && only2("exitCode") && (v.exitCode === void 0 || Number.isSafeInteger(v.exitCode) && Number(v.exitCode) >= 1 && Number(v.exitCode) <= 255))
+      return { reason: "runner_exit", ...v.exitCode === void 0 ? {} : { exitCode: v.exitCode } };
+    if (only2() && ["runner_error", "invalid_runner_response", "unexpected_runner_configuration"].includes(String(v.reason)))
+      return { reason: v.reason };
+  }
+  if (code === "invalid_input" && only2() && ["invalid_tools", "tools_require_file"].includes(String(v.reason)))
+    return { reason: v.reason };
+  if (code === "unsupported_file" && v.reason === "unsupported_media_type" && only2("mediaType") && typeof v.mediaType == "string" && isCanonicalOriginalMediaType(v.mediaType))
+    return { reason: "unsupported_media_type", mediaType: v.mediaType };
+}
+function routineAIErrorMessage(code, value) {
+  let detail = parseRoutineAIErrorDetail(code, value);
+  if (code === "invalid_output" && detail) return routineAIOutputMessage(detail);
+  if (detail) switch (detail.reason) {
+    case "turn_limit":
+      return `AI stopped before finishing the request.
+It reached the ${detail.limit}-turn limit.`;
+    case "runner_exit":
+      return `AI couldn\u2019t complete the request.
+The local AI runner stopped before returning a usable answer.`;
+    case "runner_error":
+      return `AI couldn\u2019t complete the request.
+The local AI runner reported an error. No more specific reason was available.`;
+    case "invalid_runner_response":
+      return `AI couldn\u2019t complete the request.
+The local AI runner did not return a complete, readable response.`;
+    case "unexpected_runner_configuration":
+      return `OS couldn\u2019t accept the AI response.
+The runner\u2019s model, tools or configuration did not match the permitted setup.`;
+    case "invalid_tools":
+      return `The AI request is invalid.
+Set tools to true or false.`;
+    case "tools_require_file":
+      return `The AI request is invalid.
+Using tools requires a File input.`;
+    case "unsupported_media_type":
+      return `AI couldn\u2019t read this file.
+Its media type is ${detail.mediaType}, which this input path doesn\u2019t support.
+
+Check the file\u2019s stored media type before retrying. The model was not called.`;
+  }
+  switch (code) {
+    case "access_denied":
+      return "This routine doesn\u2019t currently have permission to use AI.";
+    case "capability_unavailable":
+      return "AI is unavailable in this execution environment.";
+    case "invalid_input":
+      return "The AI request is invalid. Check its input, instructions and schema.";
+    case "unsupported_file":
+      return "AI couldn\u2019t read this file in the requested format.";
+    case "file_unavailable":
+      return "AI couldn\u2019t read or verify the file.";
+    case "input_too_large":
+      return "The AI input exceeds the size limit for this execution path.";
+    case "output_too_large":
+      return "The AI response exceeds the size limit for this execution path.";
+    case "provider_failure":
+      return "AI couldn\u2019t complete the request. No more specific reason was recorded.";
+    case "invalid_output":
+      return "AI returned an answer OS could not accept.";
+    case "cancelled":
+      return "The AI operation was stopped before it completed.";
+  }
+}
+
 var ROUTINE_AI_VALUE_BYTES = 256 * 1024, ROUTINE_AI_RESULT_BYTES = 6 * ROUTINE_AI_VALUE_BYTES + 1024, ROUTINE_AI_EVIDENCE_BYTES = 4 * 1024;
 var AIError = class extends Error {
   constructor(code, options = {}) {
-    let detail = code === "invalid_output" ? parseRoutineAIOutputIssue(options.detail) : void 0;
-    super(detail ? routineAIOutputMessage(detail) : code);
+    let detail = parseRoutineAIErrorDetail(code, options.detail);
+    super(routineAIErrorMessage(code, detail));
     this.code = code;
     this.name = "AIError", 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 });
   }
@@ -813,13 +939,18 @@ function capture(value, invalid9, oversized, limit = ROUTINE_AI_VALUE_BYTES) {
 function parseRoutineAIRequest(value) {
   let v = capture(value, "invalid_input", "input_too_large");
   try {
-    if (assertRoutineFields(v, v.kind === "generateObject" ? ["kind", "instructions", "input", "schema"] : ["kind", "instructions", "input"]), !["generateText", "generateObject"].includes(v.kind) || typeof v.instructions != "string" || !v.instructions.trim()) throw new Error();
+    if (assertRoutineFields(v, v.kind === "generateObject" ? ["kind", "instructions", "input", "schema", "tools"] : ["kind", "instructions", "input", "tools"]), !["generateText", "generateObject"].includes(v.kind) || typeof v.instructions != "string" || !v.instructions.trim()) throw new Error();
     let input = typeof v.input == "string" ? v.input : parseFileDescriptor(v.input);
-    if (v.kind === "generateText") return freezeRoutineMetadata({ kind: v.kind, instructions: v.instructions, input });
+    if (Object.hasOwn(v, "tools") && typeof v.tools != "boolean")
+      throw new AIError("invalid_input", { detail: { reason: "invalid_tools" } });
+    if (v.tools === !0 && typeof input == "string")
+      throw new AIError("invalid_input", { detail: { reason: "tools_require_file" } });
+    let tools = v.tools === !0 ? { tools: !0 } : {};
+    if (v.kind === "generateText") return freezeRoutineMetadata({ kind: v.kind, instructions: v.instructions, input, ...tools });
     let schema2 = parseAppRoutineContract({ routine: "ai", input: v.schema, steps: [{ id: "generate" }] }).input;
-    return freezeRoutineMetadata({ kind: v.kind, instructions: v.instructions, input, schema: schema2 });
-  } catch {
-    throw new AIError("invalid_input");
+    return freezeRoutineMetadata({ kind: v.kind, instructions: v.instructions, input, schema: schema2, ...tools });
+  } catch (error) {
+    throw error instanceof AIError ? error : new AIError("invalid_input");
   }
 }
 function parseRoutineAIResult(request2, value) {
@@ -995,11 +1126,12 @@ async function executeRoutineDefinition(definition, input, runtime) {
       if (!runtime.ai) throw new AIError("capability_unavailable");
       let request2;
       try {
-        assertRoutineFields(value, kind === "generateObject" ? ["instructions", "input", "schema"] : ["instructions", "input"]), request2 = parseRoutineAIRequest({
+        assertRoutineFields(value, kind === "generateObject" ? ["instructions", "input", "schema", "tools"] : ["instructions", "input", "tools"]), request2 = parseRoutineAIRequest({
           kind,
           instructions: value.instructions,
           input: value.input,
-          ...kind === "generateObject" ? { schema: schemaMetadata(value.schema).schema } : {}
+          ...kind === "generateObject" ? { schema: schemaMetadata(value.schema).schema } : {},
+          ...value.tools === void 0 ? {} : { tools: value.tools }
         });
       } catch (error) {
         throw error instanceof AIError ? error : new AIError("invalid_input");
@@ -1021,10 +1153,16 @@ async function executeRoutineDefinition(definition, input, runtime) {
   }) : value, validateHandlers = (value) => {
     for (let question2 of value.questions ?? []) if (question2.handler && !contract.responses.some((handler) => handler.id === question2.handler.id)) return invalid3();
     return value;
-  }, os2 = Object.freeze({
+  }, activeStep, progress2 = /* @__PURE__ */ new Map(), os2 = Object.freeze({
     ...guarded({
       ...runtime,
-      run: freezeRoutineMetadata({ ...runtime.run }),
+      run: freezeRoutineMetadata({ id: runtime.run.id, async progress(value) {
+        assertRoutineFields(value, ["completed", "total"]);
+        let { completed, total } = value, prior = activeStep ? progress2.get(activeStep) : void 0;
+        if (!active2 || broken || !activeStep || !Number.isSafeInteger(completed) || !Number.isSafeInteger(total) || completed < 1 || completed > total || prior && (prior.total !== total || completed <= prior.completed)) return invalid3();
+        let accepted = freezeRoutineMetadata({ step: activeStep, completed, total });
+        await runtime.run.progress(accepted), progress2.set(activeStep, accepted);
+      } }),
       ai: {
         generateText: (value) => generate("generateText", value),
         generateObject: (value) => generate("generateObject", value)
@@ -1049,13 +1187,13 @@ async function executeRoutineDefinition(definition, input, runtime) {
         if (broken) return invalid3();
         reached.add(id3);
         try {
-          await runtime.step(id3, { status: "running" });
+          await runtime.step(id3, { status: "running" }), activeStep = id3;
           let output = await steps[id3].run(saved, os2);
           if (assertRoutineFields(output, ["summary", "data"]), !Object.hasOwn(output, "summary") || !Object.hasOwn(output, "data")) return invalid3();
           let summary2 = captureJson(output.summary), data3 = captureJson(output.data);
-          return await runtime.step(id3, { status: "completed", summary: summary2, data: data3 }), freezeRoutineMetadata({ summary: summary2, data: data3 });
+          return await runtime.step(id3, { status: "completed", summary: summary2, data: data3 }), activeStep = void 0, freezeRoutineMetadata({ summary: summary2, data: data3 });
         } catch (error) {
-          throw broken = !0, await runtime.step(id3, { status: "failed" }), error;
+          throw broken = !0, activeStep = void 0, await runtime.step(id3, { status: "failed" }), error;
         }
       });
       return work = next.then(() => {
@@ -1541,7 +1679,7 @@ function capture3(value, ancestors = /* @__PURE__ */ new Set(), depth = 0) {
     ancestors.delete(value);
   }
 }
-function recordPagination(select) {
+function recordPagination(queryRecords) {
   function pages(query) {
     let captured = capture3(query), names = Object.keys(historyProperties(captured));
     for (let name2 of names) {
@@ -1563,7 +1701,7 @@ function recordPagination(select) {
         let request2 = Object.fromEntries(active2.map((name2) => {
           let selection2 = captured[name2], next = state.get(name2).next;
           return [name2, next === void 0 ? selection2 : { ...selection2, $: { ...selection2.$, after: next } }];
-        })), response2 = await select(request2), page;
+        })), response2 = await queryRecords(request2), page;
         try {
           page = capture3(response2);
           let keys4 = Object.keys(historyProperties(page));
@@ -1647,7 +1785,7 @@ var genericData = {
       let refs = captureRecordsReadRefs(typeof input == "string" ? [input] : input), captured = captureRecordsReadOptions(options), result2 = await send3({ operation: "records.read", refs, ...options === void 0 ? {} : { options: captured } });
       return typeof input == "string" ? result2.records[0] : result2;
     }
-    let select = (query) => send3({ operation: "records.select", query });
+    let queryRecords = (query) => send3({ operation: "records.query", query });
     return {
       collections: {
         list: () => send3({ operation: "collections.list" }),
@@ -1655,8 +1793,8 @@ var genericData = {
       },
       records: {
         read: read2,
-        select,
-        ...recordPagination(select),
+        query: queryRecords,
+        ...recordPagination(queryRecords),
         search: async (query, options) => send3({ operation: "records.search", ...captureRecordsSearchInput(query, options) })
       },
       history: {
@@ -2301,16 +2439,16 @@ function parseConnectionLease(raw, now = Date.now()) {
   if (!v || typeof v != "object" || Array.isArray(v) || !connectionUuid(v.connectionId) || !connectionUuid(v.runId) || typeof v.name != "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(v.name) || typeof v.accessToken != "string" || !/^[A-Za-z0-9._~+/-]{1,8192}={0,2}$/.test(v.accessToken))
     throw new Error("Invalid connection credential");
   if (v.provider === "outlook" || v.provider === "sharepoint") {
-    if (!(v.provider === "outlook" ? Object.keys(v).sort().join(",") === "accessToken,connectionId,expiresAt,mailboxEmail,name,provider,runId" && validMicrosoftMailbox(v.mailboxEmail) : Object.keys(v).sort().join(",") === "accessToken,connectionId,expiresAt,name,provider,runId,siteId,siteUrl" && typeof v.siteUrl == "string" && canonicalSharePointSiteUrl(v.siteUrl) === v.siteUrl && validSharePointSiteId(v.siteId, v.siteUrl)) || typeof v.expiresAt != "string" || !Number.isFinite(Date.parse(v.expiresAt)) || Date.parse(v.expiresAt) <= now + 6e4 || Date.parse(v.expiresAt) > now + 36e5)
+    if (!(v.provider === "outlook" ? Object.keys(v).sort().join(",") === "accessToken,connectionId,expiresAt,mailboxEmail,name,provider,runId" && validMicrosoftMailbox(v.mailboxEmail) : Object.keys(v).sort().join(",") === "accessToken,connectionId,expiresAt,name,provider,runId,siteId,siteUrl" && typeof v.siteUrl == "string" && canonicalSharePointSiteUrl(v.siteUrl) === v.siteUrl && validSharePointSiteId(v.siteId, v.siteUrl)) || typeof v.expiresAt != "string" || !Number.isFinite(Date.parse(v.expiresAt)) || Date.parse(v.expiresAt) <= now || Date.parse(v.expiresAt) > now + 36e5)
       throw new Error("Invalid connection credential");
     return v;
   }
   if (v.provider === "gmail") {
-    if (Object.keys(v).sort().join(",") !== "accessToken,accountEmail,connectionId,expiresAt,name,provider,runId,scopes" || typeof v.accountEmail != "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v.accountEmail) || !validGoogleScopes(v.scopes) || typeof v.expiresAt != "string" || !Number.isFinite(Date.parse(v.expiresAt)) || Date.parse(v.expiresAt) <= now + 6e4 || Date.parse(v.expiresAt) > now + 36e5)
+    if (Object.keys(v).sort().join(",") !== "accessToken,accountEmail,connectionId,expiresAt,name,provider,runId,scopes" || typeof v.accountEmail != "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v.accountEmail) || !validGoogleScopes(v.scopes) || typeof v.expiresAt != "string" || !Number.isFinite(Date.parse(v.expiresAt)) || Date.parse(v.expiresAt) <= now || Date.parse(v.expiresAt) > now + 36e5)
       throw new Error("Invalid connection credential");
     return v;
   }
-  if (v.provider === "airtable" && Object.keys(v).sort().join(",") === "accessToken,baseId,connectionId,name,provider,runExpiresAt,runId" && typeof v.baseId == "string" && /^app[A-Za-z0-9]+$/.test(v.baseId) && typeof v.runExpiresAt == "string" && Number.isFinite(Date.parse(v.runExpiresAt)) && Date.parse(v.runExpiresAt) > now + 6e4 && Date.parse(v.runExpiresAt) <= now + 15 * 6e4 || v.provider === "dropbox" && Object.keys(v).sort().join(",") === "access,accessToken,accountId,connectionId,expiresAt,name,provider,rootPath,runId,scopes" && typeof v.accountId == "string" && /^dbid:[A-Za-z0-9_-]{1,128}$/.test(v.accountId) && v.access === "full_dropbox" && validDropboxRootPath(v.rootPath) && validDropboxFileScopes(v.scopes) && typeof v.expiresAt == "string" && Number.isFinite(Date.parse(v.expiresAt)) && Date.parse(v.expiresAt) > now + 6e4 && Date.parse(v.expiresAt) <= now + 144e5)
+  if (v.provider === "airtable" && Object.keys(v).sort().join(",") === "accessToken,baseId,connectionId,name,provider,runExpiresAt,runId" && typeof v.baseId == "string" && /^app[A-Za-z0-9]+$/.test(v.baseId) && typeof v.runExpiresAt == "string" && Number.isFinite(Date.parse(v.runExpiresAt)) && Date.parse(v.runExpiresAt) > now && Date.parse(v.runExpiresAt) <= now + 15 * 6e4 || v.provider === "dropbox" && Object.keys(v).sort().join(",") === "access,accessToken,accountId,connectionId,expiresAt,name,provider,rootPath,runId,scopes" && typeof v.accountId == "string" && /^dbid:[A-Za-z0-9_-]{1,128}$/.test(v.accountId) && v.access === "full_dropbox" && validDropboxRootPath(v.rootPath) && validDropboxFileScopes(v.scopes) && typeof v.expiresAt == "string" && Number.isFinite(Date.parse(v.expiresAt)) && Date.parse(v.expiresAt) > now && Date.parse(v.expiresAt) <= now + 144e5)
     return v;
   throw new Error("Invalid connection credential");
 }
@@ -4173,6 +4311,11 @@ function times(value) {
 function bounded(value) {
   return assertRoutineJson(value), new TextEncoder().encode(JSON.stringify(value)).byteLength > 256 * 1024 ? invalid8() : value;
 }
+function progress(value) {
+  if (value === void 0) return {};
+  let v = record3(value);
+  return Object.keys(v).sort().join(",") !== "completed,total" || !Number.isSafeInteger(v.completed) || !Number.isSafeInteger(v.total) || v.completed < 1 || v.completed > v.total ? invalid8() : { progress: { completed: v.completed, total: v.total } };
+}
 function parseRunStep(value, expected) {
   let v = record3(value);
   return typeof v.id != "string" || !name.test(v.id) || expected !== void 0 && v.id !== expected || typeof v.title != "string" || !v.title.trim() || v.title.length > 256 || !["pending", "running", "completed", "failed", "skipped"].includes(v.status) ? invalid8() : {
@@ -4180,6 +4323,7 @@ function parseRunStep(value, expected) {
     title: v.title,
     status: v.status,
     ...times(v),
+    ...progress(v.progress),
     ...Object.hasOwn(v, "summary") ? { summary: bounded(v.summary) } : {},
     ...Object.hasOwn(v, "data") ? { data: bounded(v.data) } : {}
   };
@@ -4283,12 +4427,12 @@ async function request(key, suffix, init2, maximum = SUMMARY_BYTES, retained, re
 function summary(value, key, context, id3) {
   if (context.kind !== "local")
     try {
-      return (!only(value, "id,routine,placement,status,createdAt,startedAt,finishedAt,steps,result,failure") || !Array.isArray(value.steps) || value.steps.some((step) => !only(step, "id,title,status,startedAt,finishedAt,summary,detailAvailable")) || value.failure !== void 0 && !only(value.failure, "message")) && fail3("execution_unavailable"), parseRemoteRun(value, { routine: key, id: id3 });
+      return (!only(value, "id,routine,placement,status,createdAt,startedAt,finishedAt,steps,result,failure") || !Array.isArray(value.steps) || value.steps.some((step) => !only(step, "id,title,status,startedAt,finishedAt,progress,summary,detailAvailable")) || value.failure !== void 0 && !only(value.failure, "message")) && fail3("execution_unavailable"), parseRemoteRun(value, { routine: key, id: id3 });
     } catch {
       return fail3("execution_unavailable");
     }
   let run = value;
-  return (!only(run, "id,routine,placement,status,createdAt,startedAt,finishedAt,steps,result,failure,local") || typeof run.id != "string" || !uuid2.test(run.id) || id3 !== void 0 && run.id !== id3 || run.routine !== key || run.placement !== "local" || !["queued", "running", "succeeded", "failed"].includes(run.status) || !timestamp(run.createdAt) || !optionalTimes(run) || !Array.isArray(run.steps) || run.steps.length > 64 || run.steps.some((step) => !only(step, "id,title,status,startedAt,finishedAt,summary,detailAvailable") || typeof step.detailAvailable != "boolean" || !validStep(step)) || new Set(run.steps.map((step) => step.id)).size !== run.steps.length || Object.hasOwn(run, "result") && (run.status !== "succeeded" || !bounded2(run.result)) || run.failure !== void 0 && (run.status !== "failed" || !only(run.failure, "message") || !message(run.failure.message)) || run.local !== void 0 && !validLocalActivity(run.local)) && fail3("execution_unavailable"), run;
+  return (!only(run, "id,routine,placement,status,createdAt,startedAt,finishedAt,steps,result,failure,local") || typeof run.id != "string" || !uuid2.test(run.id) || id3 !== void 0 && run.id !== id3 || run.routine !== key || run.placement !== "local" || !["queued", "running", "succeeded", "failed"].includes(run.status) || !timestamp(run.createdAt) || !optionalTimes(run) || !Array.isArray(run.steps) || run.steps.length > 64 || run.steps.some((step) => !only(step, "id,title,status,startedAt,finishedAt,progress,summary,detailAvailable") || typeof step.detailAvailable != "boolean" || !validStep(step)) || new Set(run.steps.map((step) => step.id)).size !== run.steps.length || Object.hasOwn(run, "result") && (run.status !== "succeeded" || !bounded2(run.result)) || run.failure !== void 0 && (run.status !== "failed" || !only(run.failure, "message") || !message(run.failure.message)) || run.local !== void 0 && !validLocalActivity(run.local)) && fail3("execution_unavailable"), run;
 }
 function only(value, allowed) {
   return !!value && typeof value == "object" && !Array.isArray(value) && Object.keys(value).every((key) => allowed.split(",").includes(key));
@@ -4298,7 +4442,7 @@ function optionalTimes(value) {
   return (value.startedAt === void 0 || timestamp(value.startedAt)) && (value.finishedAt === void 0 || timestamp(value.finishedAt));
 }
 function validStep(step) {
-  return typeof step.id == "string" && identifier.test(step.id) && typeof step.title == "string" && step.title.length > 0 && step.title.length <= 256 && ["pending", "running", "completed", "failed", "skipped"].includes(step.status) && optionalTimes(step) && (!Object.hasOwn(step, "summary") || bounded2(step.summary)) && (!Object.hasOwn(step, "data") || bounded2(step.data));
+  return typeof step.id == "string" && identifier.test(step.id) && typeof step.title == "string" && step.title.length > 0 && step.title.length <= 256 && ["pending", "running", "completed", "failed", "skipped"].includes(step.status) && optionalTimes(step) && (step.progress === void 0 || only(step.progress, "completed,total") && Number.isSafeInteger(step.progress.completed) && Number.isSafeInteger(step.progress.total) && step.progress.completed > 0 && step.progress.completed <= step.progress.total) && (!Object.hasOwn(step, "summary") || bounded2(step.summary)) && (!Object.hasOwn(step, "data") || bounded2(step.data));
 }
 function validLocalActivity(value) {
   let paths = (value2) => Array.isArray(value2) && value2.every((path) => typeof path == "string" && path.length > 0 && path.length <= 4096 && !path.startsWith("/") && !path.includes("\\") && !path.split("/").some((part) => !part || part === "." || part === "..") && !/[\x00-\x1f\x7f]/.test(path));
@@ -4339,11 +4483,11 @@ function handle(key, id3, context) {
       let value = await request(key, `runs/${id3}/steps/${step}`, void 0, 514 * 1024, context, !0);
       if (context.kind !== "local")
         try {
-          return only(value, "id,title,status,startedAt,finishedAt,summary,data") || fail3("execution_unavailable"), parseRunStep(value, step);
+          return only(value, "id,title,status,startedAt,finishedAt,progress,summary,data") || fail3("execution_unavailable"), parseRunStep(value, step);
         } catch {
           return fail3("execution_unavailable");
         }
-      return (!only(value, "id,title,status,startedAt,finishedAt,summary,data") || value.id !== step || !validStep(value)) && fail3("execution_unavailable"), value;
+      return (!only(value, "id,title,status,startedAt,finishedAt,progress,summary,data") || value.id !== step || !validStep(value)) && fail3("execution_unavailable"), value;
     }
   });
 }