@zackbart/connecta 0.7.6 → 0.7.8

package/src/connectors/remote-mcp.ts

@@ -393,7 +393,7 @@ interface ConnectionState {
   connecting: Promise<void> | null;
   authRequired: boolean;
   provider: KvOAuthProvider | null;
-  connectedGeneration: number | null;
+  connectedGeneration: string | null;
   /**
    * One-way latch: set by closeScope and never cleared, so neither a late
    * connect nor a `reset()` can cache a client into a scope that is already
@@ -451,6 +451,16 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       { cause },
     );
 
+  class OperatorDisconnectedError extends ConnectorCallError {
+    constructor() {
+      super(
+        "auth_required",
+        `Connector "${id}" was disconnected by an operator — explicitly start authorization to reconnect it.`,
+      );
+    }
+  }
+  const operatorDisconnectedError = () => new OperatorDisconnectedError();
+
   const scopeEndedError = () =>
     new Error(`Connector "${id}" scope ended during connection.`);
 
@@ -518,16 +528,23 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     return state.provider;
   };
 
+  const newProvider = (ctx: ConnectorContext): KvOAuthProvider =>
+    new KvOAuthProvider(
+      id,
+      ctx.storage,
+      `${ctx.baseUrl}/oauth/callback/${id}`,
+    );
+
   const buildTransport = (
     ctx: ConnectorContext,
-    state: ConnectionState,
+    provider: KvOAuthProvider | null,
   ): Transport => {
     if (opts._transportFactory) return opts._transportFactory(ctx);
     const url = new URL(opts.url);
     const guardedFetch = redirectSafeFetch(id, opts.redirects);
     if (opts.auth?.type === "oauth") {
       return new StreamableHTTPClientTransport(url, {
-        authProvider: getProvider(ctx, state),
+        authProvider: provider ?? newProvider(ctx),
         fetch: guardedFetch,
       });
     }
@@ -547,6 +564,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     state.transport = null;
     state.connecting = null;
     state.authRequired = false;
+    state.provider = null;
     state.connectedGeneration = null;
     // `closed` is deliberately not cleared — see ConnectionState.
   };
@@ -563,97 +581,160 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         new UnauthorizedError("Downstream authorization is no longer valid."),
       );
     }
+    // Read the OAuth epoch before trusting either a cached client or starting a
+    // transport. A disconnected epoch is a durable operator instruction, not
+    // merely the absence of credentials: passive status/tool probes must not
+    // turn it back into a pending consent flow.
+    let oauthGeneration: string | undefined;
+    if (isOauth && (state.client || state.connecting)) {
+      const provider = getProvider(ctx, state);
+      oauthGeneration = await provider.generation();
+      if (provider.isOperatorDisconnectedGeneration(oauthGeneration)) {
+        const connecting = state.connecting;
+        const client = state.client;
+        const transport = state.transport;
+        reset(state);
+        void connecting?.catch(() => {});
+        try {
+          if (client) await client.close();
+          else await transport?.close();
+        } catch {
+          // The disconnected epoch is authoritative even if local close fails.
+        }
+        throw operatorDisconnectedError();
+      }
+    }
     // Cross-isolate force re-auth: another isolate bumped the KV generation and
     // wiped credentials. This request's cached client still speaks the old
     // token — drop it so the next connect runs against current state.
-    if (state.client && isOauth && state.connectedGeneration !== null) {
-      const generation = await getProvider(ctx, state).generation();
+    if (state.client && oauthGeneration !== undefined && state.connectedGeneration !== null) {
       if (state.closed) throw scopeEndedError();
-      if (generation !== state.connectedGeneration) {
+      if (oauthGeneration !== state.connectedGeneration) {
         reset(state);
       }
     }
     if (state.closed) throw scopeEndedError();
     if (state.client) return;
-    state.connecting ??= (async () => {
-      const provider = isOauth ? getProvider(ctx, state) : null;
-      const genAtStart = provider ? await provider.generation() : 0;
-      if (state.closed) throw scopeEndedError();
-      // Stamp the provider so any saveTokens/saveClientInformation the SDK fires
-      // during this connect (code exchange, DCR) — or during a later refresh on
-      // the resulting client — is dropped if a concurrent force bumps the
-      // generation past this point, instead of re-persisting wiped credentials.
-      provider?.captureGeneration(genAtStart);
-      // The SDK defaults to AJV, which compiles every advertised outputSchema
-      // with `new Function`. Cloudflare Workers prohibit dynamic code
-      // generation, so a remote such as Stripe fails during tools/list unless
-      // the SDK's edge-safe validator is selected explicitly.
-      const c = new Client(
-        { name: "connecta", version: CONNECTA_VERSION },
-        { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
-      );
-      const t = buildTransport(ctx, state);
-      state.transport = t;
-      try {
-        await c.connect(t);
-        // A probe deadline can end its scope while connect is still in flight.
-        // The transport is closed immediately by closeScope; if connect wins
-        // that race anyway, close the resulting client rather than resurrecting
-        // a session in the detached state object.
-        if (state.closed) {
+    if (!state.connecting) {
+      let attempt!: Promise<void>;
+      attempt = (async () => {
+        const ownsAttempt = () =>
+          state.connecting === attempt && !state.closed;
+        const abandon = async (owner: Client | Transport) => {
           try {
-            await c.close();
+            await owner.close();
           } catch {
-            // The scope has already been discarded either way.
+            // The attempt is detached either way.
           }
           throw scopeEndedError();
+        };
+        // Let the assignment immediately below this async IIFE publish
+        // `state.connecting = attempt` before ownership is checked. OAuth's
+        // generation read naturally yields; unauthenticated transports do not.
+        await Promise.resolve();
+        // A provider belongs to exactly one connect attempt. A force reset can
+        // abandon that attempt while its transport still holds the provider;
+        // the replacement must never mutate the abandoned provider's epoch.
+        const provider = isOauth ? newProvider(ctx) : null;
+        const genAtStart = provider ? await provider.generation() : "";
+        if (!ownsAttempt()) throw scopeEndedError();
+        if (provider?.isOperatorDisconnectedGeneration(genAtStart)) {
+          throw operatorDisconnectedError();
         }
-        // A force re-auth that landed WHILE we were connecting wiped the creds
-        // this client just bound to. Discard it rather than cache a connection
-        // that resurrects the wiped-and-reauthorized connector from a stale
-        // isolate. Surfaces as auth_required — the connector genuinely needs
-        // re-consent now.
-        if (provider) {
-          const generation = await provider.generation();
-          // closeScope can land while the generation read is pending, after
-          // connect succeeded but before this client is cached. Discard the
-          // client on that side of the await too.
-          if (state.closed) {
-            try {
-              await c.close();
-            } catch {
-              // The scope has already been discarded either way.
+        provider?.captureGeneration(genAtStart);
+        // The SDK defaults to AJV, which compiles every advertised outputSchema
+        // with `new Function`. Cloudflare Workers prohibit dynamic code
+        // generation, so a remote such as Stripe fails during tools/list unless
+        // the SDK's edge-safe validator is selected explicitly.
+        const c = new Client(
+          { name: "connecta", version: CONNECTA_VERSION },
+          { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
+        );
+        const t = buildTransport(ctx, provider);
+        if (!ownsAttempt()) await abandon(t);
+        state.transport = t;
+        try {
+          await c.connect(t);
+          // A probe deadline can end its scope while connect is still in flight.
+          // The transport is closed immediately by closeScope; if connect wins
+          // that race anyway, close the resulting client rather than
+          // resurrecting a session in the detached state object.
+          if (!ownsAttempt()) await abandon(c);
+          // A force re-auth that landed WHILE we were connecting wiped the
+          // credentials this client just bound to. Discard it rather than
+          // cache a stale-isolate connection.
+          if (provider) {
+            const generation = await provider.generation();
+            // closeScope can land while the generation read is pending, after
+            // connect succeeded but before this client is cached. Discard the
+            // client on that side of the await too.
+            if (!ownsAttempt()) await abandon(c);
+            if (generation !== genAtStart) {
+              try {
+                await c.close();
+              } catch {
+                // discarding either way
+              }
+              throw new UnauthorizedError(
+                "Connector was re-authorized during connect; reconnect required.",
+              );
             }
-            throw scopeEndedError();
           }
-          if (generation !== genAtStart) {
-            try {
-              await c.close();
-            } catch {
-              // discarding either way
-            }
-            throw new UnauthorizedError(
-              "Connector was re-authorized during connect; reconnect required.",
-            );
+          if (!ownsAttempt()) await abandon(c);
+          state.client = c;
+          state.connectedGeneration = genAtStart;
+          state.authRequired = false;
+        } catch (err) {
+          // Only a real 401/UnauthorizedError means auth is the problem — a
+          // network error on an oauth connector must surface as "error", not
+          // "auth_required".
+          if (err instanceof UnauthorizedError && ownsAttempt()) {
+            state.authRequired = true;
           }
+          if (err instanceof UnauthorizedError) {
+            throw authRequiredError(err);
+          }
+          throw err;
+        } finally {
+          // Force reset may have abandoned this attempt and installed a new one
+          // in the same request scope. An old completion must not erase the new
+          // promise and allow a third concurrent connect.
+          if (state.connecting === attempt) state.connecting = null;
         }
-        state.client = c;
-        state.connectedGeneration = genAtStart;
-        state.authRequired = false;
-      } catch (err) {
-        // Only a real 401/UnauthorizedError means auth is the problem — a
-        // network error on an oauth connector must surface as "error", not
-        // "auth_required".
-        if (err instanceof UnauthorizedError) {
-          state.authRequired = true;
-          throw authRequiredError(err);
+      })();
+      state.connecting = attempt;
+    }
+    return state.connecting;
+  };
+
+  const disconnectAuthorization = async (
+    ctx: ConnectorContext,
+    state: ConnectionState,
+    operatorDisconnected = false,
+  ): Promise<void> => {
+    const provider = getProvider(ctx, state);
+    // Publish the replacement epoch before waiting on or closing any
+    // request-local transport. A hung connect therefore cannot delay the
+    // fence, and every late OAuth write stays in the older namespace.
+    const connecting = state.connecting;
+    try {
+      await provider.resetAuthorization(operatorDisconnected);
+    } finally {
+      // Consume the abandoned connect and close whichever half of the
+      // client/transport exists. Reset is unconditional because KV may already
+      // be fenced behind a newer epoch after a cleanup error.
+      void connecting?.catch(() => {});
+      try {
+        if (state.client) {
+          await state.client.close();
+        } else {
+          await state.transport?.close();
         }
-        throw err;
-      } finally {
-        state.connecting = null;
+      } catch {
+        // best-effort; the state is discarded either way
       }
-    })();
-    return state.connecting;
+      reset(state);
+    }
   };
 
   const connector: Connector = {
@@ -760,7 +841,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         // Classify that exactly like connect-time and call-time authorization
         // failures, and latch it for the rest of this request scope.
         if (err instanceof UnauthorizedError) {
-          state.authRequired = true;
+          if (state.client === client) state.authRequired = true;
           throw authRequiredError(err);
         }
         throw err;
@@ -788,8 +869,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     async callTool(name, args, ctx) {
       const state = stateFor(ctx);
       await ensureConnected(ctx, state);
+      const client = state.client!;
       try {
-        return await state.client!.callTool(
+        return await client.callTool(
           {
             name,
             arguments: (args ?? {}) as Record<string, unknown>,
@@ -805,7 +887,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       } catch (err) {
         // A grant revoked after connect surfaces here, not in ensureConnected.
         if (err instanceof UnauthorizedError) {
-          state.authRequired = true;
+          if (state.client === client) state.authRequired = true;
           throw authRequiredError(err);
         }
         throw err;
@@ -860,6 +942,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
             message: "Authorization required — open the URL to connect.",
           };
         }
+        if (err instanceof OperatorDisconnectedError) {
+          return { state: "auth_required", message: err.message };
+        }
         return { state: "error", message: msg(err) };
       }
     },
@@ -867,12 +952,11 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     async finishAuth(code, ctx) {
       const state = stateFor(ctx);
       const provider = getProvider(ctx, state);
-      // The provider here may carry no captured generation, so its token saves
-      // fail open. That is safe only because generation advances solely via the
-      // force path, which always wipes oauth:state — so verifyState rejects any
-      // pre-force callback before this runs. Keep those two facts coupled.
+      // verifyState ran on this request-scoped provider first and captured the
+      // pending flow's generation. If force reset races the exchange, any late
+      // token write remains tagged with that older generation and is unreadable.
       const t = (state.transport ??
-        buildTransport(ctx, state)) as StreamableHTTPClientTransport;
+        buildTransport(ctx, provider)) as StreamableHTTPClientTransport;
       await t.finishAuth(code);
       await provider.clearPending();
       // Reset so the next use reconnects with the freshly stored tokens.
@@ -895,31 +979,15 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       return getProvider(ctx, state).verifyState(oauthState);
     };
 
+    connector.disconnectAuth = async (ctx) => {
+      await disconnectAuthorization(ctx, stateFor(ctx), true);
+    };
+
     connector.startAuth = async (ctx, startOpts) => {
       const state = stateFor(ctx);
       const p = getProvider(ctx, state);
-      if (startOpts?.force) {
-        // Wipe stored credentials and drop the live connection so the next
-        // connect attempt runs the flow from scratch (DCR + PKCE + consent).
-        // Fence the in-flight connect first: a late-completing attempt must not
-        // resurrect the credentials we're about to wipe, nor leave `client` set
-        // (which would make ensureConnected below report already-authorized and
-        // silently defeat force).
-        await state.connecting?.catch(() => {});
-        try {
-          await state.client?.close();
-        } catch {
-          // best-effort; the connection is being discarded either way
-        }
-        // Bump the shared generation FIRST so any other isolate — one mid-
-        // connect, or on its next tool call — sees the advance and drops its
-        // client instead of keeping the token we're about to revoke.
-        await p.bumpGeneration();
-        // Wipe KV before dropping in-memory state so nothing racing back in can
-        // write tokens over a half-cleared slot.
-        await p.invalidateCredentials("all");
-        await p.clearPending();
-        reset(state);
+      if (startOpts?.force || (await p.operatorDisconnected())) {
+        await disconnectAuthorization(ctx, state);
       } else {
         // A consent URL already outstanding? Re-issue it rather than re-running
         // the SDK flow, which would overwrite the PKCE verifier and invalidate

package/src/execute.ts

@@ -369,20 +369,33 @@ export async function buildSandboxProviders(
           score: number;
           order: number;
         }> = [];
-        let orderBase = 0;
-        for (const connector of connectors) {
-          if (args.connector && connector.id !== args.connector) continue;
-          const tools = catalogs.get(connector.id);
-          if (!tools) continue;
-          for (const ranked of rankTools(tools, args.query ?? "")) {
-            matches.push({
-              connector: connector.id,
-              tool: ranked.tool,
-              score: ranked.score,
-              order: orderBase + ranked.order,
-            });
+        let matchMode: "all" | "partial" = "all";
+        const collectMatches = (mode: "all" | "partial") => {
+          matches.length = 0;
+          let orderBase = 0;
+          for (const connector of connectors) {
+            if (args.connector && connector.id !== args.connector) continue;
+            const tools = catalogs.get(connector.id);
+            if (!tools) continue;
+            for (const ranked of rankTools(
+              tools,
+              args.query ?? "",
+              mode,
+            )) {
+              matches.push({
+                connector: connector.id,
+                tool: ranked.tool,
+                score: ranked.score,
+                order: orderBase + ranked.order,
+              });
+            }
+            orderBase += tools.length;
           }
-          orderBase += tools.length;
+        };
+        collectMatches("all");
+        if ((args.query ?? "").trim() && matches.length === 0) {
+          matchMode = "partial";
+          collectMatches(matchMode);
         }
         matches.sort((a, b) => b.score - a.score || a.order - b.order);
         const offset = Math.max(0, Math.trunc(args.offset ?? 0));
@@ -428,6 +441,9 @@ export async function buildSandboxProviders(
           limit,
           hasMore: nextOffset !== undefined,
           ...(nextOffset !== undefined ? { nextOffset } : {}),
+          ...(matchMode === "partial" && matches.length > 0
+            ? { matchMode }
+            : {}),
         };
         assertDiscoveryResultSize(
           result,

package/src/index.ts

@@ -94,7 +94,7 @@ export interface ConnectaDiscoveryConfig {
   probeTimeoutMs?: number;
 }
 
-/** Deployment-wide call deadlines and inline-result paging threshold. */
+/** Deployment-wide call deadlines and inline-result paging thresholds. */
 export interface ConnectaCallsConfig {
   /**
    * Deadline (ms) for `call_tool`/`batch_call` calls that pass no `timeoutMs`.
@@ -111,6 +111,13 @@ export interface ConnectaCallsConfig {
    * 50_000. Connectors may override it individually.
    */
   maxResultBytes?: number;
+  /**
+   * Max serialized `batch_call` envelope size (bytes) before the full batch is
+   * stashed for `get_result` and only an ordered outcome summary is returned
+   * inline. Must be a finite whole number >= 1; invalid values warn and fall
+   * back to 100_000. This cap is independent of per-connector child caps.
+   */
+  maxBatchResultBytes?: number;
 }
 
 export interface AdmissionPoolConfig {
@@ -544,6 +551,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     persistToolCatalog: config.discovery?.persistCatalog,
     toolCatalogStaleSeconds: config.discovery?.staleCatalogSeconds,
     maxResultBytes: config.calls?.maxResultBytes,
+    maxBatchResultBytes: config.calls?.maxBatchResultBytes,
     credentialHealth: config.credentials?.health,
   });
   // Throws on every structural mistake it can see (see resolveToolkits): a
