@zackbart/connecta 0.40.0 → 0.42.0

package/dist/usage-guide.js

@@ -1,4 +1,5 @@
 import { META_ROUTES } from "./agent-routes.js";
+import { READ_PROGRAM_SOURCE } from "./tool-safety.js";
 import { UNCOUNTED_GUEST_FUNCTIONS } from "./guest-functions.js";
 /** Self-contained content for the usage skill; independent of skill registration. */
 export const USAGE_SKILL = `---
@@ -14,7 +15,7 @@ Route as the server instructions and ${META_ROUTES.program}'s first sentence say
 Read one account with ${META_ROUTES.read}: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
 On a read-only endpoint search omits writes (guides may name them) and each
 fails read_only_endpoint; tell the user. Unannotated tools fail closed to writes.
-Connecta classifies and routes a requested write; the host owns approval.
+Where listed, ${READ_PROGRAM_SOURCE} refuses writes, marked \`callable: false\`.
 
 ## The global and the envelopes
 
@@ -28,7 +29,7 @@ Parse \`format: "text"\` only when documented as JSON. Verify collection roots.
 \`connecta.read("resource://id/"+encodeURIComponent(uri))\` returns \`{ contents }\` for advertised URIs.
 
 Search/describe return \`{ tools }\`, never an array. Check search's
-\`catalogErrors\` and \`absence\` before selecting a match. Search defaults to a
+\`catalogErrors\` and \`absence\` before selecting a match; a \`stale: true\` error's tools are listed from an older catalog, and a call still checks the live one. Search defaults to a
 TypeScript \`signature\`; text schemas have \`schemaFormat: "text"\` and no .properties.
 A \`readyCalls\` entry is a complete read: \`connecta.call(entry.address, entry.args)\`. Select the exact tool and
 account/environment, inspect its schema, and supply its required keys and types.
@@ -85,14 +86,14 @@ Otherwise fetch for units, pagination, aliases, or sequences.
 
 ## Large results and recovery
 
-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.
+Large results carry resultId. Follow nextOffset in UTF-8 bytes, reassemble and reduce
+inside one program. Use that id for 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.
+Calls inline up to 1 MiB; larger return
+\`{ format: "paged", valueFormat, resultId?, totalBytes, hint }\`. Follow its hint:
+\`connecta.result(handle, { all: true })\` gives \`{ data, format }\` for one host call,
+or throws result_too_large; then page. IDs last 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.
 
@@ -100,7 +101,7 @@ fixed across pages; connector caps and the 32 KiB bridge ceiling apply.
 async () => {
   let text = "", offset = 0, page;
   do {
-    page = await connecta.result("result-id", { offset, maxBytes: 8000 });
+    page = await connecta.result("result-id", { offset });
     text += page.text;
     offset = page.nextOffset;
   } while (page.hasMore);
@@ -108,13 +109,13 @@ async () => {
 }
 \`\`\`
 
-Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown or writeOutcome forbids retry, even if caught.
+Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown or writeOutcome forbids retry, even if caught. Give the user any approval link in the tool's words; a call after approval is new.
 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.
+resource-owner access. Auth failures carry the handoff in error.data; give it to the
+user or operator.
 
 ## Output
 

package/dist/utility-recovery.js

@@ -0,0 +1,33 @@
+/** Actions outside the tool namespace never invent a route on a serving surface. */
+export function utilityRecovery(code, message, retryable = false) {
+    return {
+        code,
+        message,
+        retryable,
+        nextAction: {
+            action: ["unsupported_capability", "input_required_unsupported", "invalid_args"].includes(code)
+                ? "inspect_capabilities"
+                : code === "not_found"
+                    ? "recover_result"
+                    : "contact_operator",
+            purpose: ["unsupported_capability", "input_required_unsupported", "invalid_args"].includes(code)
+                ? "Inspect the supported utility input and client capabilities before a fresh call. Never repeat a write whose outcome is unknown."
+                : code === "not_found"
+                    ? "Use a retained result handle if available. Otherwise report the missing output; never repeat a write to recover output."
+                    : "Ask the operator to restore availability. Retry reads only after recovery; reconcile any write whose outcome is unknown.",
+        },
+    };
+}
+/** Missing skill names need local discovery, never service restoration or result recovery. */
+export function skillLookupRecovery(message) {
+    return {
+        code: "not_found",
+        message,
+        retryable: false,
+        nextAction: {
+            tool: "skills",
+            arguments: {},
+            purpose: "List available skills, then fetch an exact name from that list.",
+        },
+    };
+}

package/dist/validate.js

@@ -190,7 +190,7 @@ function receivedType(value) {
  * No caller values are used to invent an example, and a writeOnly position or
  * anything inside one never renders a schema literal. A candidate must validate.
  */
-function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, active: new Set() }, secret = false) {
+function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, active: new Set(), placeholders: false }, secret = false, key) {
     if (--budget.remaining < 0)
         throw new Error("Example synthesis budget exhausted");
     if (depth > 12 || schema === false)
@@ -224,7 +224,7 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
             candidate = Object.fromEntries(required
                 .filter((key) => typeof key === "string")
                 .slice(0, 30)
-                .map((key) => [key, exampleCandidate(properties[key], root, depth + 1, budget, secret)]));
+                .map((key) => [key, exampleCandidate(properties[key], root, depth + 1, budget, secret, key)]));
             if (Array.isArray(node.allOf)) {
                 for (const branch of node.allOf.slice(0, 20)) {
                     candidate = mergeExample(candidate, exampleCandidate(branch, root, depth + 1, budget, secret));
@@ -258,7 +258,7 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
             // Branches may declare required keys while their types live on the parent.
             for (const key of Object.keys(schemaObject(candidate))) {
                 if (schemaObject(candidate)[key] === undefined) {
-                    schemaObject(candidate)[key] = exampleCandidate(properties[key], root, depth + 1, budget, secret);
+                    schemaObject(candidate)[key] = exampleCandidate(properties[key], root, depth + 1, budget, secret, key);
                 }
             }
         }
@@ -290,10 +290,11 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
                 uri: "https://example.com",
                 uuid: "00000000-0000-4000-8000-000000000000",
             };
+            const named = budget.placeholders && !secret && key !== undefined ? namedPlaceholder(key, node) : undefined;
             candidate =
                 typeof node.format === "string" && formats[node.format]
                     ? formats[node.format]
-                    : "x".repeat(Math.min(typeof node.minLength === "number" ? node.minLength : 0, 128));
+                    : (named ?? "x".repeat(Math.min(typeof node.minLength === "number" ? node.minLength : 0, 128)));
         }
         return candidate;
     }
@@ -301,6 +302,19 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
         budget.active.delete(node);
     }
 }
+/**
+ * `<id>` for a plain string argument: an empty string would satisfy local
+ * validation and reach the downstream looking like a real value. A secret
+ * position, an odd key, and a length bound it misses keep the plain sample.
+ */
+function namedPlaceholder(key, node) {
+    if (!/^[\w.-]{1,64}$/.test(key))
+        return undefined;
+    const text = `<${key}>`;
+    const min = typeof node.minLength === "number" ? node.minLength : 0;
+    const max = typeof node.maxLength === "number" ? node.maxLength : Infinity;
+    return text.length >= min && text.length <= max ? text : undefined;
+}
 function mergeExample(a, b) {
     if (a !== null &&
         b !== null &&
@@ -501,12 +515,17 @@ function validationIssues(schema, args, units) {
 export function schemaExample(schema) {
     try {
         const validator = validators.get(schema) ?? new Validator(schema, "2020-12", false);
-        // Serialization makes the validation cover exactly what the agent receives.
-        const example = JSON.parse(JSON.stringify(exampleCandidate(schema, schema)));
-        if (validator.validate(example).valid) {
-            minimizeExample(example, validator);
-            if (validator.validate(example).valid)
-                return { example };
+        // Named placeholders first; a schema that refuses them, such as one with a
+        // pattern, falls back to the plain sample rather than losing its example.
+        for (const placeholders of [true, false]) {
+            const budget = { remaining: 128, active: new Set(), placeholders };
+            // Serialization makes the validation cover exactly what the agent receives.
+            const example = JSON.parse(JSON.stringify(exampleCandidate(schema, schema, 0, budget)));
+            if (validator.validate(example).valid) {
+                minimizeExample(example, validator);
+                if (validator.validate(example).valid)
+                    return { example };
+            }
         }
     }
     catch {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.40.0";
+export declare const CONNECTA_VERSION = "0.42.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.40.0";
+export const CONNECTA_VERSION = "0.42.0";

package/dist/worker.js

@@ -7,6 +7,7 @@ import { awaitExecutorLease, provideExecutorProgram, executorProgram } from "./r
 import { DynamicWorkerExecutor, normalizeCode } from "@cloudflare/codemode";
 import { AdmissionController, ExecutorExecutionError } from "./executor-admission.js";
 import { brandExecutor } from "./executor-contract.js";
+import { TOKEN_END } from "./errors.js";
 import { InvocationFailure } from "./invocation.js";
 import { parse } from "acorn";
 import { guestInitializer, guestPrelude, guestPromiseInitializer, isolateGuestProgram } from "./guest-runtime.js";
@@ -43,15 +44,25 @@ function routeGuestImports(source) {
     }
     return source;
 }
+/**
+ * The guest deadline when `timeout` is unset: below `execute.watchdogMs`, and
+ * so below the 60 s MCP clients give one request. Upstream's own default is
+ * that 60 s, which races them.
+ */
+const DEFAULT_TIMEOUT_MS = 50_000;
+const DEFAULT_QUEUE_TIMEOUT_MS = 40_000;
 /** Loader-only upstream sandbox whose lease disposes handles at run end. */
 export function workerExecutor(options) {
-    // One pool per executor, so per isolate. A queued run may wait out one
+    const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    // One pool per executor, so per isolate. A queued run may wait most of a
     // default guest deadline: programs spend it awaiting host calls, and a
-    // five-second wait refused nearly every run queued behind one.
+    // five-second wait refused nearly every run queued behind one. The wait
+    // spends the request's response ceiling, so it stops short enough to leave
+    // the run time to work and the refusal time to reach the client.
     const admission = new AdmissionController(options.admission ?? {
         concurrency: 2,
         maxQueueSize: 8,
-        queueTimeoutMs: 60_000,
+        queueTimeoutMs: DEFAULT_QUEUE_TIMEOUT_MS,
         retryAfterMs: 1_000,
     });
     const active = new Set();
@@ -99,6 +110,20 @@ export function workerExecutor(options) {
         // The SDK prepares its source/dispatchers against this inert loader.
         // Actual Loader and RPC acquisition belongs to the native program below.
         let prepared;
+        // Upstream 0.5.5+ answers every host call that settles after its
+        // evaluate() with a late-call error. Its inert evaluate stays pending
+        // until the native evaluation ends, so the SDK's gate stays open for the
+        // whole run and closes once the run is over or the lease is released.
+        let evaluating;
+        const evaluated = new Promise((resolve) => {
+            evaluating = resolve;
+        });
+        let settleUpstream;
+        const endUpstream = () => {
+            const settle = settleUpstream;
+            settleUpstream = undefined;
+            settle?.();
+        };
         const dispose = (resource) => Effect.sync(() => {
             try {
                 const method = Reflect.get(resource, Symbol.dispose);
@@ -163,19 +188,27 @@ export function workerExecutor(options) {
                         isolated = isolated.replace("setTimeout(() => reject(timeoutError)", "nativeSetTimeout(() => reject(timeoutError)");
                         isolated = isolated.replace("return { result: undefined, error: err.message, logs: __logs };", `
       const failureId = lookup(failures, err);
