@zackbart/connecta 0.24.3 → 0.25.0

package/dist/fix-prompt.js

@@ -0,0 +1,37 @@
+/**
+ * The frame every copyable fix prompt shares: the operator page's failure
+ * notices and the OAuth callback page both hand an operator text to paste into
+ * a coding agent working in the deployment's repository.
+ *
+ * A prompt is assembled from fixed catalogue text and, at most, a configured
+ * connector id. It has no parameter an error message, a downstream body, a
+ * token, or a URL could arrive through — which is the whole guarantee: the
+ * text leaves the page on a clipboard, into a tool the deployment does not
+ * control, so it must be something the deployment would be content to publish.
+ * The agent finds the underlying cause where it belongs, in the deployment's
+ * own logs and a local reproduction.
+ */
+const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
+/**
+ * Render one prompt. A connector id is the only variable part, and only when
+ * it has the shape configuration enforces; anything else is dropped rather
+ * than escaped, since a value that is not a connector id is not config.
+ */
+export function renderFixPrompt(spec, connectorId) {
+    const id = connectorId !== undefined && CONNECTOR_ID_RE.test(connectorId)
+        ? connectorId
+        : undefined;
+    return [
+        "Diagnose and fix a problem in this connecta deployment (the @zackbart/connecta package). " +
+            "It is configured as code: connectors, credential slots, OAuth clients, pools, and inbound auth " +
+            "are declared in the deployment's source and environment, so the fix belongs there and not in the operator page.",
+        `Problem: ${spec.problem}` + (id ? `\nConnector id: ${id}` : ""),
+        `Where to look:\n${spec.steps.map((step) => `- ${step}`).join("\n")}`,
+        "This prompt deliberately carries no error text, tokens, or URLs. Find the underlying cause in the deployment's " +
+            "own logs (lines prefixed [connecta]) or by reproducing the failure locally. Never put a secret in source, " +
+            "a log line, or your reply: secrets belong in the deployment's environment or its credential vault.",
+        "Make the smallest change that fixes it, then verify it by redeploying and refreshing the connection on the " +
+            "operator Connections page. If the fix needs something you cannot do yourself — a provider console setting, " +
+            "a secret only the operator holds — name that exact step instead.",
+    ].join("\n\n");
+}

package/dist/index.d.ts

@@ -47,7 +47,7 @@ export interface ConnectaCallsConfig {
     /**
      * Max inline result size (bytes) before truncation and `get_result` paging.
      * Must be a finite whole number >= 1; invalid values warn and fall back to
-     * 50_000. Connectors may override it individually.
+     * 24_000. Connectors may override it individually.
      */
     maxResultBytes?: number;
 }
@@ -81,6 +81,15 @@ export interface ConnectaExecuteConfig {
      * values fall back to the default.
      */
     hostCallTimeoutMs?: number;
+    /**
+     * Hard ceiling on one execution, in milliseconds, enforced outside the
+     * sandbox. Default 120_000, above both executors' own deadlines (QuickJS
+     * 30_000, the Dynamic Worker 60_000), so it only ends a run whose executor
+     * never settled; that run fails as unresponsive and its admission slot is
+     * released. Keep it above any raised executor deadline. Invalid values
+     * fall back to the default.
+     */
+    watchdogMs?: number;
 }
 export interface AdmissionPoolConfig {
     /** Simultaneous work admitted to this pool. */
@@ -222,5 +231,5 @@ export { CONNECTA_VERSION } from "./version.js";
 export type { Registry } from "./registry.js";
 export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRedirectPolicy, } from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
-export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
+export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
 export type { ActivityActor, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, CatalogDriftActivityEvent, ToolCallActivityEvent, } from "./activity.js";

package/dist/index.js