@@ -719,8 +727,11 @@ export type {
   ActivityCallSource,
   ActivityOutcome,
   ActivityPage,
+  ActivityReadActor,
+  ActivityReadEvent,
   ActivityReader,
   ActivityReadGate,
+  ActivityReadPage,
   ActivitySink,
   ActivityStore,
   ToolCallActivityEvent,

package/src/meta-tools.ts

@@ -406,6 +406,15 @@ async function stashResult(
   };
 }
 
+/** Keep an oversized batch's inline outcome summary at fixed string overhead. */
+function batchSummaryString(value: string): string {
+  const bytes = enc.encode(value);
+  const maxBytes = 512;
+  if (bytes.length <= maxBytes) return value;
+  const end = alignEndToCharBoundary(bytes, 0, maxBytes, bytes.length);
+  return `${dec.decode(bytes.slice(0, end))}…`;
+}
+
 /**
  * Return `text` as a single content block; if it exceeds `cap` bytes, stash the
  * full text and return the first `cap` bytes followed by a JSON truncation
@@ -575,10 +584,10 @@ export interface SkillArgs {
  * supplies a deadline for calls that don't carry one. (execute_code, the
  * optional tenth tool, is registered separately by registerExecuteTool.)
  *
- * The deployment-wide result-size cap is read off the registry view rather than
- * passed in: `ConnectaConfig.calls.maxResultBytes` and the per-connector
- * override are the only places a cap is set, so there is one answer to where a
- * deployment sets it (issue #44).
+ * Deployment-wide result-size caps are read off the registry view rather than
+ * passed in: `ConnectaConfig.calls.maxResultBytes`, its per-connector override,
+ * and the independent `calls.maxBatchResultBytes` final-envelope boundary each
+ * have one runtime source of truth.
  */
 export function createMetaTools(
   registry: RegistryView,
@@ -595,6 +604,7 @@ export function createMetaTools(
 ) {
   // Already normalized and warned about at registry construction.
   const globalCap = registry.maxResultBytes;
+  const batchCap = registry.maxBatchResultBytes;
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
   const probeTimeoutMs =
     normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
@@ -1141,26 +1151,36 @@ export function createMetaTools(
           ),
         ),
       );
