@zackbart/connecta 0.28.0 → 0.29.0

package/examples/worker/kv-to-d1.wrangler.jsonc

@@ -0,0 +1,26 @@
+// Bindings for the one-shot Workers KV → D1 copy in scripts/copy-kv-to-d1.mjs.
+// Never deployed: `wrangler deploy` reads wrangler.jsonc, which binds no KV.
+// Both bindings are remote, so the script reads the real namespace and writes
+// the real database through your `wrangler login` session. Fill in the ids,
+// stop traffic/writers, wait for stable KV, copy and verify before deploying,
+// then mark cutover before reopening traffic. README.md § "Upgrading from
+// 0.28" has the steps.
+{
+  "name": "connecta-kv-to-d1",
+  "compatibility_date": "2025-01-01",
+  "kv_namespaces": [
+    {
+      "binding": "CONNECTA_KV",
+      "id": "replace-with-kv-namespace-id",
+      "remote": true,
+    },
+  ],
+  "d1_databases": [
+    {
+      "binding": "CONNECTA_DB",
+      "database_name": "connecta",
+      "database_id": "replace-with-d1-database-id",
+      "remote": true,
+    },
+  ],
+}

package/examples/worker/scripts/copy-kv-to-d1.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// Run only during the maintenance-window cutover. See README "Upgrading from 0.28".
+
+export const HELP = `Usage: node scripts/copy-kv-to-d1.mjs [config] --maintenance [options]
+Config defaults to kv-to-d1.wrangler.jsonc; source is its CONNECTA_KV namespace id.
+1. Bulk-export KV and export D1 with wrangler d1 export. Preserve the credentials key.
+2. Block traffic and all background writers, then drain in-flight requests.
+3. Wait at least 60 seconds, or the longest configured KV cacheTtl, whichever is
+   greater. Propagation can take longer. Two consecutive listing/hash passes
+   must match; this script checks them before copying or verifying.
+4. Copy BEFORE switching traffic. Resolve invalid/conflict counts under maintenance.
+   --overwrite-family <family> may be repeated; there is no blanket overwrite.
+   Token/OAuth/vault families also require --confirm-stale-d1 after the operator
+   confirms that D1's conflicting rows are stale. Run --verify for exact value
+   hashes and expiries; it reports mismatch counts by family, never payloads.
+5. Deploy D1 config under maintenance. Run doctor and check an existing OAuth
+   connector, cta_ token, vault credential, and visible activity. Set
+   CONNECTA_ACTIVITY="on"; config lives in src/connecta.config.ts.
+6. Run --mark-live before reopening traffic. It permanently seals this source
+   in D1. Never rerun afterward. --i-know-this-is-stale overrides the seal only
+   after assessing stale KV state, with traffic and writers stopped again.
+   Keep backups before deleting KV.
+Options: --verify, --mark-live, --overwrite-family <family>, --confirm-stale-d1,
+         --i-know-this-is-stale, --maintenance, --help`;
+
+export class MigrationUsageError extends Error {}
+
+export function parseArgs(args) {
+  const options = { configPath: "kv-to-d1.wrangler.jsonc", overwriteFamilies: [] };
+  let hasConfig = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--overwrite-family") {
+      const family = args[++i];
+      if (!family || family.startsWith("--")) throw new MigrationUsageError("--overwrite-family requires a family");
+      options.overwriteFamilies.push(family);
+    } else if (arg === "--maintenance") options.maintenance = true;
+    else if (arg === "--verify") options.verify = true;
+    else if (arg === "--mark-live") options.markLive = true;
+    else if (arg === "--confirm-stale-d1") options.confirmStale = true;
+    else if (arg === "--i-know-this-is-stale") options.allowStale = true;
+    else if (arg === "--help") options.help = true;
+    else if (!arg.startsWith("--") && !hasConfig) {
+      options.configPath = arg;
+      hasConfig = true;
+    } else throw new MigrationUsageError("Unknown argument; use --help");
+  }
+  if (options.help) return options;
+  if (!options.maintenance)
+    throw new MigrationUsageError(
+      "Traffic and writers must be stopped; pass --maintenance after draining and waiting for KV propagation",
+    );
+  if (
+    options.overwriteFamilies.some(
+      (family) => family === "access-token" || family === "credential" || family.startsWith("oauth"),
+    ) &&
+    !options.confirmStale
+  ) {
+    throw new MigrationUsageError(
+      "Token/OAuth/vault overwrite requires --confirm-stale-d1 after confirming D1 rows are stale",
+    );
+  }
+  if ((options.verify || options.markLive) && options.overwriteFamilies.length)
+    throw new MigrationUsageError("Verification and cutover marking cannot overwrite families");
+  if (options.verify && options.markLive)
+    throw new MigrationUsageError("Verify before marking cutover in a separate command");
+  return options;
+}
+
+const encode = new TextEncoder();
+const hash = async (value) => {
+  const bytes = await crypto.subtle.digest("SHA-256", encode.encode(value));
+  return Array.from(new Uint8Array(bytes), (n) => n.toString(16).padStart(2, "0")).join("");
+};
+
+// Keep only entry digests. Sorting makes the comparison independent of list order.
+async function sourceHash(kv) {
+  const digests = [];
+  let cursor;
+  do {
+    const page = await kv.list({ limit: 1000, ...(cursor ? { cursor } : {}) });
+    for (const key of page.keys) {
+      if (key.expiration !== undefined && key.expiration * 1000 <= Date.now()) continue;
+      const value = await kv.get(key.name, "text");
+      if (value !== null) digests.push(await hash(JSON.stringify([key.name, key.expiration ?? null, value])));
+    }
+    cursor = page.list_complete ? undefined : page.cursor;
+  } while (cursor);
+  return hash(digests.sort().join(""));
+}
+
+/** Injected operations let the Workers suite exercise the real migration flow. */
+export async function runMigration(kv, db, options, operations, output = console) {
+  if (!options.maintenance) throw new MigrationUsageError("Migration requires maintenance");
+  if (options.markLive) {
+    await operations.markKvToD1Live(db, options.source);
+    output.log("Cutover sealed in D1. Reopen traffic after deployment verification; never copy stale KV afterward.");
+    return 0;
+  }
+  if ((await sourceHash(kv)) !== (await sourceHash(kv))) {
+    throw new MigrationUsageError("Workers KV source is not stable; keep maintenance active, wait, and repeat");
+  }
+  const families = {};
+  let cursor;
+  do {
+    const result = await operations.copyKvToD1(kv, db, {
+      source: options.source,
+      cursor,
+      overwriteFamilies: options.overwriteFamilies,
+      verify: options.verify,
+      allowStale: options.allowStale,
+    });
+    for (const [family, counts] of Object.entries(result.families)) {
+      const into = (families[family] ??= {});
+      for (const [field, n] of Object.entries(counts)) into[field] = (into[field] ?? 0) + n;
+    }
+    cursor = result.cursor;
+  } while (cursor);
+  output.table(families);
+  if (Object.values(families).some((counts) => counts.invalid > 0 || counts.conflicts > 0 || counts.mismatches > 0)) {
+    output.error(
+      "Invalid entries, conflicts, or verification mismatches remain. Keep maintenance active and resolve the per-family counts.",
+    );
+    return 1;
+  }
+  return 0;
+}
+
+async function main() {
+  let proxy;
+  let operations;
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log(HELP);
+      return;
+    }
+    const wranglerModule = "wrangler";
+    const d1Module = "@zackbart/connecta/d1";
+    const { getPlatformProxy, unstable_readConfig } = await import(/* @vite-ignore */ wranglerModule);
+    operations = await import(/* @vite-ignore */ d1Module);
+    const config = unstable_readConfig({ config: options.configPath });
+    const source = config.kv_namespaces?.find((binding) => binding.binding === "CONNECTA_KV")?.id;
+    if (!source || source.startsWith("replace-"))
+      throw new MigrationUsageError("Configure the CONNECTA_KV namespace id before copying");
+    proxy = await getPlatformProxy({ configPath: options.configPath, persist: false });
+    const { CONNECTA_KV: kv, CONNECTA_DB: db } = proxy.env;
+    if (!kv || !db) throw new MigrationUsageError("Copy config must bind CONNECTA_KV and CONNECTA_DB");
+    process.exitCode = await runMigration(kv, db, { ...options, source }, operations);
+  } catch (error) {
+    console.error(
+      error instanceof MigrationUsageError || (operations && error instanceof operations.KvToD1CopyError)
+        ? error.message
+        : "Workers KV to D1 migration stopped; keep maintenance active and inspect the configuration",
+    );
+    process.exitCode = 1;
+  } finally {
+    await proxy?.dispose();
+  }
+}
+
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv?.[1]}`) await main();

package/examples/worker/src/connecta.config.ts

@@ -0,0 +1,151 @@
+/**
+ * connecta on Cloudflare Workers: this deployment's configuration.
+ *
+ * One MCP endpoint aggregating a downstream remote MCP and an HTTP API, guarded
+ * by Cloudflare Access. It needs three resources and nothing else: one D1
+ * database (CONNECTA_DB) holding every piece of state, the Worker Loader
+ * binding (LOADER) behind execute_code, and one secret
+ * (CREDENTIAL_ENCRYPTION_KEY) sealing credentials in that database. Access
+ * admits the request before this Worker runs and supplies trusted human
+ * identity through ctx.access. Machines use stored cta_ tokens inside connecta.
+ *
+ * Optional modules are type-checked code switched by the environment: the
+ * credential vault by the CREDENTIAL_ENCRYPTION_KEY secret, and activity
+ * history by the CONNECTA_ACTIVITY var ("on"), in the same database. README.md § "Select optional
+ * modules" walks through each.
+ *
+ * Setup (this example has no package.json of its own — it self-references the
+ * installed `@zackbart/connecta` package):
+ *   1. `npm install` in the connecta package root (../../ from here) so the
+ *      package import and wrangler resolve. A copy in its own repository
+ *      installs `@zackbart/connecta @cloudflare/codemode` instead. Codemode is
+ *      an optional peer.
+ *   2. `wrangler d1 create connecta` and put its id in wrangler.jsonc under
+ *      `d1_databases`. connecta creates its tables on first use.
+ *   3. Set secrets:
+ *        wrangler secret put DOWNSTREAM_TOKEN
+ *        wrangler secret put CREDENTIAL_ENCRYPTION_KEY
+ *      and PUBLIC_URL as a plain var in wrangler.jsonc.
+ *   4. Attach Cloudflare Access to this Worker. Enable Managed OAuth and
+ *      Dynamic Client Registration. Its Allowed redirect URIs must include
+ *      Claude's https://claude.ai/api/mcp/auth_callback plus ChatGPT's
+ *      https://chatgpt.com/connector_platform_oauth_redirect and
+ *      https://chatgpt.com/connector/oauth/* forms (see ../AGENTS.md).
+ *   5. Use the Workers Paid plan required by the `worker_loaders` binding.
+ *   6. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
+ *      lives. Point your MCP client at `<PUBLIC_URL>/mcp`.
+ */
+import { api, defineConfig, remoteMcp } from "@zackbart/connecta";
+import { activityHistory } from "@zackbart/connecta/activity";
+import { accessTokens } from "@zackbart/connecta/auth/access-tokens";
+import { cloudflareAccessAuth } from "@zackbart/connecta/auth/cloudflare-access";
+import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
+import { d1ActivityStore, d1Storage } from "@zackbart/connecta/d1";
+import { operatorUi } from "@zackbart/connecta/ui";
+import { workerExecutor } from "@zackbart/connecta/worker";
+
+export interface Env {
+  /** The one D1 database: OAuth grants, sealed credentials, catalogs, tokens, activity. */
+  CONNECTA_DB: D1Database;
+  /**
+   * Base64 32-byte AES key encrypting operator-managed credentials in D1.
+   * Unset means no vault: credential management is unavailable in the operator
+   * UI. Never put it in D1, since it is what protects D1.
+   */
+  CREDENTIAL_ENCRYPTION_KEY?: string;
+  DOWNSTREAM_TOKEN: string;
+  PUBLIC_URL: string;
+  /** "on" switches on activity history, in CONNECTA_DB. */
+  CONNECTA_ACTIVITY?: string;
+  /**
+   * Worker Loader binding (wrangler.jsonc `worker_loaders`) powering
+   * execute_code. Dynamic Workers require the Workers Paid plan.
+   */
+  LOADER: WorkerLoader;
+}
+
+export default defineConfig((env: Env) => {
+  const storage = d1Storage(env.CONNECTA_DB);
+  return {
+    publicUrl: env.PUBLIC_URL,
+    storage,
+    // Required adapter owns each run's handles; direct upstream construction throws.
+    executor: workerExecutor({ loader: env.LOADER }),
+    // Access owns edge admission and proves human identity for MCP and the
+    // operator pages. Machines need Access service headers at the edge plus a
+    // stored cta_ bearer inside connecta; a service identity alone is refused.
+    auth: [cloudflareAccessAuth()],
+    // Always installed over the same D1 storage. Empty storage admits no
+    // machine client; an Access-authenticated operator can provision tokens.
+    accessTokens: accessTokens(storage),
+    // Code-owned roster. Access proves the identity; connecta derives
+    // connector visibility and management permissions from the stable id it
+    // supplies. Add `connectorAccess` and `activityAccess` to split members
+    // from operators; here every signed-in human may manage every connector
+    // and access token. Machine tokens never receive interactive authority.
+    identity: {
+      credentialAdministration: () => "all",
+      personalConnection: () => "all",
+      accessTokenManagement: () => true,
+    },
+    // Connectors that declare a `credential` slot become editable by every
+    // signed-in human who can see that connector, encrypted with this key
+    // before anything reaches D1. A saved replacement takes effect on the
+    // next call; credentials fail at use.
+    vault: env.CREDENTIAL_ENCRYPTION_KEY ? encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY) : undefined,
+    // Payload-free activity at /ui/api/activity in CONNECTA_DB. The shared
+    // D1 mapping persists the build version and validated client facts, and
+    // adds nullable columns to old tables. Each write prunes expired rows.
+    activity:
+      env.CONNECTA_ACTIVITY === "on"
+        ? activityHistory({
+            store: d1ActivityStore(env.CONNECTA_DB, { retentionDays: 90 }),
+            deploymentId: "production",
+          })
+        : undefined,
+    // Branding is code too: operatorUi({ branding }).
+    ui: operatorUi(),
+    connectors: [
+      remoteMcp("notion", {
+        url: "https://mcp.notion.com/mcp",
+        description: "Notion — pages, databases, comments (static token)",
+        auth: {
+          type: "headers",
+          headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
+          // The vault-backed alternative for a downstream that authenticates
+          // with a static key: the operator manages it inside its connection
+          // in the operator UI, so no Worker secret holds it.
+          //   type: "credential",
+          //   credential: { label: "Notion internal integration token" },
+        },
+        // Use `authScope: "personal"` with OAuth or credential auth when each
+        // Access user connects their own downstream account. Literal headers
+        // are deployment-owned and cannot be personal.
+      }),
+      api("echo", {
+        description: "Echo — text transforms",
+        // What a vault-backed connector adds — an operator edits this slot
+        // inside its connection and the handler reads it with
+        // `await ctx.credential?.get()`, so the secret never lives in source:
+        //   credential: { label: "API token" },
+        tools: [
+          {
+            name: "shout",
+            description: "Uppercase the given text.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                text: { type: "string", description: "Text to uppercase." },
+              },
+              required: ["text"],
+            },
+            annotations: { readOnlyHint: true },
+            handler: async (args: { text: string }) => ({
+              shouted: args.text.toUpperCase(),
+            }),
+          },
+        ],
+      }),
+    ],
+  };
+});

package/examples/worker/src/index.ts

@@ -1,205 +1,22 @@
-import { operatorUi } from "@zackbart/connecta/ui";
-// import { activityHistory } from "@zackbart/connecta/activity";
-import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
 /**
- * connecta on Cloudflare Workers.
- *
- * One MCP endpoint aggregating a downstream remote MCP and an HTTP API, guarded
- * by Cloudflare Access, with OAuth/cache state in a KV namespace. Access
- * authenticates the request before this Worker runs and supplies the trusted
- * identity through ctx.access. The required Worker Loader binding in
- * wrangler.jsonc backs the seven-tool surface.
- *
- * The operator surface is wired here except for activity history, which needs
- * a database this example does not create for you: sign-in and the credential
- * vault are on, and activity is three commented lines below. README.md
- * § "Select optional modules" walks through all three.
- *
- * Setup (this example has no package.json of its own — it self-references the
- * installed `@zackbart/connecta` package):
- *   1. `npm install` in the connecta package root (../../ from here) so the
- *      package import and wrangler resolve. A copy in its own repository
- *      installs `@zackbart/connecta @cloudflare/codemode` instead. Codemode is
- *      an optional peer.
- *   2. Create a KV namespace and put its id in wrangler.jsonc under `kv_namespaces`.
- *   3. Set secrets:
- *        wrangler secret put DOWNSTREAM_TOKEN
- *        wrangler secret put CREDENTIAL_ENCRYPTION_KEY
- *      and PUBLIC_URL as a plain var in wrangler.jsonc.
- *   4. Attach Cloudflare Access to this Worker. Enable Managed OAuth and
- *      Dynamic Client Registration. Its Allowed redirect URIs must include
- *      Claude's https://claude.ai/api/mcp/auth_callback plus ChatGPT's
- *      https://chatgpt.com/connector_platform_oauth_redirect and
- *      https://chatgpt.com/connector/oauth/* forms (see ../AGENTS.md).
- *   5. Use the Workers Paid plan required by the `worker_loaders` binding.
- *   6. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
- *      lives. Point your MCP client at `<PUBLIC_URL>/mcp`.
+ * connecta on Cloudflare Workers. Configuration lives in connecta.config.ts,
+ * which also lists setup; this file only starts it.
  */
-import { DynamicWorkerExecutor } from "@cloudflare/codemode";
-import {
-  api,
-  createConnecta,
-  remoteMcp,
-} from "@zackbart/connecta";
-import { cloudflareAccessAuth } from "@zackbart/connecta/auth/cloudflare-access";
-import { cloudflareKvStorage } from "./cloudflare-kv.js";
-// import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
-// import { d1Storage } from "./d1-storage.js";
-// Activity history, off by default because it needs a D1 database.
-// import { d1ActivityStore } from "./d1-activity.js";
-
-interface Env {
-  CONNECTA_KV: KVNamespace;
-  /**
-   * Base64 32-byte AES key encrypting operator-managed credentials in KV.
-   * Unset means no vault: credential management is unavailable in the operator
-   * UI. Never put it in KV, since it is what protects KV.
-   */
-  CREDENTIAL_ENCRYPTION_KEY: string;
-  DOWNSTREAM_TOKEN: string;
-  PUBLIC_URL: string;
-  /** Uncomment with the `d1_databases` binding to enable activity history. */
-  // ACTIVITY_DB: D1Database;
-  /**
-   * Worker Loader binding (wrangler.jsonc `worker_loaders`) powering
-   * execute_code. Dynamic Workers require the Workers Paid plan.
-   */
-  LOADER: WorkerLoader;
-}
-
-function build(env: Env) {
-  const storage = cloudflareKvStorage(env.CONNECTA_KV);
-  // Optional refreshable pages need the D1 binding, not Workers KV:
-  // const artifactModule = artifacts({ store: kvArtifactStore(d1Storage(env.STORAGE_DB)) });
-  // scheduledArtifacts.module = artifactModule;
-  return createConnecta({
-    publicUrl: env.PUBLIC_URL,
-    storage,
-    executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
-    auth: [
-      // Access owns admission policy. A human identity may use MCP and the
-      // operator pages; a service token may use MCP but cannot mutate operator
-      // state. Neither path asks connecta to parse a JWT.
-      cloudflareAccessAuth(),
-    ],
-    // Optional code-owned roster. Access proves the identity; connecta derives
-    // connector visibility and deployment-operator status from the stable id
-    // it supplies. A signed-in human may manage auth for every connector this
-    // view includes. Omit the block to keep every connector visible and every
-    // human a deployment operator.
-    // identity: {
-    //   connectorAccess: ({ principal }) =>
-    //     principal?.id === "ACCESS_USER_UUID"
-    //       ? ["notion", "echo"]
-    //       : ["echo"],
-    //   activityAccess: ({ id }) => id === "ACCESS_USER_UUID",
-    // },
-    // Connectors that declare a `credential` slot become editable by every
-    // signed-in human who can see that connector, inside its connection on /,
-    // encrypted with this key before anything reaches KV. A saved replacement takes
-    // effect on the next call — no redeploy, and no liveness probe:
-    // credentials fail at use.
-    //
-    // The key is the vault, not the form: a credential form appears only on a
-    // connector that declares a slot. Neither connector below does — Notion
-    // here carries a deployment-owned static header and echo has no secret at
-    // all — so this example ships the vault ready and nothing to fill in.
-    // Declare a slot (see the commented shape on `echo`, or use a provider
-    // connector like `notion()`, which declares its own) and the form appears
-    // on the next load.
-    vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY),
-    // Branding is code too: name, owner, description, favicon, and five theme
-    // tokens that every other color is mixed from. A value that fails its
-    // check falls back to the default, and the startup warning names it.
-    // ui: operatorUi({
-    //   branding: {
-    //     productName: "Acme Tools",
-    //     ownerName: "Acme",
-    //     theme: {
-    //       accent: "#2f5fe0", // hex only
-    //       radius: 10, // pixels, or a CSS length such as "0.5rem"
-    //       fontFamily: "Inter, system-ui, sans-serif",
-    //       monoFamily: "ui-monospace, monospace",
-    //       colorScheme: "system", // or "light" | "dark"
-    //     },
-    //   },
-    // }),
-    ui: operatorUi(),
-    // artifacts: artifactModule,
-    identity: { credentialAdministration: () => "all", personalConnection: () => "all" },
-    // Payload-free activity at /activity, off until a database exists to hold
-    // it. Uncomment the `d1_databases` binding in wrangler.jsonc, apply the
-    // schema in README.md § "Activity history", then these three lines and the
-    // import above.
-    // activity: activityHistory({
-    //   store: d1ActivityStore(env.ACTIVITY_DB),
-    //   deploymentId: "production",
-    // }),
-    connectors: [
-      remoteMcp("notion", {
-        url: "https://mcp.notion.com/mcp",
-        description: "Notion — pages, databases, comments (static token)",
-        auth: {
-          type: "headers",
-          headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
-          // The vault-backed alternative for a downstream that authenticates
-          // with a static key: the operator manages it inside its connection
-          // in the operator UI, so no Worker secret holds it.
-          //   type: "credential",
-          //   credential: { label: "Notion internal integration token" },
-        },
-        // Use `authScope: "personal"` with OAuth or credential auth when each
-        // Access user connects their own downstream account. Literal headers
-        // are deployment-owned and cannot be personal.
-      }),
-      api("echo", {
-        description: "Echo — text transforms",
-        // What a vault-backed connector adds — an operator edits this slot
-        // inside its connection in the operator UI and the handler reads it with
-        // `await ctx.credential?.get()`, so the secret never lives in source
-        // or in a Worker variable:
-        //   credential: { label: "API token" },
-        tools: [
-          {
-            name: "shout",
-            description: "Uppercase the given text.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                text: { type: "string", description: "Text to uppercase." },
-              },
-              required: ["text"],
-            },
-            annotations: { readOnlyHint: true },
-            handler: async (args: { text: string }) => ({
-              shouted: args.text.toUpperCase(),
-            }),
-          },
-        ],
-      }),
-    ],
-  });
-}
+import { createConnecta, type Connecta } from "@zackbart/connecta";
+import connectaConfig, { type Env } from "./connecta.config.js";
 
 // Lazy per-isolate singleton: reuses the plain-data tool cache. Downstream MCP
 // clients are request-scoped internally so Worker I/O never crosses requests.
-let connecta: ReturnType<typeof build> | undefined;
-const scheduledArtifacts: { module?: { runDue(): Promise<unknown> } } = {};
+let started: Connecta | undefined;
+function start(env: Env) {
+  if (!started) {
+    const config = connectaConfig(env);
+    started = createConnecta(config);
+  }
+  return started;
+}
 
 export default {
-  // Pass `ctx` through: connecta hands deferred work (activity sinks) to
-  // ctx.waitUntil so it settles after the response is returned instead of
-  // being cancelled with the request.
-  async fetch(
-    request: Request,
-    env: Env,
-    ctx: ExecutionContext,
-  ): Promise<Response> {
-    connecta ??= build(env);
-    return connecta.fetch(request, env, ctx);
-  },
-  async scheduled(_event: ScheduledController, env: Env): Promise<void> {
-    connecta ??= build(env);
-    await scheduledArtifacts.module?.runDue();
-  },
+  // Pass `ctx` through: deferred work (activity sinks) settles on ctx.waitUntil.
+  fetch: (request: Request, env: Env, ctx: ExecutionContext) => start(env).fetch(request, env, ctx),
 };

package/examples/worker/wrangler.jsonc

@@ -6,14 +6,13 @@
   "compatibility_flags": ["nodejs_compat", "enable_request_signal"],
   "observability": { "enabled": true },
 
-  // Uncomment with artifacts and D1 in src/index.ts. Every hourly tick runs
-  // at most 10 due pages; each page's own daily/weekly schedule lives in data.
-  // "triggers": { "crons": ["0 * * * *"] },
-
   // Plain vars. Secrets (CREDENTIAL_ENCRYPTION_KEY, DOWNSTREAM_TOKEN) are set with
   // `wrangler secret put <NAME>`, not here.
+  // CONNECTA_ACTIVITY switches on activity history in src/connecta.config.ts
+  // when "on"; its data stays in CONNECTA_DB.
   "vars": {
-    "PUBLIC_URL": "https://connecta.example.workers.dev"
+    // "CONNECTA_ACTIVITY": "on",
+    "PUBLIC_URL": "https://connecta.example.workers.dev",
   },
 
   // Local-only Access identity. Remove this block to exercise the
@@ -22,39 +21,20 @@
   "access": {
     "dev": {
       "aud": "connecta-local",
-      "identity": { "email": "operator@example.com" }
-    }
+      "identity": { "email": "operator@example.com" },
+    },
   },
 
-  // Create with `wrangler kv namespace create CONNECTA_KV` and paste the id.
-  "kv_namespaces": [
-    { "binding": "CONNECTA_KV", "id": "replace-with-kv-namespace-id" }
+  // The one database. Create with `wrangler d1 create connecta` and paste
+  // the id. connecta creates its tables on first use; nothing to apply.
+  "d1_databases": [
+    {
+      "binding": "CONNECTA_DB",
+      "database_name": "connecta",
+      "database_id": "replace-with-d1-database-id",
+    },
   ],
 
-  // D1 databases, off by default so this example deploys without one.
-  // Uncomment the array and keep the entries you use.
-  //
-  // ACTIVITY_DB: activity history. Create with `wrangler d1 create
-  // connecta-activity`, paste the id, apply the schema in README.md, then
-  // uncomment the matching lines in src/index.ts.
-  //
-  // STORAGE_DB: strongly consistent storage with compare-and-set, in place of
-  // CONNECTA_KV. Create with `wrangler d1 create connecta-storage`, paste the
-  // id, apply the schema in README.md § "Strongly consistent storage", then
-  // pass `d1Storage(env.STORAGE_DB)` as `storage` in src/index.ts.
-  // "d1_databases": [
-  //   {
-  //     "binding": "ACTIVITY_DB",
-  //     "database_name": "connecta-activity",
-  //     "database_id": "replace-with-d1-database-id"
-  //   },
-  //   {
-  //     "binding": "STORAGE_DB",
-  //     "database_name": "connecta-storage",
-  //     "database_id": "replace-with-d1-database-id"
-  //   }
-  // ],
-
   // Required by execute_code; Dynamic Workers use the Workers Paid plan.
-  "worker_loaders": [{ "binding": "LOADER" }]
+  "worker_loaders": [{ "binding": "LOADER" }],
 }