@@ -2,10 +2,12 @@ import { credentialTestRule, describeCredentialTestMismatch, } from "./credentia
 import { Registry } from "./registry.js";
 import { parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
 import { createFetchHandler } from "./server.js";
-import { droppedBrandingUrls, droppedUiAuthUrls } from "./branding.js";
+import { droppedBrandingUrls, droppedThemeTokens, droppedUiAuthUrls, } from "./branding.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
 import { AdmissionController, executorName, isAdmittingExecutor, withExecutorAdmission, } from "./executor-admission.js";
+import { disposeEdgeRuntime } from "./runtime/run.js";
+import { createCoreRuntime, resolveLogger } from "./runtime/services.js";
 const REQUEST_ADMISSION_DEFAULTS = {
     concurrency: 16,
     maxQueueSize: 32,
@@ -26,14 +28,6 @@ function admissionController(options, defaults) {
         retryAfterMs: options?.retryAfterMs ?? defaults.retryAfterMs,
     });
 }
-function defaultLogger() {
-    return {
-        debug: (...a) => console.debug("[connecta]", ...a),
-        info: (...a) => console.info("[connecta]", ...a),
-        warn: (...a) => console.warn("[connecta]", ...a),
-        error: (...a) => console.error("[connecta]", ...a),
-    };
-}
 /** Bearer providers are checked before Clerk (per spec). */
 function normalizeAuth(auth) {
     const list = auth ? (Array.isArray(auth) ? auth : [auth]) : [];
@@ -84,6 +78,7 @@ const CONFIG_SCHEMA = {
         maxEmittedBlocks: null,
         maxHostCalls: null,
         hostCallTimeoutMs: null,
+        watchdogMs: null,
     },
     admission: {
         requests: admissionPoolSchema,
@@ -151,7 +146,7 @@ function assertKnownConfig(config) {
             }
         }
     }
-    if (config.vault && ["get", "getAll", "set", "setAll", "metadata", "delete"].some(key => typeof config.vault[key] !== "function"))
+    if (config.vault && (["get", "getAll", "set", "setAll", "metadata", "delete"].some(key => typeof config.vault[key] !== "function") || ["seal", "open"].some(key => !["undefined", "function"].includes(typeof config.vault[key]))))
         throw new Error("ConnectaConfig.vault must implement CredentialVault");
     if (config.ui && (typeof config.ui.handle !== "function" || typeof config.ui.credentialHandoffUrl !== "function" || !Array.isArray(config.ui.reservedPaths)))
         throw new Error("ConnectaConfig.ui must be created with operatorUi(...)");
@@ -262,6 +257,17 @@ function warnInsecureConfig(config, inboundAuth, logger) {
             "used as an href, so it must be an absolute http(s) URL (favicon.href " +
             "may also be a root-relative path). The default is rendered instead.");
     }
+    // Theme tokens are written into a `:root` block, so each is gated
+    // syntactically and a rejected value takes the stylesheet's default. Same
+    // reason as the branding URLs above: the page still renders, so without this
+    // line the only evidence is that the operator's color never showed up.
+    const droppedTheme = droppedThemeTokens(config.ui?.branding?.theme);
+    if (droppedTheme.length > 0) {
+        logger.warn(`[connecta] branding ${droppedTheme.join(", ")} dropped: accent must be ` +
+            "a hex color, radius a CSS length, the font families a plain " +
+            "font-family list, and colorScheme one of system/light/dark. The " +
+            "default is rendered instead.");
+    }
     // Operator shells render exactly one provider's browser sign-in config — the
     // first that offers one, matching the server route's `find` — and that
     // provider's URLs reach the browser: frontendApiUrl as the loader's
@@ -285,18 +291,31 @@ function warnInsecureConfig(config, inboundAuth, logger) {
     }
     // A credential test hook that cannot test the declared credential shape.
     // The shape picks the hook (see `credentialTestRule`) and the other one is
