@open-everywhere/create 0.1.4 → 0.2.1

package/template/agent/lib/register-adapters.ts

@@ -1,286 +1,25 @@
-// Adapter selection — the app's choice of vendor implementations, wired at startup.
-// Mirrors register-config.ts: a side-effect import from agent.ts. Core ships only
-// portable defaults (env broker, sqlite stores, Eve-owned sandbox egress); this is
-// where the deploy opts into Vercel/Neon. Self-host swaps these lines (or rolls its
-// own adapter package) without touching core.
-
-import { registerOeOauth } from "@open-everywhere/adapters/agent/oe-oauth/register.js";
-import { oeOauthEnabled, loadOeOauthConfig } from "@open-everywhere/adapters/agent/oe-oauth/config.js";
-import { registerAgentBrowser } from "@open-everywhere/adapters/agent/browser/register.js";
-import { agentBrowserEnabled, loadAgentBrowserConfig } from "@open-everywhere/adapters/agent/browser/config.js";
-import { registerAwsAccess } from "@open-everywhere/adapters/agent/aws/register.js";
-import { awsAccessEnabled } from "@open-everywhere/adapters/agent/aws/config.js";
-import { registerDirectoryAdapter } from "@open-everywhere/adapters/agent/directory/register.js";
-import {
-  registerDbCredentialBroker,
-  CREDENTIAL_KEY_ENV,
-  registerGitHubConfigPrProvider,
-  setBlobPutter,
-  registerAuditDropCounter,
-  emitTelemetry,
-  getOperationalStore,
-  bootVerifyAuditChainTail,
-  bootBackfillLinkTenants,
-  registerOperationalPgliteLazy,
-  resolveOperationalSelection,
-  resolveMemoryProviderId,
-  onVercel,
-  declareProviderSelection,
-  assertConnectorMemoryGrants,
-  applySubtreeSurfaceClaims,
-  reconcileSurfaceCommands,
-} from "@open-everywhere/core/agent/adapter-api.js";
-import { SELECTED_PROVIDERS, SELECTED_PROVIDER_IDS } from "./providers.generated.js";
-import { loadDomains, loadSilos } from "../memory/config/domains.js";
-import { domainMemoryGrants } from "./memory-grants.js";
-import { registerNeon } from "@open-everywhere/adapters/agent/postgres/neon.js";
-import { vercelBlobPutter } from "@open-everywhere/adapters/agent/blob/hosting.js";
-
-// NOTE: these are STATIC imports on purpose. Eve bundles each authored module
-// (agent.ts and its import graph) into a SINGLE rolldown chunk — a literal dynamic
-// `import("…")` of an internal module code-splits into a second chunk and trips Eve's
-// "expected one authored module" invariant. Static import keeps it one chunk. Laziness
-// is preserved where it matters: registerNeon() only CONSTRUCTS the @neondatabase/serverless
-// driver via an inner variable-specifier import when it is actually CALLED (guarded below),
-// and registerNotionProvider() just writes registry rows (its memory token resolves lazily via
-// the broker). Provider BUNDLES (@open-everywhere/provider-*) are wired here the same way — one
-// static import + one register call per bundle.
-
-// PROVIDER SELECTION — declared FIRST, before any bundle registers (OPE-116 stage 5). The table
-// (./providers.generated.ts) is the single list of provider bundles this deployment carries; core
-// takes the ids as opaque strings and every platform-keyed registration seam then refuses anything
-// outside them, so an unselected provider is structurally absent from every registry rather than
-// half-wired. Declaring first matters: a row that lands ahead of the declaration cannot be retracted
-// (core warns loudly if one does).
+// Adapter wiring — a side-effect import from agent.ts, beside register-config.ts.
 //
