@oddington/sdk 0.1.40 → 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' },