@zackbart/connecta 0.10.5 → 0.11.0

package/src/index.ts

@@ -18,7 +18,6 @@ import type { ActivityReadGate, ActivityStore } from "./activity.js";
 import type {
   Connector,
   ConnectaBranding,
-  ConnectaSurface,
   Executor,
   InboundAuth,
   KVStorage,
@@ -77,10 +76,11 @@ export interface ConnectaDiscoveryConfig {
   staleCatalogSeconds?: number;
   /**
    * Deadline (ms) for each downstream probe/catalog call fanned out by
-   * `list_connectors`, `search_tools`, and `describe_tools`. Defaults to
-   * 30_000. A timed-out connector degrades independently; this does not apply
-   * to tool calls. Catalog walks receive the same cancellation signal, which
-   * aborts an in-flight page where supported and prevents another from starting.
+   * `search_tools` and by `connecta.search`/`connecta.describe` inside
+   * `execute_code`. Defaults to 30_000. A timed-out connector degrades
+   * independently; this does not apply to tool calls. Catalog walks receive the
+   * same cancellation signal, which aborts an in-flight page where supported and
+   * prevents another from starting.
    */
   probeTimeoutMs?: number;
 }
@@ -88,9 +88,9 @@ export interface ConnectaDiscoveryConfig {
 /** Deployment-wide call deadlines and inline-result paging thresholds. */
 export interface ConnectaCallsConfig {
   /**
-   * Deadline (ms) for `call_tool`/`batch_call` calls that pass no `timeoutMs`.
-   * An explicit per-call value wins. Opt-in: unset by default, so existing
-   * long-running calls gain no surprise deadline.
+   * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
+   * `timeoutMs`. An explicit per-call value wins. Opt-in: unset by default, so
+   * existing long-running calls gain no surprise deadline.
    *
    * This bounds one attempt, not all retries. `execute_code` host calls are
    * unaffected because they already carry their own bound.
@@ -102,13 +102,19 @@ export interface ConnectaCallsConfig {
    * 50_000. Connectors may override it individually.
    */
   maxResultBytes?: number;
+}
+
+/** Budgets for rich output emitted by execute_code programs (`connecta.emit`). */
+export interface ConnectaExecuteConfig {
   /**
-   * 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.
+   * Aggregate serialized bytes `connecta.emit` accepts per run. Default
+   * 4_000_000 — a transport bound, not a context bound: emitted image/audio
+   * blocks reach the model as media, not base64 text. Invalid values fall
+   * back to the default.
    */
-  maxBatchResultBytes?: number;
+  maxEmittedBytes?: number;
+  /** Content blocks `connecta.emit` accepts per run. Default 32. */
+  maxEmittedBlocks?: number;
 }
 
 export interface AdmissionPoolConfig {
@@ -164,6 +170,8 @@ export interface ConnectaConfig {
   discovery?: ConnectaDiscoveryConfig;
   /** Deployment-wide call deadlines and result paging threshold. */
   calls?: ConnectaCallsConfig;
+  /** Budgets for the `connecta.emit` rich-output channel in execute_code. */
+  execute?: ConnectaExecuteConfig;
   /** Bounded MCP and fallback code-mode admission. */
   admission?: ConnectaAdmissionConfig;
   /** Optional browser UI and OAuth result-page labels. */
@@ -182,22 +190,12 @@ export interface ConnectaConfig {
   /** Deployment metadata exposed by /health (for example a Worker version). */
   deploymentInfo?: Record<string, unknown>;
   /**
-   * Sandbox for `execute_code`, and the switch that decides the surface: with
-   * an executor a model sees the seven code-first tools, without one the nine
-   * classic ones. Workers: `new DynamicWorkerExecutor({ loader: env.LOADER })`
-   * from `@cloudflare/codemode`. Node: `quickJsExecutor()` from
-   * "@zackbart/connecta/quickjs".
-   */
-  executor?: Executor;
-  /**
-   * Override the surface the `executor` implies. The only reason to set it is
-   * `"classic"` alongside an executor — ten tools, the shape the eval gate's
-   * *incremental* arm measures ("does adding `execute_code` to classic help on
-   * its own?"). The gate's control arm is executor-free classic, which needs no
-   * override. `"code-first"` is the default wherever an executor exists and
-   * throws without one.
+   * Required sandbox for `execute_code`. Workers use
+   * `new DynamicWorkerExecutor({ loader: env.LOADER })` from
+   * `@cloudflare/codemode`; Node uses `quickJsExecutor()` from
+   * `@zackbart/connecta/quickjs`.
    */
-  surface?: ConnectaSurface;
+  executor: Executor;
 }
 
 export interface Connecta {
@@ -291,6 +289,20 @@ function assertNoLegacyConfig(config: ConnectaConfig): void {
         "issue #179. Credentials now fail at use; see ethos.md.",
     );
   }
+  const calls = candidate.calls;
+  if (
+    typeof calls === "object" &&
+    calls !== null &&
+    hasOwn(calls, "maxBatchResultBytes")
+  ) {
+    throw new Error(
+      "`calls.maxBatchResultBytes` was removed in issue #273 along with " +
+        "batch_call. Remove it; a program's batching is bounded by " +
+        "execute_code's own limits — connecta.batch's per-run call ceiling " +
+        "and the executor result cap — while each call inside it still honours " +
+        "calls.maxResultBytes and any per-connector override.",
+    );
+  }
   const found: Array<readonly [string, string]> = [];
   if (hasOwn(candidate, "activity")) {
     const activity = candidate.activity;
@@ -429,43 +441,22 @@ function warnInsecureConfig(
   }
 }
 
-/**
- * The advertised surface: the executor is the switch. Configure one and the
- * deployment serves the seven-tool code-first surface; omit it and there is no
- * program to fold discovery and batching into, so it serves classic.
- *
- * Two mistakes are structural rather than recoverable, so neither is warned
- * past: a surface name connecta does not implement, which would otherwise
- * resolve to something the operator did not ask for; and `code-first` without
- * an executor, which would advertise six tools and no program surface.
- */
-function resolveSurface(config: ConnectaConfig): ConnectaSurface {
-  const surface = config.surface;
-  if (surface === undefined) {
-    return config.executor ? "code-first" : "classic";
-  }
-  if (surface !== "classic" && surface !== "code-first") {
+export function createConnecta(config: ConnectaConfig): Connecta {
+  assertNoLegacyConfig(config);
+  if (Object.prototype.hasOwnProperty.call(config, "surface")) {
     throw new Error(
-      `ConnectaConfig.surface must be "classic" or "code-first", not ` +
-        `${JSON.stringify(surface)}.`,
+      "ConnectaConfig.surface was removed in issue #273. Remove it; connecta " +
+        "now serves one seven-tool surface.",
     );
   }
-  if (surface === "code-first" && !config.executor) {
+  if (!config.executor) {
     throw new Error(
-      'ConnectaConfig.surface "code-first" requires an executor: it folds ' +
-        "list_connectors, describe_tools, and batch_call into connecta.search, " +
-        "connecta.describe, and connecta.batch inside execute_code, so without " +
-        "an executor there is nothing left to reach them through. Configure " +
-        "one (quickJsExecutor() from \"@zackbart/connecta/quickjs\" on Node, " +
-        "new DynamicWorkerExecutor({ loader: env.LOADER }) on Workers).",
+      "ConnectaConfig.executor is required. Configure quickJsExecutor() from " +
+        '"@zackbart/connecta/quickjs" on Node, or ' +
+        "new DynamicWorkerExecutor({ loader: env.LOADER }) from " +
+        '"@cloudflare/codemode" on Workers.',
     );
   }
-  return surface;
-}
-
-export function createConnecta(config: ConnectaConfig): Connecta {
-  assertNoLegacyConfig(config);
-  const surface = resolveSurface(config);
   const storage = config.storage ?? memoryStorage();
   const logger = config.logger ?? defaultLogger();
   const credentialConnectors = config.connectors.filter((c) => c.credential);
@@ -509,9 +500,6 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     ...(config.calls?.maxResultBytes !== undefined
       ? { maxResultBytes: config.calls.maxResultBytes }
       : {}),
-    ...(config.calls?.maxBatchResultBytes !== undefined
-      ? { maxBatchResultBytes: config.calls.maxBatchResultBytes }
-      : {}),
   });
   const inboundAuth = normalizeAuth(
     accessTokens ? [accessTokens.auth, ...configuredAuth] : configuredAuth,
@@ -527,10 +515,10 @@ export function createConnecta(config: ConnectaConfig): Connecta {
   );
   let codeAdmission: AdmissionController | undefined;
   let executor = config.executor;
-  if (executor && !isAdmittingExecutor(executor)) {
+  if (!isAdmittingExecutor(executor)) {
     codeAdmission = configuredCodeAdmission;
     executor = withExecutorAdmission(executor, codeAdmission);
-  } else if (executor && config.admission?.code) {
+  } else if (config.admission?.code) {
     logger.warn(
       "[connecta] admission.code is ignored because the configured executor " +
         "implements acquire() and owns its admission pool; configure that " +
@@ -556,8 +544,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     ...(config.activity?.deploymentId !== undefined
       ? { activityDeploymentId: config.activity.deploymentId }
       : {}),
-    ...(executor !== undefined ? { executor } : {}),
-    surface,
+    executor,
     requestAdmission,
     ...(config.calls?.defaultTimeoutMs !== undefined
       ? { defaultToolTimeoutMs: config.calls.defaultTimeoutMs }
@@ -568,6 +555,12 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     ...(config.discovery?.concurrency !== undefined
       ? { discoveryConcurrency: config.discovery.concurrency }
       : {}),
+    ...(config.execute?.maxEmittedBytes !== undefined
+      ? { maxEmittedBytes: config.execute.maxEmittedBytes }
+      : {}),
+    ...(config.execute?.maxEmittedBlocks !== undefined
+      ? { maxEmittedBlocks: config.execute.maxEmittedBlocks }
+      : {}),
     ...(credentialVault !== undefined ? { credentialVault } : {}),
     ...(accessTokens !== undefined ? { accessTokens } : {}),
     ...(config.deploymentInfo !== undefined
@@ -632,7 +625,6 @@ export type {
   ConnectorCallAdmissionRule,
   ConnectorRollingWindowBudget,
   ConnectaBranding,
-  ConnectaSurface,
   ConnectorCredentialAccess,
   ConnectorCredentialConfig,
   ConnectorCredentialFieldConfig,
@@ -667,6 +659,7 @@ export type {
   ActivityReadPage,
   ActivitySink,
   ActivityStore,
+  AgentFriction,
   ToolCallActivityEvent,
 } from "./activity.js";
 export { InvalidActivityCursorError } from "./activity.js";

package/src/invocation.ts

@@ -2,6 +2,7 @@ import {
   recordToolActivity,
   type ActivityCallSource,
   type ActivityRequestContext,
+  type AgentFriction,
 } from "./activity.js";
 import { isCallAdmissionError } from "./call-admission.js";
 import {
@@ -12,12 +13,13 @@ import {
 import {
   classifyCallError,
   ConnectorCallError,
+  echoedCallArgs,
   framingError,
   type AuthRecoveryMode,
   type CallErrorDetails,
 } from "./errors.js";
 import { unwrapMcpResult } from "./mcp-result.js";
-import type { RegistryView } from "./registry.js";
+import { splitAddress, type RegistryView } from "./registry.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 import type { ToolDef } from "./types.js";
 import { validateToolInput } from "./validate.js";
@@ -150,6 +152,13 @@ export interface InvocationContext<T> {
     value: unknown,
     resolved: ResolvedCatalogTool,
   ) => T | Promise<T>;
+  /**
+   * Optional payload-free friction class derived from a *successful* result —
+   * today only an oversized one that had to be paged. It is deliberately not an
+   * `errorCode`: the call succeeded, and a consumer that keys its dashboards on
+   * "has an error code" must not count a truncation as a failure.
+   */
+  activityFriction?: (value: T) => AgentFriction | undefined;
   /**
    * Called after address/catalog/safety admission and before the first provider
    * attempt. Code mode uses it for its host-call budget.
@@ -252,6 +261,10 @@ export class InvocationService {
     let activityTarget:
       | Pick<ResolvedCatalogTool, "connector" | "toolName">
       | undefined;
+    // The address as written, used for activity when resolution never reached
+    // a connector. Only its two halves are recorded — the same fields activity
+    // has always carried — so no new class of payload enters the log.
+    const attempted = splitAddress(address);
     const timing = (): InvocationTiming => ({
       catalogMs,
       admissionMs,
@@ -262,25 +275,56 @@ export class InvocationService {
     });
     const record = (
       outcome: "success" | "error" | "timeout" | "cancelled",
-      errorCode?: string,
+      classification: { errorCode?: string; friction?: AgentFriction } = {},
     ) => {
-      if (!activityTarget) return;
+      const identity = activityTarget
+        ? {
+            connectorId: activityTarget.connector.id,
+            toolName: activityTarget.toolName,
+          }
+        : attempted;
+      if (!identity) return;
       recordToolActivity(this.activity, {
-        connectorId: activityTarget.connector.id,
-        toolName: activityTarget.toolName,
-        address: `${activityTarget.connector.id}.${activityTarget.toolName}`,
+        connectorId: identity.connectorId,
+        toolName: identity.toolName,
+        address: `${identity.connectorId}.${identity.toolName}`,
         source: context.source,
         outcome,
         durationMs: Date.now() - started,
         attempts,
-        ...(errorCode ? { errorCode } : {}),
+        ...(classification.errorCode
+          ? { errorCode: classification.errorCode }
+          : {}),
+        ...(classification.friction
+          ? { friction: classification.friction }
+          : {}),
       });
     };
     const failed = (error: CallErrorDetails): InvocationOutcome<T> => {
       const diagnostics = timing();
       const target = resolved ?? activityTarget;
+      const echoed =
+        error.code === "destructive_tool_requires_approval"
+          ? echoedCallArgs(args)
+          : {};
       const details =
-        error.code === "auth_required" && target
+        error.code === "destructive_tool_requires_approval" && target
+          ? {
+              ...error,
+              nextAction: {
+                tool: "call_destructive_tool" as const,
+                arguments: {
+                  address: `${target.connector.id}.${target.toolName}`,
+                  ...echoed,
+                },
+                purpose:
+                  "Ask the MCP host to approve this consequential call. " +
+                  ("args" in echoed
+                    ? "Re-send these arguments and add a short reason for the human reviewer."
+                    : "Re-send the arguments you just sent — they are too large to echo back — and add a short reason for the human reviewer."),
+              },
+            }
+          : error.code === "auth_required" && target
           ? {
               ...error,
               connector: target.connector.id,
@@ -305,16 +349,13 @@ export class InvocationService {
                 ...error,
                 connector: target.connector.id,
                 operation: `${target.connector.id}.${target.toolName}`,
-                nextAction: {
-                  tool: "search_tools" as const,
-                  arguments: {
+                nextAction: this.catalog.searchRecovery(
+                  {
                     query: target.toolName,
                     connector: target.connector.id,
-                    includeSchemas: "compact" as const,
                   },
-                  purpose:
-                    "Inspect the current input shape if the validation findings are not sufficient.",
-                },
+                  "Inspect the current input shape if the validation findings are not sufficient.",
+                ),
                 retry:
                   `Correct the listed arguments and retry ` +
                   `${target.connector.id}.${target.toolName}.`,
@@ -326,7 +367,7 @@ export class InvocationService {
           : details.code === "cancelled"
             ? "cancelled"
             : "error",
-        details.code,
+        { errorCode: details.code },
       );
       return {
         ok: false,
@@ -354,8 +395,8 @@ export class InvocationService {
         // A connector whose catalog cannot be fetched is as unusable as one
         // whose execution fails, so it feeds health accounting the same way the
         // attempt catch below does — otherwise a connector every call fails
-        // against (a revoked downstream grant, say) still reads clean from the
-        // cheap `list_connectors({ probe: false })` signal.
+        // against (a revoked downstream grant, say) still reads clean in the
+        // deployment's health log.
         //
         // Recorded HERE rather than inside the registry's catalog fetch because
         // a cache hit that avoids a live listTools call records nothing — it is
@@ -591,7 +632,8 @@ export class InvocationService {
         : (result as T);
       resultProcessingMs += Date.now() - processingStarted;
       const diagnostics = timing();
-      record("success");
+      const friction = context.activityFriction?.(value);
+      record("success", friction ? { friction } : {});
       return {
         ok: true,
         value,