-// 🔴 `./providers.generated.ts` is BUILD OUTPUT (OPE-375), gitignored and written by `oe build` from
-// `roster.config.ts`'s `providers` map — the same edit that generates each bundle's app-tree stubs.
-// Do not hand-edit it; change roster.config.ts.
-declareProviderSelection(SELECTED_PROVIDER_IDS);
-
-// Connector-plane user-auth flow (OAuth mint/authorize) — core is vendor-SDK-free since R2
-// (OPE-82) and fails closed on the mint paths when no flow is registered, so this deploy's
-// choice must be wired explicitly. The built-in v1 flow is OWN-ROLLED OAuth (OPE-88), registered
-// when the master flag OE_OAUTH_ENABLED is armed AND a provider config block is present
-// (OE_OAUTH_CONFIG / OE_OAUTH_NOTION_RESOURCE) — DCR+PKCE against a hosted MCP server, tokens in
-// our own AES vault, callback at GET /oauth/v1/callback. Flag-off OR config-absent ⇒ NO flow
-// registers and core's OAuth mint paths fail closed (the callback route 404s) — there is no
-// vendor fallback (the legacy Vercel Connect adapter was deleted; rollback is a git revert).
-{
-  const oeOauthCfg = oeOauthEnabled() ? loadOeOauthConfig() : undefined;
-  if (oeOauthCfg) {
-    registerOeOauth({ providers: oeOauthCfg });
-  }
-}
-
-// Make the "db" credential broker resolvable by name (task #113 — a core, vendor-SDK-free broker
-// whose store is our own operational DB). REGISTRATION = CONFIGURED (no selection any more): register
-// it iff its backing config exists — the AES key (OE_CREDENTIAL_ENCRYPTION_KEY, AES-256-GCM) that
-// encrypts every stored credential at rest. Without the key the broker fails closed on both store and
-// read, so registering it would falsely advertise the "Set API key" chat intake (which keys off db
-// being REGISTERED). A credential stamped `broker: "db"` still fails closed here if the key is absent —
-// registration just gates the OFFER. It resolves credentials an org member pastes into the Slack
-// "Set API key" modal, encrypted at rest.
-if (process.env[CREDENTIAL_KEY_ENV]) {
-  registerDbCredentialBroker();
-}
-
-// Wire the agent-browser toolkit (the in-sandbox browser plane, OPE-43). Mirrors the oe-oauth
-// guard: register ONLY when the master flag (browser.enabled) is armed AND the operator domain
-// allowlist parses (loadAgentBrowserConfig is fail-closed + loud on a flag-on misconfig). Flag-off
-// OR config-absent ⇒ nothing registers ⇒ byte-identical (no browser tools mount, no extra egress
-// hosts, no sandbox bake — the bake side reads the SAME config in agent/sandbox/sandbox.ts).
-// registerAgentBrowser itself can still refuse (returns false, loud) if the vendor extension's
-// config binding didn't take — the uncontained-defaults hazard fails closed there.
-// 🔴 THE PLATFORM GATE IS INSIDE loadAgentBrowserConfig (OPE-1793), so this mount needs no
-// `onVercel()` of its own: off Vercel the config is `undefined`, nothing registers, and neither the
-// 20 `browser_*` tools nor the declared egress hosts open for a browser the image cannot run.
-{
-  const browserCfg = agentBrowserEnabled() ? loadAgentBrowserConfig() : undefined;
-  if (browserCfg) {
-    registerAgentBrowser(browserCfg);
-  }
-}
-
-// Wire the AWS-access layer (review/design/aws-access-plan.md, Door 1, Phase 0). Mirrors the oe-oauth
-// guard: register ONLY when the master flag (OE_AWS_ENABLED) is armed. Flag-off ⇒ nothing registers ⇒
-// byte-identical behaviour (no AWS identity provider, no `aws` executor) and core's AWS mint/exec
-// paths fail closed (requireAwsIdentityProvider / requireAwsExecutor throw — never a silent no-op).
-// registerAwsAccess constructs the OIDC→STS identity provider + the `aws` CLI executor and hands each
-// to core's DI seam; there is no fallback (rollback is not arming the flag).
-if (awsAccessEnabled()) {
-  registerAwsAccess();
-}
-
-// Wire the identity-DIRECTORY plane (review/design/identity-linking-plan.md, P2 — Okta first). Same
-// guard shape as the three above: registerDirectoryAdapter() is a no-op unless OE_DIRECTORY_PROVIDER
-// names an adapter, and fails LOUD if it names one whose config is incomplete. Selector-off ⇒
-// nothing registers ⇒ core's DirectoryProvider port stays empty and the feature is cleanly OFF —
-// the daily sync schedule logs one line and touches nothing, and the control verbs say so. The IdP
-// is a sync source, never a live dependency: nothing on a request path reads this.
-registerDirectoryAdapter();
-
-// (The "github" memory backing MOVED to the github provider bundle at OPE-390 — it registers
-// itself from `provider.register()` in the SELECTED_PROVIDERS loop below, beside the rest of that
-// vendor's wiring. Core keeps only the first-party postgres/sqlite backings.)
-
-// Register the GitHub config-repo PR mechanism as the default ConfigPrProvider (OPE-86 / R6). The
-// credential-binding flow (credentials/binding-pr.ts) opens the custody-flip PR through this port;
-// GitHub is the built-in default, a self-host swaps in a GitLab/Gitea provider here. Unconditional:
-// harmless when unused (resolveWriteToken only runs on a real binding PR and fails loud there if no
-// GitHub credential is configured — same as before this seam existed).
-registerGitHubConfigPrProvider();
-
-// THE PROVIDER BUNDLES (OPE-114 stages 3-4, selection-driven since stage 5). One boot call per
-// SELECTED bundle, taken straight from the generated table — there is no second, hand-maintained
-// call list to drift out of step with it, which is the whole point (this module names no provider;
-// read roster.config.ts's `providers` map, or ./providers.generated.ts, for what each bundle does). Every call is unconditional and cheap: a bundle's
-// register fn only writes registry rows, and every live vendor call behind them resolves its
-// credential lazily at call time.
-for (const provider of SELECTED_PROVIDERS) {
-  provider.register();
-}
-
-// THE PREFETCH INVARIANT (OPE-390), cross-validated at boot and fail-LOUD — HERE, not in
-// register-config.ts, and the ordering is the whole reason: a connector-owned memory capability is
-// DECLARED by its provider bundle's register() in the loop directly above, so a check that ran
-// earlier would see an empty capability registry and pass every silo vacuously (the same boot-order
-// trap assertWindowSourcesVouched documents on the vouch register).
+// The wiring itself is PRODUCT code: `registerDefaultAdapters()` in `@open-everywhere/adapters`
+// registers the default adapters, this app's selected provider bundles and the operational store,
+// with the product's selection rules and floors. An upgrade of the package upgrades the wiring, so
+// this file needs no merge on upgrade.
 //