+      // tokenPrefix, for text the host redacts after this cut.
+      const tokenEnd = (unit) => ${[...TOKEN_END].map((unit) => `unit === ${unit}`).join(" || ")};
+      const prefix = (text, units) => {
+        if (units >= text.length) return text;
+        let end = units;
+        while (end > 0 && !tokenEnd(charCodeAt(text, end))) end--;
+        return slice(text, 0, end);
+      };
       let name = "Error", message = "Program threw a value.", stack = "";
       try {
-        if (typeof err === "string") message = slice(err, 0, 1000);
+        if (typeof err === "string") message = prefix(err, 1000);
         else if (err) {
-          if (typeof err.name === "string") name = slice(err.name, 0, 64);
-          if (typeof err.message === "string") message = slice(err.message, 0, 1000);
+          if (typeof err.name === "string") name = prefix(err.name, 64);
+          if (typeof err.message === "string") message = prefix(err.message, 1000);
           if (typeof err.stack === "string") stack = slice(err.stack, 0, 1000);
         }
       } catch {}
       const location = exec(/connecta-guest\\.js:(\\d+):\\d+/, stack);
       return { result: undefined, error: message, logs: __logs, failure: {
         name, ...(failureId ? { failureId } : {}), ...(location ? { line: toNumber(location[1]) - 1 } : {}),
-        ...(err === timeoutError ? { timeout: { elapsedMs: ${options.timeout ?? 60_000}, deadlineMs: ${options.timeout ?? 60_000} } } : {})
+        ...(err === timeoutError ? { timeout: { elapsedMs: ${timeoutMs}, deadlineMs: ${timeoutMs} } } : {})
       } };`);
                         const preludes = [];
                         let firstInitializer;
@@ -309,7 +342,10 @@ const {
                             getEntrypoint: () => ({
                                 evaluate: (...evaluateArgs) => {
                                     acquisition.args = evaluateArgs;
-                                    return Promise.resolve({ result: undefined });
+                                    return new Promise((resolve) => {
+                                        settleUpstream = () => resolve({ result: undefined });
+                                        evaluating?.();
+                                    });
                                 },
                             }),
                         };
@@ -342,15 +378,21 @@ const {
                 const started = Date.now();
                 const operation = Effect.gen(function* () {
                     const setup = yield* Effect.tryPromise({
-                        try: () => new DynamicWorkerExecutor({
-                            loader,
-                            ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
-                        }).execute(code, detached),
+                        try: () => {
+                            const upstream = new DynamicWorkerExecutor({
+                                loader,
+                                timeout: timeoutMs,
+                            }).execute(code, detached);
+                            // The SDK's own result, which settles only after endUpstream(),
+                            // carries nothing; the native evaluation below owns the outcome.
+                            upstream.catch(() => undefined);
+                            return Promise.race([upstream, evaluated.then(() => undefined)]);
+                        },
                         catch: (error) => error,
                     });
                     // Provider validation can return before the SDK reaches its loader.
-                    if (!prepared)
-                        return setup;
+                    if (setup !== undefined || !prepared)
+                        return setup ?? { result: undefined };
                     const load = prepared.load;
                     const args = prepared.args;
                     const open = () => Effect.suspend(() => released || resources.state._tag === "Closed"
@@ -369,7 +411,7 @@ const {
                             try: () => Reflect.apply(Reflect.get(entrypoint, "evaluate"), entrypoint, args ?? []),
                             catch: (error) => error,
                         });
-                    }).pipe(Scope.provide(resources));
+                    }).pipe(Scope.provide(resources), Effect.ensuring(Effect.sync(endUpstream)));
                     const result = yield* evaluation;
                     const outcome = result;
                     if (outcome.failure) {
@@ -407,6 +449,7 @@ const {
                 }));
             }).pipe(Effect.raceFirst(Deferred.await(stopped)), Effect.catchDefect((error) => Effect.fail(error)), Effect.ensuring(Effect.sync(() => {
                 runEnded = true;
+                endUpstream();
                 hostProviders = undefined;
                 prepared = undefined;
                 hostFailures.clear();
@@ -420,6 +463,7 @@ const {
                 if (released)
                     return;
                 released = true;
+                endUpstream();
                 hostProviders = undefined;
                 prepared = undefined;
                 hostFailures.clear();
@@ -438,6 +482,7 @@ const {
     const acquireShell = (request) => runEdge(acquire(request));
     const executor = {
         name: "DynamicWorkerExecutor",
+        deadlineMs: timeoutMs,
         acquire: acquireShell,
         execute: (code, providers) => runEdge(execute(code, providers)),
         admissionSnapshot: () => admission.snapshot(),