@zackbart/connecta 0.22.3 → 0.24.0

package/dist/invocation.js

@@ -1,10 +1,9 @@
-import { recordToolActivity, } from "./activity.js";
 import { isCallAdmissionError } from "./call-admission.js";
 import { classifyCallError, ConnectorCallError, echoedCallArgs, framingError, } from "./errors.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import { splitAddress } from "./registry.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
-import { sleep, withDeadline } from "./timeout.js";
+import { withDeadline } from "./timeout.js";
 import { validateToolInput } from "./validate.js";
 function defined(values) {
     return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
@@ -18,40 +17,6 @@ async function timed(bucket, fn) {
         bucket(Date.now() - started);
     }
 }
-/**
- * The longest the engine will park a synchronous inbound request in *waiting
- * alone*. The engine already treats ~15 s as the outer bound of one reasonable
- * connector call (EXECUTE_HOST_CALL_TIMEOUT_MS), so sleeping for minutes trades
- * a fast, informative failure for a hung one. A connector-reported window this
- * long isn't truncated — it's declined (see `retryBackoffMs`) and reported
- * verbatim as `error.retryAfterMs`, so the agent, which can afford to wait,
- * decides when to re-issue.
- */
-export const MAX_RETRY_BACKOFF_MS = 10_000;
-/**
- * How long to wait before the next attempt, or `undefined` for "don't retry".
- *
- * A connector that read a `Retry-After` header knows the window exactly, so it
- * is honoured **exactly or not at all**: truncating an exponential *guess* is
- * harmless, but truncating a *known* window means deliberately retrying inside
- * a rate limit — the harm this channel exists to prevent. A window longer than
- * `MAX_RETRY_BACKOFF_MS` therefore declines the retry rather than shortening
- * it. (`retryAfterMs` is normalized non-negative, so `0` means "retry now".)
- * Connectors that report no window keep the historical exponential guess.
- *
- * Waits are per attempt, matching the per-attempt `timeoutMs` race in
- * `InvocationService.invoke`. Exported for direct testing.
- */
-export function retryBackoffMs(attempt, retryAfterMs) {
-    if (retryAfterMs === undefined) {
-        return Math.min(250 * 2 ** (attempt - 1), 1_000);
-    }
-    return retryAfterMs <= MAX_RETRY_BACKOFF_MS ? retryAfterMs : undefined;
-}
-function retrySafe(definition) {
-    return (definition.annotations?.readOnlyHint === true ||
-        definition.annotations?.idempotentHint === true);
-}
 function callerCancelledDetails() {
     return {
         code: "cancelled",
@@ -62,7 +27,7 @@ function callerCancelledDetails() {
 function recoveryMode(registry, connector, baseUrl) {
     if (connector.startAuth)
         return "oauth";
-    if (connector.credential &&
+    if (registry.credentialUiAvailable() && connector.credential &&
         registry.contextFor(connector.id, baseUrl).credential) {
         return "operator_config";
     }
@@ -122,23 +87,10 @@ export class InvocationService {
         this.activity = activity;
     }
     async invoke(address, args, context) {
-        const options = defined({ signal: context.requestSignal });
-        return this.invokeWithResolution(address, args, context, () => this.catalog.resolveTool(address, options));
-    }
-    /**
-     * Code-mode namespace dispatch preserves JavaScript-safe tool aliases while
-     * still feeding the resolved catalog entry through the one invocation path.
-     */
-    async invokeToolAlias(connectorId, toolAlias, aliasFor, args, context) {
-        const options = defined({ signal: context.requestSignal });
-        return this.invokeWithResolution(`${connectorId}.${toolAlias}`, args, context, () => this.catalog.resolveToolAlias(connectorId, toolAlias, aliasFor, options));
-    }
-    async invokeWithResolution(address, args, context, resolve) {
         const started = Date.now();
         let catalogMs = 0;
         let admissionMs = 0;
         let connectorMs = 0;
-        let backoffMs = 0;
         let resultProcessingMs = 0;
         let attempts = 0;
         let resolved;
@@ -151,7 +103,6 @@ export class InvocationService {
             catalogMs,
             admissionMs,
             connectorMs,
-            backoffMs,
             resultProcessingMs,
             totalMs: Date.now() - started,
         });
@@ -164,7 +115,7 @@ export class InvocationService {
                 : attempted;
             if (!identity)
                 return;
-            recordToolActivity(this.activity, {
+            this.activity?.recordTool?.(this.activity, {
                 connectorId: identity.connectorId,
                 toolName: identity.toolName,
                 address: `${identity.connectorId}.${identity.toolName}`,
@@ -248,7 +199,7 @@ export class InvocationService {
                 error: details,
             };
         };
-        const resolution = await resolve();
+        const resolution = await this.catalog.resolveTool(address, defined({ signal: context.requestSignal }));
         catalogMs += resolution.catalogMs;
         if (!resolution.ok) {
             if (resolution.connector && resolution.toolName) {
@@ -290,80 +241,61 @@ export class InvocationService {
                 ? error.details
                 : classifyCallError(error));
         }
-        const maxRetries = Math.min(2, Math.max(0, Math.trunc(context.maxRetries ?? 0)));
         let result;
         let observedResult;
-        while (true) {
-            attempts++;
-            let permit;
-            let attemptError;
-            let attemptFailed = false;
-            try {
-                permit = await timed((elapsed) => { admissionMs += elapsed; }, () => this.registry.admitCall(resolved.connector.id, {
-                    toolName: resolved.toolName,
-                    args: args ?? {},
-                    ...defined({ signal: context.requestSignal }),
-                }));
-                const raw = await timed((elapsed) => { connectorMs += elapsed; }, () => {
-                    const call = (callSignal) => {
-                        const connectorContext = this.registry.contextFor(resolved.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs }));
-                        if (resolved.connector.credential &&
-                            !connectorContext.credential) {
-                            throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
-                                `authorize_connector({ connector: "${resolved.connector.id}" }).`);
-                        }
-                        // Cancellation can arrive during admission or context construction.
-                        if (callSignal?.aborted)
-                            throw callSignal.reason;
-                        return resolved.connector.callTool(resolved.toolName, args ?? {}, connectorContext);
-                    };
-                    if (!context.timeoutMs && !context.requestSignal)
-                        return call();
-                    return withDeadline(call, {
-                        ...defined({
-                            timeoutMs: context.timeoutMs,
-                            signal: context.requestSignal,
-                        }),
-                        timeoutError: new ConnectorCallError("timeout", `Tool call timed out after ${context.timeoutMs}ms`),
-                    });
-                });
-                // isError is checked here for BOTH result shapes so every adapter
-                // reports the same downstream-failure wording, and the throw lands
-                // inside the attempt where it stays retry-eligible and feeds health.
-                assertRawMcpSuccess(resolved.connector.kind, raw);
-                observedResult = unwrapMcpResult(resolved.connector.kind, raw);
-                result = context.unwrapResult ? observedResult : raw;
-            }
-            catch (error) {
-                attemptFailed = true;
-                attemptError = error;
-            }
-            finally {
-                permit?.release();
-            }
-            if (attemptFailed) {
-                const callerCancelled = isCallerCancellation(attemptError, context.requestSignal);
-                const details = callerCancelled
-                    ? callerCancelledDetails()
-                    : classifyCallError(attemptError);
-                if (!callerCancelled &&
-                    attempts <= maxRetries &&
-                    retrySafe(resolved.definition) &&
-                    details.retryable) {
-                    const wait = retryBackoffMs(attempts, details.retryAfterMs);
-                    if (wait !== undefined) {
-                        const completed = await timed((elapsed) => { backoffMs += elapsed; }, () => sleep(wait, context.requestSignal));
-                        if (!completed)
-                            return failed(callerCancelledDetails());
-                        continue;
+        attempts = 1;
+        let permit;
+        let attemptError;
+        let attemptFailed = false;
+        try {
+            permit = await timed((elapsed) => { admissionMs += elapsed; }, () => this.registry.admitCall(resolved.connector.id, {
+                toolName: resolved.toolName,
+                args: args ?? {},
+                ...defined({ signal: context.requestSignal }),
+            }));
+            const raw = await timed((elapsed) => { connectorMs += elapsed; }, () => {
+                const call = (callSignal) => {
+                    const connectorContext = this.registry.contextFor(resolved.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs }));
+                    if (resolved.connector.credential &&
+                        !connectorContext.credential) {
+                        throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
+                            `authorize_connector({ connector: "${resolved.connector.id}" }).`);
                     }
-                    // The reported window is longer than the engine will park a
-                    // synchronous request for. Fall through to failure with
-                    // retryAfterMs reported verbatim so the agent can re-issue.
-                }
-                return failed(details);
-            }
-            break;
+                    // Cancellation can arrive during admission or context construction.
+                    if (callSignal?.aborted)
+                        throw callSignal.reason;
+                    return resolved.connector.callTool(resolved.toolName, args ?? {}, connectorContext);
+                };
+                if (!context.timeoutMs && !context.requestSignal)
+                    return call();
+                return withDeadline(call, {
+                    ...defined({
+                        timeoutMs: context.timeoutMs,
+                        signal: context.requestSignal,
+                    }),
+                    timeoutError: new ConnectorCallError("timeout", `Tool call timed out after ${context.timeoutMs}ms`),
+                });
+            });
+            // isError is checked here for BOTH result shapes so every adapter
+            // reports the same downstream-failure wording, and the throw lands
+            // inside the attempt where it feeds health.
+            assertRawMcpSuccess(resolved.connector.kind, raw);
+            observedResult = unwrapMcpResult(resolved.connector.kind, raw);
+            result = context.unwrapResult ? observedResult : raw;
+        }
+        catch (error) {
+            attemptFailed = true;
+            attemptError = error;
+        }
+        finally {
+            permit?.release();
+        }
+        if (attemptFailed) {
+            const callerCancelled = isCallerCancellation(attemptError, context.requestSignal);
+            const details = callerCancelled
+                ? callerCancelledDetails()
+                : classifyCallError(attemptError);
+            return failed(details);
         }
         try {
             const value = await timed((elapsed) => { resultProcessingMs += elapsed; }, async () => {

package/dist/meta-tools.d.ts

@@ -2,9 +2,8 @@ import type { McpServer } from "@modelcontextprotocol/server";
 import type { ActivityRequestContext } from "./activity.js";
 import { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT } from "./catalog-service.js";
 import type { DeferredWork } from "./connector-scope.js";
-import { MAX_RETRY_BACKOFF_MS, retryBackoffMs } from "./invocation.js";
 import { type RegistryView } from "./registry.js";
-export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_RETRY_BACKOFF_MS, MAX_SEARCH_LIMIT, retryBackoffMs, };
+export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, };
 interface TextContent {
     type: "text";
     text: string;
@@ -48,8 +47,6 @@ export interface CallArgs {
     args?: Record<string, unknown>;
     resultMode?: ResultMode;
     timeoutMs?: number;
-    /** Retries after the first attempt; honored only for safely annotated tools. */
-    maxRetries?: number;
     /** Include connector/catalog/result-processing timing segments. */
     diagnostics?: boolean;
 }
@@ -97,6 +94,8 @@ export declare function createMetaTools(registry: RegistryView, baseUrl: string,
     /** Maximum simultaneous connector discovery operations. Default 4. */
     discoveryConcurrency?: number | undefined;
     activity?: ActivityRequestContext | undefined;
+    canManageAuth?: ((id: string) => boolean) | undefined;
+    credentialHandoffUrl?: string | undefined;
     /** Inbound request cancellation shared by every call this request makes. */
     requestSignal?: AbortSignal | undefined;
     /** Runtime-owned tail for stale catalog refreshes. */
@@ -112,8 +111,8 @@ export declare function createMetaTools(registry: RegistryView, baseUrl: string,
 /**
  * Register the six explicit meta-tools onto an McpServer instance.
  * `registerExecuteTool` adds the seventh, `execute_code`. Broad discovery and
- * multi-call work is reached through `connecta.search` / `connecta.describe` /
- * `connecta.batch` inside a program, which `execute_code` builds over the same
+ * multi-call work uses discovery and ordinary JavaScript promises inside a
+ * program, which `execute_code` builds over the same
  * `CatalogService` and `InvocationService` these handlers use — one shared
  * services layer, two adapters above it.
  */
@@ -123,6 +122,8 @@ export declare function registerMetaTools(server: McpServer, registry: RegistryV
     probeTimeoutMs?: number | undefined;
     discoveryConcurrency?: number | undefined;
     activity?: ActivityRequestContext | undefined;
+    canManageAuth?: ((id: string) => boolean) | undefined;
+    credentialHandoffUrl?: string | undefined;
     requestSignal?: AbortSignal | undefined;
     defer?: DeferredWork | undefined;
 }): void;

package/dist/meta-tools.js

@@ -3,11 +3,11 @@ import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPo
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { msg } from "./errors.js";
 import { serializeResultText } from "./executor-result.js";
-import { InvocationService, MAX_RETRY_BACKOFF_MS, retryBackoffMs, } from "./invocation.js";
+import { InvocationService, } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
 import { hasConnectorGuides, listSkills, resolveSkill, } from "./skills.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
-export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_RETRY_BACKOFF_MS, MAX_SEARCH_LIMIT, retryBackoffMs, };
+export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, };
 const RESULT_TTL_SECONDS = 900;
 const enc = new TextEncoder();
 const dec = new TextDecoder();
@@ -267,9 +267,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 ? { allowDestructive: options.allowDestructive }
                 : {}),
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            ...(call.maxRetries !== undefined
-                ? { maxRetries: call.maxRetries }
-                : {}),
             ...(opts.requestSignal !== undefined
                 ? { requestSignal: opts.requestSignal }
                 : {}),
@@ -451,12 +448,12 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     });
                 }
                 const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
-                if (!ctx.credential) {
+                if (!ctx.credential || !opts.credentialHandoffUrl) {
                     return jsonResult({
                         connector: connector.id,
                         recovery: "unavailable",
-                        message: "Credential storage is not configured. Configure " +
-                            "credentials.encryptionKey, redeploy, then call " +
+                        message: "Credential recovery needs both a vault and the optional UI. Configure " +
+                            "vault and ui in deployment code, then call " +
                             "authorize_connector again.",
                     });
                 }
@@ -477,7 +474,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         label: connector.credential.label,
                         fields,
                     },
-                    operatorUrl: new URL("/credentials", baseUrl).toString(),
+                    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"
@@ -485,6 +482,8 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                             : "Shared credential mutation requires a signed-in human with access to this connector."),
                 });
             }