-// What it refuses: a domain whose memory list names a connector-owned silo the domain holds no
-// connector grant for, or whose container reaches past that grant (a github silo on an ungranted
-// repo). Memory rides the same route as connector access; a silo must not be a side door onto a
-// source the connector plane would refuse. First-party postgres/sqlite silos are skipped by
-// construction — the deployment holds their credential, so there is nothing to check.
-assertConnectorMemoryGrants(loadDomains(), loadSilos(), domainMemoryGrants);
-
-// THE SUBTREE CLAIM (OPE-539), settled HERE for the SAME boot-order reason as the line above. An
-// operator widens ONE trust entry with `subtree: true` (agent/identity/surfaces.ts); the platform
-// that HONOURS the word declares so from its own bundle's register(), in the loop above. So this is
-// the first line at which both halves are up:
-//   • a claim on a platform no SELECTED bundle honours throws — the registry never accepts a line
-//     that would grant nothing;
-//   • every platform that does honour it receives its keys, and validates them by its own rules
-//     (a Notion key whose last segment is not a page id is a boot error here).
-// Core names no vendor either side of this call.
-applySubtreeSurfaceClaims();
+// To add or replace an adapter, put the registration in `customAdapters` below. It runs after every
+// default adapter and provider bundle registers, and before the boot checks that read them. Keep
+// imports STATIC: Eve bundles this module's import graph into one chunk, and a dynamic `import()`
+// splits it.
 
-// Neon (hosted Postgres) is LIVE-ONLY — only wire it when a Postgres backing is actually selected
-// AND a DATABASE_URL exists. registerNeon() is a no-op at import; it only builds the driver (inner
-// variable-specifier import) when called here.
-//
-// 🔴 THE SELECTION IS THE RUNTIME'S OWN RULE, NOT A SECOND ENV TEST (OPE-2230). Both selectors
-// DEFAULT to postgres when DATABASE_URL is present, so a hand-written `OE_MEMORY_PROVIDER ===
-// "postgres"` here refuses to build the driver for exactly the deployment the default was added for:
-// the Neon Marketplace integration sets DATABASE_URL and nothing else, `getOperationalStore()` then
-// resolves to postgres, no client is ever registered, and the first audit append throws. The
-// scaffolded app is dead rather than degraded, and it mounts no status route to say why.
-// `scripts/scaffold-test.ts` reds if this returns to testing the two env names.
-const operationalSelection = resolveOperationalSelection(process.env);
-const postgresSelected =
-  resolveMemoryProviderId(process.env) === "postgres" ||
-  (operationalSelection.id === "postgres" && operationalSelection.floor === "none");
-if (postgresSelected && process.env.DATABASE_URL) {
-  await registerNeon();
-}
-
-// Embedded-Postgres (PGlite) operational FLOOR (OPE-113) — the zero-wiring default. Arm it when
-// NO provider is selected AND there is no DATABASE_URL: getOperationalStore() then resolves to the
-// same postgres.ts store backed by an in-process, file-backed PGlite instance (one dialect
-// everywhere; sqlite is deprecated). Skipped on Vercel (the floor is per-instance ephemeral — the
-// provider's own guard fails loud there, and OE_ALLOW_EPHEMERAL_OPERATIONAL=1 is the single-instance
-// escape) and whenever a provider/DATABASE_URL is set (hosted path, or explicit sqlite). registerNeon
-// above never fires on this branch, so there's no double-register. Takes a single-writer lockfile and
-// refuses to boot against a data dir a live process already holds (PGlite has no cross-process lock).
-// OPE-391: armed LAZILY (registerOperationalPgliteLazy). The store is registered synchronously —
-// getOperationalStore() resolves to the floor from this line on — but the lock + WASM boot + schema
-// init happen on the first QUERY. `eve start` evaluates this very module inside the CLI process (its
-// sandbox-prewarm step) and then spawns the built server as a child that evaluates it again; an
-// eager arm made the CLI parent the lock holder and the server child refused to boot ("LOCKED by a
-// LIVE process"), so a fresh zero-wiring directory could never start. Deferring the open means only
-// the process that actually uses the store touches the data dir. The boot-time store checks ride
-// along as the first-open callback (see below) so they still run exactly once, in that process.
-const pgliteFloorArmed =
-  operationalSelection.floor === "pglite" &&
-  (!onVercel() || process.env.OE_ALLOW_EPHEMERAL_OPERATIONAL === "1");
-if (pgliteFloorArmed) {
-  registerOperationalPgliteLazy(undefined, runBootStoreChecks);
-}
-
-// Wire the audit drop counter (audit-wedge WS-5). audit.ts can import telemetry.ts neither
-// statically (module-init cycle: telemetry → commands/config → approvals → audit, TDZ on the
-// action REGISTRY) nor dynamically (the one-chunk invariant above), so it exposes a registration
-// seam and THIS boot module — which already sits outside that cycle — injects the emitter.
-registerAuditDropCounter((action, platform) => emitTelemetry("oe.audit.dropped", { "oe.action": action, "oe.platform": platform }));
-
-// Governance-channel floor tripwire member supplier (OPE-110): now registered inside
-// registerSlackProvider() above — the supplier arm is slack code, so it rides the bundle's one
-// boot call instead of a dedicated barrel function (OPE-114 stage 4).
-
-// Vercel Blob putter for the HTML-artifact hosting seam (core agent/blob/hosting.ts). Same
-// posture as the gateway ModelBackend: core owns the injection point, this is the app's vendor
-// choice. Registering unconditionally is harmless — hostHtmlArtifact is only ever reached when
-// an org has opted in (resolveBlobHosting), and the putter itself fails loud if the OIDC env
-// isn't present.
-setBlobPutter(vercelBlobPutter);
-
-// The two boot-time store checks, in one place so they can run either eagerly (hosted/sqlite paths,
-// where the store is live the moment it is registered) or on the embedded floor's FIRST OPEN
-// (OPE-391 — the lazy arm above; running them inline would defeat the whole point by opening PGlite
-// in eve's CLI process). Same posture either way: availability over integrity, never throws.
-//
-//  1. Audit hash-chain tail-check (OPE-52, audit-wedge WS-6c): re-verify the last N per-org audit
-//     links and log ONE loud warn on any break (silent out-of-band deletion/mutation is the thing it
-//     catches). If the operational store can't even be resolved (a provider misconfig, or the
-//     Vercel-ephemeral-sqlite guard that is SUPPOSED to fail loud), leave surfacing that to the
-//     app's own first store use rather than swallowing it in a different guise.
-//  2. Identity-link tenant backfill (OPE-309 phase 2): stamp the deployment's sole admitted
-//     workspace onto link rows written before `identity_linked_ids` had a `tenant` column. Same
-//     posture, sharper reason: a row it cannot fix is already INERT (an un-named row matches
-//     nothing, so the link is dormant and standing is lost rather than mis-granted), so there is
-//     nothing a thrown boot would protect. It re-runs on every start and only ever fills blanks, so
-//     declaring the workspace's channel heals it.
-async function runBootStoreChecks(): Promise<void> {
-  try {
-    await bootVerifyAuditChainTail(getOperationalStore());
-  } catch {
-    /* store not resolvable — its first real use raises the reason loudly; skip the check */
-  }
-  try {
-    await bootBackfillLinkTenants();
-  } catch {
-    /* store not resolvable — see above; bootBackfillLinkTenants swallows everything else */
-  }
-}
-
-if (!pgliteFloorArmed) await runBootStoreChecks();
+import { registerDefaultAdapters } from "@open-everywhere/adapters/agent/register-defaults.js";
+import { SELECTED_PROVIDERS } from "./providers.generated.js";
+import { loadDomains, loadSilos } from "../memory/config/domains.js";
+import { domainMemoryGrants } from "./memory-grants.js";
 
