@zackbart/connecta 0.37.0 → 0.38.0

package/dist/executors/quickjs-runtime.js

@@ -1,3 +1,4 @@
+import { utf8Length } from "../bytes.js";
 // QuickJS-in-WebAssembly runtime used inside the disposable child process.
 //
 // Model-written code runs inside a QuickJS interpreter compiled to WASM:
@@ -37,30 +38,6 @@ function logTransportBytes(entry) {
     // encoded into ChildToParentMessage. Measure the units the IPC cap sees.
     return serializedBytes(JSON.stringify(JSON.stringify(entry)));
 }
-function exceedsUtf8ByteLimit(value, limit) {
-    let bytes = 0;
-    for (let index = 0; index < value.length; index += 1) {
-        const code = value.charCodeAt(index);
-        if (code <= 0x7f)
-            bytes += 1;
-        else if (code <= 0x7ff)
-            bytes += 2;
-        else if (code >= 0xd800 &&
-            code <= 0xdbff &&
-            index + 1 < value.length &&
-            value.charCodeAt(index + 1) >= 0xdc00 &&
-            value.charCodeAt(index + 1) <= 0xdfff) {
-            bytes += 4;
-            index += 1;
-        }
-        else {
-            bytes += 3;
-        }
-        if (bytes > limit)
-            return true;
-    }
-    return false;
-}
 /** Normalize model output into an async-arrow expression: strip markdown fences, wrap bare bodies. */
 export function normalizeCode(code) {
     let c = code.trim();
@@ -216,7 +193,7 @@ function installBridge(ctx, providers, logs, onLog) {
             catch (err) {
                 throw new Error(`Host result from ${label} could not be serialized: ${msg(err)}`);
             }
-            if (exceedsUtf8ByteLimit(json, MAX_HOST_RESULT_BYTES)) {
+            if (utf8Length(json, MAX_HOST_RESULT_BYTES) > MAX_HOST_RESULT_BYTES) {
                 throw new Error(`Host result from ${label} exceeds the ${MAX_HOST_RESULT_BYTES}-byte serialized bridge limit.`);
             }
             return { json };

package/dist/executors/quickjs.js

@@ -119,7 +119,7 @@ function terminate(child) {
 }
 let providePoolProgram;
 class QuickJsChildPool {
-    /** What `/health` and `connecta doctor` call this sandbox (#368). */
+    /** What `/health` and `connecta doctor` call this sandbox. */
     name = "QuickJS";
     admission;
     slots;

package/dist/guest-runtime.js

@@ -160,6 +160,8 @@ export function guestInitializer() {
     read: provider.read,
     result: provider.result,
     skill: provider.skill,
+    // Undeclared alias: models write connecta.skills, the top-level tool's name.
+    skills: provider.skill,
     emit(block) {
       const ref = block && typeof block === "object" ? weakGet(nativeRefs, block) : undefined;
       return trackEmission(emit(ref || block));
@@ -224,10 +226,10 @@ export function programError(raw, code) {
         /(?:const|let|var|function|\()\s*connecta\b/.test(code)) {
         hint = "Do not shadow connecta. Use the host-provided connecta global.";
     }
-    else if (/callTool|\bskills\b|connecta\.(?:guide|skills)/.test(message) ||
-        (["TypeError", "ReferenceError"].includes(name) && /connecta\.(?:guide|skills)\b/.test(code))) {
+    else if (/callTool|\bskills\b|connecta\.guide/.test(message) ||
+        (["TypeError", "ReferenceError"].includes(name) && /connecta\.guide\b/.test(code))) {
         hint =
-            "Use connecta.call(address, args), connecta.search, connecta.describe, connecta.result, and connecta.skill(name). Services are addressed by connector.tool, never guest globals.";
+            'Use connecta.call(address, args), connecta.search, connecta.describe, connecta.result, and connecta.skill("usage"). Services are addressed by connector.tool, never guest globals.';
     }
     return {
         code: "program_error",

package/dist/guest-types.d.ts

@@ -103,7 +103,7 @@ export type GuestBlock = {
     mimeType: string;
 };
 type SchemaFormat = "json" | "compact" | "typescript";
-export interface CatalogSearchArgs {
+interface CatalogSearchArgs {
     query?: string;
     connector?: string;
     safety?: "readOnly" | "approvalRequired" | "all";
@@ -113,7 +113,7 @@ export interface CatalogSearchArgs {
     includeSchemas?: SchemaFormat;
     includeSchemaKeys?: boolean;
 }
-export interface CatalogDescribeArgs {
+interface CatalogDescribeArgs {
     address?: unknown;
     addresses?: unknown;
     format?: SchemaFormat;
@@ -140,7 +140,7 @@ interface CatalogSearchFailure extends CatalogFailureDetail {
     }>;
     retry?: string;
 }
-export interface CatalogSearchPage {
+interface CatalogSearchPage {
     catalogErrors: CatalogSearchFailure[];
     absence?: {
         service: string;
@@ -170,14 +170,14 @@ export interface CatalogSearchPage {
         guidance?: string;
     };
 }
-export type CatalogSearchResult = CatalogSearchPage & {
+type CatalogSearchResult = CatalogSearchPage & {
     tools: Array<CatalogSearchTool & {
         connectorTitle?: string;
         guide?: string;
         guideSummary?: string;
     }>;
 };
-export interface CatalogDescription {
+interface CatalogDescription {
     address: string;
     schemaFormat?: "json" | "text";
     name?: string;

package/dist/http/client.js

@@ -1,6 +1,6 @@
 import { confinementBase, REDIRECT_STATUSES, BODILESS_STATUSES } from "../http-policy.js";
 import { guardedTransport, sendGuarded } from "../guarded-transport.js";
-// Guarded HTTP transport (decision 0010, B.2). Unreachable from src/index.ts.
+// Guarded HTTP transport. Unreachable from src/index.ts.
 //
 // The guarded transport as an Effect `HttpClient`, with the behaviour of
 // src/connectors/guarded-fetch.ts: requests confined beneath one base URL,

package/dist/http/errors.js

@@ -1,4 +1,4 @@
-// Internal HTTP failure contract (decision 0010, B.3). Unreachable from src/index.ts.
+// Internal HTTP failure contract. Unreachable from src/index.ts.
 //
 // Every way a kit request can fail, as a tagged error, and the one mapping
 // from those to the wire `ConnectorCallError`. A provider supplies meaning
@@ -26,7 +26,7 @@
 // refusing status counts only for the request that received it. Advice to
 // send a call again is a segment of its own (`resendAdvice`), never part of
 // the message, so output composes it only where the outcome allows.
-// Q8 policy is decided once by the core's `settleWrite` (#917), from the
+// Q8 policy is decided once by the core's `settleWrite`, from the
 // ledger entries this kit forwards its matched proof and renewals to. A
 // write answered 401 stays unknown; only renewal removes its handoff, and
 // only a reviewed authentication-before-execution declaration proves refusal.

package/dist/http/json-schema.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // One Schema is a tool's type, its argument decoder, and its catalog JSON
 // Schema. Effect's generator is correct but spells some things differently

package/dist/http/node-transport.js

@@ -238,4 +238,3 @@ export function createNodeGuardedTransport(proxy) {
         },
     };
 }
-export const nodeGuardedTransport = createNodeGuardedTransport();

package/dist/http/oauth.js

@@ -1,4 +1,4 @@
-// Refresh-once middleware (decision 0010, B.2). Unreachable from src/index.ts.
+// Refresh-once middleware. Unreachable from src/index.ts.
 //
 // Refresh-once for a connection that authenticates with a token it can
 // renew: a downstream OAuth grant, a service-account assertion, a machine

package/dist/http/paging.js

@@ -1,4 +1,5 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+import { bytesToHex, decodeBase64url } from "../bytes.js";
+// Provider kit. Unreachable from src/index.ts.
 //
 // List tools take one page at a time. Lookahead detects an extra row; bound
 // cursors authenticate the tool, arguments, connection and credential owner.
@@ -52,7 +53,7 @@ async function signingKey(storage) {
         return cached;
     let raw = await storage.get(continuationKeys.signingKey);
     if (raw === null) {
-        const candidate = Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        const candidate = bytesToHex(crypto.getRandomValues(new Uint8Array(32)));
         raw = (await storage.compareAndSet(continuationKeys.signingKey, null, candidate))
             ? candidate
             : await storage.get(continuationKeys.signingKey);
@@ -92,7 +93,7 @@ export const boundCursor = {
             const expected = yield* digest(tool, args);
             let parsed;
             try {
-                parsed = JSON.parse(new TextDecoder().decode(fromBase64url(token)));
+                parsed = JSON.parse(new TextDecoder().decode(decodeBase64url(token)));
             }
             catch {
                 parsed = undefined;
@@ -108,7 +109,7 @@ export const boundCursor = {
             if (token !== base64url(JSON.stringify({ v: record.v, d: record.d, c: record.c, m: record.m })))
                 return yield* Effect.fail(new Refusal({ error: new ConnectorCallError("invalid_args", STRAY_CURSOR) }));
             const key = yield* keyForCall;
-            const mac = fromBase64url(record.m);
+            const mac = decodeBase64url(record.m);
             const binding = yield* ContinuationBinding;
             const claims = new TextEncoder().encode(canonicalJson([record.v, binding.connection, binding.principal, record.d, record.c]));
             const valid = yield* Effect.promise(() => crypto.subtle.verify("HMAC", key, mac, claims));
@@ -125,7 +126,7 @@ function digest(tool, args) {
         .sort()
         .map((key) => [key, args[key]]);
     const bytes = new TextEncoder().encode(canonicalJson([tool, shape]));
-    return Effect.promise(() => crypto.subtle.digest("SHA-256", bytes)).pipe(Effect.map((hash) => Array.from(new Uint8Array(hash).slice(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("")));
+    return Effect.promise(() => crypto.subtle.digest("SHA-256", bytes)).pipe(Effect.map((hash) => bytesToHex(new Uint8Array(hash).slice(0, 16))));
 }
 function base64url(text) {
     return base64urlBytes(new TextEncoder().encode(text));
@@ -136,7 +137,3 @@ function base64urlBytes(bytes) {
         binary += String.fromCharCode(byte);
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-function fromBase64url(token) {
-    const binary = atob(token.replace(/-/g, "+").replace(/_/g, "/"));
-    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
-}

package/dist/http/provider.js

@@ -1,4 +1,4 @@
-// Internal provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Internal provider kit. Unreachable from src/index.ts.
 import { Context, Effect, Option } from "effect";
 import { api } from "../connectors/api.js";
 import { OAUTH_CHALLENGE_MAX_BYTES } from "../auth/renewable-grant.js";

package/dist/http/safety.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // The one value-safety boundary of a kit connection. `connect` requires it,
 // and `Send` hands a provider nothing it has not passed: a named tool, a

package/dist/http/services.js

@@ -3,7 +3,7 @@ import { Context, Effect } from "effect";
 import { dispatchProviderRequest, providerRequest } from "../provider-call.js";
 import { callClassification } from "../call-classification.js";
 import { fromSignal } from "../runtime/run.js";
-import { callFromContext, ContinuationBinding, ContinuationStorage, openCall as openCoreCall, serviceFor, Signal, } from "../runtime/call.js";
+import { callFromContext, ContinuationBinding, ContinuationStorage, serviceFor, Signal } from "../runtime/call.js";
 import { RequestRefused, ResendRefused } from "./errors.js";
 export { writeRequestKey } from "./write-request.js";
 export { Caller, Credentials, Secrets, RequestSecrets, Budget, Recovery, Signal, Classification, Ledger, } from "../runtime/call.js";
@@ -70,10 +70,3 @@ export function fromConnectorContext(ctx, fallback) {
         services: lease.services.pipe(Context.add(ContinuationStorage, serviceFor(ctx, ContinuationStorage) ?? ctx.storage), Context.add(ContinuationBinding, serviceFor(ctx, ContinuationBinding) ?? { connection: "", principal: null }), Context.add(Dispatches, []), Context.add(WriteCapacity, new Map([["write", new Map([[undefined, undefined]])]]))),
     };
 }
-export function openCall(inputs) {
-    const lease = openCoreCall(inputs);
-    return {
-        ...lease,
-        services: lease.services.pipe(Context.add(Dispatches, []), Context.add(WriteCapacity, new Map([["write", new Map([[undefined, undefined]])]]))),
-    };
-}

package/dist/http/tools.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // Tool builders. A tool is a name, a description, an input Schema, an output
 // Schema, and a program; the builder renders both Schemas as catalog JSON
@@ -24,7 +24,6 @@ import { fieldsInput, fieldsProblem, selectFields } from "./fields.js";
 import { catalogSchema, Integer } from "./json-schema.js";
 import { boundCursor, Cursor, StandardPage } from "./paging.js";
 import { Classification, Dispatches, IdempotencyKey, Recovery, ReadTool, WriteCapacity, writeRequestKey, fromConnectorContext, } from "./services.js";
-const inputs = new WeakMap();
 const keyed = new WeakSet();
 /** Whether a kit write builder declared an idempotency key for this tool. */
 export function takesIdempotencyKey(tool) {
@@ -62,10 +61,6 @@ function originalOrder(decoded, original) {
     };
     return copy(decoded, original);
 }
-/** The input Schema a kit tool decodes with, for the catalog/decoder agreement check. */
-export function kitInput(tool) {
-    return inputs.get(tool);
-}
 /** A Struct's own property names, for `fields`. */
 function propertyNames(schema, what) {
     const fields = schema.fields;
@@ -350,7 +345,6 @@ rendered) {
         })));
     });
     registerToolEntry(tool, (args, ctx) => program(args, ctx, inLogicalCall(ctx)));
-    inputs.set(tool, spec.input);
     if (idempotency)
         keyed.add(tool);
     return tool;

package/dist/http/vendor.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // A vendor is an `HttpApi`: endpoints with Schemas for path params, query,
 // and payload, from which requests are encoded and the endpoint manifest is
@@ -13,13 +13,13 @@
 // empty 200. Every answer, from a declared operation or a hatch's path, takes
 // one route: bounded read, JSON, closed public classifier facts captured,
 // the request's sent secrets redacted from
-// every value of the whole body before anything can cut or extract from it
-// (#911), its keys kept for value safety to match by name, status (with
+// every value of the whole body before anything can cut or extract from it,
+// its keys kept for value safety to match by name, status (with
 // its operation, so value safety decides what a failure may quote), the
 // vendor's `result` hook, then the connection's ResultSafety. A provider
 // cannot reach a body earlier. A Content-Type redaction altered selects the
 // format the vendor reads as JSON, so no altered type routes a body around
-// ResultSafety as text or bytes (#703).
+// ResultSafety as text or bytes.
 import { Context, Effect } from "effect";
 import * as HttpClientRequest from "effect/http/HttpClientRequest";
 import * as HttpApi from "effect/http-api/HttpApi";
@@ -233,12 +233,12 @@ export function connect(vendor, guarded, options) {
                     : defect)));
             });
             // Header-derived format decisions see only redacted Content-Type. Names are protocol
-            // constants `Headers` must accept, so only the values are redacted, together (#703).
+            // constants `Headers` must accept, so only the values are redacted, together.
             const entries = [...reply.headers];
             const values = secrets.redact(entries.map(([, value]) => value));
             const headers = new Headers(entries.map(([name], index) => [name, values[index]]));
             // Whole, before a detail line trims it or a projection extracts from it. Values only:
-            // result safety and projections match fields by their vendor names (#703).
+            // result safety and projections match fields by their vendor names.
             let classifierFacts;
             const parsed = reply.bytes !== undefined
                 ? {
@@ -400,7 +400,7 @@ export function connect(vendor, guarded, options) {
 /**
  * The Content-Type a format decision reads. One redaction altered reads as
  * `application/json`: a vendor's text or binary choice for it would hand
- * result safety a body it cannot read field by field (#703).
+ * result safety a body it cannot read field by field.
  */
 function formatType(redacted) {
     return redactionAltered(redacted) ? "application/json" : redacted.toLowerCase();

package/dist/identity.js

@@ -1,5 +1,5 @@
+import { sha256Hex } from "./bytes.js";
 const IDENTITY_PART_RE = /^[\x21-\x7e]{1,256}$/;
-const encoder = new TextEncoder();
 export function validIdentityReference(value) {
     return Boolean(value &&
         typeof value.namespace === "string" &&
@@ -7,11 +7,7 @@ export function validIdentityReference(value) {
         IDENTITY_PART_RE.test(value.namespace) &&
         IDENTITY_PART_RE.test(value.id));
 }
-function bytesToHex(bytes) {
-    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
 /** Deterministic pseudonymous partition; raw emails and ids do not enter keys. */
 export async function identityStorageKey(identity) {
-    const digest = await crypto.subtle.digest("SHA-256", encoder.encode(`${identity.namespace}\n${identity.id}`));
-    return bytesToHex(new Uint8Array(digest));
+    return sha256Hex(`${identity.namespace}\n${identity.id}`);
 }

package/dist/index.js

@@ -177,8 +177,7 @@ function warnInsecureConfig(config) {
             logger.warn(`[connecta] connector "${connector.id}" has an OAuth callback with no ` +
                 `state/CSRF check: /oauth/callback/${connector.id} refuses every ` +
                 "callback rather than exchange an unverified code. Implement " +
-                "`verifyState` to complete authorization (the shipped remoteMcp " +
-                "connector already does).");
+                "`verifyState` to complete authorization.");
         }
     }
 }

package/dist/invocation-auth.js

@@ -1,3 +1,4 @@
+import { bytesToHex } from "./bytes.js";
 import { authCall, authFlow, registerAuth } from "./auth/native.js";
 import { upwardStep } from "./upward.js";
 import { runEdge } from "./runtime/run.js";
@@ -34,7 +35,7 @@ export async function classificationDigest(definition) {
             annotations,
             schema,
         }));
-        return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
     }
     catch {
         // A digest refusal blocks recovery, not an ordinary call.

package/dist/invocation.js

@@ -766,7 +766,13 @@ export class InvocationService {
                     : Effect.succeed(result);
             const processed = yield* Effect.exit(timed((elapsed) => {
                 resultProcessingMs += elapsed;
-            }, Effect.tap(processing, () => Effect.sync(() => {
+            }, Effect.tap(withDeadlineEffect(() => processing, {
+                ...defined({
+                    timeoutMs: context.timeoutMs === undefined ? undefined : Math.max(1, context.timeoutMs - (Date.now() - started)),
+                    signal: context.requestSignal,
+                }),
+                timeoutError: new ConnectorCallError("timeout", "Result processing exceeded the tool call deadline."),
+            }), () => Effect.sync(() => {
                 if (inputRequiredValue)
                     return;
                 try {
@@ -777,7 +783,7 @@ export class InvocationService {
                 }
             }))));
             // Past this point the call has happened, so nothing may invite a retry.
-            const unprocessable = () => failed(framingError("result_processing_failed", "The downstream call completed, but its result could not be processed. Do not repeat the call to recover its result."));
+            const unprocessable = () => failed(framingError("result_processing_failed", "The downstream call completed, but its result could not be processed. Any write already happened. Do not repeat the call to recover its result."));
             if (Exit.isFailure(processed))
                 return unprocessable();
             try {

package/dist/meta-tools.js

@@ -1,3 +1,4 @@
+import { toolError } from "./tool-error.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, authMethod, authStorage, registerAuth } from "./auth/native.js";
 import { registryProgram } from "./runtime/registry.js";
@@ -20,7 +21,7 @@ import { AUTHORIZE_OUTPUT, SEARCH_OUTPUT, SKILLS_OUTPUT } from "./meta-output.js
 import { RESULT_TTL_SECONDS, resultKeys } from "./storage/keys.js";
 import { agentOutputOperations, sentSecretsForRequest } from "./sent-secrets.js";
 import { captureDownstreamInput } from "./downstream-input.js";
-import { PROGRAM_RESULT_WIRE_BYTES } from "./program-result.js";
+import { PROGRAM_RESULT_PAGE_BYTES, PROGRAM_RESULT_WIRE_BYTES } from "./program-result.js";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT };
 const enc = new TextEncoder();
 // Each page is a slice of payload bytes, so a leading U+FEFF is data.
@@ -37,15 +38,7 @@ function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
 function discoveryErrorResult(error) {
-    const result = jsonResult({
-        error: {
-            code: error.code,
-            message: error.message,
-            retryable: false,
-        },
-    });
-    result.isError = true;
-    return result;
+    return toolError({ code: error.code, message: error.message, retryable: false });
 }
 const discoveryResult = function (operation, hint) {
     return authFlow(function* () {
@@ -86,8 +79,8 @@ function isValidResultOffset(value) {
  * Backwards, never forwards: re-serving a few bytes the caller already has is
  * recoverable, silently skipping the rest of a character is not. Offsets the
  * server itself produced (`nextOffset`) are already boundaries and come back
- * unchanged, so this only moves an offset a client computed on its own
- * (issue #38). An offset at or past `bytes.length` is left alone — there is no
+ * unchanged, so this only moves an offset a client computed on its own.
+ * An offset at or past `bytes.length` is left alone — there is no
  * character there to split.
  */
 function alignStartToCharBoundary(bytes, offset) {
@@ -149,6 +142,15 @@ function base64Of(bytes) {
     }
     return out;
 }
+/**
+ * The page a notice's nextAction asks a program to read: it fits the program's
+ * return even if every byte escapes to six JSON characters, with room for the
+ * page envelope, and never asks for more than the stash or bridge will serve.
+ */
+function programPageBytes(results) {
+    const fits = Math.floor(((results.programChars ?? MAX_EXECUTE_RESULT_CHARS) - 1024) / 6);
+    return Math.max(4, Math.min(fits, results.cap, PROGRAM_RESULT_PAGE_BYTES));
+}
 /** Opens a write's notice, ahead of any paging instruction. */
 const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see its result.";
 /** UTF-8 cannot represent lone UTF-16 surrogates without changing them. */
@@ -229,7 +231,7 @@ const stashResult = function (bytes, results, preview, rawText) {
         try {
             // Base64 permits byte-range decoding, and splitting the envelope across
             // keys keeps a page's storage read proportional to the page instead of to
-            // the whole result (issue #540). Chunk 0 carries the header; the connecta.result
+            // the whole result. Chunk 0 carries the header; the connecta.result
             // reader below maps a byte offset back to chunk index and base64 quad.
             const chunkBytes = resultChunkBytes(totalBytes);
             const binding = base64Of(enc.encode(JSON.stringify(results.binding)));
@@ -280,7 +282,7 @@ const stashResult = function (bytes, results, preview, rawText) {
                     // A byte may cost six JSON characters when escaped. Leave room for the
                     // result id, page counters, and continuation metadata in the returned page.
                     arguments: {
-                        code: `async () => await connecta.result(${JSON.stringify(id)}, { offset: ${preview.kind === "prefix" ? preview.bytes : 0}, maxBytes: ${Math.floor((MAX_EXECUTE_RESULT_CHARS - 1024) / 6)} })`,
+                        code: `async () => await connecta.result(${JSON.stringify(id)}, { offset: ${preview.kind === "prefix" ? preview.bytes : 0}, maxBytes: ${programPageBytes(results)} })`,
                     },
                 },
         };
@@ -325,10 +327,10 @@ const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult,
     });
 });
 /** Program returns share the direct stash, with all host-admitted call dependencies. */
-export function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite) {
-    return runEdge(guardProgramReturnNative(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite));
+export function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars) {
+    return runEdge(guardProgramReturnNative(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars));
 }
-const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn, function (value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite) {
+const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn, function (value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars) {
     return authFlow(function* () {
         const serialized = serializeResultText(value);
         if (serialized.length <= maxChars)
@@ -347,6 +349,7 @@ const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn
             },
             write: completedWrite,
             cap,
+            ...(programChars !== undefined ? { programChars } : {}),
             set: authMethod((id, chunks, ttl) => registryProgram(registry, "stashResult", id, chunks, ttl)),
             warn: () => logFailure(logger, "result paging unavailable", failureRecord({})),
         };
@@ -453,16 +456,11 @@ function escapedHeadOf(bytes, cap) {
  * Bound a downstream MCP `content` array by `cap`.
  *
  * A lone text block is measured, stashed, previewed, and paged as its text:
- * its envelope adds nothing but a wrapper and a second layer of JSON escaping,
- * which made a JSON payload's preview unreadable and inflated every page.
+ * its envelope adds nothing but a wrapper and a second layer of JSON escaping.
  *
  * Anything else is measured as the serialized envelope — the same string that
  * gets stashed and paged, and the one that counts every block rather than only
- * the text ones. Both halves matter (issue #43). Measuring only text blocks
- * meant an oversized all-image result scored zero bytes and was returned inline
- * unbounded, with no `resultId` to page from; and measuring one string while
- * truncating another left `totalBytes` describing something the cap was never
- * compared against.
+ * the text ones. Measure the same representation that gets truncated and paged.
  *
  * Over the cap, what a client gets depends on whether a preview is usable.
  * Several text blocks preview as their text joined by newlines, while
@@ -624,6 +622,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                             write: resolved.definition.classification !== "read",
                             cap,
                             ...(opts.pagingTool ? { pagingTool: opts.pagingTool } : {}),
+                            ...(opts.maxProgramResultChars !== undefined ? { programChars: opts.maxProgramResultChars } : {}),
                             set: authMethod((id, value, ttlSeconds) => registryProgram(registry, "stashResult", id, value, ttlSeconds)),
                             // The catalog entry, never `toolName`: a record names a tool
                             // only through the grammar check (src/operator-record.ts).
@@ -670,7 +669,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 const structuredRecovery = outcome.error.nextAction !== undefined;
                 const recoveryRequired = structuredRecovery ||
                     // Sanitized `unavailable` diagnostics ride the structured shape too;
-                    // the plain-text path would drop them (#539).
+                    // the plain-text path would drop them.
                     outcome.error.details !== undefined ||
                     // So does a conflict's `current`: where things stand is the retry.
                     outcome.error.current !== undefined ||
@@ -733,7 +732,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         content: [
                             {
                                 type: "text",
-                                text: 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
+                                text: "Available skills. Fetch one by exact name with this tool.\n\n" +
                                     listing.map((skill) => `- \`${skill.name}\` — ${skill.description}`).join("\n"),
                             },
                         ],
@@ -949,7 +948,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             // client that computes its own offsets can land inside a multi-byte
             // character, which would decode as U+FFFD; the offset actually served is
             // the boundary at or before it, and it is what the response reports back
-            // as `offset` (issue #38).
+            // as `offset`.
             const offset = start + alignStartToCharBoundary(bytes, requestedOffset - start);
             // Both sides of `maxBytes` are validated by now — the argument above, the
             // cap at intake — so `offset + maxBytes` always reaches past `offset`.
@@ -1084,6 +1083,7 @@ const AUTHORIZE_INPUT = advertisedSchema(z.object({
  */
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
+        maxProgramResultChars: ctx.maxProgramResultChars,
         ...(ctx.native && !ctx.native.executeCode ? { pagingTool: "read_result" } : {}),
         ...(ctx.native ? { activitySource: "native" } : {}),
         downstreamInput: Boolean(ctx.authElicitation),

package/dist/native-tools.js

@@ -1,3 +1,4 @@
+import { bytesToHex } from "./bytes.js";
 import { duringViewEffect } from "./runtime/call.js";
 import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { Effect } from "effect";
@@ -35,7 +36,7 @@ function shortHash(text) {
 const shortHashNative = /* @__PURE__ */ registerAuth(shortHash, function (text) {
     return authFlow(function* () {
         const digest = new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", enc.encode(text)])));
-        return [...digest.subarray(0, HASH_CHARS / 2)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+        return bytesToHex(digest.subarray(0, HASH_CHARS / 2));
     });
 });
 /**

package/dist/oauth-handoff.js

@@ -1,3 +1,4 @@
+import { decodeBase64url } from "./bytes.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, authStorage, registerAuth } from "./auth/native.js";
 import { runEdge } from "./runtime/run.js";
@@ -58,8 +59,7 @@ function encodeSegment(value) {
 function decodeSegment(value) {
     if (!/^[A-Za-z0-9_-]+$/.test(value))
         throw new Error("Invalid handoff encoding");
-    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
-    const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+    const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(decodeBase64url(value));
     if (encodeSegment(decoded) !== value)
         throw new Error("Noncanonical handoff encoding");
     return decoded;

package/dist/operation-vocabulary.js

@@ -2,7 +2,7 @@
 import { lexicalSearchContent, lexicalQueryTerms } from "./catalog.js";
 const tools = new WeakMap();
 const connectors = new WeakMap();
-export const OPERATION_VOCABULARY_BOUNDS = {
+const OPERATION_VOCABULARY_BOUNDS = {
     operations: 8192,
     rowChars: 1024,
     chars: 2_097_152,