@zackbart/connecta 0.22.3 → 0.24.0

package/dist/routes/shared.d.ts

@@ -1,12 +1,12 @@
 import type { Implementation } from "@modelcontextprotocol/server";
-import type { AccessTokenManager } from "../access-tokens.js";
+import type { ActivityModule, OperatorSurface } from "../module-contracts.js";
 import type { ActivityActor, ActivityReadGate, ActivityStore } from "../activity.js";
-import type { CredentialVault } from "../credentials.js";
+import type { CredentialVault } from "../credential-contract.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
 import type { Registry } from "../registry.js";
-import type { AuthenticatedIdentity, ConnectaBranding, Executor, IdentityReference, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
-import type { ConnectaIdentityConfig } from "../index.js";
+import type { AuthenticatedIdentity, ConnectaBranding, Executor, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
+import type { ConnectorPermission, ConnectaIdentityConfig } from "../index.js";
 export { msg } from "../errors.js";
 export interface ServerOptions {
     registry: Registry;
@@ -37,8 +37,9 @@ export interface ServerOptions {
     requestAdmission: AdmissionController;
     /** Encrypted connector-credential storage backing the Credentials page. */
     credentialVault?: CredentialVault | undefined;
-    /** Hashed deployment access tokens backing MCP admission and the Tokens page. */
-    accessTokens?: AccessTokenManager | undefined;
+    /** Optional browser routes, with no implementation import in core. */
+    ui?: OperatorSurface | undefined;
+    activityModule?: ActivityModule | undefined;
     /** Optional browser UI and OAuth result-page labels. */
     branding?: ConnectaBranding | undefined;
 }
@@ -74,22 +75,14 @@ export declare function authorize(request: Request, baseUrl: string, auth: Inbou
     principalKey?: string;
     connectorIds: "all" | readonly string[];
     operator: boolean;
+    credentialAdministration: ConnectorPermission;
+    personalConnection: ConnectorPermission;
     /** Backward-compatible name used by operator views. */
     uiAdminEligible?: boolean;
 } | {
     ok: false;
     response: Response;
 }>;
-export declare function authorizeUiAdmin(request: Request, baseUrl: string, auth: InboundAuth[], purpose?: string, runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig): Promise<{
-    ok: true;
-    userId: string;
-    principal?: IdentityReference;
-    principalKey?: string;
-    connectorIds: "all" | readonly string[];
-} | {
-    ok: false;
-    response: Response;
-}>;
 export declare function authorizeUiIdentity(request: Request, baseUrl: string, auth: InboundAuth[], purpose: string, runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig): Promise<Extract<Awaited<ReturnType<typeof authorize>>, {
     ok: true;
 }> | {
@@ -97,4 +90,13 @@ export declare function authorizeUiIdentity(request: Request, baseUrl: string, a
     response: Response;
 }>;
 export declare function isSameOrigin(request: Request, baseUrl: string): boolean;
-export declare function withSecurityHeaders(response: Response, requestUrl: URL, path: string): Response;
+export declare function withSecurityHeaders(response: Response, requestUrl: URL, _path: string): Response;
+type AuthorizedIdentity = Extract<Awaited<ReturnType<typeof authorize>>, {
+    ok: true;
+}>;
+/** Unknown configured ids refuse the complete view, including management rights. */
+export declare function validateAuthPermissions(authz: AuthorizedIdentity, registry: Registry): void;
+export declare function mayManageConnector(authz: AuthorizedIdentity, connector: {
+    id: string;
+    authScope?: "shared" | "personal";
+}): boolean;

package/dist/routes/shared.js

@@ -1,5 +1,4 @@
 import { identityStorageKey, validIdentityReference } from "../identity.js";
-import { operatorPageForPath } from "../ui.js";
 export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
     const headers = new Headers(init.headers);
@@ -36,7 +35,9 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
         const identity = { actor, interactive: false };
         let connectorIds = "all";
         try {
-            connectorIds = await identityConfig?.connectorAccess?.(identity) ?? "all";
+            connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
+            if (connectorIds !== "all" && (!Array.isArray(connectorIds) || !connectorIds.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
+                throw new Error("invalid connector permission");
         }
         catch {
             return {
@@ -44,7 +45,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
             };
         }
-        return { ok: true, actor, identity, connectorIds, operator: false };
+        return { ok: true, actor, identity, connectorIds, operator: false, credentialAdministration: "none", personalConnection: "none" };
     }
     let lastResponse = null;
     for (const provider of auth) {
@@ -74,14 +75,26 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 interactive,
             };
             let operator = interactive;
+            let credentialAdministration = "none";
+            let personalConnection = "none";
             let connectorIds = "all";
             try {
-                if (identityConfig?.operatorAccess) {
+                if (identityConfig?.activityAccess) {
                     operator = interactive && principal
-                        ? await identityConfig.operatorAccess(principal)
+                        ? await identityConfig.activityAccess(principal)
                         : false;
                 }
-                connectorIds = await identityConfig?.connectorAccess?.(identity) ?? "all";
+                connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
+                if (interactive) {
+                    credentialAdministration = identityConfig?.credentialAdministration ? await identityConfig.credentialAdministration(identity) : "none";
+                    personalConnection = principal && identityConfig?.personalConnection ? await identityConfig.personalConnection(identity) : "none";
+                }
+                if (typeof operator !== "boolean")
+                    throw new Error("invalid activity permission");
+                for (const permission of [connectorIds, credentialAdministration, personalConnection]) {
+                    if (permission !== "all" && permission !== "none" && (!Array.isArray(permission) || !permission.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
+                        throw new Error("invalid identity permission");
+                }
             }
             catch {
                 return {
@@ -100,6 +113,8 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                     ? { principalKey: await identityStorageKey(principal) }
                     : {}),
                 connectorIds,
+                credentialAdministration,
+                personalConnection,
                 operator,
                 ...(operator ? { uiAdminEligible: true } : {}),
             };
@@ -118,34 +133,6 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
             }),
     };
 }
-export async function authorizeUiAdmin(request, baseUrl, auth, purpose = "credential management", runtimeContext, identityConfig) {
-    // Operator mutation is intentionally narrower than /mcp and /ui/data: only
-    // an interactive provider may admit it. A static bearer token is useful
-    // for headless tool calls but must not become a deployment-admin key.
-    //
-    // Every interactive provider gets a turn, the way the /mcp gate does.
-    // Stopping at the first would make admission depend on config order: a failed gate or
-    // missing user may simply mean a later provider is the one meant to admit.
-    // The last refusal is returned if none do.
-    const authz = await authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext, identityConfig);
-    if (!authz.ok)
-        return authz;
-    if (!authz.operator || !authz.actor.id) {
-        return {
-            ok: false,
-            response: privateJson({ error: `${purpose} requires operator access` }, { status: 403 }),
-        };
-    }
-    return {
-        ok: true,
-        userId: authz.identity.principal?.id ?? authz.actor.id,
-        ...(authz.identity.principal
-            ? { principal: authz.identity.principal }
-            : {}),
-        ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
-        connectorIds: authz.connectorIds,
-    };
-}
 export async function authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext, identityConfig) {
     const providers = auth.filter((candidate) => candidate.interactiveOperator);
     if (providers.length === 0) {
@@ -181,25 +168,42 @@ export function isSameOrigin(request, baseUrl) {
         return false;
     }
 }
-export function withSecurityHeaders(response, requestUrl, path) {
+export function withSecurityHeaders(response, requestUrl, _path) {
     const headers = new Headers(response.headers);
     headers.set("X-Content-Type-Options", "nosniff");
     headers.set("Referrer-Policy", "no-referrer");
     if (requestUrl.protocol === "https:") {
         headers.set("Strict-Transport-Security", "max-age=31536000");
     }
-    if (operatorPageForPath(path) || path === "/ui") {
-        // Operator HTML responses ship their own nonce-based script CSP (which
-        // already includes frame-ancestors 'none'); only fall back to the
-        // framing-only directive when no CSP is present (for example redirects).
-        if (!headers.has("Content-Security-Policy")) {
-            headers.set("Content-Security-Policy", "frame-ancestors 'none'");
-        }
-        headers.set("X-Frame-Options", "DENY");
-    }
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
         headers,
     });
 }
+/** Unknown configured ids refuse the complete view, including management rights. */
+export function validateAuthPermissions(authz, registry) {
+    for (const value of [
+        authz.connectorIds,
+        authz.credentialAdministration,
+        authz.personalConnection,
+    ]) {
+        if (value === "all" || value === "none")
+            continue;
+        if (!Array.isArray(value) || value.some(id => !registry.getConnector(id))) {
+            throw new Error("invalid identity permission connector ids");
+        }
+    }
+}
+export function mayManageConnector(authz, connector) {
+    if (!authz.identity.interactive)
+        return false;
+    if (authz.connectorIds !== "all" && !authz.connectorIds.includes(connector.id)) {
+        return false;
+    }
+    const permission = connector.authScope === "personal"
+        ? authz.personalConnection
+        : authz.credentialAdministration;
+    return permission === "all" ||
+        (permission !== "none" && permission.includes(connector.id));
+}

package/dist/routes/ui.js

@@ -1,6 +1,7 @@
+import { CONNECTA_VERSION } from "../version.js";
 import { CONNECTA_FAVICON_ICO } from "../favicon.js";
-import { buildUiData, CONNECTA_FAVICON_SVG, credentialManagementCapability, operatorPageForPath, renderUiHtml, } from "../ui.js";
-import { authorize, msg, privateJson, } from "./shared.js";
+import { buildUiData, CONNECTA_FAVICON_SVG, operatorPageForPath, renderUiHtml, } from "../ui.js";
+import { authorize, mayManageConnector, validateAuthPermissions, msg, privateJson, } from "./shared.js";
 /**
  * Headers that make an operator-supplied favicon body inert on this origin.
  * The SVG route is the sharp one: `image/svg+xml` is an *active* content type,
@@ -67,7 +68,7 @@ export async function routeUi(context) {
         });
     }
     const operatorPage = operatorPageForPath(path);
-    if (operatorPage) {
+    if (operatorPage && (operatorPage !== "activity" || opts.activity?.list)) {
         if (request.method !== "GET" && request.method !== "HEAD") {
             return privateJson({ error: "method not allowed" }, { status: 405 });
         }
@@ -97,13 +98,17 @@ export async function routeUi(context) {
             },
         });
     }
-    if (path !== "/ui/data")
+    const detail = /^\/ui\/connectors\/([a-z0-9_-]+)$/.exec(path);
+    if (path !== "/ui/data" && !detail)
         return null;
+    if (request.method !== "GET")
+        return privateJson({ error: "method not allowed" }, { status: 405 });
     const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity);
     if (!authz.ok)
         return authz.response;
     let registry;
     try {
+        validateAuthPermissions(authz, opts.registry);
         registry = opts.registry.scoped({
             connectorIds: authz.connectorIds,
             ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
@@ -113,33 +118,31 @@ export async function routeUi(context) {
     catch (error) {
         return privateJson({ error: msg(error) }, { status: 403 });
     }
-    const eligibleOperator = authz.uiAdminEligible === true;
-    const interactiveManager = authz.identity.interactive;
-    const personalManager = Boolean(interactiveManager && authz.principalKey);
-    const visibleConnectors = registry.listConnectors();
-    const hasManageableCredentialSlot = visibleConnectors.some((connector) => Boolean(connector.credential) &&
-        (connector.authScope !== "personal" || personalManager));
-    const credentialManagement = interactiveManager && hasManageableCredentialSlot
-        ? opts.credentialVault
-            ? "available"
-            : "vault_not_configured"
-        : credentialManagementCapability({
-            eligibleOperator: interactiveManager,
-            hasCredentialSlots: visibleConnectors.some((connector) => Boolean(connector.credential)),
-            hasCredentialVault: Boolean(opts.credentialVault),
-        });
-    // As with connector credentials, a Bearer-authenticated observer learns
-    // only that an interactive operator is required, not whether this deployment has opted into
-    // token issuance. Configuration topology is operator data.
-    const accessTokenManagement = !eligibleOperator
-        ? "requires_operator"
-        : opts.accessTokens
-            ? "available"
-            : "not_configured";
-    const data = await buildUiData(registry, baseUrl, opts.serverInfo, 
-    // A static headless bearer may read connector health, but only an
-    // interactive human receives credential metadata for visible connectors.
-    interactiveManager ? opts.credentialVault : undefined, Boolean(opts.activity?.list) &&
-        (!opts.identity?.operatorAccess || eligibleOperator), credentialManagement, defer, interactiveManager, opts.discoveryConcurrency, accessTokenManagement, personalManager ? authz.principalKey : undefined);
-    return privateJson(data);
+    const visible = registry.listConnectors();
+    const mayManage = (id) => { const connector = registry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); };
+    const permissions = (connector) => ({
+        use: true,
+        manageSharedAuth: connector.authScope !== "personal" && mayManage(connector.id),
+        connectPersonal: connector.authScope === "personal" && mayManage(connector.id),
+    });
+    const activityEnabled = Boolean(opts.activity?.list) && authz.operator;
+    const credentialManagement = visible.some(c => c.credential && mayManage(c.id))
+        ? opts.credentialVault ? "available" : "vault_not_configured"
+        : authz.identity.interactive && !visible.some(c => c.credential) ? "no_slots" : "requires_operator";
+    if (detail) {
+        const connector = registry.getConnector(detail[1]);
+        if (!connector)
+            return privateJson({ error: "unknown connector" }, { status: 404 });
+        const one = opts.registry.scoped({ connectorIds: [connector.id], ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}), ...(authz.principalKey ? { principalKey: authz.principalKey } : {}) });
+        const data = await buildUiData(one, baseUrl, opts.serverInfo, opts.credentialVault, activityEnabled, credentialManagement, defer, false, 1, authz.principalKey, { mayManage, timeoutMs: opts.probeTimeoutMs ?? 30_000, signal: request.signal });
+        return privateJson({ ...data.connectors[0], permissions: permissions(connector) });
+    }
+    return privateJson({
+        serverInfo: opts.serverInfo,
+        connectaVersion: CONNECTA_VERSION,
+        activityEnabled,
+        credentialManagement,
+        oauthManagement: visible.some(c => mayManage(c.id)),
+        connectors: visible.map(c => ({ id: c.id, ...(c.title ? { title: c.title } : {}), ...(c.description ? { description: c.description } : {}), authScope: c.authScope ?? "shared", status: "loading", toolCount: 0, tools: [], oauth: Boolean(c.startAuth && c.disconnectAuth), permissions: permissions(c) })),
+    });
 }

package/dist/server.d.ts

@@ -4,7 +4,6 @@ export type { ServerOptions } from "./routes/shared.js";
  * Build the Web-standard fetch handler.
  *
  * Route ordering is the contract: private mutation routes precede wildcard
- * OPTIONS, every built-in precedes connector-owned routes, and the security
- * wrapper is applied to every response.
+ * OPTIONS, and the security wrapper is applied to every response, including 404s.
  */
 export declare function createFetchHandler(opts: ServerOptions): (request: Request, runtimeContext?: RuntimeExecutionContext) => Promise<Response>;

package/dist/server.js

@@ -1,17 +1,12 @@
 import { isAdmittingExecutor } from "./executor-admission.js";
-import { routeAccessTokens } from "./routes/access-tokens.js";
-import { routeActivity } from "./routes/activity.js";
-import { routeCredentials } from "./routes/credentials.js";
 import { createMcpRoute, MCP_CORS_HEADERS } from "./routes/mcp.js";
-import { routeOAuthCallback, routeOAuthManagement, } from "./routes/oauth.js";
+import { routeOAuthCallback, } from "./routes/oauth.js";
 import { withSecurityHeaders, } from "./routes/shared.js";
-import { routeUi } from "./routes/ui.js";
 /**
  * Build the Web-standard fetch handler.
  *
  * Route ordering is the contract: private mutation routes precede wildcard
- * OPTIONS, every built-in precedes connector-owned routes, and the security
- * wrapper is applied to every response.
+ * OPTIONS, and the security wrapper is applied to every response, including 404s.
  */
 export function createFetchHandler(opts) {
     const { auth, publicUrl, registry } = opts;
@@ -60,15 +55,9 @@ export function createFetchHandler(opts) {
         };
         const route = async () => {
             // Private mutations own OPTIONS so they never inherit wildcard CORS.
-            const accessTokens = await routeAccessTokens(context);
-            if (accessTokens)
-                return accessTokens;
-            const credentials = await routeCredentials(context);
-            if (credentials)
-                return credentials;
-            const oauthManagement = await routeOAuthManagement(context);
-            if (oauthManagement)
-                return oauthManagement;
+            const uiResponse = await opts.ui?.handle(context);
+            if (uiResponse)
+                return uiResponse;
             if (request.method === "OPTIONS") {
                 for (const provider of auth) {
                     if (provider.handleMetadata) {
@@ -124,12 +113,8 @@ export function createFetchHandler(opts) {
                         },
                         reservedRoutes: [
                             "/health",
-                            "/",
-                            "/credentials",
-                            "/tokens",
-                            "/activity",
-                            "/ui",
-                            "/ui/*",
+                            ...(opts.ui?.reservedPaths ?? []),
+                            ...(opts.ui && opts.activity?.list ? ["/activity"] : []),
                         ],
                     },
                     ...(opts.deploymentInfo ? { deployment: opts.deploymentInfo } : {}),
@@ -138,32 +123,9 @@ export function createFetchHandler(opts) {
             const oauthCallback = await routeOAuthCallback(context);
             if (oauthCallback)
                 return oauthCallback;
-            const ui = await routeUi(context);
-            if (ui)
-                return ui;
-            const activity = await routeActivity(context);
-            if (activity)
-                return activity;
             const mcp = await routeMcp(context);
             if (mcp)
                 return mcp;
-            // Connector-owned public routes, dispatched last: a connector can add a
-            // route but never shadow one of connecta's own. A throw here is the
-            // connector's bug, not a missing route, so it surfaces as 500 rather
-            // than falling through to 404.
-            for (const connector of registry.listConnectors()) {
-                if (!connector.handleRequest)
-                    continue;
-                try {
-                    const response = await connector.handleRequest(request, registry.contextFor(connector.id, baseUrl));
-                    if (response)
-                        return response;
-                }
-                catch (error) {
-                    opts.logger.error(`[connecta] connector "${connector.id}" handleRequest failed`, error);
-                    return new Response("Internal Server Error", { status: 500 });
-                }
-            }
             return new Response("Not Found", { status: 404 });
         };
         return withSecurityHeaders(await route(), url, path);

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with one execute_code program that discovers, calls, and returns the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Guidance is on demand: fetch skills({ name: \"usage\" }) only when these instructions and the tool description are insufficient or a run needs repair.";
+export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: \"usage\" }) only when these instructions and the tool description are insufficient or a run needs repair.";
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export declare const USAGE_SKILL: string;
 /** The always-loaded MCP `instructions` string. */

package/dist/skills.js

@@ -1,59 +1,58 @@
-export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with one execute_code program that discovers, calls, and returns the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
+export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
 const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
 
 Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Read-only discovery and multi-call work live in a program. Top-level search remains for catalog inspection and approval-required work.
 
-The always-loaded MCP instructions are authoritative for choosing the top-level route. Read this skill at most once, and only when their program workflow is insufficient or a run needs repair.
+Follow the MCP instructions for routing. Read at most once for syntax or repair.
 
 ## Inside a program
 
-Write one plain-JavaScript async arrow function. TypeScript syntax and portable imports do not work. Return JSON-shaped data and reduce large results before returning.
+Write one plain-JavaScript async arrow function, without TypeScript or imports. Return reduced JSON-shaped data.
 
 The minimum guest API is:
 
-- \`<connectorId>.<toolName>(args)\` calls a sanitized shortcut. Non-identifier characters become \`_\`; leading digits gain \`_\`; reserved words gain a trailing \`_\`.
 - \`connecta.call("connector.tool", args)\` uses the canonical address and returns the unwrapped value.
 - \`connecta.search(args)\` returns \`{ tools, total, offset, limit, hasMore }\`; \`connecta.describe(args)\` returns \`{ tools }\`.
-- \`connecta.batch(calls)\` runs 2–10 independent calls. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails }\`.
-- \`console.log(...)\` is captured. \`connecta.emit(block)\` and \`connecta.ui(html)\` produce rich output.
+- Use \`Promise.all\` for independent calls, or \`Promise.allSettled\` to keep successes and failures.
+- \`console.log(...)\` is captured. \`connecta.emit(block)\` produces rich output.
 
 ## Discover and select
 
-Search inside the run and finish the task there. A discovery-only program wastes a round trip. Use 2–4 distinctive action/object terms, not the full request. Use separate short searches for distinct operations.
+Search and call in one run when schemas suffice. For unfamiliar result formats, return a small sample and continue; do not guess a parser. Use 2–4 distinctive action/object terms; search distinct operations separately.
 
-For top-level catalog inspection or approval-required discovery, omit \`limit\` initially (the default is 10), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An observed shape carries \`outputSchemaSource: "observed"\`; treat it as routing evidence rather than a provider contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
+For top-level catalog inspection or approval-required discovery, omit \`limit\` initially (the default is 8), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An \`outputSchemaSource: "observed"\` shape is a hint, not a contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
 
 - \`connecta.search({})\` loads all catalogs. Pass \`connector: "<id>"\` when the integration is obvious. Use \`safety: "readOnly"\` for program calls. These inputs filter discovery; they grant no authority.
-- Request \`includeSchemas: "compact"\`. Check address, purpose, annotations, required inputs, truncation, safety, and available outputs. Never select only because a result ranks first or has fewer required inputs.
+- Use \`includeSchemas: "json"\` for programmatic schema inspection; compact schemas are text, not objects with \`.properties\`. Check connectorTitle for the account/environment, then address, purpose, annotations, inputs, and outputs. Never select only because a result ranks first or has fewer required inputs.
 - Supply every \`requiredInputKey\` from the task or a prior result. For dependencies, match the earlier \`outputKey\` to the later required key. An empty required-key list does not permit invented arguments. Missing \`outputKeys\` means inspect \`outputSchema\`.
 - Use \`connecta.describe({ address })\` or \`{ addresses }\` when a compact schema is truncated or insufficient. Use \`format: "json"\` only for exact constraints. Write the property names the schema displays; never guess positions or aliases.
-- Reduce through available output keys. Treat an observed key as a hint, since later results may omit it or add others. Do not guess collection roots such as \`items\` or \`results\`. If a match or result key is missing, inspect, re-search, or describe inside the same run instead of returning discovery for another call.
+- Reduce through available output keys. Treat an observed key as a hint, since later results may omit it or add others. Do not guess collection roots such as \`items\` or \`results\`. If a match is missing, re-search or describe. If a result shape is unclear, return a small sample for inspection before continuing.
 - Match provider identifiers and names exactly after resolving them from source data or a connector guide. A broad regular expression that merely finds a plausible value is not identity resolution.
-- Preserve the schema's JSON types exactly: a numeric id is a number, not a numeric-looking string. Call the search and describe functions directly; batch accepts canonical connector tool addresses, not guest API function names.
+- Preserve the schema's JSON types exactly: a numeric id is a number, not a numeric-looking string.
 - Validate tabular headers, row arrays, and row widths before mapping them. Never let a header or partial row become data.
 
 Only tools explicitly annotated \`readOnlyHint: true\` are reachable. The catalog, credential, admission, and read-only gates run below the sandbox; code cannot widen its authority.
 
 ## Errors and repair
 
-Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`details\`. Batch failures expose the same classification in \`errorDetails\`. Branch on fields, never prose. Do not retry \`retryable: false\`, and do not retry \`rate_limited\` immediately because portable code has no timer.
+Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`details\`. Promise rejections retain these fields. Branch on fields, never prose. After a shared argument failure, repair one call before repeating it across other records. Do not retry \`retryable: false\`, and do not retry \`rate_limited\` immediately because portable code has no timer.
 
 - \`destructive_tool_requires_approval\`: stop the program and use the returned canonical address with top-level \`call_destructive_tool\`.
 - \`auth_required\`: let the failure reach the model, then use top-level \`authorize_connector\`, give its handoff to the operator, and retry after recovery.
 - A truncated direct-call result: follow its \`get_result\` action. A truncated program result has no page handle; filter, map, or slice inside a new program.
 - Unknown addresses and tools carry scoped search recovery. Use it inside the current run. Do not invent an address.
 
-For a direct call, \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. \`maxRetries\` is honored only for safely annotated tools. \`diagnostics: true\` adds timing.
+For a direct call, \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. Every call makes one attempt; use the returned error classification and retry hint to decide whether to reissue. \`diagnostics: true\` adds timing.
 
 \`get_result({ id, offset?, maxBytes? })\` returns \`{ text, offset, nextOffset?, totalBytes }\` for a direct-call result. Both sizes are byte counts: \`maxBytes\` must be a whole number at least 1 and defaults to the deployment cap; \`offset\` must be a whole number at least 0 and defaults to 0. An offset inside a multi-byte character moves back to its first byte, and the response reports the served offset. Follow \`nextOffset\` to reassemble pages. An unknown or expired id is an error.
 
-Limits: 20 host calls per run, 10 calls per batch, and a 15-second deadline per host call.
+Limits: 20 host calls per run and a 15-second deadline per host call.
 
 ## Runtime portability
 
-Portable code uses only connector globals, \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch, process, timers, crypto, and WebSocket. Dynamic Workers must use only \`{ loader }\`; bindings, modules, or globalOutbound grant ambient authority. With loader only, environment maps are empty; node:fs/http/https are absent; outbound fetch, WebSocket, node:net, and node:tls are denied; DNS is unresolved. Runtime builtins remain through \`import()\` and \`process.getBuiltinModule()\`, including node:path and cloudflare:workers; this set can drift. Timers, process, crypto, WebSocket, and data: fetch remain. Avoid every runtime-only capability because QuickJS fails.
+Portable code uses standard JavaScript builtins, \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch, process, timers, crypto, and WebSocket. Dynamic Workers must use only \`{ loader }\`; bindings, modules, or globalOutbound grant ambient authority. With loader only, environment maps are empty; node:fs/http/https are absent; outbound fetch, WebSocket, node:net, and node:tls are denied; DNS is unresolved. Runtime builtins remain through \`import()\` and \`process.getBuiltinModule()\`, including node:path and cloudflare:workers; this set can drift. Timers, process, crypto, WebSocket, and data: fetch remain. Avoid every runtime-only capability because QuickJS fails.
 
 ## Examples
 
@@ -61,13 +60,29 @@ One read-only call at a known address:
 
 \`async () => await connecta.call("crm.get_account", { id: "acct_42" })\`
 
-Dependent calls, only when the second needs a value from the first:
+Dependent lookup: verify connector \`ci\`, run 42, and these schema fields first.
 
-\`async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const address = (suffix) => { const tool = tools.find((entry) => entry.address.endsWith(suffix)); if (!tool) throw new Error("missing " + suffix); return tool.address; }; const run = await connecta.call(address(".get_run"), { runId: 42 }); const logs = await connecta.call(address(".get_job_logs"), { jobId: run.failedJobId }); return logs.map(({ timestamp, message }) => ({ timestamp, message })); }\`
+\`\`\`js
+async () => {
+  const find = async name => {
+    const page = await connecta.search({ connector: "ci", query: name, safety: "readOnly", includeSchemas: "compact" });
+    if (page.queryAnalysis?.catalogError) throw new Error(JSON.stringify(page.queryAnalysis.catalogError));
+    return page.tools.find(tool => tool.name === name);
+  };
+  const runTool = await find("get_run");
+  if (!runTool) return { gap: "Run lookup not resolved" };
+  const run = await connecta.call(runTool.address, { runId: 42 });
+  if (!run.failedJobId) return { status: run.status, gap: "No failed job identified" };
+  const logsTool = await find("get_job_logs");
+  if (!logsTool) return { status: run.status, gap: "Job logs not resolved" };
+  const logs = await connecta.call(logsTool.address, { jobId: run.failedJobId });
+  return logs.filter(row => row.level === "error").map(({ timestamp, message }) => ({ timestamp, message }));
+}
+\`\`\`
 
-## Rendering a view
+## Media output
 
-\`connecta.emit\` accepts text, image, or audio blocks and delivers them only on success. \`connecta.ui(html)\` renders one success-only display view outside model context. The view has local HTML and JavaScript only: no network, connector calls, discovery, conversation messages, or host links. One shared budget applies to the UI and emitted content, not separate budgets. Fetch and check the data shape first. On empty or missing data, return a trimmed first record instead of rendering. Otherwise render returned variables and return the same summary because the model reads the return value, not the view. A second, invalid, or over-budget UI call throws catchably.
+\`connecta.emit\` accepts text, image, or audio blocks and delivers them only on success. Its byte and block budgets are separate from the JSON return budget. Return data for the client to render as a view.
 
 `;
 /** Deployment-scoped guide routing appended to the shared usage guide. */
@@ -95,12 +110,33 @@ export function hasConnectorGuides(connectors) {
 function usageSkill(_connectors) {
     return USAGE_SKILL;
 }
+const INVESTIGATE_SKILL = `# Investigate across services
+
+## Plan the investigation
+
+Start from the user's question and the evidence that would answer it. Select the app, account, and environment from connector titles, purposes, and relevant guides before looking up records. Reuse verified ids within the task; never carry an id across connectors just because its name matches.
+
+- Purchase verification: resolve the same customer and environment across payment, subscription access, and analytics. Check each separately; a recorded payment does not prove access, and a missing analytics event does not prove payment failure.
+- Experiment checks: confirm the project, experiment, time window, and exposure population before comparing outcomes. Return the requested comparison and any missing evidence; do not expand into an unrelated analytics audit.
+- Customer or deployment investigations: locate the exact customer or deployment first, then follow only the records needed to explain the reported symptom. Use provider links or ids so the answer can be checked.
+
+Establish capability limits early. A partial search is not proof that a tool is absent, and an unavailable catalog is not an empty dataset. Try a scoped search for the missing operation, inspect its guide when relevant, and distinguish unsupported work from missing data or authorization. If the required evidence is unavailable, return what was verified and the specific gap instead of approximating a different question through repeated calls.
+
+A host transport error that requires reconnecting this MCP server cannot be repaired by a downstream tool. Reconnect in the host; do not repeatedly call \`authorize_connector\` through the failed connection.
+
+Return the answer first, then the evidence and any unresolved gap. Include the app/environment, time window, and source ids or links needed to check it. Separate observed facts from inferences. Stop when the requested evidence is sufficient.
+`;
 const AVAILABLE_SKILLS = [
     {
         name: "usage",
         description: "How to route work between one execute_code program and Connecta's explicit call, authorization, and result tools.",
         content: usageSkill,
     },
+    {
+        name: "investigate",
+        description: "Plan purchase verification, experiment checks, and customer or deployment investigations across services; resolve scope and capability limits before querying.",
+        content: () => INVESTIGATE_SKILL,
+    },
 ];
 /**
  * Namespace for operator-authored per-connector guides. Built-in skill names

package/dist/types.d.ts

@@ -132,6 +132,8 @@ export interface CredentialTestResult {
     message?: string;
 }
 export interface ConnectorContext {
+    /** Explicit downstream consent initiation, never set by status/catalog/calls. */
+    allowAuthorization?: boolean;
     /** Storage namespaced to this connector. */
     storage: KVStorage;
     logger: Logger;
@@ -312,19 +314,6 @@ export interface Connector {
      * server's RFC 9207 `iss` response parameter for SDK validation.
      */
     finishAuth?(code: string, ctx: ConnectorContext, callbackParams?: URLSearchParams): Promise<void>;
-    /**
-     * Optional: serve a connector-owned HTTP route — for example a signed
-     * download link minted by one of the connector's tools. Called only after
-     * every built-in route misses, so a connector can never shadow `/mcp`,
-     * `/`, `/credentials`, `/activity`, `/health`, or the credential API. The
-     * first connector to return a Response wins, in registration order; return
-     * null to decline. See documentation/architecture.md route 9.
-     *
-     * These routes are PUBLIC: connecta applies no auth gate to them. A
-     * connector that serves data here MUST authenticate the request itself — for
-     * example with a signed capability token in the URL.
-     */
-    handleRequest?(request: Request, ctx: ConnectorContext): Promise<Response | null>;
 }
 export interface ConnectorUsageGuide {
     /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
@@ -355,8 +344,7 @@ export interface ExecutorProvider {
     fns: Record<string, (...args: unknown[]) => Promise<unknown>>;
     /**
      * Optional trusted sandbox-side setup run after provider globals exist.
-     * Connecta uses this to install lazy connector namespace proxies without
-     * materializing one host closure per tool. This is host-authored code, never
+     * Connecta uses this to restore typed host errors. This is host-authored code, never
      * model input. See documentation/code-mode.md#what-an-executor-must-implement.
      */
     prelude?: string;