-      let orderBase = 0;
-      catalogs.forEach((catalog, connectorIndex) => {
-        const c = conns[connectorIndex];
-        if (catalog.status === "fulfilled") {
-          for (const ranked of rankTools(catalog.value, q)) {
-            matches.push({
-              connectorId: c.id,
-              connectorTitle: c.title,
-              connectorDescription: c.description,
-              ...(connectorGuide(c)
-                ? { connectorGuideSkill: connectorSkillName(c.id) }
-                : {}),
-              tool: ranked.tool,
-              score: ranked.score,
-              order: orderBase + ranked.order,
-            });
+      let matchMode: "all" | "partial" = "all";
+      const collectMatches = (mode: "all" | "partial") => {
+        matches.length = 0;
+        let orderBase = 0;
+        catalogs.forEach((catalog, connectorIndex) => {
+          const c = conns[connectorIndex];
+          if (catalog.status === "fulfilled") {
+            for (const ranked of rankTools(catalog.value, q, mode)) {
+              matches.push({
+                connectorId: c.id,
+                connectorTitle: c.title,
+                connectorDescription: c.description,
+                ...(connectorGuide(c)
+                  ? { connectorGuideSkill: connectorSkillName(c.id) }
+                  : {}),
+                tool: ranked.tool,
+                score: ranked.score,
+                order: orderBase + ranked.order,
+              });
+            }
           }
-        }
-        orderBase += catalog.status === "fulfilled" ? catalog.value.length : 1;
-      });
+          orderBase +=
+            catalog.status === "fulfilled" ? catalog.value.length : 1;
+        });
+      };
+      collectMatches("all");
+      if (q.trim() && matches.length === 0) {
+        matchMode = "partial";
+        collectMatches(matchMode);
+      }
       matches.sort((a, b) => b.score - a.score || a.order - b.order);
       const page = matches.slice(offset, offset + limit);
       const groups: {
@@ -1235,6 +1255,9 @@ export function createMetaTools(
           limit,
           hasMore: nextOffset !== undefined,
           ...(nextOffset !== undefined ? { nextOffset } : {}),
+          ...(matchMode === "partial" && matches.length > 0
+            ? { matchMode }
+            : {}),
         },
         "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
       );
@@ -1457,9 +1480,50 @@ export function createMetaTools(
             : {}),
         };
       });
