@zackbart/connecta 0.37.1 → 0.38.0

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,

package/dist/operator-record.js

@@ -1,52 +1,4 @@
-// What an operator may read about a failure: log records and status text.
-// Web-API only — no node: imports here.
-//
-// Inbound identity-provider text never enters operator logs or status, even
-// when it fits a grammar. Activity retains its separate typed actor fields.
-//
-// Threat model. INV-6 here covers records of calls and failures: logs,
-// activity rows, status and statusFor, health, doctor output, and any native
-// runtime output connecta triggers (workerd's console). Text a downstream
-// server, HTTP API, or client authored, and anything derived from it, never
-// reaches one as arbitrary text. Self-declared client name/version facts in
-// activity use the bounded ASCII grammars in activityClientFact; invalid values are
-// absent at recording, SQL write/read, and operator UI boundaries. Client
-// capabilities and other metadata are never recorded. Every typed field
-// connecta records is checked against a closed set or a grammar. Operator-
-// authored code (custom connectors, plugin `status()`, decorators) is trusted
-// to follow the contract, and connecta still checks
-// the typed fields it records from it; deliberately adversarial operator code
-// is out of scope.
-//
-// Catalog metadata a connector serves is configuration the operator chose to
-// load, and agents already see it: a tool name that fits MCP's tool-name
-// grammar, a description, and input and output schemas may appear in the
-// authenticated operator page's catalog views, and such a name may be
-// logged. A name outside the grammar is withheld everywhere operator-facing,
-// the page included. Names containing C0, DEL, or C1 are dropped at catalog
-// intake; spaces and non-ASCII names remain callable with withheld records.
-//
-// INV-6 says logs carry no arguments, results, code, or raw downstream error
-// text. Filtering errors where they arise kept missing sources: a validator's
-// diagnostic, a stream's TypeError, a JSON-RPC error the agent may see. So the
-// rule is enforced here, at the sink. A failure reaches an operator only as
-// the fields of a `FailureRecord`, which `failureRecord` alone builds: each
-// one copied from an explicit list, checked against a constant table or a
-// grammar, and never taken from an error's message, cause, stack, data,
-// nested errors, or name. `logFailure` writes nothing else, and every status
-// message about a failure comes from `describeFailure`
-// (test/operator-record-sources.node.test.ts holds src/ to that).
-//
-// Provenance is by identity, never by shape. Text that merely looks like
-// connecta's (an error named like one of its classes, a status sentence
-// shaped like a record) carries no weight: a class label comes from the
-// prototype chain, a status message from the status object connecta built.
-//
-// Agent-facing results are a different surface with a different rule: a
-// downstream's own answer to a call may reach the agent that made it (see
-// documentation/architecture.md, "Errors and records"). Core's sent-secrets
-// boundary removes credentials used by the upstream request from those answers, including
-// allowed diagnostics, tool results and nested error causes/data (INV-5).
+// Payload-free operator failure records. See documentation/architecture.md, "Errors and records".
 import { carryProviderFailure } from "./provider-call-facts.js";
 import { followRedactedCopies, keepErrorName } from "./redaction-identity.js";
 import { classificationCode, ConnectorCallError, NETWORK_ERROR_CODES, WithheldTextError, } from "./errors.js";

package/dist/operator-ui/contract.d.ts

@@ -26,7 +26,7 @@ export interface OperatorConnectorOverlay {
     /** Latest visible call in the bounded activity window, or null when unknown. */
     lastCall: OperatorLastCall | null;
 }
-/** Whole connector access, or exact tool grants. `requireReadOnly` is always false since guarded grants were removed (#837). */
+/** Whole connector access, or exact tool grants. `requireReadOnly` is always false since guarded grants were removed. */
 export interface OperatorGrant {
     connectorId: string;
     tools: "all" | Array<{
@@ -197,5 +197,5 @@ export interface OperatorUiContractV2 {
         viewerKey: string;
     };
 }
-/** The operator contract `GET /ui/api/config` serves; schema version 1 was removed (#837). */
+/** The operator contract `GET /ui/api/config` serves; schema version 1 was removed. */
 export type OperatorUiContract = OperatorUiContractV2;