@zackbart/connecta 0.29.0 → 0.30.0

package/dist/skills.js

@@ -5,7 +5,7 @@ import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { closeScopeOnExit } from "./runtime/connector-scope.js";
 import { sentSecretsForRequest } from "./sent-secrets.js";
 const ROUTE = "Choose a route before discovery. One known-address read uses call_tool; one known-address write uses call_destructive_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Sample unfamiliar reads.";
-const RECOVERY = 'After auth_required use authorize_connector. After a truncated direct result use connecta.result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
+const RECOVERY = 'When an auth error includes a handoff, give it to the user or operator. Use authorize_connector for a fresh link. Page resultId notices and format:"paged" handles with connecta.result(handleOrId, { page? }). Fetch skills({ name: "usage" }) only for missing guidance or program repair.';
 /**
  * The always-loaded MCP `instructions` string. A program runs reads and the
  * writes in trusted pools; a read-only pool routes every write to top-level
@@ -348,11 +348,14 @@ async function localRecords(connectors) {
         const description = connectorGuideSummary(connector);
         const root = `skill://connecta/connectors/${encodeURIComponent(name)}`;
         const content = `---\n${JSON.stringify({ name, description }, null, 2)}\n---\n\n${connectorGuide(connector)}`;
-        return localRecord(name, `${root}/SKILL.md`, description, content, [
-            connectorSkillName(connector.id),
-            `skill://connecta/connectors/${encodeURIComponent(connector.id)}`,
-            root,
-        ]);
+        return {
+            ...localRecord(name, `${root}/SKILL.md`, description, content, [
+                connectorSkillName(connector.id),
+                `skill://connecta/connectors/${encodeURIComponent(connector.id)}`,
+                root,
+            ]),
+            connector,
+        };
     }));
     if (new Set(guides.map((guide) => guide.entry.uri)).size !== guides.length)
         throw new ConnectorCallError("unavailable", "Connector skill slugs collide.");
@@ -583,18 +586,18 @@ export class SkillsRegistry {
         return record;
     }
     missing(name) {
-        const available = [
-            "usage",
-            ...this.registry
-                .listConnectors()
-                .filter((connector) => connectorGuide(connector) !== undefined)
-                .map((connector) => connectorSkillName(connector.id)),
-            "investigate",
-        ].join(", ");
+        const guides = this.registry.listConnectors().filter((connector) => connectorGuide(connector) !== undefined);
+        // The recovery message exposes these guide names even though no skill was
+        // read. Keep their visibility bindings if a guest catches and returns it.
+        for (const connector of guides)
+            this.options.onRead?.(connector, "local");
+        const available = ["usage", ...guides.map((connector) => connectorSkillName(connector.id)), "investigate"].join(", ");
         // Caller-authored URI/error text never enters operator records. Preserve
         // legacy guidance without allowing a missing name to probe a hidden view.
         const id = name.startsWith(CONNECTOR_SKILL_PREFIX) ? name.slice(CONNECTOR_SKILL_PREFIX.length) : name;
         const connector = this.registry.getConnector(id);
+        if (connector)
+            this.options.onRead?.(connector, "local");
         const message = name.startsWith(CONNECTOR_SKILL_PREFIX)
             ? connector
                 ? `Connector "${boundedEchoText(id)}" has no usage guide.`
@@ -638,7 +641,11 @@ export class SkillsRegistry {
         if (local) {
             const record = await withManifest(local);
             this.assertSafe([record]);
-            return { ...PRIVATE, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text: record.content }] };
+            if (record.connector)
+                this.options.onRead?.(record.connector, "local");
+            // A connector guide is operator-authored payload, like a downstream file; built-in guides are Connecta's own.
+            const text = record.connector ? sentSecretsForRequest(this.scope).redact(record.content) : record.content;
+            return { ...PRIVATE, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text }] };
         }
         if (!uri.startsWith("skill://downstream/"))
             throw this.missing(uri);
@@ -664,7 +671,10 @@ export class SkillsRegistry {
         }
         if (bytes > MAX_SKILL_BYTES)
             throw new ConnectorCallError("unavailable", "Downstream skill file exceeds the byte bound.");
-        return { ...PRIVATE, contents: [{ ...content, uri }] };
+        this.options.onRead?.(record.connector, "downstream");
+        // Downstream file contents take the request's full payload rules before any reader sees them.
+        const clean = sentSecretsForRequest(this.scope).redact(content);
+        return { ...PRIVATE, contents: [{ ...clean, uri }] };
     }
     async text(name) {
         const record = await this.lookup(name);

package/dist/sqlite.js

@@ -135,15 +135,22 @@ export function importStateFile(database, statePath, now = Date.now()) {
             throw new TypeError(`${statePath} is not a connecta state file: entry ${index + 1} has no string value`);
         }
     }
-    const db = typeof database === "string" ? openSqlite(database) : database;
+    let db;
+    let transaction = false;
+    let step = "open the SQLite database";
     const result = { imported: 0, kept: 0, expired: 0 };
-    db.exec("BEGIN IMMEDIATE");
     try {
+        db = typeof database === "string" ? openSqlite(database) : database;
+        step = "begin the import transaction";
+        db.exec("BEGIN IMMEDIATE");
+        transaction = true;
+        step = "prepare the key-value table";
         for (const statement of KV_SCHEMA)
             db.exec(statement);
         const insert = db.prepare(`INSERT INTO connecta_kv (key, value, expires_at_ms) VALUES (?, ?, ?)
        ON CONFLICT (key) DO NOTHING`);
-        for (const [key, entry] of entries) {
+        for (const [index, [key, entry]] of entries.entries()) {
+            step = `import entry ${index + 1} into the key-value table`;
             const { value, exp } = entry;
             if (exp !== undefined && exp <= now) {
                 result.expired += 1;
@@ -156,11 +163,19 @@ export function importStateFile(database, statePath, now = Date.now()) {
                 result.kept += 1;
             }
         }
+        step = "commit the import transaction";
         db.exec("COMMIT");
     }
-    catch (error) {
-        db.exec("ROLLBACK");
-        throw error;
+    catch {
+        if (transaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Rollback errors can contain stored text too. Report the failed step.
+            }
+        }
+        throw new Error(`State import failed: could not ${step}`);
     }
     return result;
 }

package/dist/storage/keys.js

@@ -75,8 +75,8 @@ export const resultKeys = {
 };
 // --- root families --------------------------------------------------------
 /**
- * The runtime-wide result stash ledger: every live stash entry's partition
- * key, byte charge, and expiry. One record, swapped by compare-and-set, so the
+ * The runtime-wide result stash ledger: every live stash entry's reservation
+ * id, byte charge, and expiry. One record, swapped by compare-and-set, so the
  * stash bounds hold across isolates and processes sharing the store.
  */
 export const stashLedgerKeys = {
@@ -86,13 +86,27 @@ export const stashLedgerKeys = {
         prefixes: ["result-stash:v1:"],
         version: { number: 1, in: "key" },
         codec: jsonCodec,
-        // Durable as a record, self-pruning by content: an entry leaves the
-        // ledger once its result's TTL has passed.
-        ttl: { kind: "durable" },
+        // Every reservation is finite; the row expires with its latest charge.
+        ttl: { kind: "configured", by: "latest live stash reservation deadline" },
         durable: false,
     },
     ledger: "result-stash:v1:ledger",
 };
