@zackbart/connecta 0.29.0 → 0.30.0

package/dist/meta-tools.js

@@ -1,3 +1,4 @@
+import { authorizationHandoff, bindAuthorizationHandoffs } from "./authorization-handoff.js";
 import { bindMcpClient } from "./mcp-client-context.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { z } from "zod";
@@ -6,18 +7,20 @@ import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPo
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { boundedEchoText, ConnectorCallError, msg } from "./errors.js";
 import { failureRecord, logFailure } from "./operator-record.js";
-import { MAX_EXECUTE_RESULT_CHARS, serializeResultText } from "./executor-result.js";
+import { guardExecuteResultValue, MAX_EXECUTE_RESULT_CHARS, serializeResultText } from "./executor-result.js";
 import { InvocationService } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
 import { hasConnectorGuides, SkillsRegistry } from "./skills.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs } from "./timeout.js";
-import { AUTHORIZE_OUTPUT, CALL_OUTPUT, SEARCH_OUTPUT, SKILLS_OUTPUT } from "./meta-output.js";
+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";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT };
 const enc = new TextEncoder();
-const dec = new TextDecoder();
+// Each page is a slice of payload bytes, so a leading U+FEFF is data.
+const dec = new TextDecoder("utf-8", { ignoreBOM: true, fatal: false });
 export function jsonResult(obj, text = JSON.stringify(obj)) {
     return {
         content: [{ type: "text", text }],
@@ -142,6 +145,23 @@ function base64Of(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. */
+function isWellFormedText(text) {
+    const native = String.prototype.isWellFormed;
+    if (native)
+        return native.call(text);
+    for (let at = 0; at < text.length; at++) {
+        const unit = text.charCodeAt(at);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = text.charCodeAt(++at);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff)
+            return false;
+    }
+    return true;
+}
 /**
  * Offers a read the route meta-tools.md prefers for finding something in it:
  * repeat the call inside a program and reduce it there. Paging comes second,
@@ -153,6 +173,8 @@ const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see i
 const READ_REDUCE_FIRST = "To find something specific, repeat this read inside execute_code with connecta.call and filter or search the result there, returning only what matters";
 function pagingHint(results, totalBytes, preview) {
     if (!results.write) {
+        if (results.binding.program)
+            return "filter/map/slice data inside execute_code and return only what you need; page this completed return with connecta.result using nextAction.";
         const [shown, full] = preview.kind === "prefix"
             ? [`Bytes 0-${preview.bytes} of ${totalBytes} follow.`, "to read it in full, page the rest"]
             : preview.kind === "text-of-envelope"
@@ -177,8 +199,17 @@ function pagingHint(results, totalBytes, preview) {
  * documentation/meta-tools.md#result-representation). It is one compact JSON
  * line with no raw newline, so the preview starts after the first `\n`.
  */
-async function stashResult(bytes, results, preview) {
+async function stashResult(bytes, results, preview, rawText) {
     const totalBytes = bytes.length;
+    // Direct pages promise offsets into the original UTF-8 text. JSON-escaping
+    // raw text would change that contract; never stash the encoder's replacement
+    // characters as if they were the completed call's output.
+    if (rawText !== undefined && !isWellFormedText(rawText))
+        return {
+            truncated: true,
+            totalBytes,
+            hint: `${results.write ? WRITE_ALREADY_RAN + " " : ""}Paging is unavailable: text contains unpaired surrogates and can't be paged as text; request the value as JSON (value mode or a JSON-returning call) to recover it.`,
+        };
     if (!results.pageable)
         return {
             truncated: true,
@@ -238,6 +269,74 @@ async function stashResult(bytes, results, preview) {
         },
     };
 }
+/** Program calls use the direct-call envelope, ledger, expiry and authority. */
+export async function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, trust, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
+    const data = secrets.redact(value);
+    const wire = JSON.stringify({ data, format });
+    if (enc.encode(wire).length <= wireBytes)
+        return { data, format };
+    const text = secrets.text(format === "text" ? String(data) : serializeResultText(data));
+    const bytes = enc.encode(text);
+    const write = resolved.definition.classification !== "read";
+    const notice = await stashResult(bytes, {
+        pageable: !write || trust === "trusted",
+        binding: {
+            identity: registry.resultIdentity(),
+            baseUrl,
+            connector: resolved.connector.id,
+            tool: resolved.definition.name,
+            classification: write ? "write" : "read",
+        },
+        write,
+        cap: resolveMaxResultBytes(resolved.connector.maxResultBytes, registry.maxResultBytes),
+        set: (id, chunks, ttl) => registry.stashResult(id, chunks, ttl),
+        warn: () => logFailure(registry.contextFor(resolved.connector.id, baseUrl, requestScope).logger, "result paging unavailable", failureRecord({ connector: resolved.connector.id, tool: resolved.definition })),
+    }, { kind: "none" }, format === "text" ? text : undefined);
+    return {
+        format: "paged",
+        valueFormat: format,
+        ...(notice.resultId ? { resultId: notice.resultId } : {}),
+        totalBytes: bytes.length,
+        truncated: true,
+        hint: notice.resultId
+            ? `${write ? WRITE_ALREADY_RAN + " " : ""}Page this result with connecta.result(handle); do not repeat the call for output.`
+            : notice.hint,
+    };
+}
+/** Program returns share the direct stash, with all host-admitted call dependencies. */
+export async function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, trust, logger, maxChars, completedWrite) {
+    const serialized = serializeResultText(value);
+    if (serialized.length <= maxChars)
+        return value;
+    const text = secrets.text(serialized);
+    const bytes = enc.encode(text);
+    const write = dependencies.some((dependency) => dependency.classification === "write");
+    const cap = Math.min(registry.maxResultBytes, ...dependencies.map((dependency) => resolveMaxResultBytes(registry.getConnector(dependency.connector)?.maxResultBytes, registry.maxResultBytes)));
+    const results = {
+        secrets,
+        pageable: !write || trust === "trusted",
+        binding: {
+            identity: registry.resultIdentity(),
+            baseUrl,
+            classification: write ? "write" : "read",
+            program: dependencies,
+        },
+        write: completedWrite,
+        cap,
+        set: (id, chunks, ttl) => registry.stashResult(id, chunks, ttl),
+        warn: () => logFailure(logger, "result paging unavailable", failureRecord({})),
+    };
+    const notice = await stashResult(bytes, results, { kind: "none" }, text);
+    // Put the entire recovery route ahead of the preview in both response forms.
+    // A client retaining only the first 2,000 characters still sees the action.
+    if (notice.resultId) {
+        const base = { ...notice, totalChars: text.length, preview: "" };
+        const budget = Math.max(0, maxChars - JSON.stringify(base).length);
+        return { ...base, preview: escapedHeadOf(bytes, Math.min(512, budget)) };
+    }
+    const fallback = guardExecuteResultValue(secrets.redact(value), maxChars, notice.hint);
+    return { truncated: true, totalChars: fallback.totalChars, hint: fallback.hint, preview: fallback.preview };
+}
 /** The first `cap` bytes of `bytes`, ending on a character boundary. */
 function headOf(bytes, cap) {
     return bytes.subarray(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length));
@@ -246,7 +345,6 @@ function headOf(bytes, cap) {
 function noticeFirst(notice, preview) {
     return {
         content: [{ type: "text", text: `${JSON.stringify(notice)}\n${preview}` }],
-        structuredContent: { ...notice, format: "text" },
     };
 }
 /**
@@ -264,6 +362,10 @@ async function guardEncoded(text, bytes, results, cap) {
             truncated: false,
         };
     }
+    if (!isWellFormedText(text)) {
+        const notice = await stashResult(bytes, results, { kind: "none" }, text);
+        return { result: noticeFirst(notice, ""), truncated: true };
+    }
     const head = headOf(bytes, cap);
     const notice = await stashResult(bytes, results, {
         kind: "prefix",
@@ -380,13 +482,6 @@ async function guardContent(content, results, cap) {
         truncated: true,
     };
 }
-/**
- * The sentence that closes the OAuth handoff, telling the operator's agent how
- * to confirm the flow landed through the one surface it can call.
- */
-function oauthFollowUp(connectorId) {
-    return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
-}
 /**
  * Every meta-tool handler over a registry, one per registered tool. Exported for
  * direct testing; registerMetaTools() wires the six explicit tools onto an
@@ -415,6 +510,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     // identity lets remote connectors reuse one downstream client inside that
     // request without leaking request-bound I/O into the next one.
     const requestScope = opts.requestScope ?? {};
+    if (opts.canManageAuth || opts.oauthConnectUrl || opts.credentialHandoffUrl || opts.oauthConnectUnavailable) {
+        bindAuthorizationHandoffs(requestScope, (connector) => authorizationHandoff(registry, baseUrl, requestScope, opts, { connector }));
+    }
     const sentSecrets = sentSecretsForRequest(requestScope);
     const skills = new SkillsRegistry(registry, baseUrl, {
         requestScope,
@@ -498,12 +596,14 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         ];
                     }
                     const guarded = await guardContent(content, results, cap);
-                    guarded.result.structuredContent = { ...guarded.result.structuredContent, format };
+                    // Native blocks and bounded previews are the result. A format-only
+                    // structuredContent hides them in clients that prefer that field.
+                    guarded.result._meta = { "dev.connecta/format": format };
                     return processed(guarded.result, guarded.truncated);
                 }
                 const value = result;
                 const guarded = await guardText(serializeResultText(value), results, cap);
-                guarded.result.structuredContent = { ...guarded.result.structuredContent, format };
+                guarded.result._meta = { "dev.connecta/format": format };
                 return processed(guarded.result, guarded.truncated, { value });
             },
             activityFriction: (processed) => processed.friction,
@@ -615,6 +715,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 return errorResult(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
                     `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`);
             }
+            if (args.page !== undefined && (!Number.isSafeInteger(args.page) || args.page < 0 || args.offset !== undefined)) {
+                return errorResult("Use a whole page >= 0, without offset.");
+            }
             const results = registry.resultsStorage();
             const unavailableResult = () => ({
                 ...jsonResult({
@@ -668,21 +771,48 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 binding.identity.principal !== identity.principal ||
                 binding.identity.endpoint !== identity.endpoint ||
                 binding.identity.origin !== identity.origin ||
-                typeof binding.connector !== "string" ||
-                typeof binding.tool !== "string" ||
+                (binding.program === undefined
+                    ? typeof binding.connector !== "string" || typeof binding.tool !== "string"
+                    : !Array.isArray(binding.program) ||
+                        binding.program.some((dependency) => !dependency ||
+                            typeof dependency.connector !== "string" ||
+                            (dependency.tool !== undefined && typeof dependency.tool !== "string") ||
+                            (dependency.access !== undefined &&
+                                (dependency.access !== "catalog" || dependency.classification !== "read")) ||
+                            !["read", "write"].includes(dependency.classification))) ||
                 !["read", "write"].includes(binding.classification))
                 return denied();
             const allowed = async () => {
                 options.signal?.throwIfAborted();
                 try {
-                    const address = `${binding.connector}.${binding.tool}`;
-                    if (!(await registry.recheckResultAccess(address, binding.classification, options.signal)))
+                    if (binding.program &&
+                        !(await registry.recheckResultAccess(undefined, binding.classification, options.signal)))
                         return false;
-                    if (!registry.getConnector(binding.connector))
+                    if (binding.classification === "write" && opts.trust !== "trusted")
                         return false;
-                    const tools = await registry.getTools(binding.connector, baseUrl, requestScope, options.signal ? { signal: options.signal } : {});
-                    const tool = tools.find((tool) => tool.name === binding.tool);
-                    return Boolean(tool && ((binding.classification === "read" && tool.classification === "read") || opts.trust === "trusted"));
+                    const dependencies = binding.program ?? [binding];
+                    for (const dependency of dependencies) {
+                        const address = dependency.tool === undefined ? dependency.connector : `${dependency.connector}.${dependency.tool}`;
+                        if (!(await registry.recheckResultAccess(address, dependency.classification, options.signal, dependency.access)))
+                            return false;
+                        if (dependency.tool === undefined) {
+                            if (dependency.access === "catalog"
+                                ? !registry.getConnector(dependency.connector)
+                                : !registry.getResourceConnector(dependency.connector))
+                                return false;
+                            continue;
+                        }
+                        if (!registry.getConnector(dependency.connector))
+                            return false;
+                        const tools = await registry.getTools(dependency.connector, baseUrl, requestScope, options.signal ? { signal: options.signal } : {});
+                        const tool = tools.find((tool) => tool.name === dependency.tool);
+                        if (!tool ||
+                            !(dependency.access === "catalog" ||
+                                (dependency.classification === "read" && tool.classification === "read") ||
+                                opts.trust === "trusted"))
+                            return false;
+                    }
+                    return true;
                 }
                 catch {
                     options.signal?.throwIfAborted();
@@ -691,7 +821,8 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             };
             if (!(await allowed()))
                 return denied();
-            const requestedOffset = args.offset ?? 0;
+            opts.onResultRead?.(binding.program ?? [binding]);
+            let requestedOffset = args.offset ?? 0;
             const cap = Number(header[4]);
             if (!isValidMaxResultBytes(cap))
                 return denied();
@@ -708,6 +839,12 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     chunkBytes < 3 ||
                     chunkBytes % 3 !== 0)
                     return denied();
+                if (args.page !== undefined) {
+                    // At least one complete UTF-8 codepoint per nominal window. Adjacent
+                    // pages align both edges backwards, so no character repeats or vanishes.
+                    const width = Math.max(4, maxBytes);
+                    requestedOffset = Math.min(total, Math.min(args.page, Math.ceil(total / width)) * width);
+                }
                 start = Math.floor(Math.max(0, Math.min(requestedOffset, total) - 3) / 3) * 3;
                 const end = Math.min(total, requestedOffset + maxBytes + 4);
                 bytes = new Uint8Array(Math.max(0, end - start));
@@ -744,7 +881,10 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             // never split across pages (which would emit U+FFFD on both sides).
             // `nextOffset` is this aligned end, so it is a valid boundary for the
             // next call and paging reassembles the original byte-for-byte.
-            const end = start + alignEndToCharBoundary(bytes, offset - start, offset - start + maxBytes, total - start);
+            const end = args.page === undefined
+                ? start + alignEndToCharBoundary(bytes, offset - start, offset - start + maxBytes, total - start)
+                : start +
+                    alignStartToCharBoundary(bytes, Math.min(total - start, requestedOffset - start + Math.max(4, maxBytes)));
             const slice = dec.decode(bytes.subarray(offset - start, end - start));
             const hasMore = end < total;
             // The same notice-first shape as a truncated call: one line of header,
@@ -766,76 +906,8 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             return page;
         },
         async authorizeConnector(args) {
-            const connector = registry.getConnector(args.connector);
-            if (!connector) {
-                return errorResult(`Unknown connector "${boundedEchoText(args.connector)}"`);
-            }
-            if (!connector.startAuth) {
-                if (!connector.credential) {
-                    return jsonResult({
-                        connector: connector.id,
-                        recovery: "unavailable",
-                        message: `Connector "${connector.id}" declares neither downstream OAuth ` +
-                            "nor an operator-managed credential slot. Update the connector " +
-                            "or deployment configuration before retrying.",
-                    });
-                }
-                const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
-                if (!ctx.credential || !opts.credentialHandoffUrl) {
-                    return jsonResult({
-                        connector: connector.id,
-                        recovery: "unavailable",
-                        message: "Credential recovery needs both a vault and the optional UI. Configure " +
-                            "vault and ui in deployment code, then call " +
-                            "authorize_connector again.",
-                    });
-                }
-                const fields = connector.credential.fields?.map((field) => ({
-                    name: field.name,
-                    guidance: field.description ?? field.label,
-                })) ?? [
-                    {
-                        name: "value",
-                        guidance: connector.credential.description ?? connector.credential.label,
-                    },
-                ];
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "operator_config",
-                    credential: {
-                        label: connector.credential.label,
-                        fields,
-                    },
-                    operatorUrl: opts.credentialHandoffUrl,
-                    instructions: "Have the operator open operatorUrl, set and test the credential, " +
-                        "then retry the original call. No redeploy is needed. " +
-                        (connector.authScope === "personal"
-                            ? "Credential mutation requires the signed-in principal who owns this connection."
-                            : "Shared credential mutation requires a signed-in human with access to this connector."),
-                });
-            }
-            if (opts.oauthConnectUnavailable || !opts.oauthConnectUrl)
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "unavailable",
-                    message: opts.oauthConnectUnavailable ??
-                        "OAuth connection requires an interactive provider and a credential vault with a handoff signing key.",
-                });
-            if (!opts.canManageAuth?.(connector.id))
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "unavailable",
-                    message: "Your identity is not permitted to manage authentication for this connection.",
-                });
             try {
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "oauth",
-                    status: "auth_required",
-                    authorizationUrl: await opts.oauthConnectUrl(connector.id, args.force),
-                    instructions: "Open authorizationUrl in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
-                        oauthFollowUp(connector.id),
-                });
+                return jsonResult(await authorizationHandoff(registry, baseUrl, requestScope, opts, args));
             }
             catch (err) {
                 return errorResult(msg(err));
@@ -967,7 +1039,7 @@ export function registerMetaTools(server, registry, ctx) {
     server.registerTool("call_tool", {
         description: CALL_DESC,
         inputSchema: CALL_INPUT,
-        outputSchema: CALL_OUTPUT,
+        // Default mode returns native content, so no structured result is promised.
         // call_tool admits only tools that are themselves explicitly read-only;
         // anything else is refused and routed to call_destructive_tool.
         annotations: READ_ONLY_REMOTE,
@@ -980,7 +1052,6 @@ export function registerMetaTools(server, registry, ctx) {
     server.registerTool("call_destructive_tool", {
         description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
         inputSchema: CALL_DESTRUCTIVE_INPUT,
-        outputSchema: CALL_OUTPUT,
         annotations: {
             destructiveHint: true,
             readOnlyHint: false,

package/dist/oauth-handoff.js

@@ -1,6 +1,66 @@
 import { oauthConnectKeys } from "./storage/keys.js";
 const HANDOFF_TTL_MS = 15 * 60_000;
 const INTERACTIVE_OAUTH_REQUIRED = "An interactive provider (Clerk or Cloudflare Access) is required to connect OAuth connectors.";
+// Length-prefixed fields avoid JSON keys and escaping without reserving any
+// character in an identity. This is an opaque wire encoding, not encryption.
+function encodeHandoff(h) {
+    return [
+        h.connector,
+        h.owner,
+        h.principal,
+        h.origin,
+        h.expiresAt.toString(36),
+        h.nonce,
+        h.force ? "1" : "0",
+        h.after ?? "",
+    ]
+        .map((field) => `${field.length}:${field}`)
+        .join("");
+}
+function decodeHandoff(value) {
+    const fields = [];
+    let offset = 0;
+    while (offset < value.length && fields.length < 8) {
+        const colon = value.indexOf(":", offset);
+        const lengthText = value.slice(offset, colon);
+        if (colon < offset || !/^(0|[1-9][0-9]*)$/.test(lengthText))
+            throw new Error("Invalid handoff field");
+        const length = Number(lengthText);
+        offset = colon + 1;
+        if (!Number.isSafeInteger(length) || length > value.length - offset)
+            throw new Error("Invalid handoff length");
+        fields.push(value.slice(offset, offset + length));
+        offset += length;
+    }
+    const [connector, owner, principal, origin, expiry, nonce, force, after] = fields;
+    if (fields.length !== 8 || offset !== value.length || !/^[0-9a-z]+$/.test(expiry) || !/^[01]$/.test(force))
+        throw new Error("Invalid handoff fields");
+    return {
+        connector: connector,
+        owner: owner,
+        principal: principal,
+        origin: origin,
+        expiresAt: parseInt(expiry, 36),
+        nonce: nonce,
+        force: force === "1",
+        ...(after ? { after } : {}),
+    };
+}
+function encodeSegment(value) {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(value))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+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)));
+    if (encodeSegment(decoded) !== value)
+        throw new Error("Noncanonical handoff encoding");
+    return decoded;
+}
 export function oauthConnectUnavailable(opts) {
     if (!opts.config.auth.some((provider) => provider.interactiveOperator &&
         (provider.uiAuth?.kind === "clerk" || provider.uiAuth?.kind === "cloudflare-access"))) {
@@ -34,10 +94,13 @@ export async function oauthConnectLink(opts, baseUrl, connectorId, principal, fo
     const vault = opts.config.vault;
     if (opaque && (!vault.seal || !vault.open))
         throw new Error("URL elicitation requires a sealing credential vault.");
+    const compact = encodeHandoff(handoff);
     const payload = opaque
-        ? `v2:${btoa(await vault.seal(connectorId, "connecta:connect-link:v2", JSON.stringify(handoff)))}`
-        : btoa(JSON.stringify(handoff));
-    const signature = await opts.config.vault.signOAuthHandoff(payload);
+        ? `v4.${encodeSegment(await vault.seal(connectorId, "connecta:connect-link:v4", compact))}`
+        : `v3.${encodeSegment(compact)}`;
+    // Preserve the vault's entire signature and its representation, including
+    // custom vaults, while keeping every URL segment unpadded base64url.
+    const signature = encodeSegment(await vault.signOAuthHandoff(payload));
     const url = new URL(`/connect/${connectorId}`, baseUrl);
     url.searchParams.set("h", `${payload}.${signature}`);
     return { url: url.toString(), nonce: handoff.nonce };
@@ -63,15 +126,29 @@ export async function claimAuthRetry(opts, baseUrl, id, nonce) {
 export async function verifyOAuthHandoff(opts, baseUrl, connectorId, token) {
     if (!token || token.length > 4096)
         return null;
-    const [payload, signature, ...rest] = token.split(".");
-    if (!payload || !signature || rest.length)
-        return null;
     try {
-        if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, signature)))
-            return null;
-        const h = JSON.parse(payload.startsWith("v2:")
-            ? await opts.config.vault.open(connectorId, "connecta:connect-link:v2", atob(payload.slice(3)))
-            : atob(payload));
+        const parts = token.split(".");
+        let h;
+        if (parts.length === 3 && (parts[0] === "v3" || parts[0] === "v4")) {
+            const [version, body, signature] = parts;
+            const payload = `${version}.${body}`;
+            if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, decodeSegment(signature))))
+                return null;
+            const decoded = decodeSegment(body);
+            h = decodeHandoff(version === "v4" ? await opts.config.vault.open(connectorId, "connecta:connect-link:v4", decoded) : decoded);
+        }
+        else {
+            // Keep pre-upgrade JSON and sealed v2 links until their original expiry.
+            // Authenticate their exact original text; never normalize before verifying.
+            const [payload, signature, ...rest] = parts;
+            if (!payload || !signature || rest.length)
+                return null;
+            if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, signature)))
+                return null;
+            h = JSON.parse(payload.startsWith("v2:")
+                ? await opts.config.vault.open(connectorId, "connecta:connect-link:v2", atob(payload.slice(3)))
+                : atob(payload));
+        }
         const connector = opts.registry.getConnector(connectorId);
         if (!connector ||
             h.connector !== connectorId ||

package/dist/program-result.js

@@ -0,0 +1,5 @@
+/** Shared transport policy, independent of any optional executor implementation. */
+export const PROGRAM_RESULT_INLINE_BYTES = 1024 * 1024;
+/** Leave room for the bridge envelope and six-character JSON escapes per byte. */
+export const PROGRAM_RESULT_PAGE_BYTES = 32 * 1024;
+export const PROGRAM_RESULT_WIRE_BYTES = 240 * 1024;

package/dist/program-writes.js

@@ -104,6 +104,10 @@ export class ProgramWrites {
     get isClosed() {
         return this.closed;
     }
+    /** Whether a dispatched write completed successfully in this run. */
+    get hasSucceeded() {
+        return this.states.includes("ok");
+    }
     close() {
         this.closed = true;
     }
@@ -151,7 +155,7 @@ export class ProgramWrites {
         if (writes.unknown > 0) {
             return errorEnvelope({
                 code: "write_outcome_unknown",
-                message: "A write this program sent has no known outcome, so that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it.",
+                message: "A write this program sent has no known outcome, so that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call.",
                 retryable: false,
                 ...(this.deadlines.length > 0 ? { details: this.deadlines[0] } : {}),
                 ...(this.deadlines.length > 1 ? { timeouts: this.deadlines } : {}),

package/dist/provider.d.ts

@@ -35,11 +35,11 @@ export declare const PROVIDER_COMMON: {
             maxPartitions: Field<unknown, unknown, true>;
         };
     };
+    instructions: Field<unknown, unknown, true>;
     title: Field<unknown, unknown, true>;
     authScope: Field<unknown, unknown, true>;
     maxResultBytes: Field<unknown, unknown, true>;
     purpose: Field<unknown, unknown, true>;
-    instructions: Field<unknown, unknown, true>;
 };
 /** The provider's maintained, connection-independent usage guide. */
 export interface ProviderSkill {

package/dist/providers/_shared/google/workspace.d.ts

@@ -109,12 +109,12 @@ export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js
                 maxPartitions: import("../../../config-schema.js").Field<unknown, unknown, true>;
             };
         };
+        instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
         title: import("../../../config-schema.js").Field<unknown, unknown, true>;
         maxResultBytes: import("../../../config-schema.js").Field<unknown, unknown, true>;
         baseUrl: import("../../../config-schema.js").Field<unknown, unknown, true>;
         subject: import("../../../config-schema.js").Field<unknown, unknown, true>;
         purpose: import("../../../config-schema.js").Field<unknown, unknown, true>;
-        instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
     };
 };
 /** The checked, construction-time half of {@link GoogleWorkspaceOptions}. */