-      return jsonResult({
+      const envelope = {
         results,
         durationMs: Date.now() - batchStarted,
+      };
+      const text = serializeResultText(envelope);
+      const bytes = enc.encode(text);
+      if (bytes.length <= batchCap) return jsonResult(envelope);
+
+      const notice = await stashResult(
+        text,
+        registry.resultsStorage(),
+        bytes.length,
+      );
+      return jsonResult({
+        results: results.map((result) => {
+          const common = {
+            address: batchSummaryString(result.address),
+            ok: !("error" in result),
+            ...("durationMs" in result
+              ? { durationMs: result.durationMs }
+              : {}),
+            ...("attempts" in result ? { attempts: result.attempts } : {}),
+            ...("timing" in result ? { timing: result.timing } : {}),
+          };
+          if (!("error" in result)) return common;
+          const error = result.error ?? "Batch call failed";
+          const details =
+            result.errorDetails ??
+            errorDetails("batch_call_failed", error);
+          return {
+            ...common,
+            error: batchSummaryString(error),
+            errorDetails: {
+              code: batchSummaryString(details.code),
+              message: batchSummaryString(details.message),
+              retryable: details.retryable,
+              ...(details.retryAfterMs !== undefined
+                ? { retryAfterMs: details.retryAfterMs }
+                : {}),
+            },
+          };
+        }),
+        durationMs: envelope.durationMs,
+        ...notice,
       });
     },
 
@@ -1527,7 +1591,7 @@ const CALL_DESTRUCTIVE_DESC =
 const GET_RESULT_DESC =
   "Page a truncated result stashed by call_tool/batch_call. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
 const BATCH_DESC =
-  "Use for 2–10 independent tools explicitly annotated readOnlyHint: true. Calls run in parallel with shared request-scoped clients; use execute_code when available instead for dependencies or in-sandbox reduction. Unannotated, write-capable, and destructive tools are refused. Batch timeout, safe retry, result mode, and diagnostics defaults may be overridden per call.";
+  "Use for 2–10 independent tools explicitly annotated readOnlyHint: true. Calls run in parallel with shared request-scoped clients; use execute_code when available instead for dependencies or in-sandbox reduction. Unannotated, write-capable, and destructive tools are refused. Batch timeout, safe retry, result mode, and diagnostics defaults may be overridden per call. An oversized final envelope returns ordered outcome summaries plus a get_result page handle.";
 const AUTHORIZE_DESC =
   "Use after a connector reports auth_required. Starts downstream OAuth and returns an authorizationUrl for the operator to open. force=true wipes stored credentials first and restarts consent.";
 const SKILLS_DESC =