@zackbart/connecta 0.24.4 → 0.26.0

package/examples/worker/wrangler.jsonc

@@ -3,9 +3,13 @@
   "name": "connecta-example",
   "main": "src/index.ts",
   "compatibility_date": "2025-01-01",
-  "compatibility_flags": ["nodejs_compat"],
+  "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.
   "vars": {
@@ -27,15 +31,27 @@
     { "binding": "CONNECTA_KV", "id": "replace-with-kv-namespace-id" }
   ],
 
-  // 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. Off by default so this example deploys without a
-  // database.
+  // 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"
   //   }
   // ],
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.24.4",
+  "version": "0.26.0",
   "type": "module",
   "sideEffects": false,
-  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
+  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of eight meta-tools.",
   "license": "MIT",
   "engines": {
     "node": ">=22.0.0"
@@ -110,13 +110,17 @@
     "./auth/bearer": {
       "types": "./dist/auth/bearer.d.ts",
       "import": "./dist/auth/bearer.js"
+    },
+    "./artifacts": {
+      "types": "./dist/artifacts.d.ts",
+      "import": "./dist/artifacts.js"
     }
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build:operator-ui": "node scripts/build-operator-ui.mjs",
     "check:operator-ui": "node scripts/build-operator-ui.mjs --check",
-    "build": "npm run build:operator-ui && npm run clean && tsc -p tsconfig.build.json",
+    "build": "npm run build:operator-ui && npm run clean && tsc -p tsconfig.build.json && node scripts/prune-declarations.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.operator-ui.json --noEmit",
     "test": "vitest run",
     "test:browser:install": "playwright install chromium",
@@ -129,9 +133,16 @@
     "check:examples": "tsc -p tsconfig.template.node.json && tsc -p tsconfig.examples.worker.json",
     "check:security": "npm audit --omit=dev --audit-level=moderate",
     "check:package": "node scripts/check-package.mjs",
+    "check:declarations": "node scripts/check-declarations.mjs --dist .",
+    "check:bundle": "node scripts/bundle-size.mjs",
     "providers:check": "tsx scripts/drift-check.mjs --specs --docs",
     "drift:check": "tsx scripts/drift-check.mjs",
-    "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run build && npm run check:examples",
+    "eval:selftest": "tsx eval/selftest.ts",
+    "eval:agent": "tsx eval/run-agent.ts",
+    "eval:smoke": "tsx eval/run-smoke.ts",
+    "eval:perf": "tsx eval/run-perf.ts",
+    "eval:report": "tsx eval/report.ts",
+    "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run test:browser && npm run build && npm run check:declarations && npm run check:bundle && npm run check:examples",
     "release:check": "npm run check && npm run check:security && npm run check:package",
     "prepack": "npm run check"
   },
@@ -139,6 +150,7 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
+    "effect": "4.0.0-rc.117",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/templates/node/AGENTS.md

@@ -3,8 +3,9 @@
 This repository is deployment configuration, not a copy of Connecta itself.
 
 - Edit `src/index.ts` for connectors, authentication, storage, and public URL.
-- Keep `executor: quickJsExecutor()` for the prescribed seven-tool code-first
-  surface.
+- Keep `executor: quickJsExecutor()` for the prescribed eight-tool code-first
+  surface. File storage supports resumable writes, so a program pauses at a
+  write until `resume_execution` approves it.
 - Keep credentials in environment variables or an external secret store.
   Never commit `.env`, `.connecta-state.json`, `.connecta-activity.jsonl`,
   tokens, or credential values.
@@ -19,6 +20,12 @@ This repository is deployment configuration, not a copy of Connecta itself.
   alone never grants it. Configured bearer auth is a client option, not a human
   management identity. Connecta-issued access tokens are removed.
   `src/file-activity.ts` remains the deployment-owned history store.