-// SLASH COMMANDS REGISTER FROM THE DEPLOYMENT ITSELF (OPE-1687). An app declares WHICH ROOMS with
-// `declareSurfaceCommandScope` (from `@open-everywhere/core/agent/channels/command-registration.js`,
-// imported by register-config.ts; this app declares none); each selected provider bundle declared
-// HOW in the loop above. This is the ONE call that joins them, and
-// it names no provider — same discipline as the bundle loop.
-//
-// HERE, at the cold start, so no separate deploy step is needed. The steady-state cost is one vendor read per process start and a write only on a real difference; a
-// deployment that declares no room pays nothing.
-//
-// AWAITED, and it never throws — the plane catches every reconciler failure and logs one line. It is
-// awaited rather than left floating because a lambda can freeze the moment it answers, and a floating
-// promise would then be cancelled mid-flight on exactly the cold start that had the work to do.
-//
-// 🔴 THE LATENCY BOUND IS THE RECONCILER'S, and it is a real one: each vendor call carries a short
-// timeout AND no 429 backoff, under one budget for the whole reconcile. A timeout alone would NOT
-// bound this — `withRetryAfter`'s default policy allows up to 60 s of sleep between attempts, and an
-// `AbortSignal` covers a request, never a sleep. See `BOOT_RETRY` in the discord bundle's
-// `commands/discord-command-sync.ts`.
-//
-// TWO CONSEQUENCES WORTH KNOWING, both stated rather than engineered away:
-//  • `eve start` evaluates this module TWICE — once in the CLI parent, once in the server child it
-//    spawns — so a local start reconciles twice. Deferring behind a first-request hook the way the
-//    PGlite floor above does would fix it and cost a seam; the hosted deployment (one evaluation per
-//    lambda instance) is the case that matters.
-//  • a reconcile WRITES whenever the process holds the surface's credentials and the declared rooms
-//    are out of step with THIS checkout. Running a branch that changes the command set against the
-//    deployment's own credentials therefore publishes that branch's commands — the warning lives on
-//    the declaration in `agent/commands/discord-commands.ts`.
-await reconcileSurfaceCommands();
+await registerDefaultAdapters({
+  // `./providers.generated.ts` is `oe build` output from roster.config.ts. Do not hand-edit it.
+  providers: SELECTED_PROVIDERS,
+  memory: { domains: loadDomains, silos: loadSilos, grants: domainMemoryGrants },
+  customAdapters: () => {
+    // This app registers no custom adapter.
+  },
+});