+/** Storage-side proof that a stash charge's absolute deadline has passed. */
+export const stashExpiryKeys = {
+    family: {
+        name: "result-stash-expiry",
+        scope: "root",
+        prefixes: ["result-stash-expiry:v1:"],
+        version: { number: 1, in: "key" },
+        codec: textCodec,
+        ttl: { kind: "configured", by: "probed stash charge deadline" },
+        durable: false,
+    },
+    // Different deadlines cannot overwrite one another's proof. Repeated probes
+    // of the same deadline always use the same value and absolute expiry.
+    deadline: (expiresAtMs) => `result-stash-expiry:v1:${expiresAtMs}`,
+};
 /**
  * A persisted downstream catalog: the manifest at `catalog:<id>`, then its
  * chunks at `catalog:<id>:chunk:<revision>:<index>`.
@@ -379,6 +393,7 @@ export const inputRetryKeys = {
 export const KEY_FAMILIES = [
     resultKeys.family,
     stashLedgerKeys.family,
+    stashExpiryKeys.family,
     catalogKeys.family,
     responseCacheKeys.family,
     oauthHandoffKeys.family,

package/dist/storage/memory.js

@@ -13,11 +13,15 @@ export function memoryStorage() {
         }
         return e;
     };
-    const write = (key, value, ttlSeconds) => {
+    const write = (key, value, opts) => {
+        const { ttlSeconds, expiresAtMs } = opts ?? {};
+        if (expiresAtMs !== undefined && (!Number.isSafeInteger(expiresAtMs) || ttlSeconds !== undefined)) {
+            throw new RangeError("expiresAtMs must be a safe integer epoch timestamp without ttlSeconds");
+        }
         if (ttlSeconds !== undefined && !Number.isFinite(ttlSeconds)) {
             throw new RangeError("ttlSeconds must produce a finite expiration timestamp");
         }
-        const exp = ttlSeconds ? Date.now() + ttlSeconds * 1000 : undefined;
+        const exp = expiresAtMs ?? (ttlSeconds ? Date.now() + ttlSeconds * 1000 : undefined);
         if (exp !== undefined && !Number.isFinite(exp)) {
             throw new RangeError("ttlSeconds must produce a finite expiration timestamp");
         }
@@ -37,6 +41,7 @@ export function memoryStorage() {
         });
     };
     return {
+        capabilities: { absoluteExpiry: true },
         describe: () => ({ kind: "memory" }),
         async get(key) {
             validateStorageKey(key);
@@ -44,7 +49,7 @@ export function memoryStorage() {
         },
         async set(key, value, opts) {
             validateStorageKey(key);
-            write(key, value, opts?.ttlSeconds);
+            write(key, value, opts);
         },
         async delete(key) {
             validateStorageKey(key);
@@ -68,7 +73,7 @@ export function memoryStorage() {
             if (next === null)
                 map.delete(key);
             else
-                write(key, next, opts?.ttlSeconds);
+                write(key, next, opts);
             return true;
         },
     };

package/dist/storage/sql.js

@@ -95,12 +95,21 @@ export function sqlStorage(driver, kind) {
     // SQLite and D1 evaluate 'now' in the database, never in a caller isolate.
     const now = "CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)";
     const live = `(expires_at_ms IS NULL OR expires_at_ms > ${now})`;
-    const expiryValue = `(${now} + ?)`;
+    const expiryOptions = (opts) => {
+        if (opts?.expiresAtMs !== undefined) {
+            if (!Number.isSafeInteger(opts.expiresAtMs) || opts.ttlSeconds !== undefined) {
+                throw new RangeError("expiresAtMs must be a safe integer epoch timestamp without ttlSeconds");
+            }
+            return { value: opts.expiresAtMs, expression: "?" };
+        }
+        return { value: ttlMillis(opts?.ttlSeconds), expression: `(${now} + ?)` };
+    };
     const current = async (key) => {
         const [row] = await driver.all(sql(`SELECT ${textColumn("value")} FROM connecta_kv WHERE key = ? AND ${live}`, key));
         return row ? textOf(row.value, row.value_bytes, `the stored value of ${JSON.stringify(key)}`) : null;
     };
     return {
+        capabilities: { absoluteExpiry: true },
         describe: () => ({ kind }),
         async get(key) {
             validateStorageKey(key);
@@ -110,15 +119,15 @@ export function sqlStorage(driver, kind) {
         async set(key, value, opts) {
             validateStorageKey(key);
             await ensure();
-            const expiry = ttlMillis(opts?.ttlSeconds);
+            const expiry = expiryOptions(opts);
             await driver.batch([
                 sql(`DELETE FROM connecta_kv WHERE key IN (
             SELECT key FROM connecta_kv WHERE expires_at_ms <= ${now} LIMIT ${SWEEP_ROWS}
           )`),
                 sql(`INSERT INTO connecta_kv (key, value, expires_at_ms)
-           VALUES (?, ?, ${expiryValue})
+           VALUES (?, ?, ${expiry.expression})
            ON CONFLICT (key) DO UPDATE SET
-             value = excluded.value, expires_at_ms = excluded.expires_at_ms`, key, value, expiry),
+             value = excluded.value, expires_at_ms = excluded.expires_at_ms`, key, value, expiry.value),
             ]);
         },
         async delete(key) {
@@ -149,7 +158,7 @@ export function sqlStorage(driver, kind) {
             }
             let expiry;
             try {
-                expiry = ttlMillis(opts?.ttlSeconds);
+                expiry = expiryOptions(opts);
             }
             catch (error) {
                 // Invalid write options do not change a failed comparison's result.
@@ -162,14 +171,14 @@ export function sqlStorage(driver, kind) {
                 // Insert, or take over a row that has expired. A live row makes the
                 // upsert's WHERE false, so nothing changes and the claim is refused.
                 return ((await driver.run(sql(`INSERT INTO connecta_kv (key, value, expires_at_ms)
-           VALUES (?, ?, ${expiryValue})
+           VALUES (?, ?, ${expiry.expression})
            ON CONFLICT (key) DO UPDATE SET
              value = excluded.value, expires_at_ms = excluded.expires_at_ms
            WHERE connecta_kv.expires_at_ms IS NOT NULL
-             AND connecta_kv.expires_at_ms <= ${now}`, key, next, expiry))) > 0);
+             AND connecta_kv.expires_at_ms <= ${now}`, key, next, expiry.value))) > 0);
             }
-            return ((await driver.run(sql(`UPDATE connecta_kv SET value = ?, expires_at_ms = ${expiryValue}
-         WHERE key = ? AND ${live} AND value = ?`, next, expiry, key, expected))) > 0);
+            return ((await driver.run(sql(`UPDATE connecta_kv SET value = ?, expires_at_ms = ${expiry.expression}
+         WHERE key = ? AND ${live} AND value = ?`, next, expiry.value, key, expected))) > 0);
         },
     };
 }

package/dist/types.d.ts

@@ -7,15 +7,28 @@ export type JsonSchema = Record<string, unknown>;
  * before accessing storage. SQL TEXT results truncate at NUL on Node 22.
  */
 export interface KVStorage {
+    /**
+     * Explicit adapter opt-in: both `set` and `compareAndSet` honor
+     * `expiresAtMs`, including delayed commits. `createConnecta` rejects adapters
+     * without this capability. Declare it only after implementing that contract.
+     */
+    readonly capabilities: {
+        readonly absoluteExpiry: true;
+    };
     /** The live value at `key`; null when absent or expired. */
     get(key: string): Promise<string | null>;
     /**
      * Write `value`. With `opts.ttlSeconds` the entry reads as absent once that
      * many seconds pass; omitted or zero means no expiry. Shared stores must
-     * create and check expiry with a storage-owned clock, not each caller's clock.
+     * create and check relative expiry with a storage-owned clock. `expiresAtMs`
+     * instead sets an absolute, safe-integer epoch-millisecond expiry, including
+     * for a delayed commit. Adapters must honor it without restarting a TTL at
+     * commit time. Supply at most one of these options; a past absolute expiry
+     * writes an already-expired value.
      */
     set(key: string, value: string, opts?: {
         ttlSeconds?: number;
+        expiresAtMs?: number;
     }): Promise<void>;
     delete(key: string): Promise<void>;
     /** Live keys beginning with `prefix`, sorted by UTF-16 code unit. */
@@ -24,8 +37,8 @@ export interface KVStorage {
      * Atomic compare-and-set: write `next` only if the key's current value is
      * exactly `expected`, and report whether the write happened. `expected:
      * null` means "absent", and an expired entry is absent. `next: null`
-     * deletes; otherwise `next` is stored with `options.ttlSeconds`, or with no
-     * expiry when that is omitted, exactly as `set` would. On `false` nothing
+     * deletes; otherwise `next` takes the relative or absolute expiry options
+     * exactly as `set` would, or no expiry when both are omitted. On `false` nothing
      * changed.
      *
      * Atomic means linearizable against every other operation on the same
@@ -41,6 +54,7 @@ export interface KVStorage {
      */
     compareAndSet(key: string, expected: string | null, next: string | null, options?: {
         ttlSeconds?: number;
+        expiresAtMs?: number;
     }): Promise<boolean>;
     /**
      * Which adapter this is, for `Connecta.describeConfig()`. The shipped

package/dist/usage-guide.js

@@ -14,56 +14,51 @@ description: How to route work between one execute_code program and Connecta's e
 | One known-address write | call_destructive_tool |
 | Discovery, multiple or dependent calls, paging, reduction | execute_code |
 
-For example, read account acct_42 with call_tool arguments
-\`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
-Discover and call in the same program when schemas suffice. Top-level search_tools
-covers catalog inspection and write discovery in read-only pools. Programs may
+Read one account with call_tool: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
+Discover and call together when schemas suffice. search_tools covers catalog
+inspection and write discovery in read-only pools. Programs may
 write only in trusted pools; the tool description states this endpoint's trust.
 Unannotated tools fail closed to writes.
 
 ## The global and the envelopes
 
-Pass one plain JavaScript async arrow, \`async () => { ... }\`. It receives no
-arguments. Use the supplied \`connecta\` global; do not shadow it with a parameter.
-No imports, require, filesystem, fetch, or timers in portable programs.
+Pass JavaScript \`async () => { ... }\`, no arguments. Do not shadow \`connecta\`.
+No imports, require, filesystem, fetch, or timers.
 
-\`connecta.call(address, args, { timeoutMs })\` is positional. The object overload
-is \`connecta.call({ address, args, timeoutMs })\`. Both return \`{ data, format }\`.
-For \`format: "json"\`, data is the JSON value. For \`format: "text"\`, data is a
-string: parse only if the provider documents JSON text. Never guess collection roots.
+Use \`connecta.call(address, args, { timeoutMs })\` or
+\`connecta.call({ address, args, timeoutMs })\`; both return \`{ data, format }\`.
+\`format: "json"\` carries JSON; \`format: "text"\` carries text. Parse text only
+when documented as JSON. Verify collection roots.
 
 \`connecta.read("resource://id/"+encodeURIComponent(uri))\` returns \`{ contents }\` for advertised URIs.
 
-Search and describe return \`{ tools }\`, never an array. Search also returns
+Search/describe return \`{ tools }\`, never an array. Search also returns
 \`catalogErrors\`, pagination, and possible \`absence\`; check failures before
 selecting a match. JSON schemas are the program default. Compact schemas have
 \`schemaFormat: "text"\`; do not read their .properties. Select the exact tool and
 account/environment, inspect its schema, and supply its required keys and types.
 
-Discover an unfamiliar run lookup, then reduce its JSON result:
+Discover an unfamiliar read and reduce its result:
 
 \`\`\`js
 async () => {
-  const page = await connecta.search({ connector: "ci", query: "get_run", safety: "readOnly" });
-  if (page.catalogErrors.length || page.absence) return { gap: page.catalogErrors, absence: page.absence };
+  const page = await connecta.search({ connector: "ci", query: "get_run" });
+  if (page.catalogErrors.length || page.absence) return page;
   const tool = page.tools.find(t => t.name === "get_run");
   if (!tool) return { gap: "get_run unavailable" };
-  const { tools } = await connecta.describe({ address: tool.address });
-  if (tools[0].error) return { gap: tools[0].error };
   const result = await connecta.call(tool.address, { runId: 42 });
-  if (result.format !== "json") return { gap: "Expected JSON" };
-  return { status: result.data.status, jobId: result.data.failedJobId };
+  return result.format === "json"
+    ? { status: result.data.status, jobId: result.data.failedJobId } : result;
 }
 \`\`\`
 
 ## Keep partial successes
 
-Await Promise.allSettled for independent calls when one failure must not discard
-other answers. Each rejected reason keeps \`code\`, \`message\`, \`retryable\`, and
-\`details\`. Branch on fields, never error prose. Repair one argument failure
-before repeating it across records. Every run reports hostCalls counts separately.
+Use Promise.allSettled to keep independent successes. Rejections retain \`code\`,
+\`message\`, \`retryable\`, and \`details\`. Branch on fields, not prose. Repair
+arguments before batching. Runs report hostCalls separately.
 
-After verifying these addresses and schemas, read JSON and plain text together:
+Read JSON and text after verifying addresses and schemas:
 
 \`\`\`js
 async () => {
@@ -83,7 +78,7 @@ async () => {
 Host-call budget exhaustion ends the run with budget_exceeded. Catch and
 allSettled cannot recover it or return partial output. Bound batches before
 starting them; search, describe, call, result, and skill spend host calls.
-Split remaining reads into another run. Never replay writes for their output.
+Split remaining reads. Never replay writes for their output.
 
 ## Per-connector guides
 
@@ -91,14 +86,21 @@ Fetch a listed guide with skills by its exact name, or \`connecta.skill(name)\`
 inside a program; it returns \`{ name, text, format: "text" }\`.
 \`guideRequired: true\` is a hard stop. connector_required and approval_required
 remain after schema expansion; schema_truncated clears after exact describe.
-Otherwise fetch for relevant units, pagination, aliases, or sequences.
+Otherwise fetch for units, pagination, aliases, or sequences.
 
 ## Large results and recovery
 
-A truncated direct result carries a resultId when paging is available. Follow
+Large direct results and program returns carry resultId when paging is available. Follow
 nextOffset in UTF-8 bytes, reassemble and reduce inside one program. Use the
 returned id in place of result-id below; this example assumes documented JSON.
 
+Calls reconstruct up to 1 MiB through stash pages. Larger values return
+\`{ format: "paged", valueFormat, resultId?, totalBytes, hint }\`. Pass the handle
+to \`connecta.result\`. No resultId means no paging. IDs expire after
+15 minutes; only explicit paging spends extra host calls.
+Use zero-based \`{ page: 0 }\` or UTF-8 \`{ offset }\`, never both. Keep maxBytes
+fixed across pages; connector caps and the 32 KiB bridge ceiling apply.
+
 \`\`\`js
 async () => {
   let text = "", offset = 0, page;
@@ -111,20 +113,24 @@ async () => {
 }
 \`\`\`
 
-Program returns have no page handle. Reduce reads before returning. After a
-write, use its existing result, check the target, or report the gap.
-write_outcome_unknown means a write was sent without a known answer: check the
-target, never resend automatically. Non-retryable errors require repair.
-Follow typed auth recovery: host_auth_required needs host connection repair;
-downstream_oauth_required or auth_required carries an authorize_connector
-handoff; provider_permission_denied needs the resource owner to grant access.
+Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown forbids retry, even if caught.
+Recovery args may be partial (argsRedacted) or absent (argsOmitted). Reconcile
+before retrying with the original args or repeating a program that sent writes.
+Non-retryable errors need repair.
+host_auth_required needs host connection repair; provider_permission_denied needs
+resource-owner access. Auth failures carry the handoff in error.data. When an auth
+error includes a handoff, give it to the user or operator.
 
 ## Output
 
-Return reduced JSON. console.log is captured. connecta.emit accepts text, image,
-or audio blocks, works without await, and delivers only after success. Images
-need canonical base64 and image/png, image/jpeg, image/gif, or image/webp.
-Text shares the result cap; the description states block and byte budgets.
+Use \`connecta.emit(await connecta.call(address, args))\` for MCP rich output,
+or \`for (const b of x.content ?? []) connecta.emit(b)\`. Both forward originals,
+including resources and metadata; edits do not change them. Page oversized
+native content with \`connecta.result(x.contentResult)\`.
+Authored blocks accept text or base64 image/audio; images require canonical
+base64 and PNG/JPEG/GIF/WebP MIME. Emit works without await, delivers on success,
+and obeys byte/block budgets; text shares the return cap. Return reduced JSON.
+
 `;
 /** Kept in sync with GuestApi by the declaration test. These are type notation, not runnable JS. */
 export const GUEST_API_DECLARATION = `search(args?: CatalogSearchArgs): Promise<CatalogSearchResult>;
@@ -132,6 +138,9 @@ describe(args?: CatalogDescribeArgs): Promise<{ tools: CatalogDescription[] }>;
 call(address: string, args?: unknown, options?: { timeoutMs?: number }): Promise<GuestResult>;
 call(request: { address: string; args?: unknown; timeoutMs?: number }): Promise<GuestResult>;
 read(uri: string): Promise<GuestResourceResult>;
-result(id: string, options?: { offset?: number; maxBytes?: number }): Promise<GuestResultPage>;
+result(
+  id: string | GuestResultHandle,
+  options?: { page?: number; offset?: number; maxBytes?: number },
+): Promise<GuestResultPage>;
 skill(name: string): Promise<{ name: string; text: string; format: "text" }>;
-emit(block: GuestBlock): PromiseLike<void>;`;
+emit(block: GuestNativeBlock | GuestResult): PromiseLike<void>;`;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.29.0";
+export declare const CONNECTA_VERSION = "0.30.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.29.0";
+export const CONNECTA_VERSION = "0.30.0";

package/dist/worker.js

@@ -160,7 +160,8 @@ export function workerExecutor(options) {
               defineProperties(error, {
                 code: { value: reply.error.code, enumerable: true },
                 retryable: { value: reply.error.retryable, enumerable: true },
-                details: { value: freeze(clone(reply.error.details)), enumerable: true }
+                details: { value: freeze(clone(reply.error.details)), enumerable: true },
+                data: { value: freeze(clone(reply.error.details)), enumerable: true }
               });
             }
             throw error;

package/documentation/README.md

@@ -0,0 +1,63 @@
+# Agent documentation
+
+Choose a route by the work you are doing. Each route identifies the task guide
+and contracts needed to operate an endpoint, set up a deployment, connect a
+service, or change Connecta itself.
+
+| Your task                                                             | Start here                                                            | Read next when needed                                                                                                                            |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Use an existing endpoint to answer a question or perform a task       | [Operating an endpoint](./operating.md)                               | [Meta-tools](./meta-tools.md), [guest API](./code-mode.md)                                                                                       |
+| Set up, configure, upgrade, or diagnose a deployment                  | [Deploying Connecta](./deploying.md)                                  | [Auth](./auth.md), [operator UI](./operator-ui.md)                                                                                               |
+| Add a maintained integration, remote MCP, or HTTP API to a deployment | [Integrating services](./integrating.md)                              | Provider skill, [classification](./architecture.md#providers-and-reviewed-classification), [downstream auth](./auth.md#shared-and-personal-auth) |
+| Change Connecta's source, tests, or published contracts               | [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md) | [Principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md), [architecture](./architecture.md), then the affected contract        |
+
+## Contract reference
+
+| Guide                                                       | Owns                                                                                                          |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [Meta-tools](./meta-tools.md)                               | Six top-level tools, discovery, direct-call results, paging, skills, and recovery                             |
+| [Code mode](./code-mode.md)                                 | JavaScript guest API, executor requirements, output, retries, cancellation, limits, and writes                |
+| [Auth](./auth.md)                                           | Inbound identity, grants, pools, machine tokens, credential ownership, and downstream OAuth                   |
+| [Architecture](./architecture.md)                           | Request lifetimes, routes, storage, configuration, import boundaries, and Effect implementation               |
+| [Operator UI](./operator-ui.md)                             | Optional UI setup, scoped configuration and live-data contract, activity disclosure, and UI implementation    |
+| [Operator UI tests](./operator-tests.md)                    | Browser state matrix, real-server flows, and snapshot maintenance                                             |
+| [Provider migration for 0.29](./provider-migration-0.29.md) | Upgrade actions for Notion, Vercel, and Cloudflare; provider reconciliation tables supply exact name mappings |
+
+Each long contract starts with task routes. Follow those section links before
+reading the whole guide. Source and test pointers identify where to check a
+claim or implement a change.
+
+## Documentation ownership
+
+The root [README](../README.md) explains the product for people. It owns what
+Connecta offers, how the pieces connect, deployment choices, and the setup
+handoff. Keep JavaScript, imports, configuration, migrations, and internal
+module maps here in agent documentation.
+
+[AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md) is the
+canonical repository policy, with `CLAUDE.md` as its symlink. Do not copy its
+verification, review, or release rules into another policy document.
+
+Deployment-local READMEs and agent instructions own runnable platform setup:
+[Node and Docker](../templates/node/README.md), [Workers](../examples/worker/README.md).
+Keep those aligned with their configuration and with this task router.
+Repository [skills](https://github.com/zackbart/connecta/tree/main/.claude/skills)
+own scoped change procedures. Each [provider folder](https://github.com/zackbart/connecta/tree/main/src/providers)
+owns its maintained `SKILL.md`, options, tests, fixtures, and review data.
+Use those details instead of copying provider catalogs into general guides.
+The provider list in the human README is generated; preserve its marker pair
+and run `npm run check:providers-generated` after edits.
+
+When changing behavior, update its owning contract and task guide in the same
+change. Check examples against current source and point to the tests that
+defend the contract. Published Markdown links to repo-only files must use
+canonical `https://github.com/zackbart/connecta/blob/main/…` or `tree/main/…`
+links. Keep `documentation/` flat, with Markdown files only.
+
+The [changelog](../CHANGELOG.md) records shipped releases.
+[Decisions](https://github.com/zackbart/connecta/tree/main/decisions) explain
+history and may be superseded. [Spec coverage](https://github.com/zackbart/connecta/blob/main/spec/coverage.json)
+records implemented support, gaps, and test evidence. The
+[0.29 plan of record](https://github.com/zackbart/connecta/issues/703) and other
+issues describe planned work; do not turn their goals into claims of shipped
+behavior.