@open-everywhere/adapters 0.1.0

package/agent/sandbox/vercel-lifecycle.ts

@@ -0,0 +1,252 @@
+// Stop-after-turn sandbox lifecycle — this file owns the DECISION, backend-stop.ts the mechanics. It exists
+// because a session VM is billed for its whole idle tail; every failure is fail-soft to the `timeout` fuse.
+
+import { defineHook, type HookContext } from "eve/hooks";
+import { bindFrom, domainKeyOf, resolvePartition, appendUsageEvent, usageForSession, recordSpend, periodOf, estimateSandboxCostUsd, routineIdOf, turnSurfaceMode, getSettings, isSubagentChildContext, liveTaskIds, subagentParentSessionId, type BindableContext } from "@open-everywhere/core/agent/adapter-api.js";
+import { resolveSandboxStopper, shouldStop, type SandboxListing, type SandboxStopper } from "./backend-stop.js";
+
+// Re-exported so the one "is this sandbox up?" predicate and the one listing shape stay
+// single-homed in backend-stop.ts while their existing import sites keep working
+// (extend-workspace-time.ts, the lifecycle tests).
+export { shouldStop, type SandboxListing, type SandboxStopper };
+
+function log(msg: string): void {
+  console.log(`[open-everywhere:sandbox-lifecycle] ${msg}`);
+}
+
+/** On by default (the `sandbox.stopAfterTurn` setting, OPE-371); declare
+ *  `sandbox: { stopAfterTurn: false }` in `agent/settings.ts`, or set the
+ *  `sandbox.stopAfterTurn` ops override, to keep sandboxes alive between turns. */
+export function stopAfterTurnEnabled(): boolean {
+  return getSettings().sandbox.stopAfterTurn;
+}
+
+/** One sandbox this sweep actually stopped, with its honestly-observed runtime window. */
+export interface StoppedSandbox {
+  readonly name: string;
+  readonly sandboxSeconds: number;
+}
+
+/**
+ * Stop every running sandbox tagged with this session. Fail-soft per sandbox — a straggler falls back to the
+ * timeout fuse. The window is measured from `createdAt`, which does NOT advance across a stop and auto-resume,
+ * so this reports the CUMULATIVE window and the billing below takes the delta.
+ */
+export async function stopSessionSandboxes(
+  sessionId: string,
+  stopper: SandboxStopper = resolveSandboxStopper(),
+  now: () => number = Date.now,
+): Promise<StoppedSandbox[]> {
+  const stopped: StoppedSandbox[] = [];
+  const sandboxes = await stopper.list(sessionId);
+  for (const s of sandboxes) {
+    if (!shouldStop(s.status)) continue;
+    try {
+      await stopper.stop(s.name);
+      const sandboxSeconds = Math.max(0, (now() - s.createdAt) / 1000);
+      stopped.push({ name: s.name, sandboxSeconds });
+    } catch (err) {
+      log(`stop of "${s.name}" failed (falls back to the timeout fuse): ${String(err)}`);
+    }
+  }
+  return stopped;
+}
+
+/**
+ * The second half of the child guard: hand the shared sandbox back to the parent, so the parent's own sweep
+ * finds it. A backend that never re-tags answers an empty result — a correct outcome, not a failure.
+ */
+export async function restoreParentSandboxTag(ctx: HookContext, stopper: SandboxStopper): Promise<string[]> {
+  const parentSessionId = subagentParentSessionId(ctx as unknown as BindableContext);
+  // No typed linkage (eve does not expose `session.parent` in every child shape) ⇒ nothing to
+  // restore the tag TO. Skipping the stop is still correct and is the half that matters.
+  if (parentSessionId === undefined) return [];
+  const restored: string[] = [];
+  for (const s of await stopper.list(ctx.session.id)) {
+    try {
+      if (await stopper.retag(s.name, parentSessionId)) restored.push(s.name);
+    } catch (err) {
+      log(`re-tag of "${s.name}" back to parent session failed (the parent reclaims it on its next sandbox use): ${String(err)}`);
+    }
+  }
+  return restored;
+}
+
+/** Name the owning backend once per process, at the first turn end. An operator must be able to
+ *  tell from the deployment which backend stops the sandbox — or that none does. */
+let ownershipLogged = false;
+function logStopOwnershipOnce(stopper: SandboxStopper): void {
+  if (ownershipLogged) return;
+  ownershipLogged = true;
+  log(stopper.ownership);
+}
+
+/** Test seam: forget that the ownership line was already logged. */
+export function resetStopOwnershipLogForTest(): void {
+  ownershipLogged = false;
+}
+
+/**
+ * WHICH delegated background tasks this session believes still hold its sandbox. Non-empty ⇒ this turn end
+ * must not stop the VM. A read, never a write, and fail-soft to EMPTY.
+ */
+export function liveDelegatedTasksHoldingSandbox(): readonly string[] {
+  try {
+    return liveTaskIds();
+  } catch {
+    return [];
+  }
+}
+
+async function onTurnEnd(ctx: HookContext, outcome: string): Promise<void> {
+  if (!stopAfterTurnEnabled()) return;
+  try {
+    const stopper = resolveSandboxStopper();
+    logStopOwnershipOnce(stopper);
+    // 🔴 OPE-447 — a delegated child shares the PARENT's sandbox and must not stop it.
+    if (isSubagentChildContext(ctx as unknown as BindableContext)) {
+      const restored = await restoreParentSandboxTag(ctx, stopper);
+      log(
+        `turn.${outcome}: SKIPPED the stop — this is an eve subagent child and the parent owns the shared sandbox` +
+          (restored.length > 0 ? `; handed ${restored.join(", ")} back to the parent session` : ""),
+      );
+      return;
+    }
+    // 🔴 OPE-595 — a live BACKGROUND child holds this session's VM after this turn ends.
+    // See the file header for the measurement and for why the skip cannot leak a VM.
+    const holding = liveDelegatedTasksHoldingSandbox();
+    if (holding.length > 0) {
+      log(
+        `turn.${outcome}: SKIPPED the stop — ${holding.length} delegated background task(s) still hold this session's sandbox ` +
+          `[${holding.join(", ")}]; the next turn end that finds none sweeps it`,
+      );
+      return;
+    }
+    const stopped = await stopSessionSandboxes(ctx.session.id, stopper);
+    if (stopped.length > 0) {
+      log(`turn.${outcome}: stopped ${stopped.map((s) => s.name).join(", ")} (auto-snapshot; next turn auto-resumes)`);
+      // Only a backend that bills runtime by wall clock gets a spend row. Pricing a self-hosted
+      // container at Vercel's GB-hour rate would invent a charge that the USD caps then enforce.
+      if (stopper.metered) await recordSandboxUsage(ctx, stopped);
+    }
+  } catch (err) {
+    // Listing failed (no credentials locally, transient API error, …) — the sandbox
+    // just idles out its timeout fuse, exactly the pre-hook behaviour.
+    log(`turn.${outcome}: sandbox stop skipped: ${String(err)}`);
+  }
+}
+
+/**
+ * Record each stopped sandbox's runtime in BOTH spend stores, best-effort. ORDER IS LOAD-BEARING: the ledger
+ * row goes FIRST and the watermark only once it succeeds, so a failure re-bills instead of under-billing.
+ */
+export async function recordSandboxUsage(ctx: HookContext, stopped: StoppedSandbox[]): Promise<void> {
+  try {
+    const p = resolvePartition(ctx);
+    // ATTRIBUTION (OPE-275) — the SAME derivations core's hooks/spend.ts stamps on the session's
+    // model rows: the ATTRIBUTED principal (a routine fire binds as its attested creator, a
+    // delegated child carries its parent's) and the dispatcher's routine marker. Before this the
+    // sandbox row wrote both as '' — so a person's delegated sandbox dollars were invisible to
+    // their `perUser` budget (surface/workspace caps caught them; the person axis did not), and a
+    // routine's reported cost excluded exactly its compute. Both reads are fail-soft: an unusual
+    // ctx degrades to an unattributed row, which is what the row always was.
+    const principalId = bindFrom(ctx).principalId;
+    const routineId = routineIdOf(ctx);
+    // OPE-1862 — the conversation's own mode, stamped on both rows below exactly as core's
+    // hooks/spend.ts stamps it on a model call. Without it a sandbox row is UNCLASSIFIED, and a
+    // report then masks the surface key it names rather than publish one it cannot classify.
+    const surfaceMode = turnSurfaceMode(ctx);
+    // The DELTA watermark (finding 4): the seconds already billed for each sandbox this session
+    // are the SUM of its prior "sandbox" usage_events deltas — the durable per-session stamp that
+    // survives a fresh serverless instance per turn. Read once; a failure leaves it empty, so the
+    // full cumulative is billed (today's overestimate), never dropped — the safe direction.
+    const priorBilled = new Map<string, number>();
+    try {
+      for (const e of await usageForSession(p.org, ctx.session.id)) {
+        if (e.kind !== "sandbox") continue;
+        const name = e.detail?.sandboxName;
+        if (typeof name !== "string") continue;
+        const secs = typeof e.detail?.sandboxSeconds === "number" ? e.detail.sandboxSeconds : 0;
+        priorBilled.set(name, (priorBilled.get(name) ?? 0) + secs);
+      }
+    } catch (err) {
+      log(`prior sandbox usage read skipped (billing the full window): ${String(err)}`);
+    }
+    // Dedupe by name: if `stopped` ever carries the same sandbox twice in one call (a
+    // list()/stop() quirk upstream), processing both entries would read the SAME
+    // priorBilled value for each and double-bill the delta. Keep the first occurrence.
+    const seenNames = new Set<string>();
+    const dedupedStopped = stopped.filter((s) => {
+      if (seenNames.has(s.name)) return false;
+      seenNames.add(s.name);
+      return true;
+    });
+    for (const s of dedupedStopped) {
+      // `s.sandboxSeconds` is the CUMULATIVE window since createdAt; bill only the increment
+      // since this sandbox's last stop (clamped ≥ 0: a sandbox recreated mid-session, finding 5,
+      // resets createdAt below the prior sum → 0 for that window, never negative).
+      const billedSeconds = Math.max(0, Math.round(s.sandboxSeconds) - (priorBilled.get(s.name) ?? 0));
+      // THE LEDGER WRITE FIRST (see the doc comment above for why the order flipped).
+      try {
+        await recordSpend(p, {
+          period: periodOf(new Date().toISOString()),
+          usage: {},
+          principalId,
+          routineId,
+          model: "",
+          ...(surfaceMode !== undefined ? { surfaceMode } : {}),
+          // Explicit usdMicros: runtime spend has no (model, tokens) key that could
+          // express it — this is the case that forced write-time pricing (OPE-265/266).
+          usdMicros: Math.round(estimateSandboxCostUsd(billedSeconds) * 1_000_000),
+        });
+      } catch (err) {
+        log(`sandbox spend-ledger record skipped for "${s.name}" (watermark NOT advanced — this window re-bills next stop): ${String(err)}`);
+        continue;
+      }
+      // The watermark: only reached once the ledger write above actually landed, so a
+      // future priorBilled sum never marks seconds "billed" that no ledger row backs.
+      try {
+        await appendUsageEvent({
+          org: p.org,
+          // SPEND grain (domainKeyOf), matching core's hooks/spend.ts: a Discord thread's
+          // sandbox seconds bill against its PARENT channel's scope (item 22); the domain
+          // key IS the surfaceKey everywhere else.
+          surfaceKey: domainKeyOf(p),
+          sessionId: ctx.session.id,
+          kind: "sandbox",
+          ...(surfaceMode !== undefined ? { surfaceMode } : {}),
+          principalId,
+          ...(routineId !== undefined ? { routineId } : {}),
+          inputTokens: 0,
+          outputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
+          // The DELTA (not the cumulative) — so the next stop's watermark sum telescopes to the
+          // true lifetime, and a session_cost view that SUMS these rows is correct rather than
+          // over-counting (which the old cumulative-per-row write silently did).
+          detail: { sandboxSeconds: billedSeconds, sandboxName: s.name },
+        });
+      } catch (err) {
+        // The ledger row above already landed — only the watermark/forensics row is missing.
+        // A future stop's priorBilled sum under-counts by this delta, so it re-bills this
+        // window too: a double-bill, but over-billing is this file's chosen safe direction.
+        log(`sandbox usage-event append skipped for "${s.name}" (watermark not advanced; a future stop may re-bill this window): ${String(err)}`);
+      }
+    }
+  } catch (err) {
+    log(`sandbox usage records skipped (no resolvable partition): ${String(err)}`);
+  }
+}
+
+export default defineHook({
+  events: {
+    // Turn boundaries are the signal: the reply has been sent, nothing is using the VM.
+    "turn.completed": async (_event, ctx) => onTurnEnd(ctx, "completed"),
+    "turn.failed": async (_event, ctx) => onTurnEnd(ctx, "failed"),
+    // Completing sessions (routines, one-shots) end with session.* — a final sweep. If
+    // another session-end hook (memory persist) touches the sandbox after us it simply
+    // auto-resumes and the leftover falls back to the fuse: no correctness impact.
+    "session.completed": async (_event, ctx) => onTurnEnd(ctx, "session-completed"),
+    "session.failed": async (_event, ctx) => onTurnEnd(ctx, "session-failed"),
+  },
+});