+            if (!opts.canManageAuth?.(connector.id))
+                return jsonResult({ connector: connector.id, recovery: "unavailable", message: "Your identity is not permitted to manage authentication for this connection." });
             const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
             try {
                 const status = await connector.startAuth(ctx, args.force !== undefined ? { force: args.force } : {});
@@ -568,14 +567,13 @@ const CALL_INPUT_SCHEMA = {
     args: z.record(z.string(), z.unknown()).optional(),
     resultMode: z.enum(["mcp", "value"]).optional(),
     timeoutMs: z.number().int().positive().optional(),
-    maxRetries: z.number().int().min(0).max(2).optional(),
     diagnostics: z.boolean().optional(),
 };
 /**
  * Register the six explicit meta-tools onto an McpServer instance.
  * `registerExecuteTool` adds the seventh, `execute_code`. Broad discovery and
- * multi-call work is reached through `connecta.search` / `connecta.describe` /
- * `connecta.batch` inside a program, which `execute_code` builds over the same
+ * multi-call work uses discovery and ordinary JavaScript promises inside a
+ * program, which `execute_code` builds over the same
  * `CatalogService` and `InvocationService` these handlers use — one shared
  * services layer, two adapters above it.
  */
@@ -585,6 +583,8 @@ export function registerMetaTools(server, registry, ctx) {
         probeTimeoutMs: ctx.probeTimeoutMs,
         discoveryConcurrency: ctx.discoveryConcurrency,
         activity: ctx.activity,
+        canManageAuth: ctx.canManageAuth,
+        credentialHandoffUrl: ctx.credentialHandoffUrl,
         requestSignal: ctx.requestSignal,
         defer: ctx.defer,
     });
