@jami-studio/core 0.92.26 → 0.92.28

package/corpus/core/src/secrets/register.ts

@@ -1,129 +1,132 @@
-/**
- * In-process registry of required / optional secrets.
- *
- * Templates call `registerRequiredSecret()` at module load time — typically
- * from a server plugin. The secrets HTTP routes and the sidebar settings UI
- * read from this registry on every request so overrides and late-registered
- * secrets are picked up without a restart.
- */
-
-export type SecretScope = "user" | "workspace" | "org";
-export type SecretKind = "api-key" | "oauth";
-
-export interface ValidatorResult {
-  ok: boolean;
-  error?: string;
-}
-
-export interface SecretValidator {
-  (
-    value: string,
-  ): Promise<ValidatorResult | boolean> | ValidatorResult | boolean;
-}
-
-export interface RegisteredSecret {
-  /** Env var name & settings key — e.g. "OPENAI_API_KEY". */
-  key: string;
-  /** Human-readable label shown in the sidebar. */
-  label: string;
-  /** Short description shown below the label. */
-  description?: string;
-  /** URL where the user can obtain the key or connect the account. */
-  docsUrl?: string;
-  /** Whether the secret is per-user or shared across a workspace/org. */
-  scope: SecretScope;
-  /** UI affordance: "api-key" renders an input; "oauth" renders Connect. */
-  kind: SecretKind;
-  /** When true, an onboarding step is auto-injected for this secret. */
-  required?: boolean;
-  /**
-   * Optional health check. Receives the plain-text value, returns `true` or
-   * `{ ok: true }` on success. Returning `{ ok: false, error }` surfaces the
-   * error to the UI. Never log the value from inside the validator.
-   */
-  validator?: SecretValidator;
-  /**
-   * For `kind: "oauth"` — the oauth-tokens provider id (e.g. "google") that
-   * backs this registration. Used to surface OAuth status in the unified UI.
-   */
-  oauthProvider?: string;
-  /**
-   * For `kind: "oauth"` — URL the Connect button should point at. Typically
-   * the framework's `/_agent-native/google/auth-url` or similar.
-   */
-  oauthConnectUrl?: string;
-}
-
-// Pin the registry to globalThis so templates that load `@agent-native/core`
-// via more than one ESM graph (e.g. dev-mode Vite + Nitro, symlinked
-// node_modules, dist/ vs src/) share a single registry. Without this, a
-// template's `register-secrets.ts` side-effect module may populate one
-// registry instance while the /_agent-native/secrets route reads from
-// another — net effect: the UI sees an empty list.
-const REGISTRY_KEY = Symbol.for("@agent-native/core/secrets.registry");
-interface GlobalWithRegistry {
-  [REGISTRY_KEY]?: Map<string, RegisteredSecret>;
-}
-const registry: Map<string, RegisteredSecret> = ((
-  globalThis as unknown as GlobalWithRegistry
-)[REGISTRY_KEY] ??= new Map());
-
-/**
- * Register (or override) a required secret.
- *
- * Subsequent registrations with the same `key` replace the previous
- * definition — later plugins can override framework defaults.
- */
-export function registerRequiredSecret(secret: RegisteredSecret): void {
-  if (!secret || typeof secret.key !== "string" || !secret.key) {
-    throw new Error("registerRequiredSecret: secret.key is required");
-  }
-  if (
-    secret.scope !== "user" &&
-    secret.scope !== "workspace" &&
-    secret.scope !== "org"
-  ) {
-    throw new Error(
-      `registerRequiredSecret: secret.scope must be "user", "workspace", or "org" (got "${secret.scope}")`,
-    );
-  }
-  if (secret.kind !== "api-key" && secret.kind !== "oauth") {
-    throw new Error(
-      `registerRequiredSecret: secret.kind must be "api-key" or "oauth" (got "${secret.kind}")`,
-    );
-  }
-  if (registry.has(secret.key) && process.env.DEBUG) {
-    console.log(
-      `[agent-native] Overriding registered secret "${secret.key}" with new registration.`,
-    );
-  }
-  registry.set(secret.key, secret);
-
-  // Auto-inject an onboarding step for required secrets. Done via dynamic
-  // import to avoid a load-order cycle between register and the onboarding
-  // registry during module bootstrap.
-  if (secret.required) {
-    // Lazy import — resolved synchronously in practice because the module is
-    // already loaded once any route handler runs, but tolerate async.
-    import("./onboarding.js")
-      .then((mod) => mod.maybeRegisterSecretOnboardingStep(secret))
-      .catch(() => {
-        // Onboarding is optional — never let it block registration.
-      });
-  }
-}
-
-/** Return all registered secrets in registration order. */
-export function listRequiredSecrets(): RegisteredSecret[] {
-  return Array.from(registry.values());
-}
-
-/** Look up a single registered secret by key. */
-export function getRequiredSecret(key: string): RegisteredSecret | undefined {
-  return registry.get(key);
-}
-
-/** Test helper — clears the registry between runs. */
-export function __resetSecretsRegistry(): void {
-  registry.clear();
-}
+/**
+ * In-process registry of required / optional secrets.
+ *
+ * Templates call `registerRequiredSecret()` at module load time — typically
+ * from a server plugin. The secrets HTTP routes and the sidebar settings UI
+ * read from this registry on every request so overrides and late-registered
+ * secrets are picked up without a restart.
+ */
+
+import { getScopedGlobal } from "../shared/global-scope.js";
+
+export type SecretScope = "user" | "workspace" | "org";
+export type SecretKind = "api-key" | "oauth";
+
+export interface ValidatorResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface SecretValidator {
+  (
+    value: string,
+  ): Promise<ValidatorResult | boolean> | ValidatorResult | boolean;
+}
+
+export interface RegisteredSecret {
+  /** Env var name & settings key — e.g. "OPENAI_API_KEY". */
+  key: string;
+  /** Human-readable label shown in the sidebar. */
+  label: string;
+  /** Short description shown below the label. */
+  description?: string;
+  /** URL where the user can obtain the key or connect the account. */
+  docsUrl?: string;
+  /** Whether the secret is per-user or shared across a workspace/org. */
+  scope: SecretScope;
+  /** UI affordance: "api-key" renders an input; "oauth" renders Connect. */
+  kind: SecretKind;
+  /** When true, an onboarding step is auto-injected for this secret. */
+  required?: boolean;
+  /**
+   * Optional health check. Receives the plain-text value, returns `true` or
+   * `{ ok: true }` on success. Returning `{ ok: false, error }` surfaces the
+   * error to the UI. Never log the value from inside the validator.
+   */
+  validator?: SecretValidator;
+  /**
+   * For `kind: "oauth"` — the oauth-tokens provider id (e.g. "google") that
+   * backs this registration. Used to surface OAuth status in the unified UI.
+   */
+  oauthProvider?: string;
+  /**
+   * For `kind: "oauth"` — URL the Connect button should point at. Typically
+   * the framework's `/_agent-native/google/auth-url` or similar.
+   */
+  oauthConnectUrl?: string;
+}
+
+// Pin the registry to globalThis so templates that load `@agent-native/core`
+// via more than one ESM graph (e.g. dev-mode Vite + Nitro, symlinked
+// node_modules, dist/ vs src/) share a single registry. Without this, a
+// template's `register-secrets.ts` side-effect module may populate one
+// registry instance while the /_agent-native/secrets route reads from
+// another — net effect: the UI sees an empty list.
+// Scope-aware + lazily resolved so unified workspace deployments (all apps in
+// one isolate) keep per-app secret registrations. See shared/global-scope.
+function getSecretsRegistry(): Map<string, RegisteredSecret> {
+  return getScopedGlobal(
+    "agent-native.secrets.registry",
+    () => new Map<string, RegisteredSecret>(),
+  );
+}
+
+/**
+ * Register (or override) a required secret.
+ *
+ * Subsequent registrations with the same `key` replace the previous
+ * definition — later plugins can override framework defaults.
+ */
+export function registerRequiredSecret(secret: RegisteredSecret): void {
+  if (!secret || typeof secret.key !== "string" || !secret.key) {
+    throw new Error("registerRequiredSecret: secret.key is required");
+  }
+  if (
+    secret.scope !== "user" &&
+    secret.scope !== "workspace" &&
+    secret.scope !== "org"
+  ) {
+    throw new Error(
+      `registerRequiredSecret: secret.scope must be "user", "workspace", or "org" (got "${secret.scope}")`,
+    );
+  }
+  if (secret.kind !== "api-key" && secret.kind !== "oauth") {
+    throw new Error(
+      `registerRequiredSecret: secret.kind must be "api-key" or "oauth" (got "${secret.kind}")`,
+    );
+  }
+  if (getSecretsRegistry().has(secret.key) && process.env.DEBUG) {
+    console.log(
+      `[agent-native] Overriding registered secret "${secret.key}" with new registration.`,
+    );
+  }
+  getSecretsRegistry().set(secret.key, secret);
+
+  // Auto-inject an onboarding step for required secrets. Done via dynamic
+  // import to avoid a load-order cycle between register and the onboarding
+  // registry during module bootstrap.
+  if (secret.required) {
+    // Lazy import — resolved synchronously in practice because the module is
+    // already loaded once any route handler runs, but tolerate async.
+    import("./onboarding.js")
+      .then((mod) => mod.maybeRegisterSecretOnboardingStep(secret))
+      .catch(() => {
+        // Onboarding is optional — never let it block registration.
+      });
+  }
+}
+
+/** Return all registered secrets in registration order. */
+export function listRequiredSecrets(): RegisteredSecret[] {
+  return Array.from(getSecretsRegistry().values());
+}
+
+/** Look up a single registered secret by key. */
+export function getRequiredSecret(key: string): RegisteredSecret | undefined {
+  return getSecretsRegistry().get(key);
+}
+
+/** Test helper — clears the registry between runs. */
+export function __resetSecretsRegistry(): void {
+  getSecretsRegistry().clear();
+}