package/dist/agent/aws/cli.d.ts

@@ -0,0 +1,24 @@
+import type { AwsExecResult, AwsExecutor } from "@open-everywhere/core/agent/adapter-api.js";
+export interface AwsExecInvocation {
+    /** The binary to launch (default "aws"). */
+    readonly file: string;
+    /** Argv AFTER the binary (creds are NEVER here). */
+    readonly args: readonly string[];
+    /** The child's full environment, with creds + region injected and ambient AWS identity stripped. */
+    readonly env: NodeJS.ProcessEnv;
+}
+/** A runner resolves with the captured outcome (ANY exit code) and REJECTS only on a launch failure —
+ *  the DI seam the offline test injects to assert env/argv without running `aws`. */
+export type AwsRunner = (inv: AwsExecInvocation) => Promise<AwsExecResult>;
+/** Construction options — DI seams for the offline test; each has a real default. */
+export interface AwsCliExecutorOptions {
+    /** The invocation runner. Default: a `node:child_process.execFile` wrapper. */
+    readonly run?: AwsRunner;
+    /** The AWS CLI binary name/path. Default "aws". */
+    readonly binary?: string;
+    /** Operator default region (OE_AWS_REGION) applied when the resolved identity names none, so the
+     *  CLI runs in the same region STS minted for. */
+    readonly defaultRegion?: string;
+}
+export declare function makeAwsCliExecutor(opts?: AwsCliExecutorOptions): AwsExecutor;
+//# sourceMappingURL=cli.d.ts.map