-    // never substituted, so the connector is simply not testable: /credentials offers no
-    // Test action and the route answers 400. Without this line the only way to
-    // discover the mistake is to click a button that isn't there.
+    // never substituted, so the connection offers no Test action in the operator
+    // UI and the route answers 400. Without this line the only way to discover
+    // the mistake is to click a button that isn't there.
     for (const connector of config.connectors) {
         const { mismatch } = credentialTestRule(connector);
         if (!mismatch)
             continue;
         logger.warn(`[connecta] connector "${connector.id}" cannot test its credential: ` +
-            `${describeCredentialTestMismatch(mismatch)}. /credentials offers no Test ` +
+            `${describeCredentialTestMismatch(mismatch)}. The connection in the operator UI offers no Test ` +
             `action and POST /ui/credentials/${connector.id}/test answers 400 ` +
             "until the matching hook is implemented.");
     }
+    // A vault written before seal/open existed encrypts credentials but cannot
+    // seal downstream OAuth state, so tokens stay plaintext at rest beside them.
+    const vault = config.vault;
+    if (vault && (typeof vault.seal !== "function" || typeof vault.open !== "function")) {
+        for (const connector of config.connectors) {
+            if (!connector.startAuth)
+                continue;
+            logger.warn(`[connecta] connector "${connector.id}" stores its downstream OAuth ` +
+                "tokens, client registration, and PKCE verifier as plaintext: the " +
+                "configured vault implements no `seal`/`open`. Use " +
+                "encryptedCredentialVault(...) or add both methods to seal them.");
+        }
+    }
     // OAuth connectors whose callback cannot perform a state/CSRF check. The
     // public route refuses every callback for these connectors rather than hand
     // an unverified code to finishAuth, so this warning explains why auth cannot
@@ -320,9 +339,7 @@ export function createConnecta(config) {
             '"@cloudflare/codemode" on Workers.');
     }
     const storage = config.storage ?? memoryStorage();
-    const logger = config.logger === "silent"
-        ? { debug() { }, info() { }, warn() { }, error() { } }
-        : config.logger ?? defaultLogger();
+    const logger = resolveLogger(config.logger);
     const credentialVault = config.vault;
     const configuredAuth = normalizeAuth(config.auth);
     const serverInfo = {
@@ -370,6 +387,22 @@ export function createConnecta(config) {
             "implements acquire() and owns its admission pool; configure that " +
             "executor's concurrency and queue options instead.");
     }
+    // Every structural check has passed, so this is the configuration the
+    // deployment runs with. Creating the runtime builds nothing — a Worker may
+    // construct its Connecta at global scope, where no fiber may start.
+    const runtime = createCoreRuntime(registry, {
+        storage,
+        logger,
+        vault: credentialVault,
+        activity: config.activity,
+        config: {
+            config,
+            serverInfo,
+            auth: inboundAuth,
+            pools,
+            executorName: configuredExecutorName,
+        },
+    });
     const handler = createFetchHandler({
         registry,
         auth: inboundAuth,
@@ -393,6 +426,7 @@ export function createConnecta(config) {
         maxEmittedBlocks: config.execute?.maxEmittedBlocks,
         maxHostCalls: config.execute?.maxHostCalls,
         hostCallTimeoutMs: config.execute?.hostCallTimeoutMs,
+        watchdogMs: config.execute?.watchdogMs,
         credentialVault,
         ui: config.ui,
         deploymentInfo: config.deploymentInfo,
@@ -406,10 +440,18 @@ export function createConnecta(config) {
         registry,
         close: async () => {
             closePromise ??= Promise.resolve().then(async () => {
-                requestAdmission.close();
-                codeAdmission?.close();
-                registry.closeCallAdmission();
-                await config.executor?.close?.();
+                try {
+                    requestAdmission.close();
+                    codeAdmission?.close();
+                    registry.closeCallAdmission();
+                    await config.executor?.close?.();
+                }
+                finally {
+                    // Last, and whether or not the executor closed cleanly. A fiber
+                    // already running keeps the services it was given; only a run
+                    // started after this is refused.
+                    await disposeEdgeRuntime(runtime);
+                }
             });
             await closePromise;
         },