package/corpus/core/src/shared/global-scope.ts

@@ -0,0 +1,75 @@
+/**
+ * Per-module-graph global scope for globalThis-pinned framework registries.
+ *
+ * Why this exists: several framework registries (file-upload providers,
+ * private-blob providers, shareable resources, event bus, notification
+ * channels, tracking providers, secrets registry) pin their state on
+ * `globalThis` so that multiple ESM graphs of ONE app (Vite dev + Nitro,
+ * symlinked node_modules, dist/ vs src/) still share a single registry.
+ *
+ * On a unified workspace deployment (Cloudflare Pages `_worker.js` dispatcher
+ * importing every app's worker into ONE isolate) that pinning goes too far:
+ * each app's bundle keeps its own module graph — so module-scope state is
+ * correctly per-app — but the `globalThis` pin collapses all apps' registries
+ * into one shared map. Real-world failure: an upload POSTed to /assets was
+ * served by the clips app's registered S3 provider (wrong object prefix).
+ *
+ * The fix: each app's generated worker entry calls `setGlobalScopeId(appId)`
+ * from a scope-init module evaluated FIRST in the entry's import graph (ESM
+ * evaluates imports depth-first in declaration order, so the scope is set
+ * before any registry module initializes or registers built-ins). Registries
+ * resolve their `globalThis` key LAZILY through `getScopedGlobal`, which
+ * namespaces the key by the module graph's scope id. Result:
+ *
+ * - Unified worker: each app's core copy has its own scope id → per-app keys
+ *   → per-app registries. Cross-app state sharing is gone.
+ * - Dev / single-app deployments: `setGlobalScopeId` is never called → keys
+ *   are unscoped → the original multi-graph dedupe behavior is preserved.
+ *
+ * This module must stay dependency-free: it is imported by the generated
+ * scope-init module before anything else in the app bundle evaluates.
+ */
+
+let moduleGraphScopeId: string | null = null;
+
+/**
+ * Set the global-registry scope for THIS module graph (this app's bundle).
+ * Called by the generated worker entry's scope-init module on unified
+ * workspace deployments. Pass `null` to clear (tests).
+ */
+export function setGlobalScopeId(id: string | null): void {
+  const trimmed = typeof id === "string" ? id.trim() : "";
+  moduleGraphScopeId = trimmed ? trimmed : null;
+}
+
+/** The active scope id for this module graph, or `null` when unscoped. */
+export function getGlobalScopeId(): string | null {
+  return moduleGraphScopeId;
+}
+
+/**
+ * The fully-qualified global key name for `base` under the active scope.
+ * Unscoped graphs get `base` unchanged, so existing dev-mode behavior
+ * (one registry across all of an app's ESM graphs) is preserved.
+ */
+export function scopedGlobalKeyName(base: string): string {
+  return moduleGraphScopeId ? `${base}::app:${moduleGraphScopeId}` : base;
+}
+
+/**
+ * Lazily resolve (and initialize once) a globalThis-pinned singleton under
+ * the scope-aware key for `base`. Registries MUST call this per access —
+ * never capture the result in module scope — so a scope id set during
+ * entry-module evaluation is honored by every later registration and read.
+ */
+export function getScopedGlobal<T>(base: string, init: () => T): T {
+  const key = Symbol.for(scopedGlobalKeyName(base));
+  const g = globalThis as unknown as Record<symbol, T | undefined>;
+  return (g[key] ??= init());
+}
+
+/** Test helper — delete the pinned singleton for `base` in the ACTIVE scope. */
+export function __deleteScopedGlobal(base: string): void {
+  const key = Symbol.for(scopedGlobalKeyName(base));
+  delete (globalThis as unknown as Record<symbol, unknown>)[key];
+}