package/dist/agent/aws/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../agent/aws/cli.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAkC,aAAa,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAC;AAE7H,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,oGAAoG;IACpG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED;qFACqF;AACrF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE3E,qFAAqF;AACrF,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;sDACkD;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAoED,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,qBAA0B,GAAG,WAAW,CAwBhF"}

package/dist/agent/aws/cli.js

@@ -0,0 +1,89 @@
+// The AWS-EXECUTOR adapter — the ONE place the `aws` binary is spawned. Credentials go in the child ENV,
+// never on argv, and that env is DENY-BY-DEFAULT. A non-zero exit returns; only a launch failure throws.
+import { execFile } from "node:child_process";
+/** Default runner — `execFile` the CLI, capturing stdout/stderr/exit. Resolves for every exit code
+ *  (non-zero included); rejects ONLY when the process could not be launched (ENOENT etc.). */
+const defaultRunner = (inv) => new Promise((resolve, reject) => {
+    execFile(inv.file, [...inv.args], { env: inv.env, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+        if (err) {
+            const code = err.code;
+            // execFile sets a NUMBER `code` for a non-zero exit, a STRING errno (e.g. "ENOENT") for a
+            // launch failure. Return the former; reject the latter.
+            if (typeof code === "number") {
+                resolve({ exitCode: code, stdout: String(stdout), stderr: String(stderr) });
+                return;
+            }
+            reject(err);
+            return;
+        }
+        resolve({ exitCode: 0, stdout: String(stdout), stderr: String(stderr) });
+    });
+});
+/**
+ * The ONLY parent-env keys the child inherits — deny-by-default. The framework process's environment holds
+ * the deployment's real secrets, and this child's argv is model-controlled.
+ */
+const CHILD_ENV_PASSTHROUGH = [
+    "PATH",
+    "HOME",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "LANG",
+    "TZ",
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "NO_PROXY",
+    "https_proxy",
+    "http_proxy",
+    "no_proxy",
+];
+/** Build the child env DENY-BY-DEFAULT: the enumerated pass-through + LC_* locale keys, the
+ *  injected temp creds + region, config/credential files pinned to /dev/null, IMDS disabled —
+ *  so the injected creds are the ONLY identity the CLI can resolve, from any source. */
+function childEnv(credentials, region) {
+    const env = {};
+    for (const k of CHILD_ENV_PASSTHROUGH) {
+        if (process.env[k] !== undefined)
+            env[k] = process.env[k];
+    }
+    for (const k of Object.keys(process.env)) {
+        if (k.startsWith("LC_"))
+            env[k] = process.env[k];
+    }
+    // No on-host profile/credential/config file is ever readable, whatever the box carries.
+    env.AWS_CONFIG_FILE = "/dev/null";
+    env.AWS_SHARED_CREDENTIALS_FILE = "/dev/null";
+    // No instance-metadata fallback: a cloud host's IMDS role must never answer for the CLI.
+    env.AWS_EC2_METADATA_DISABLED = "true";
+    env.AWS_ACCESS_KEY_ID = credentials.accessKeyId;
+    env.AWS_SECRET_ACCESS_KEY = credentials.secretAccessKey;
+    env.AWS_SESSION_TOKEN = credentials.sessionToken;
+    if (region) {
+        env.AWS_REGION = region;
+        env.AWS_DEFAULT_REGION = region;
+    }
+    return env;
+}
+export function makeAwsCliExecutor(opts = {}) {
+    const runner = opts.run ?? defaultRunner;
+    const binary = opts.binary ?? "aws";
+    const defaultRegion = opts.defaultRegion;
+    return {
+        async run(req) {
+            const inv = {
+                file: binary,
+                args: req.args,
+                env: childEnv(req.credentials, req.region ?? defaultRegion),
+            };
+            try {
+                return await runner(inv);
+            }
+            catch (err) {
+                // A rejection here means the process never launched (the runner returns non-zero exits).
+                throw new Error(`failed to launch the AWS CLI ("${binary}") — is it installed and on PATH? ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=cli.js.map

package/dist/agent/aws/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../agent/aws/cli.ts"],"names":[],"mappings":"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"}

package/dist/agent/aws/config.d.ts

@@ -0,0 +1,27 @@
+/** Truthiness for the master flag — same off-spellings as the other connector-plane flags (default
+ *  OFF: off is the inert posture; arming is a deliberate operator act). */
+export declare function awsAccessEnabled(): boolean;
+/** The AWS-access config block (env-sourced). Only a default region today; the identity/executor DI
+ *  seams are passed by the caller (register.ts), not env. */
+export interface AwsAccessConfig {
+    /** Default region applied when a role grant names none. STS itself further falls back to
+     *  `AWS_REGION` then `us-east-1` (sts.ts), so this is purely the operator's override. */
+    readonly defaultRegion?: string;
+}
+/** Load the AWS-access config block from env. Always returns a (possibly empty) config — unlike the
+ *  oe-oauth block there is no REQUIRED field, so the master flag alone gates arming. */
+export declare function loadAwsAccessConfig(): AwsAccessConfig;
+/** The Identity Center (SSO) link config block (env-sourced). Every field is optional here — the
+ *  minter fails closed with an actionable message at LINK time if a piece the link flow needs (region,
+ *  client id) is missing, so arming the master flag never requires SSO to be configured. */
+export interface AwsSsoConfig {
+    /** Identity Center region for the OIDC + portal endpoints. Undefined ⇒ fall back to the default. */
+    readonly region?: string;
+    /** The public PKCE OIDC client id for the link flow. Undefined ⇒ the link flow fails closed loudly. */
+    readonly clientId?: string;
+    /** OAuth scopes requested on the link (default applied by the minter). */
+    readonly scopes?: readonly string[];
+}
+/** Load the Identity Center SSO link config from env. Region falls back to the general AWS default. */
+export declare function loadAwsSsoConfig(): AwsSsoConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/agent/aws/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../agent/aws/config.ts"],"names":[],"mappings":"AAmBA;2EAC2E;AAC3E,wBAAgB,gBAAgB,IAAI,OAAO,CAK1C;AAED;6DAC6D;AAC7D,MAAM,WAAW,eAAe;IAC9B;6FACyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;wFACwF;AACxF,wBAAgB,mBAAmB,IAAI,eAAe,CAGrD;AAED;;4FAE4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,uGAAuG;AACvG,wBAAgB,gBAAgB,IAAI,YAAY,CAc/C"}

package/dist/agent/aws/config.js

@@ -0,0 +1,46 @@
+// The `aws` access master arming flag and config block. Flag-off ⇒ NOTHING registers and core's AWS paths
+// fail closed, with no fallback. Config is env-sourced at the adapter boundary, like DATABASE_URL.
+/** The master arming flag env var — one string this module's readers share. */
+const OE_AWS_ENABLED_ENV = "OE_AWS_ENABLED";
+/** Optional default region for STS + the CLI when a grant names none. */
+const OE_AWS_REGION_ENV = "OE_AWS_REGION";
+// The per-user Identity Center link config. These vars configure the LINK flow only — a mint needs the
+// region and the stored token. NO secrets here: the OIDC client is a PUBLIC PKCE client.
+/** The Identity Center region (where oidc.<region>.amazonaws.com + portal.sso.<region>.amazonaws.com
+ *  live). Falls back to the general default region ({@link OE_AWS_REGION_ENV} / AWS_REGION). */
+const OE_AWS_SSO_REGION_ENV = "OE_AWS_SSO_REGION";
+/** The pre-registered PUBLIC OIDC client id for the Identity Center auth-code + PKCE link flow. */
+const OE_AWS_SSO_CLIENT_ID_ENV = "OE_AWS_SSO_CLIENT_ID";
+/** Optional space-separated OAuth scopes for the link (default "sso:account:access"). */
+const OE_AWS_SSO_SCOPES_ENV = "OE_AWS_SSO_SCOPES";
+/** Truthiness for the master flag — same off-spellings as the other connector-plane flags (default
+ *  OFF: off is the inert posture; arming is a deliberate operator act). */
+export function awsAccessEnabled() {
+    const raw = process.env[OE_AWS_ENABLED_ENV];
+    if (raw === undefined)
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false" && v !== "off" && v !== "no";
+}
+/** Load the AWS-access config block from env. Always returns a (possibly empty) config — unlike the
+ *  oe-oauth block there is no REQUIRED field, so the master flag alone gates arming. */
+export function loadAwsAccessConfig() {
+    const defaultRegion = process.env[OE_AWS_REGION_ENV]?.trim() || process.env.AWS_REGION?.trim();
+    return { ...(defaultRegion ? { defaultRegion } : {}) };
+}
+/** Load the Identity Center SSO link config from env. Region falls back to the general AWS default. */
+export function loadAwsSsoConfig() {
+    const region = process.env[OE_AWS_SSO_REGION_ENV]?.trim() ||
+        process.env[OE_AWS_REGION_ENV]?.trim() ||
+        process.env.AWS_REGION?.trim();
+    const clientId = process.env[OE_AWS_SSO_CLIENT_ID_ENV]?.trim();
+    const scopes = process.env[OE_AWS_SSO_SCOPES_ENV]?.trim()
+        ? process.env[OE_AWS_SSO_SCOPES_ENV].trim().split(/\s+/u).filter(Boolean)
+        : undefined;
+    return {
+        ...(region ? { region } : {}),
+        ...(clientId ? { clientId } : {}),
+        ...(scopes && scopes.length ? { scopes } : {}),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/agent/aws/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../agent/aws/config.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,mGAAmG;AAEnG,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAC5C,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAE1C,uGAAuG;AACvG,yFAAyF;AAEzF;gGACgG;AAChG,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAClD,mGAAmG;AACnG,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AACxD,yFAAyF;AACzF,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAElD;2EAC2E;AAC3E,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;AAC7E,CAAC;AAUD;wFACwF;AACxF,MAAM,UAAU,mBAAmB;IACjC,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/F,OAAO,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACzD,CAAC;AAcD,uGAAuG;AACvG,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GACV,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE;QAC1C,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE;QACtC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE,IAAI,EAAE,CAAC;IAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE;QACvD,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QAC1E,CAAC,CAAC,SAAS,CAAC;IACd,OAAO;QACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC"}

package/dist/agent/aws/register.d.ts

@@ -0,0 +1,23 @@
+import { type AwsIdentityProvider, type AwsExecutor } from "@open-everywhere/core/agent/adapter-api.js";
+import { type AwsStsProviderOptions } from "./sts.js";
+import { type AwsCliExecutorOptions } from "./cli.js";
+import { type AwsSsoMinter, type AwsSsoMinterOptions } from "./sso.js";
+/** Registration input — the DI seams for tests (the boot call passes none). */
+export interface RegisterAwsAccessOptions {
+    /** STS identity-provider seams (injectable fetch + token-file reader). */
+    readonly identity?: AwsStsProviderOptions;
+    /** CLI executor seams (injectable runner + binary). */
+    readonly executor?: AwsCliExecutorOptions;
+    /** Identity Center (SSO) minter seams (injectable fetch + stores + config). */
+    readonly sso?: AwsSsoMinterOptions;
+}
+/**
+ * Construct the STS provider (with its delegated SSO minter), the `aws` CLI executor and the per-principal
+ * link store, and register all three for core lookup. Idempotent overwrite in the registries — last wins.
+ */
+export declare function registerAwsAccess(opts?: RegisterAwsAccessOptions): {
+    provider: AwsIdentityProvider;
+    executor: AwsExecutor;
+    sso: AwsSsoMinter;
+};
+//# sourceMappingURL=register.d.ts.map

package/dist/agent/aws/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../agent/aws/register.ts"],"names":[],"mappings":"AAGA,OAAO,EAML,KAAK,mBAAmB,EACxB,KAAK,WAAW,EACjB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAA8D,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAGnI,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IAC1C,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,wBAA6B,GAAG;IACtE,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,WAAW,CAAC;IACtB,GAAG,EAAE,YAAY,CAAC;CACnB,CA6BA"}

package/dist/agent/aws/register.js

@@ -0,0 +1,39 @@
+// Register the AWS-access layer, called only when the OE_AWS_ENABLED master flag is armed. Flag-off ⇒
+// nothing registers and core's AWS mint, exec and link paths fail closed; rollback is not arming the flag.
+import { registerAwsIdentityProvider, registerAwsExecutor, registerAwsSsoLinkStore, registerAwsSsoCallbackCompleter, registerCredentialPurgeHook, } from "@open-everywhere/core/agent/adapter-api.js";
+import { makeAwsStsProvider } from "./sts.js";
+import { makeAwsCliExecutor } from "./cli.js";
+import { makeAwsSsoMinter, makeAwsSsoLinkStore, makeAwsSsoPurgeHook } from "./sso.js";
+import { loadAwsAccessConfig, loadAwsSsoConfig } from "./config.js";
+/**
+ * Construct the STS provider (with its delegated SSO minter), the `aws` CLI executor and the per-principal
+ * link store, and register all three for core lookup. Idempotent overwrite in the registries — last wins.
+ */
+export function registerAwsAccess(opts = {}) {
+    // The operator's default region (OE_AWS_REGION / AWS_REGION) — applied when a role grant names none,
+    // consistently to both the STS mint and the CLI. Explicit test seams (opts.*) win over it.
+    const { defaultRegion } = loadAwsAccessConfig();
+    const ssoCfg = loadAwsSsoConfig();
+    // Phase 1: the per-principal Identity Center link store (vault-backed) + the SSO minter. Register the
+    // store on core's port FIRST so the minter's requireAwsSsoLinkStore() resolves it.
+    registerAwsSsoLinkStore(makeAwsSsoLinkStore());
+    // The purge hook registers ALONGSIDE the link store: a deployment that can mint per-person AWS credentials
+    // and cannot destroy them on offboarding is the state this closed. Registration is KEYED, so this ADDS.
+    registerCredentialPurgeHook("aws-sso", makeAwsSsoPurgeHook());
+    const sso = makeAwsSsoMinter({
+        ...(ssoCfg.region ? { region: ssoCfg.region } : defaultRegion ? { region: defaultRegion } : {}),
+        ...(ssoCfg.clientId ? { clientId: ssoCfg.clientId } : {}),
+        ...(ssoCfg.scopes ? { scopes: ssoCfg.scopes } : {}),
+        ...opts.sso,
+    });
+    // Wire the `GET OE_AWS_SSO_CALLBACK_PATH` route to the SSO minter's code→token exchange, mirroring the
+    // own-rolled OAuth adapter's registerOeOauthCallbackCompleter. Fires under the OE_AWS_ENABLED boot
+    // guard; flag-off ⇒ the completer is never registered and the route fails closed (generic error page).
+    registerAwsSsoCallbackCompleter({ complete: ({ state, code }) => sso.completeLink(state, code) });
+    const provider = makeAwsStsProvider({ defaultRegion, mintUserSso: (req) => sso.mint(req), ...opts.identity });
+    const executor = makeAwsCliExecutor({ defaultRegion, ...opts.executor });
+    registerAwsIdentityProvider(provider);
+    registerAwsExecutor(executor);
+    return { provider, executor, sso };
+}
+//# sourceMappingURL=register.js.map

package/dist/agent/aws/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../agent/aws/register.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,2GAA2G;AAE3G,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,EACvB,+BAA+B,EAC/B,2BAA2B,GAG5B,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAA8B,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAA8B,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAA+C,MAAM,UAAU,CAAC;AACnI,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAYpE;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAA6B,EAAE;IAKnE,qGAAqG;IACrG,2FAA2F;IAC3F,MAAM,EAAE,aAAa,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAElC,sGAAsG;IACtG,mFAAmF;IACnF,uBAAuB,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC/C,2GAA2G;IAC3G,wGAAwG;IACxG,2BAA2B,CAAC,SAAS,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,gBAAgB,CAAC;QAC3B,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/F,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,IAAI,CAAC,GAAG;KACZ,CAAC,CAAC;IAEH,uGAAuG;IACvG,mGAAmG;IACnG,uGAAuG;IACvG,+BAA+B,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAElG,MAAM,QAAQ,GAAG,kBAAkB,CAAC,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9G,MAAM,QAAQ,GAAG,kBAAkB,CAAC,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzE,2BAA2B,CAAC,QAAQ,CAAC,CAAC;IACtC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC9B,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AACrC,CAAC"}