package/template/agent/lib/register-config.ts

@@ -75,6 +75,11 @@ import "../identity/authors.js";
 // import degrades loudly (a routine that names a collector stops being creatable) rather than
 // silently widening anything.
 import "../routines/collectors.js";
+// Side effect: register the deployment-wide half of the SHIPPED MANUAL (OPE-138, OPE-2215) so the
+// read_docs tool serves the configuration reference, the security docs and the how-it-works pages.
+// Each provider package registers its own setup runbook from register<X>Provider() instead. Drop
+// this import and read_docs serves those runbooks and nothing else.
+import "./register-docs.js";
 
 // The BEHAVIOUR half of config-as-code (OPE-371), registered FIRST — before registerConfig, and
 // before the boot-time cross-validations below — because a settings-sensitive gate consulted during

package/template/agent/lib/register-docs.ts

@@ -0,0 +1,17 @@
+// Shipped-manual wiring (OPE-138) — hands core the deployment-wide half of the docs the agent can
+// read about itself. SELF-REGISTERING: importing this module performs the registration, the same
+// shape as agent/identity/surfaces.js (see register-config.ts, which imports both for their
+// side effects, so every process that resolves config also carries the manual).
+//
+// This half is the UNIVERSAL manual. Each provider bundle registers its OWN setup runbook from its
+// register<X>Provider(), so a de-selected bundle's docs are not in the import graph at all.
+//
+// The manual ships INSIDE `@open-everywhere/core` (OPE-2215), so this app serves the pages of the
+// core version it installed, and an upgrade of core upgrades the manual with it. Nothing here is
+// copied at scaffold time. To add your own pages, call registerDocs again with more entries. An
+// entry with the same `path` as a shipped page replaces that page.
+
+import { registerDocs } from "@open-everywhere/core/agent/adapter-api.js";
+import { UNIVERSAL_DOCS } from "@open-everywhere/core/agent/docs/generated/index.js";
+
+registerDocs(UNIVERSAL_DOCS);

package/template/agent/memory/config/agents.generated.ts

@@ -1,14 +1,15 @@
 // GENERATED + MACHINE-OWNED — DO NOT HAND-EDIT.
 //
 // The agents overlay: DATA ONLY. Written exclusively by the deterministic codemod
-// (packages/core/agent/memory/agents-codemod.ts) on a bot-PR branch; the PR merge is the approval gate.
+// (@open-everywhere/core/agent/memory/agents-codemod.js) on a bot-PR branch; the PR merge is the approval gate.
 //
 // The codemod re-emits this file from its own parsed content and refuses to rewrite it when the
-// bytes differ, so a hand-edit stops the next machine PR. Before a merge, nothing checks that the
-// file is still data only unless the repository runs its own check: the person who merges the PR
-// is the gate. Read a PR to this file as code, because it is code.
+// data or the import differ, so a hand-edit there stops the next machine PR. Before a merge,
+// nothing checks that the file is still data only unless the repository runs
+// `npx oe build --check` or `npx oe overlays check`: the person who merges the PR is the gate.
+// Read a PR to this file as code, because it is code.
 //
-// To change it by hand, edit only the data below and keep the layout exactly as emitted.
+// To change it by hand, edit only the data below, then run `npx oe overlays normalize`.
 
 import type { AgentsFile } from "@open-everywhere/core/agent/memory/agents-codemod.js";
 

package/template/agent/sandbox/backend-select.ts

@@ -1,8 +1,8 @@
 // Off-Vercel sandbox backend selection — the app-side re-export of the PURE decision logic.
 //
-// The decision itself lives in core (`packages/core/agent/sandbox/backend-select.ts`) because
+// The decision itself lives in core (`@open-everywhere/core/agent/sandbox/backend-select.js`) because
 // TWO packages need it and a rule has one home: this file wires it into `sandbox.ts`, and the
-// turn-end stop hook (`packages/adapters/agent/sandbox/backend-stop.ts`) reads the SAME answer
+// turn-end stop hook (`@open-everywhere/adapters/agent/sandbox/backend-stop.js`) reads the SAME answer
 // through the adapter-api barrel to pick which backend owns the stop. A second parse of
 // `OE_SANDBOX_BACKEND` would let the backend that runs and the backend that stops disagree.
 

package/template/agent/sandbox/sandbox.ts

@@ -1,15 +1,18 @@
-import { defineSandbox } from "eve/sandbox";
-import { vercel } from "eve/sandbox/vercel";
-import { justbash } from "eve/sandbox/just-bash";
-import { docker } from "eve/sandbox/docker";
+import { defineSandbox, type RuntimeSandboxSession, type SandboxEnvironment, type SandboxSession } from "eve/sandbox";
+import { VercelSandbox } from "eve/sandbox/vercel";
+import { JustBashSandbox } from "eve/sandbox/just-bash";
+import { DockerSandbox } from "eve/sandbox/docker";
 import { bindFrom, type BindableContext } from "@open-everywhere/core/agent/identity/binding.js";
 import { resolvePartition } from "@open-everywhere/core/agent/memory/partition.js";
 import { sandboxPresetFor } from "@open-everywhere/core/agent/roles/role.js";
 import { getConfig } from "@open-everywhere/core/agent/access/config.js";
 import { onVercel } from "@open-everywhere/core/agent/access/platform.js";