+- Brand the operator UI in `operatorUi({ branding })`: product and owner names,
+  description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
+  `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
+  rather than leaving the default. The commented block above
+  `ui: operatorUi()` in `src/index.ts` shows the shape; README "Select optional
+  modules" covers the rest.
 - Run `npm run typecheck` after configuration changes. With the server running,
   run `CONNECTA_TOKEN=... npm run doctor` before calling setup complete.
 - `Dockerfile` and `docker-compose.yml` containerize *this* source; they are

package/templates/node/README.md

@@ -46,11 +46,32 @@ reproducible `npm ci` path.
 
 ## Select optional modules
 
+For scheduled artifact pages, uncomment the `artifacts()` module and hourly
+`setInterval` block in `src/index.ts`. The module uses the same CAS-capable
+state file and exposes `runDue()` for the timer; core starts no job on its own.
+Each tick starts at most 10 due pages. Refresh programs can call only shared
+connectors' explicitly read-only tools within the program owner's current
+grants. Revoking refresh or pool access stops future runs. Failed runs leave the last good data
+and mark the viewer stale.
+
 The template explicitly enables `ui: operatorUi()` from
 `@zackbart/connecta/ui`. Open `http://localhost:8787/` and supply the configured
 bearer to inspect Connections. Omit that option and import for an API-only
 server. OAuth callbacks remain in core even with no UI.
 
+The page labels whether each tool runs in programs or needs approval. For
+classified connection failures it offers a fixed repair prompt, and its
+endpoint section has client setup commands for `/mcp` and any pool available
+to the signed-in identity. Those commands contain no bearer token.
+
+Branding belongs in `operatorUi({ branding })`: `productName`, `ownerName`,
+their URLs, `description`, `pageTitle`, `favicon`, and `theme`. The theme is
+five tokens — `accent`, `radius`, `fontFamily`, `monoFamily`, and
+`colorScheme` — and every other color is mixed from them, so one accent themes
+the whole page. A value that fails its gate falls back to the default, and the
+startup warning names it. `src/index.ts` carries the full shape commented out
+above `ui: operatorUi()`.
+
 Connection management needs an interactive identity. A configured bearer is a
 client key and never authorizes browser credential mutations. To enable Clerk:
 
@@ -89,6 +110,12 @@ it through `await ctx.credential?.get()`, or use a provider such as `notion()`
 that declares its own slot. Authorized humans manage the slot inside that
 connection on `/`; there is no separate Credentials tab.
 