package/corpus/core/src/shared/init-memo.ts

@@ -0,0 +1,94 @@
+/**
+ * Workerd-safe memoization for module-scope init promises.
+ *
+ * Nearly every SQL-backed store memoizes its table-creation promise at module
+ * scope (`let _initPromise`). On Cloudflare Workers (workerd) that pattern has
+ * a lethal failure mode: workerd cancels a request's pending I/O the moment
+ * its response returns, so an init promise CREATED during an early-responding
+ * request (auth probe, 404) FREEZES forever — and every later caller that
+ * awaits the memo hangs permanently. Proven live: `ensureObservabilityTables`
+ * frozen by a `get-session`-first ordering wedged every agent chat run at
+ * "Starting agent" on the unified Cloudflare runtime.
+ *
+ * `createInitMemo` keeps the single-flight memo semantics everywhere, and on
+ * workerd adds two layers of defense:
+ *   1. The init promise is tied to the creating request's lifetime via
+ *      `__cf_ctx.waitUntil`, so workerd keeps its I/O alive to completion
+ *      even when the response returns first (same remedy as the plugin-init
+ *      freeze fix in framework-request-handler.ts).
+ *   2. Awaits on a still-pending memo are bounded; on timeout the memo is
+ *      re-run under the CURRENT (live) request. Init bodies are idempotent
+ *      (CREATE TABLE IF NOT EXISTS / guarded ALTERs), so a re-run is safe.
+ *
+ * On Node the behavior is identical to the raw memo pattern (single flight,
+ * failed init clears the memo so the next caller retries).
+ */
+
+import { isCloudflareRuntime } from "./runtime.js";
+
+/** How long a pending memo may be awaited on workerd before it is presumed
+ * frozen and re-run. Long enough for a slow cold init (Neon DDL over HTTP),
+ * short enough that a frozen memo degrades to a slow call, not a hang. */
+export const INIT_MEMO_FROZEN_RETRY_MS = 15_000;
+
+const FROZEN = Symbol("init-memo-frozen");
+
+export function createInitMemo(
+  init: () => Promise<void>,
+  options?: { frozenRetryMs?: number; label?: string },
+): () => Promise<void> {
+  const frozenRetryMs = options?.frozenRetryMs ?? INIT_MEMO_FROZEN_RETRY_MS;
+  let promise: Promise<void> | undefined;
+  let settled = false;
+
+  const start = (): Promise<void> => {
+    settled = false;
+    const p = init().then(
+      () => {
+        settled = true;
+      },
+      (err) => {
+        // Failed init must not be memoized — the next caller retries.
+        promise = undefined;
+        throw err;
+      },
+    );
+    // Keep the init's I/O alive past the creating request's response on
+    // workerd. The extra catch keeps waitUntil from surfacing the rejection
+    // twice; callers still see it through the memoized promise.
+    try {
+      (
+        globalThis as {
+          __cf_ctx?: { waitUntil?: (p: Promise<unknown>) => void };
+        }
+      ).__cf_ctx?.waitUntil?.(p.catch(() => {}));
+    } catch {
+      /* not on Cloudflare — nothing to extend */
+    }
+    return p;
+  };
+
+  return async (): Promise<void> => {
+    if (!promise) promise = start();
+    if (settled || !isCloudflareRuntime()) return promise;
+
+    // workerd + still pending: the memo may belong to a completed request
+    // whose I/O was frozen. Bounded wait, then re-run under this request.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const raced = await Promise.race([
+      promise,
+      new Promise<typeof FROZEN>((resolve) => {
+        timer = setTimeout(() => resolve(FROZEN), frozenRetryMs);
+      }),
+    ]).finally(() => {
+      if (timer) clearTimeout(timer);
+    });
+    if (raced !== FROZEN) return;
+
+    console.warn(
+      `[agent-native] init memo${options?.label ? ` (${options.label})` : ""} still pending after ${frozenRetryMs}ms — presumed frozen by a completed request; re-running under the current request`,
+    );
+    promise = start();
+    return promise;
+  };
+}