-import { agentBrowserSandboxHooks } from "@open-everywhere/adapters/agent/browser/sandbox.js";
-import { recordCreatedSandbox } from "@open-everywhere/adapters/agent/sandbox/created-sandbox-registry.js";
+import { agentBrowserSandboxHooks, type BakeableSandbox } from "@open-everywhere/adapters/agent/browser/sandbox.js";
+import { registerSandboxFirewall } from "@open-everywhere/core/agent/sandbox/network-policy.js";
 import { resolveSelfHostBackendKind, selfHostBackendBootLog } from "./backend-select.js";
+// The KIND type has one home — core's adapter-api barrel — so the backend that runs and the backend
+// that stops cannot disagree about its spelling (see ./backend-select.ts's header).
+import type { SelfHostBackendKind } from "@open-everywhere/core/agent/adapter-api.js";
 import {
   resolveSandboxRegionPlan,
   vercelSandboxCreateOptions,
@@ -148,22 +151,67 @@ const VERCEL_CREATE_OPTIONS = vercelSandboxCreateOptions({
 // ── Agent-browser PRE-BAKE (the in-sandbox browser plane, OPE-43 — flag-gated) ──
 // When browser.enabled: true with at least one row in the host declaration
 // (agent/access/browser-hosts.ts, registered through lib/register-config.ts) (and only on the
-// Vercel backend), this contributes { revalidationKey, bootstrap } that bake the agent-browser
-// CLI + Chromium into the sandbox TEMPLATE — sessions boot warm, and nothing is ever fetched
-// mid-session (the runtime firewall wouldn't allow it; the vendor tools additionally run with
-// autoInstall bound off). Unarmed it is {} — the definition below carries NO bootstrap /
-// revalidationKey property at all, byte-identical to the pre-capability shape. Rationale +
-// fail-closed matrix live in the adapter (packages/adapters/agent/browser/sandbox.ts).
+// Vercel backend), this bakes the agent-browser CLI + Chromium into the sandbox TEMPLATE —
+// sessions boot warm, and nothing is ever fetched mid-session (the runtime firewall wouldn't allow
+// it; the vendor tools additionally run with autoInstall bound off). Unarmed it is {}, and the
+// environment below carries NO `prepare` at all. Rationale + fail-closed matrix live in the adapter
+// (@open-everywhere/adapters/agent/browser/sandbox.js).
 const AGENT_BROWSER_BAKE = agentBrowserSandboxHooks();
 
-function selfHostBackend() {
+// 🔴 eve 0.69.0 TOOK `revalidationKey` AWAY, AND THE TEMPLATE KEY IS NOW THE ENVIRONMENT'S OWN HASH
+// (OPE-2247). Through 0.68.x the bake contributed `{ revalidationKey, bootstrap }` to the sandbox
+// definition, and bumping the agent-browser pin changed that key, which rebuilt the template. 0.69.0
+// replaced both: setup is the environment's `prepare`, and a template is keyed by
+// `sha256(stableSerialize(environment options))` — which serialises a function by its SOURCE TEXT
+// (`shared/sandbox-environment.js`), not by the values it closes over. So ARMING or DISARMING the
+// bake rebuilds the template (the `prepare` key appears or disappears), and EDITING this file's
+// prepare body rebuilds it, but bumping the agent-browser version alone does NOT: the pin lives
+// inside the vendor installer, behind a closure, where the hash cannot see it. The consequence is a
+// stale warm template after a pin bump, not an unfenced session. Re-deriving a revalidation input the
+// hash can see belongs with the browser plane, not with this port — it is handed to the orchestrator
+// as a follow-up rather than guessed at here, because every field of these options is forwarded to
+// Vercel's own `Sandbox.create`, so inventing a carrier key is a change to the create call.
+const AGENT_BROWSER_PREPARE =
+  AGENT_BROWSER_BAKE.bootstrap === undefined
+    ? {}
+    : {
+        // `installAgentBrowser` reads only `run` off the session it is given, verified in the vendor
+        // bytes: `sandbox.id` appears once in `@agent-browser/eve/dist/sandbox/sandbox.js`, inside
+        // `runAgentBrowser` (the TOOL path), never on the install path. eve 0.69.0's `prepare` hands
+        // over a `SandboxSession`, which carries `run` and no `id` — and `BakeableSandbox.id` is
+        // optional for exactly that reason, so this is a widening to the adapter's own shape rather
+        // than a cast that hides a missing field.
+        prepare: async (sandbox: SandboxSession): Promise<void> => {
+          const bootstrap = AGENT_BROWSER_BAKE.bootstrap;
+          if (bootstrap === undefined) return;
+          await bootstrap({ use: async () => sandbox satisfies BakeableSandbox });
+        },
+      };
+
+// ── The three provider ENVIRONMENTS (eve 0.64.0 + 0.66.0 shape) ──
+// eve replaced the object-form `defineSandbox({ backend, … })` with environments a selector opens.
+// The environment is also the capability carrier: only a Vercel session takes a full
+// `SandboxNetworkPolicy`, Docker takes the coarse `"allow-all"` / `"deny-all"` alone, and just-bash
+// takes none because its policy is fixed at creation. Core's firewall sites reach whichever one is
+// live through `registerSandboxFirewall` below, because they cannot import this file.
+const VERCEL_ENVIRONMENT = VercelSandbox.environment({ ...VERCEL_CREATE_OPTIONS, ...AGENT_BROWSER_PREPARE });
+
+interface SelfHostSandbox {
+  readonly kind: SelfHostBackendKind;
+  /** The environment itself, for the named `environment` export eve's compiler requires. */
+  readonly environment: SandboxEnvironment<object | undefined, SandboxSession>;
+  /** Opening is a closure because each provider's open options differ, and the union of two
+   *  environments has no callable `open` signature. */
+  readonly open: () => Promise<RuntimeSandboxSession>;
+}
+
+function selfHostEnvironment(): SelfHostSandbox {
   // Fail-loud selection: unknown OE_SANDBOX_BACKEND throws here at boot (never a silent fallback).
   const kind = resolveSelfHostBackendKind();
   const bootLog = selfHostBackendBootLog(kind);
   if (bootLog.warn !== undefined) console.warn(bootLog.warn);
-  console.info(bootLog.info); // chosen backend, one info line either way (ids only)
-  // Surface the egress POSTURE at boot too (off-Vercel only): otherwise a "no proxy, no escape
-  // hatch" deployment looks healthy until the first wake, when every session silently aborts.
+  console.info(bootLog.info);
+  // ── EGRESS POSTURE (self-host only) ──
   const egressLog = selfHostEgressBootLog();
   if (egressLog.warn !== undefined) console.warn(egressLog.warn);
   console.info(egressLog.info);
@@ -176,67 +224,73 @@ function selfHostBackend() {
   // readable file (the compose stack mounts one; a bare self-host run does not), and the timer is
   // unref'd, so nothing about this can keep a process alive or take one down.
   startEgressDenialPoller();
-  if (kind === "justbash") return justbash();
+  if (kind === "justbash") {
+    const environment = JustBashSandbox.environment({});
+    registerSandboxFirewall({ carries: "none", backend: "justbash" });
+    return { kind, environment, open: async () => await environment.open() };
+  }
   const image = getSettings().sandbox.image;
-  return docker(image ? { image } : {});
+  const environment = image ? DockerSandbox.environment({ image }) : DockerSandbox.environment({});
+  registerSandboxFirewall({ carries: "coarse", environment });
+  return { kind, environment, open: async () => await environment.open() };
 }
 
-export default defineSandbox({
-  backend: ON_VERCEL ? vercel(VERCEL_CREATE_OPTIONS) : selfHostBackend(),
-  ...AGENT_BROWSER_BAKE,
+// Resolved at module load, exactly as the backend ternary was: one boot decision, one set of logs,
+// and the registration core's firewall sites read must be in place before the first turn.
+const SELF_HOST = ON_VERCEL ? undefined : selfHostEnvironment();
+if (ON_VERCEL) registerSandboxFirewall({ carries: "full", environment: VERCEL_ENVIRONMENT });
+
+/**
+ * The environment eve's COMPILER reads, and it must be exactly one (`compiler/normalize-sandbox.js`:
+ * "Sandbox must export an environment"). eve records its `provider` name and this export's name in
+ * the compiled binding, so the built app is specialised to the backend resolved HERE, at module load —
+ * which is what the old `backend:` ternary already did, so nothing about that is new. The selector
+ * below opens the same environment; this export is how the build learns which provider that is.
+ */
+export const environment: SandboxEnvironment<object | undefined, SandboxSession> =
+  SELF_HOST === undefined ? (VERCEL_ENVIRONMENT as SandboxEnvironment<object | undefined, SandboxSession>) : SELF_HOST.environment;
+
+export default defineSandbox(async (context) => {
   // ── Per-domain/role sandbox SIZING (item 26 stretch) ──
   // A domain (or the role preset it adopts) may declare `sandbox: { vcpus: N }`
-  // (core memory/domain.ts SandboxPreset); this hook applies it to the live session —
-  // eve forwards `use({ resources })` to the Vercel SDK's Sandbox.update, so the size
-  // change lands on the session VM. FAIL-OPEN end to end (sizing is a tuning knob, the
-  // turn must never die for it): identity/config resolution errors → default size; an
-  // update rejection retries a bare use(). NB Sandbox.update applies `resources` on the
-  // session, so a preset takes effect per-session (stop-after-turn recycles sessions
-  // every turn, so in practice the next turn after a config change).
-  onSession: async ({ ctx, use }) => {
-    // Per-session vcpu sizing is a Vercel-only knob (it forwards to Sandbox.update).
-    // justbash()/docker() don't honor `resources` — open straight through.
-    if (!ON_VERCEL) {
-      await use();
-      return;
-    }
-    // With the backend now a union (vercel | justbash | docker), `use`'s param type
-    // narrows to the intersection (no `resources`); but this branch only runs on Vercel,
-    // whose backend DOES accept `{ resources }`. Type the sized open explicitly. The resolved
-    // session's `.id` is eve's own session key — see created-sandbox-registry.ts for why that is
-    // the same value the Vercel binding names the sandbox with.
-    const useSized = use as unknown as (options?: { resources: { vcpus: number } }) => Promise<{ id: string }>;
-    let options: { resources: { vcpus: number } } | undefined;
-    try {
-      // SessionContext structurally satisfies BindableContext (session.auth carries the
-      // platform attributes); a ctx with no resolvable identity falls through the
-      // binding bridge or resolves no domain — either way: no preset, default size.
-      const bindable = ctx as BindableContext;
-      const preset = sandboxPresetFor(bindFrom(bindable), resolvePartition(bindable), getConfig().loadDomains());
-      const vcpus = preset?.vcpus;
-      if (typeof vcpus === "number" && Number.isFinite(vcpus) && vcpus > 0) {
-        options = { resources: { vcpus: Math.floor(vcpus) } };
-      }
-    } catch (err) {
-      console.warn(`[open-everywhere:sandbox] vcpus preset resolution failed — using default size (${String(err)})`);
-    }
-    // OPE-722: record the ACTUAL vendor sandbox name eve just opened for this session, so the
-    // turn-end stop hook (backend-stop.ts) can find it directly instead of depending on
-    // Sandbox.list's tag index for a sandbox THIS turn just created — a hardening against the
-    // same-turn creation race OPE-722 reported, regardless of whether the vendor's tag index is
-    // ever actually stale (see backend-stop.ts's createVercelList doc comment for the full
-    // account). `recordCreatedSandbox` is documented to never throw, so no extra try/catch layer
-    // is needed here — it fails as loud as `recordCreatedSandbox`'s own contract allows.
-    const record = (session: { id: string }): void => recordCreatedSandbox(ctx.session.id, session.id);
-    try {
-      record(await useSized(options));
-    } catch (err) {
-      // The sized open failed (e.g. the update was rejected for this plan/region):
-      // fall back to the default size rather than blocking the turn. A bare use()
-      // failure is a real sandbox outage — let that one propagate.
-      if (options === undefined) throw err;
-      console.warn(`[open-everywhere:sandbox] applying vcpus=${options.resources.vcpus} failed — retrying default size (${String(err)})`);
-      record(await useSized());
+  // (core memory/domain.ts SandboxPreset); this selector applies it when it opens the session —
+  // eve forwards `resources` to the Vercel SDK's create/update, so the size change lands on the
+  // session VM. FAIL-OPEN end to end (sizing is a tuning knob, the turn must never die for it):
+  // identity/config resolution errors → default size; a rejected sized open retries unsized.
+  // Per-session vcpu sizing is a Vercel-only knob, so every other backend opens straight through.
+  if (SELF_HOST !== undefined) return await SELF_HOST.open();
+  let options: { resources: { vcpus: number } } | undefined;
+  try {
+    // SandboxSelectorContext structurally satisfies BindableContext (session.auth carries the
+    // platform attributes); a context with no resolvable identity falls through the binding bridge
+    // or resolves no domain — either way: no preset, default size.
+    const bindable = context as unknown as BindableContext;
+    const preset = sandboxPresetFor(bindFrom(bindable), resolvePartition(bindable), getConfig().loadDomains());
+    const vcpus = preset?.vcpus;
+    if (typeof vcpus === "number" && Number.isFinite(vcpus) && vcpus > 0) {
+      options = { resources: { vcpus: Math.floor(vcpus) } };
     }
-  },
+  } catch (err) {
+    console.warn(`[open-everywhere:sandbox] vcpus preset resolution failed — using default size (${String(err)})`);
+  }
+  // 🔴 OPE-722's CREATED-SANDBOX RECORD IS GONE, BECAUSE eve 0.69.0 NO LONGER EXPOSES THE NAME
+  // (OPE-2247). The old `onSession` hook's `use()` resolved to an object carrying `.id` — the vendor
+  // sandbox name — and this file recorded it so the turn-end stop hook could reach the sandbox with a
+  // primary-key `Sandbox.get` rather than `Sandbox.list`'s tag index. On 0.69.0 neither
+  // `SandboxSession` nor `RuntimeSandboxSession` carries an `id`, so there is nothing to record and no
+  // authored surface that can learn it. The stop hook degrades to exactly the pre-OPE-722 path:
+  // `created-sandbox-registry.ts` documents an absent record as "falls back to the vendor's tag
+  // index, exactly as before this fix", so stop-after-turn still works and the narrow create-then-stop
+  // race OPE-722 hardened against is open again. Re-deriving a name the hook can use is handed to the
+  // orchestrator as a follow-up; it is not guessable from these bytes.
+  if (options === undefined) return await VERCEL_ENVIRONMENT.open();
+  try {
+    return await VERCEL_ENVIRONMENT.open(options);
+  } catch (err) {
+    // The sized open failed (e.g. the size was rejected for this plan/region): fall back to the
+    // default size rather than blocking the turn. A bare open() failure is a real sandbox outage —
+    // that one propagates, from the call below.
+    console.warn(`[open-everywhere:sandbox] applying vcpus=${options.resources.vcpus} failed — retrying default size (${String(err)})`);
+    return await VERCEL_ENVIRONMENT.open();
+  }
 });