+In 0.25.0, this vault also seals downstream OAuth tokens on their first read.
+That is a one-way state migration for those tokens: rolling back to 0.24.x
+requires authorizing each OAuth connector again. See the
+[0.25.0 changelog](../../CHANGELOG.md#0250--2026-09-23) before upgrading a
+deployment with existing OAuth connections.
+
 A saved replacement takes effect on the next call. Connecta tests credentials
 only on an explicit action and otherwise fails at use. Without a vault or UI,
 static credential recovery reports unavailable instead of offering a dead link.
@@ -132,16 +159,17 @@ npm run typecheck
 CONNECTA_TOKEN=dev-token npm run doctor
 ```
 
-Doctor checks health, the executor, and the exact prescribed seven-tool
+Doctor checks health, the executor, and the exact prescribed eight-tool
 model-facing surface by running a harmless sandbox program. It reads the bearer
 from `CONNECTA_TOKEN`; it never accepts the secret as a command-line argument.
 Remote URLs must use HTTPS.
 
 A fully-wired deployment reports exactly the same line as a bare one —
-connector count, QuickJS executed, seven tools, plus any catalog drift:
+connector count, QuickJS executed, eight tools, plus any catalog drift, and
+a note if resumable writes are off:
 
 ```text
-Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed seven-tool surface.
+Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed eight-tool surface.
 ```
 
 `QuickJS` is this deployment's sandbox, reported by the deployment itself —

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.24.4",
+    "@zackbart/connecta": "0.26.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/index.ts

@@ -27,6 +27,7 @@ import { operatorUi } from "@zackbart/connecta/ui";
 import { api, createConnecta } from "@zackbart/connecta";
 import { fileStorage, listen } from "@zackbart/connecta/node";
 import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+// import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
 // Operator sign-in. Needs `npm install @clerk/backend` — it is an optional
 // peer, so it does not install with Connecta.
 // import { clerkAuth } from "@zackbart/connecta/auth/clerk";
@@ -45,6 +46,8 @@ const port = Number(process.env.PORT ?? 8787);
 const stateFile = process.env.CONNECTA_STATE_FILE || "./.connecta-state.json";
 const publicUrl = process.env.PUBLIC_URL || `http://localhost:${port}`;
 const storage = fileStorage(stateFile);
+// Optional artifact pages and refresh jobs use the same CAS-capable state file:
+// const artifactModule = artifacts({ store: kvArtifactStore(storage) });
 
 // Operator sign-in. A bearer token is a client key: it may call tools and read
 // connector status, but only a Clerk-authenticated human may write a visible
@@ -103,7 +106,25 @@ const connecta = createConnecta({
   //   ),
   //   deploymentId: "production",
   // }),
+  // The operator UI at /. Its branding is code, like everything else here:
+  // 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,
   connectors: [
     api("time", {
       description: "Time — current timestamp",
@@ -126,3 +147,9 @@ const connecta = createConnecta({
 
 listen(connecta, port);
 console.log(`connecta listening on port ${port}; MCP at ${publicUrl}/mcp`);
+// The deployment owns this timer; core starts no background work. Uncomment
+// with artifactModule above. Each tick starts at most 10 due pages.
+// const refreshTimer = setInterval(() => {
+//   void artifactModule.runDue().catch((error) => console.error("artifact refresh failed", error));
+// }, 60 * 60 * 1000);
+// refreshTimer.unref();

package/dist/auth/downstream-oauth.d.ts

@@ -1,200 +0,0 @@
-import type { FetchLike, OAuthClientInformationContext, OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthDiscoveryState, OAuthTokens } from "@modelcontextprotocol/client";
-import type { KVStorage } from "../types.js";
-type OAuthRefreshFlightOutcome = {
-    status: "refreshed";
-} | {
-    status: "retired";
-} | {
-    status: "failed";
-    error: unknown;
-};
-interface OAuthRefreshFlight {
-    done: Promise<OAuthRefreshFlightOutcome>;
-    release: (outcome: OAuthRefreshFlightOutcome) => void;
-    stopObservingOwnerAbort: () => void;
-    mutationId: object;
-    writing: boolean;
-    /**
-     * Set once the token endpoint answered with valid tokens: the authorization
-     * server has consumed the rotating refresh token, so if the SDK's own
-     * saveTokens never arrives (owner cancelled, redirected, or invalidated),
-     * `fail` persists this copy itself rather than stranding the marker or
-     * letting a contender redeem the retired token.
-     */
-    acceptedTokens?: OAuthTokens;
-    persist?: (tokens: OAuthTokens) => Promise<void>;
-}
-/**
- * Share one rotating-token redemption within one connector runtime and OAuth
- * generation. The first request still owns the real fetch and response. Its
- * abort signal has one bounded listener until the exact flight settles, so a
- * cancellation after the response cannot strand waiters during token storage.
- * Followers wait for that provider to save tokens, then re-read storage. The
- * map never retains a token response or transport.
- *
- * This is intentionally runtime-local. KVStorage has no atomic coordination
- * operation, so a second isolate can still race the same refresh token.
- */
-export declare class OAuthRefreshCoordinator {
-    private readonly flights;
-    /** Opaque identities only: no request promise, signal, callback, or response. */
-    private readonly pendingMutations;
-    /** One bounded latest-success slot, containing only generation + identity. */
-    private successfulRefresh;
-    /** Replaced on every map mutation, closing flight/pending ABA across awaits. */
-    private stateRevision;
-    private advanceStateRevision;
-    private observeAuthoritativeGeneration;
-    private settle;
-    private markMutationPending;
-    private finishMutation;
-    /** @internal Opaque basis for issuer-aware provider token reads. */
-    successfulRefreshIdentity(generation: string): object | undefined;
-    coordinatedFetch(provider: KvOAuthProvider, baseFetch: FetchLike, requestSignal?: AbortSignal): FetchLike;
-    /** Start storage only while this owner still holds its exact flight. */
-    beginMutation(generation: string, flight: OAuthRefreshFlight): boolean;
-    /** Publish one exact owner's successful save without disturbing a newer try. */
-    succeedMutation(generation: string, flight: OAuthRefreshFlight): void;
-    /** Give joined callers a fetch/flow failure, without rejecting the gate. */
-    fail(generation: string, flight: OAuthRefreshFlight, error: unknown): void;
-    /** Finish an exact failed credential write, then publish its failure. */
-    failMutation(generation: string, flight: OAuthRefreshFlight, error: unknown): void;
-    /** Force reauthorization fences and wakes every waiter on the retired epoch. */
-    retire(generation: string): void;
-}
-/**
- * Physical key for an OAuth value in one authorization epoch. Legacy values
- * keep their historical names so upgrades can read an existing grant. Modern
- * values get an epoch-specific namespace: a stale write or delete can then
- * affect only its own flow, even if it lands after a replacement flow.
- */
-export declare function oauthValueStorageKey(key: string, generation: string | null): string;
-/**
- * OAuthClientProvider implemented over KVStorage for a single downstream
- * connector. Keys live in the connector's namespace as `oauth:<field>`.
- *
- * Headless twist: redirectToAuthorization() cannot navigate a user agent, so it
- * STORES the authorization URL; the registry surfaces it as status
- * "auth_required" and the operator opens it. The /oauth/callback/<id> route then
- * drives transport.finishAuth(code).
- */
-export declare class KvOAuthProvider implements OAuthClientProvider {
-    private readonly connectorId;
-    private readonly storage;
-    private readonly redirectUri;
-    private readonly refreshCoordinator?;
-    private readonly allowAuthorization;
-    /**
-     * The reset generation this provider's flow started under. Every OAuth value
-     * it writes carries this epoch, so a late write can land after a reset without
-     * becoming readable under the new generation.
-     */
-    private capturedGeneration;
-    private refreshFlight;
-    /** Tokens this request's issuer-aware auth flow decided to refresh. */
-    private refreshBasis;
-    constructor(connectorId: string, storage: KVStorage, redirectUri: string, refreshCoordinator?: OAuthRefreshCoordinator | undefined, allowAuthorization?: boolean);
-    /**
-     * Stamp the force-reauth generation the current connect flow started under.
-     * Called by the connector once per connect, before c.connect(). The callback
-     * path captures the generation stored beside its verified state instead.
-     */
-    captureGeneration(gen: string): void;
-    /** The generation captured for this flow, before a concurrent reset. */
-    flowGeneration(): Promise<string>;
-    /** @internal Record the refresh attempt this provider owns. */
-    captureRefreshFlight(generation: string, flight: OAuthRefreshFlight): void;
-    private failRefreshFlight;
-    /** True when another request saved a refresh result after this flow's read. */
-    refreshBasisChanged(current: OAuthTokens, generation: string): boolean;
-    /**
-     * The epoch this provider writes under. Direct unit/custom use lazily captures
-     * the current generation; connector-driven connect and callback paths stamp it
-     * explicitly before the SDK can write.
-     */
-    private writeGeneration;
-    /**
-     * Store a value in the flow's physical epoch namespace. The pre-write check
-     * avoids needless stale residue. The namespaced key closes the remaining
-     * check-then-write race: a late old write cannot overwrite a replacement
-     * flow's value because the two writes have different physical keys.
-     */
-    private writeValue;
-    /**
-     * Read a value only when it belongs to the active generation. Plain legacy
-     * values remain readable until the first v2 reset, so upgrades do not discard
-     * an existing grant; once a modern epoch exists, untagged residue fails
-     * closed.
-     */
-    private readValue;
-    /**
-     * Read credentials only for the authorization server that issued them.
-     *
-     * Values written before issuer binding are bound on their first read with a
-     * validated SDK issuer, preserving an existing grant across this upgrade.
-     * A later issuer change is different: publish a new generation before
-     * returning no credentials, so every isolate drops the old registration and
-     * token set and the SDK starts authorization from scratch.
-     */
-    private readIssuerBoundValue;
-    /** Attempt every key deletion, then report the first backend failure. */
-    private deleteAll;
-    private cleanupBacklog;
-    private rememberRetiredGeneration;
-    private valueKeysForGeneration;
-    get redirectUrl(): string;
-    get clientMetadata(): OAuthClientMetadata;
-    clientInformation(ctx?: OAuthClientInformationContext): Promise<OAuthClientInformationMixed | undefined>;
-    saveClientInformation(info: OAuthClientInformationMixed, ctx?: OAuthClientInformationContext): Promise<void>;
-    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
-    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
-    tokens(ctx?: OAuthClientInformationContext): Promise<OAuthTokens | undefined>;
-    saveTokens(tokens: OAuthTokens, ctx?: OAuthClientInformationContext): Promise<void>;
-    /**
-     * OAuth `state`. The SDK calls this (when present) and appends the value to
-     * the authorization URL. We generate a fresh random value and persist it so
-     * the public /oauth/callback route can prove the callback belongs to a flow
-     * WE started. Without it, anyone holding a pending authorization URL could
-     * complete consent with their own account (login CSRF) — PKCE does not help,
-     * since the verifier belongs to connecta, not the attacker. Cleared in
-     * clearPending() once the flow completes.
-     */
-    state(): Promise<string>;
-    /**
-     * Constant-time check of a callback's `state` against the stored one-shot
-     * value. Absent stored state or absent candidate → false (fail closed).
-     */
-    verifyState(candidate: string | null): Promise<boolean>;
-    saveCodeVerifier(verifier: string): Promise<void>;
-    codeVerifier(): Promise<string>;
-    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
-    /** The stored authorization URL, if a flow is pending. */
-    pendingAuthorizationUrl(): Promise<string | undefined>;
-    /** Clear one-shot flow state after the callback completes. */
-    clearPending(): Promise<void>;
-    /**
-     * Force-reauth epoch shared across isolates through storage. Old numeric
-     * generations remain valid strings for migration; new resets use unique
-     * nonces, avoiding the lost-update race of read/increment/write.
-     */
-    generation(): Promise<string>;
-    /** True only after an operator disconnect, until an explicit authorization starts. */
-    operatorDisconnected(): Promise<boolean>;
-    /** Interpret a generation already read by a connector without another KV lookup. */
-    isOperatorDisconnectedGeneration(generation: string): boolean;
-    /** Publish a unique active epoch without a read/modify/write race. */
-    bumpGeneration(): Promise<string>;
-    /**
-     * Fence every flow that could still write, then remove all durable and
-     * one-shot authorization state. The generation is intentionally retained:
-     * it is the epoch fence that tells another isolate not to resurrect
-     * credentials it read before this reset.
-     *
-     * Once the fence is durable, attempt every deletion even if one fails. A
-     * partial backend outage should not leave unrelated secrets behind merely
-     * because an earlier key happened to be the first failed delete.
-     */
-    resetAuthorization(operatorDisconnected?: boolean): Promise<void>;
-    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
-}
-export {};

package/dist/catalog-fingerprint.d.ts

@@ -1,19 +0,0 @@
-import type { ToolDef } from "./types.js";
-export interface CatalogSnapshot {
-    tools: ToolDef[];
-    /** SHA-256 over the exact serialized tool array, prefixed with its size. */
-    fingerprint: string;
-    /** UTF-8 form reused by hashing, size enforcement, and chunking. */
-    serializedBytes: Uint8Array;
-}
-/** Fingerprint an already serialized catalog without parsing/reserializing it. */
-export declare function fingerprintSerializedCatalog(serializedTools: string): Promise<{
-    fingerprint: string;
-    byteLength: number;
-}>;
-/**
- * Capture every persisted/discovered field in one deterministic snapshot.
- * Object key order is allowed to cause a conservative extra write; changing
- * any serialized field must change the digest.
- */
-export declare function snapshotCatalog(tools: ToolDef[]): Promise<CatalogSnapshot>;

package/dist/catalog-limits.d.ts

@@ -1,9 +0,0 @@
-/** Complete-catalog ceiling shared by dynamically listed connector catalogs. */
-export declare const MAX_CATALOG_TOOLS = 100000;
-/**
- * Large enough to cross a single Workers KV value boundary while keeping the
- * serialized form at one quarter of a 128 MiB Worker heap.
- */
-export declare const MAX_SERIALIZED_CATALOG_BYTES: number;
-/** Persisted values stay comfortably below platform per-value limits. */
-export declare const MAX_CATALOG_CHUNK_BYTES: number;