@@ -592,7 +592,6 @@ export function registerMetaTools(server, registry, ctx) {
         description: describedFor(registry, SKILLS_DESC, "skills"),
         inputSchema: z.object({ name: z.string().optional() }),
         annotations: READ_ONLY_LOCAL,
-        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.skills(args));
     server.registerTool("search_tools", {
         description: describedFor(registry, SEARCH_DESC, "search"),
@@ -608,20 +607,17 @@ export function registerMetaTools(server, registry, ctx) {
             includeSchemas: z.enum(["compact", "json"]).optional(),
         }),
         annotations: READ_ONLY_REMOTE,
-        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.searchTools(args));
     server.registerTool("call_tool", {
         description: CALL_DESC,
-        inputSchema: z.object(CALL_INPUT_SCHEMA),
+        inputSchema: z.strictObject(CALL_INPUT_SCHEMA),
         // 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,
-        // Omission defaults to model + app. Display-only views may call no tool.
-        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.callTool(args));
     server.registerTool("call_destructive_tool", {
         description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
-        inputSchema: z.object({
+        inputSchema: z.strictObject({
             ...CALL_INPUT_SCHEMA,
             // Bounded above, but with no lower bound: a model that sends `""` or
             // whitespace has written no reason, and failing an entire consequential
@@ -634,7 +630,6 @@ export function registerMetaTools(server, registry, ctx) {
             readOnlyHint: false,
             openWorldHint: true,
         },
-        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => {
         // `reason` is the host's to display and connecta's to keep out of the
         // downstream call, so this destructuring is the whole of its handling:
@@ -657,7 +652,6 @@ export function registerMetaTools(server, registry, ctx) {
             destructiveHint: false,
             openWorldHint: true,
         },
-        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.authorizeConnector(args));
     server.registerTool("get_result", {
         description: GET_RESULT_DESC,
@@ -671,6 +665,5 @@ export function registerMetaTools(server, registry, ctx) {
             maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
         }),
         annotations: READ_ONLY_LOCAL,
-        _meta: { ui: { visibility: ["model"] } },
     }, async (args) => mt.getResult(args));
 }

package/dist/module-contracts.d.ts

@@ -0,0 +1,19 @@
+import type { ConnectaBranding } from "./types.js";
+import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogDriftActivity } from "./activity.js";
+import type { RouteContext } from "./routes/shared.js";
+/** Construction-time UI contract. Core never imports the implementation. */
+export interface OperatorSurface {
+    readonly branding?: ConnectaBranding;
+    readonly reservedPaths: readonly string[];
+    credentialHandoffUrl(baseUrl: string): string;
+    handle(context: RouteContext): Promise<Response | null>;
+}
+/** Optional recording and reading callbacks supplied by /activity. */
+export interface ActivityModule {
+    readonly store: ActivityStore;
+    readonly deploymentId?: string;
+    readonly readGate?: ActivityReadGate;
+    handle(context: RouteContext): Promise<Response | null>;
+    readonly recordTool: typeof recordToolActivity;
+    readonly recordDrift: typeof recordCatalogDriftActivity;
+}

package/dist/module-contracts.js

@@ -0,0 +1 @@
+export {};