open-managed-agents 0.1.0

package/dist/src/control-plane/wake-loop.js

@@ -0,0 +1,65 @@
+export function createWakeLoop(opts) {
+    const now = opts.now ?? Date.now;
+    let timer;
+    let running;
+    let closed = false;
+    const schedule = (delayMs) => {
+        if (closed)
+            return;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            void cycle();
+        }, delayMs);
+    };
+    const cycle = async () => {
+        if (closed || running !== undefined)
+            return;
+        const work = (async () => {
+            try {
+                const dueAt = await opts.nextWakeAt();
+                if (closed)
+                    return;
+                if (dueAt !== null && dueAt.getTime() <= now()) {
+                    await opts.run();
+                    if (closed)
+                        return;
+                    schedule(opts.minSleepMs);
+                    return;
+                }
+                const untilDue = dueAt === null ? opts.maxSleepMs : dueAt.getTime() - now();
+                schedule(Math.min(opts.maxSleepMs, Math.max(opts.minSleepMs, untilDue)));
+            }
+            catch (error) {
+                opts.onError(error);
+                schedule(opts.minSleepMs);
+            }
+        })();
+        running = work;
+        try {
+            await work;
+        }
+        finally {
+            running = undefined;
+        }
+    };
+    schedule(0);
+    return {
+        wake() {
+            if (closed || running !== undefined)
+                return;
+            schedule(0);
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            await running;
+        },
+    };
+}

package/dist/src/control-plane/wiring.js

@@ -0,0 +1,92 @@
+import { randomBytes } from "node:crypto";
+import { resolveSessionEgressBundle } from "./egress/policy.js";
+import { DEFAULT_SIDECAR_PORT } from "./sessions/pi/sandbox/docker-egress.js";
+/**
+ * Per-session egress bundle resolution (plan 0117e-3, Option A): session ->
+ * environment -> networking config -> secrets, resolved at sandbox-create
+ * time inside the docker factory closure. Returns undefined only when the
+ * environment has no networking or a valid hosted empty allowlist. Every
+ * other present networking shape is parsed and fails closed. Mints a fresh
+ * URL-safe proxy-auth token per session.
+ */
+export function createSessionEgressBundleResolver(stores) {
+    return async (workspaceId, sessionId, context) => {
+        // Normal prompt-time sandbox creation reads the persisted session row. The
+        // file-resource create path prepares its sandbox before that row is
+        // committed, so DefaultSessionService passes the already-validated
+        // environmentId as a creation-time hint.
+        const environmentId = context?.environmentId;
+        const session = environmentId === undefined
+            ? stores.sessions.retrieveAny(workspaceId, sessionId)
+            : undefined;
+        if (environmentId === undefined && !session)
+            return undefined;
+        const resolvedEnvironmentId = environmentId ?? session.environment_id;
+        const environment = stores.environments.retrieveAny(workspaceId, resolvedEnvironmentId);
+        if (!environment)
+            return undefined;
+        const resolved = resolveSessionEgressBundle({
+            environmentConfig: environment.config,
+            revealSecret: (name) => stores.secrets?.reveal(workspaceId, name),
+            listenPort: DEFAULT_SIDECAR_PORT,
+            proxyAuthToken: randomBytes(24).toString("hex"),
+        });
+        if (resolved === undefined)
+            return undefined;
+        return { bundle: resolved.bundle, sandboxEnv: resolved.sandboxEnv };
+    };
+}
+export function createFileMountResolver(sessionStore, fileStorage) {
+    return async (workspaceId, sessionId) => {
+        const snapshots = sessionStore.getFileMountSnapshots(workspaceId, sessionId);
+        return Promise.all(snapshots.map(async (snapshot) => snapshotToRuntimeMount(workspaceId, fileStorage, snapshot)));
+    };
+}
+export function createSkillSnapshotsProvider(sessionStore) {
+    return (workspaceId, sessionId) => sessionStore.getSkillSnapshots(workspaceId, sessionId).map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+    }));
+}
+async function snapshotToRuntimeMount(workspaceId, fileStorage, snapshot) {
+    const bytes = await fileStorage.openInternalSnapshotBytes(workspaceId, snapshot.snapshot_file_id);
+    if (!bytes) {
+        throw new Error(`Session file snapshot ${snapshot.snapshot_file_id} not found`);
+    }
+    return {
+        kind: snapshot.kind,
+        mountPath: snapshot.mount_path,
+        snapshotFileId: snapshot.snapshot_file_id,
+        sha256: snapshot.sha256,
+        sizeBytes: snapshot.size_bytes,
+        bytes,
+    };
+}
+export function createStoreBackedAgentRevisionProvider(opts) {
+    return (workspaceId, sessionId, context) => {
+        const session = opts.sessions.retrieveAny(workspaceId, sessionId);
+        const agentId = session?.agent.id ?? context?.agentId;
+        const version = session?.agent.version ?? context?.agentVersion;
+        if (!agentId || version === undefined)
+            return undefined;
+        const agent = opts.agents.retrieveVersion(workspaceId, agentId, version);
+        if (!agent) {
+            throw new Error(`Pinned agent revision not found: ${agentId}@${version}`);
+        }
+        return { model: agent.model, system: agent.system };
+    };
+}
+export function createStoreBackedCustomToolsProvider(opts) {
+    return (workspaceId, sessionId, context) => {
+        const session = opts.sessions.retrieveAny(workspaceId, sessionId);
+        const agentId = session?.agent.id ?? context?.agentId;
+        const agentVersion = session?.agent.version ?? context?.agentVersion;
+        if (!agentId || agentVersion === undefined)
+            return [];
+        const agent = opts.agents.retrieveVersion(workspaceId, agentId, agentVersion);
+        if (!agent)
+            return [];
+        const tools = agent.tools.filter((tool) => tool.type === "custom");
+        return tools;
+    };
+}

package/dist/src/control-plane/workspace.js

@@ -0,0 +1,4 @@
+export const DEFAULT_WORKSPACE_ID = "wrk_default";
+export function workspaceIdFrom(c) {
+    return c.get("workspaceId") ?? DEFAULT_WORKSPACE_ID;
+}

package/dist/src/control-plane/workspaces/store.js

@@ -0,0 +1,158 @@
+import { createHash, randomBytes } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { DEFAULT_WORKSPACE_ID } from "../workspace.js";
+import { uuidv7 } from "../../types/events.js";
+// Plan 0113 D2/D3: opaque `oma_`-prefixed 256-bit keys, SHA-256 digests at
+// rest, tombstone revocation, idempotent wrk_default seeding.
+const SCHEMA = `
+PRAGMA foreign_keys = ON;
+CREATE TABLE IF NOT EXISTS workspaces (
+  workspace_id TEXT PRIMARY KEY,
+  name         TEXT NOT NULL,
+  created_at   TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS workspace_api_keys (
+  key_sha256   TEXT PRIMARY KEY,
+  workspace_id TEXT NOT NULL REFERENCES workspaces(workspace_id),
+  label        TEXT NOT NULL,
+  created_at   TEXT NOT NULL,
+  revoked_at   TEXT
+);
+CREATE INDEX IF NOT EXISTS workspace_api_keys_by_workspace
+  ON workspace_api_keys (workspace_id, key_sha256);
+CREATE TABLE IF NOT EXISTS console_sessions (
+  token_sha256      TEXT PRIMARY KEY,
+  kind              TEXT NOT NULL CHECK (kind IN ('workspace_key', 'admin', 'admin_workspace')),
+  workspace_id      TEXT REFERENCES workspaces(workspace_id),
+  credential_sha256 TEXT NOT NULL,
+  created_at        TEXT NOT NULL,
+  expires_at        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS console_sessions_by_expiry
+  ON console_sessions (expires_at);
+`;
+export const WORKSPACE_API_KEY_PREFIX = "oma_";
+export function newWorkspaceId() {
+    return `wrk_${uuidv7()}`;
+}
+export function hashWorkspaceApiKey(plaintextKey) {
+    return createHash("sha256").update(plaintextKey).digest("hex");
+}
+export class SqliteWorkspaceStore {
+    db;
+    insertWorkspaceStmt;
+    getWorkspaceStmt;
+    insertKeyStmt;
+    authenticateStmt;
+    revokeKeyStmt;
+    listKeysStmt;
+    listWorkspacesStmt;
+    getKeyStmt;
+    countKeysStmt;
+    insertConsoleSessionStmt;
+    getConsoleSessionStmt;
+    deleteConsoleSessionStmt;
+    constructor(db) {
+        this.db = db;
+        this.db.exec(SCHEMA);
+        this.insertWorkspaceStmt = this.db.prepare(`INSERT INTO workspaces (workspace_id, name, created_at) VALUES (?, ?, ?)`);
+        this.getWorkspaceStmt = this.db.prepare(`SELECT workspace_id, name, created_at FROM workspaces WHERE workspace_id = ?`);
+        this.insertKeyStmt = this.db.prepare(`INSERT INTO workspace_api_keys (key_sha256, workspace_id, label, created_at, revoked_at)
+       VALUES (?, ?, ?, ?, NULL)`);
+        this.authenticateStmt = this.db.prepare(`SELECT workspace_id FROM workspace_api_keys
+       WHERE key_sha256 = ? AND revoked_at IS NULL`);
+        this.revokeKeyStmt = this.db.prepare(`UPDATE workspace_api_keys
+       SET revoked_at = COALESCE(revoked_at, ?)
+       WHERE key_sha256 = ?`);
+        this.listKeysStmt = this.db.prepare(`SELECT key_sha256, workspace_id, label, created_at, revoked_at
+       FROM workspace_api_keys
+       WHERE workspace_id = ?
+       ORDER BY key_sha256 ASC`);
+        this.listWorkspacesStmt = this.db.prepare(`SELECT workspace_id, name, created_at FROM workspaces
+       ORDER BY workspace_id ASC`);
+        this.getKeyStmt = this.db.prepare(`SELECT key_sha256, workspace_id, label, created_at, revoked_at
+       FROM workspace_api_keys
+       WHERE key_sha256 = ?`);
+        this.countKeysStmt = this.db.prepare(`SELECT COUNT(*) AS n FROM workspace_api_keys`);
+        this.insertConsoleSessionStmt = this.db.prepare(`INSERT INTO console_sessions
+       (token_sha256, kind, workspace_id, credential_sha256, created_at, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?)`);
+        this.getConsoleSessionStmt = this.db.prepare(`SELECT token_sha256, kind, workspace_id, credential_sha256, created_at, expires_at
+       FROM console_sessions
+       WHERE token_sha256 = ? AND expires_at > ?`);
+        this.deleteConsoleSessionStmt = this.db.prepare(`DELETE FROM console_sessions WHERE token_sha256 = ?`);
+        this.db.prepare(`INSERT OR IGNORE INTO workspaces (workspace_id, name, created_at)
+       VALUES (?, 'Default workspace', ?)`).run(DEFAULT_WORKSPACE_ID, new Date().toISOString());
+    }
+    static open(path) {
+        return new SqliteWorkspaceStore(new DatabaseSync(path));
+    }
+    createWorkspace(name, workspaceId = newWorkspaceId()) {
+        const row = {
+            workspace_id: workspaceId,
+            name,
+            created_at: new Date().toISOString(),
+        };
+        this.insertWorkspaceStmt.run(row.workspace_id, row.name, row.created_at);
+        return row;
+    }
+    getWorkspace(workspaceId) {
+        return this.getWorkspaceStmt.get(workspaceId);
+    }
+    listWorkspaces() {
+        return this.listWorkspacesStmt.all();
+    }
+    getKey(keySha256) {
+        return this.getKeyStmt.get(keySha256);
+    }
+    mintKey(workspaceId, label) {
+        if (!this.getWorkspace(workspaceId)) {
+            throw new Error(`Workspace not found: ${workspaceId}`);
+        }
+        const plaintextKey = `${WORKSPACE_API_KEY_PREFIX}${randomBytes(32).toString("base64url")}`;
+        const keySha256 = hashWorkspaceApiKey(plaintextKey);
+        this.insertKeyStmt.run(keySha256, workspaceId, label, new Date().toISOString());
+        return { plaintextKey, keySha256, workspaceId, label };
+    }
+    // Counts every key ever minted, revoked included: first boot means "no key
+    // was ever issued", not "no key currently works".
+    countApiKeys() {
+        return this.countKeysStmt.get().n;
+    }
+    authenticate(plaintextKey) {
+        const row = this.authenticateStmt.get(hashWorkspaceApiKey(plaintextKey));
+        return row?.workspace_id;
+    }
+    authenticateKeySha256(keySha256) {
+        const row = this.authenticateStmt.get(keySha256);
+        return row?.workspace_id;
+    }
+    mintConsoleSession(input) {
+        const plaintextToken = `ocs_${randomBytes(32).toString("base64url")}`;
+        const row = {
+            token_sha256: hashWorkspaceApiKey(plaintextToken),
+            kind: input.kind,
+            workspace_id: input.workspaceId ?? null,
+            credential_sha256: input.credentialSha256,
+            created_at: new Date().toISOString(),
+            expires_at: input.expiresAt.toISOString(),
+        };
+        this.insertConsoleSessionStmt.run(row.token_sha256, row.kind, row.workspace_id, row.credential_sha256, row.created_at, row.expires_at);
+        return { plaintextToken, row };
+    }
+    getConsoleSession(plaintextToken) {
+        return this.getConsoleSessionStmt.get(hashWorkspaceApiKey(plaintextToken), new Date().toISOString());
+    }
+    revokeConsoleSession(plaintextToken) {
+        return this.deleteConsoleSessionStmt.run(hashWorkspaceApiKey(plaintextToken)).changes > 0;
+    }
+    revokeKey(keySha256) {
+        return this.revokeKeyStmt.run(new Date().toISOString(), keySha256).changes > 0;
+    }
+    listKeys(workspaceId) {
+        return this.listKeysStmt.all(workspaceId);
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/src/egress-proxy-main.js

@@ -0,0 +1,103 @@
+/**
+ * Per-session egress proxy sidecar entrypoint (plan 0117d; ADR 0016 §2/§3).
+ *
+ * The vendored `createEgressProxy` runs OUT of the long-lived control-plane
+ * process, in its own short-lived container, so the control plane never joins
+ * the sandbox's network (the sandbox's sole route out is this proxy). It is
+ * launched with the SAME appliance image, only a different CMD — no second
+ * image to ship.
+ *
+ * Contract (all via env, since the sidecar takes no CLI args):
+ *   OMA_EGRESS_BUNDLE_PATH   read-only mount of the serialized SessionEgressBundle
+ *                            (policy + grants + resolved secrets + auth token).
+ *                            Holds real secret material — mounted ONLY here.
+ *   OMA_EGRESS_SHARED_DIR    a dir shared with the control plane. The sidecar
+ *                            writes `ca.crt` (its ephemeral MITM CA cert) and,
+ *                            once listening, a `ready` marker. The CA PRIVATE
+ *                            KEY never leaves this container.
+ *   OMA_EGRESS_BIND_HOST     listen address (default 0.0.0.0 — the sidecar is
+ *                            only reachable on the per-session --internal net).
+ *
+ * The proxy inherits the default SSRF/private-IP deny (we never set the
+ * dangerous test flag) and never sets mutateHeadersPlaintext, so secrets are
+ * injected only on the TLS-terminated leg.
+ */
+import { copyFileSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createEgressProxy, createMitmCA, disposeMitmCA, } from "./control-plane/egress/proxy.js";
+import { buildHooksFromBundle, } from "./control-plane/egress/policy.js";
+import { log } from "./control-plane/logging.js";
+function requiredEnv(env, key) {
+    const value = env[key];
+    if (typeof value !== "string" || value === "") {
+        throw new Error(`egress proxy sidecar requires ${key}`);
+    }
+    return value;
+}
+export function loadSessionEgressBundle(path) {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        typeof parsed.listenPort !== "number" ||
+        typeof parsed.proxyAuthToken !== "string" ||
+        !Array.isArray(parsed.grants) ||
+        typeof parsed.policy !== "object") {
+        throw new Error(`egress bundle at ${path} is malformed`);
+    }
+    return parsed;
+}
+/**
+ * Start the sidecar proxy. Generates the MITM CA in-process, publishes its
+ * cert (not its key) to the shared dir, listens, then drops the `ready`
+ * marker the control plane waits on before it launches the sandbox.
+ */
+export async function startEgressProxySidecar(env) {
+    const bundlePath = requiredEnv(env, "OMA_EGRESS_BUNDLE_PATH");
+    const sharedDir = requiredEnv(env, "OMA_EGRESS_SHARED_DIR");
+    const bindHost = env.OMA_EGRESS_BIND_HOST ?? "0.0.0.0";
+    const bundle = loadSessionEgressBundle(bundlePath);
+    // Ephemeral CA minted here; only the trust BUNDLE is published (never the
+    // key, which could forge certs for any host — it stays in this container).
+    // The bundle is the MITM CA followed by the host's public roots: the sandbox
+    // trust env vars (SSL_CERT_FILE, CURL_CA_BUNDLE, ...) REPLACE the client's
+    // store, so publishing the CA alone would break verification for any host we
+    // do NOT terminate (opaque-tunnel / cert-pinned upstreams talk to the real
+    // upstream cert). trustBundlePath already contains CA + roots.
+    const ca = createMitmCA({});
+    copyFileSync(ca.trustBundlePath, join(sharedDir, "ca.crt"));
+    const server = createEgressProxy({
+        ...buildHooksFromBundle(bundle),
+        mitmCA: ca,
+        proxyAuthToken: bundle.proxyAuthToken,
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(bundle.listenPort, bindHost, () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    // Marker is written LAST: its presence means the proxy is accepting
+    // connections, so the control plane can start the sandbox without a race.
+    writeFileSync(join(sharedDir, "ready"), "", { mode: 0o644 });
+    const stop = async () => {
+        await new Promise((resolve) => server.close(() => resolve()));
+        await disposeMitmCA(ca);
+    };
+    return { server, port: bundle.listenPort, ca, stop };
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    startEgressProxySidecar(process.env)
+        .then((running) => {
+        const shutdown = () => {
+            void running.stop().then(() => process.exit(0));
+        };
+        process.on("SIGTERM", shutdown);
+        process.on("SIGINT", shutdown);
+    })
+        .catch((error) => {
+        log.error("egress_proxy_sidecar_failed", { error });
+        process.exit(1);
+    });
+}

package/dist/src/main.js

@@ -0,0 +1,124 @@
+/**
+ * Appliance entrypoint (plan 0115, Arc A slice 1 of the 0114 roadmap).
+ *
+ * One command boots a durable, authenticated OMA server with sensible
+ * defaults; the first boot mints the initial workspace API key and prints it
+ * exactly once. Every default is an override, not a requirement:
+ *
+ *   OMA_HOME               data directory (default ~/.oma)
+ *   OMA_SQLITE_PATH        explicit DB path (overrides OMA_HOME derivation)
+ *   OMA_FILE_STORAGE_ROOT  explicit object root (ditto)
+ *   OMA_AUTH_MODE          default api-key; "disabled" is respected
+ *   OMA_PORT               default 4180 (0 = ephemeral, for tests)
+ *   OMA_HOST               bind address, default 127.0.0.1
+ *
+ * Run directly (`node --experimental-transform-types src/main.ts`) or via
+ * `oma up`, whose CLI launcher adds the Node flags and selects a sandbox.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { serve } from "@hono/node-server";
+import { createDeploymentControlPlane, } from "./control-plane/app.js";
+import { DEFAULT_WORKSPACE_ID } from "./control-plane/workspace.js";
+export const DEFAULT_APPLIANCE_PORT = 4180;
+// Pure so tests can assert the derivation. OMA_HOME only fills the storage
+// pair when neither is set explicitly; setting exactly one of the pair still
+// hits the existing "must be set together" error from deployment storage.
+export function resolveApplianceEnv(env) {
+    const resolved = { ...env };
+    if (resolved.OMA_SQLITE_PATH === undefined &&
+        resolved.OMA_FILE_STORAGE_ROOT === undefined) {
+        const home = resolved.OMA_HOME ?? join(homedir(), ".oma");
+        resolved.OMA_SQLITE_PATH = join(home, "oma.sqlite");
+        resolved.OMA_FILE_STORAGE_ROOT = join(home, "files");
+    }
+    resolved.OMA_AUTH_MODE ??= "api-key";
+    return resolved;
+}
+export function parseAppliancePort(raw) {
+    if (raw === undefined)
+        return DEFAULT_APPLIANCE_PORT;
+    const port = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(port) || port < 0 || port > 65535 || String(port) !== raw.trim()) {
+        throw new Error(`Invalid OMA_PORT: ${JSON.stringify(raw)} (expected an integer 0-65535)`);
+    }
+    return port;
+}
+export async function startAppliance(env = process.env, opts = {}) {
+    const log = opts.log ?? console.log;
+    const resolved = resolveApplianceEnv(env);
+    const port = parseAppliancePort(resolved.OMA_PORT);
+    const host = resolved.OMA_HOST ?? "127.0.0.1";
+    const plane = createDeploymentControlPlane(resolved);
+    const { app, stores, authMode } = plane;
+    let server;
+    try {
+        const bound = await new Promise((resolvePromise, reject) => {
+            const onError = (error) => reject(error);
+            const s = serve({ fetch: app.fetch, hostname: host, port }, (info) => {
+                s.off("error", onError);
+                resolvePromise({ server: s, boundPort: info.port });
+            });
+            s.on("error", onError);
+        });
+        server = bound.server;
+        const boundPort = bound.boundPort;
+        // Mint only after the server has bound. First boot = no key was ever
+        // minted (revoked tombstones count as minted), so persisting a key on a
+        // boot that then fails to bind (EADDRINUSE) would make every later boot
+        // skip minting — an unprinted key locking the operator out. A key that
+        // prints but never serves only costs a retry; the reverse costs the
+        // quickstart.
+        const minted = authMode === "api-key" && stores.workspaces.countApiKeys() === 0
+            ? stores.workspaces.mintKey(DEFAULT_WORKSPACE_ID, "first-boot")
+            : undefined;
+        const baseUrl = `http://${host}:${boundPort}`;
+        log(`open-managed-agents listening on ${baseUrl}`);
+        log(`  console: ${baseUrl}/console/`);
+        log(`  api: ${baseUrl}`);
+        log(`  data: ${resolved.OMA_SQLITE_PATH} | files: ${resolved.OMA_FILE_STORAGE_ROOT}`);
+        log(`  auth: ${authMode}`);
+        if (minted !== undefined) {
+            log("");
+            log(`First boot: minted the initial API key for ${minted.workspaceId}.`);
+            log("It is shown once and stored only as a hash — save it now:");
+            log("");
+            log(`  x-api-key: ${minted.plaintextKey}`);
+            log("");
+            log(`Connect any Anthropic SDK client with base URL ${baseUrl} and that x-api-key.`);
+            // tsx is a devDependency and absent from the Docker image; the node
+            // flag works in both the checkout and the container.
+            log("Mint more keys/workspaces: node --experimental-transform-types scripts/oma-workspaces.ts --help");
+        }
+        return {
+            port: boundPort,
+            close: async () => {
+                await closeServer(bound.server);
+                await plane.close();
+            },
+        };
+    }
+    catch (error) {
+        // Failed startups must release everything (notably .oma.lock) so the
+        // operator's retry is a clean boot, not a lock error.
+        if (server !== undefined) {
+            await closeServer(server).catch(() => { });
+        }
+        await plane.close();
+        throw error;
+    }
+}
+function closeServer(server) {
+    return new Promise((resolvePromise, reject) => {
+        server.close((err) => (err ? reject(err) : resolvePromise()));
+    });
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    const appliance = await startAppliance(process.env, {});
+    const shutdown = () => {
+        void appliance.close().then(() => process.exit(0));
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}

package/dist/src/types/agents.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/common.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/environments.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/events.js

@@ -0,0 +1,121 @@
+/**
+ * Managed Agents event types — the wire shapes we publish to API clients.
+ *
+ * The `type` strings are Tier 1 wire-compatible per ADR 0004 — they must match
+ * Anthropic's Managed Agents API verbatim. Per-type fields are deliberately
+ * modeled as an open object at this layer; typed elaboration lives in the
+ * route/translator layer where the discriminator gives us the variant.
+ */
+/**
+ * Discriminator strings emitted by the platform. MVP subset; extend as needed.
+ *
+ * Declared as a runtime `as const` array so we can iterate it in alignment
+ * tests (see `src/types/__tests__/events.test.ts`); the TS union is derived
+ * via `typeof[number]` so the compile-time and runtime views can never drift.
+ */
+export const EVENT_TYPES = [
+    // Agent-originated
+    "agent.message",
+    "agent.tool_use",
+    "agent.tool_result",
+    "agent.custom_tool_use",
+    "agent.mcp_tool_use",
+    "agent.mcp_tool_result",
+    // Span observability
+    "span.model_request_start",
+    "span.model_request_end",
+    // Session lifecycle
+    "session.status_running",
+    "session.status_idle",
+    "session.status_rescheduled",
+    "session.status_terminated",
+    "session.deleted",
+    "session.error",
+    // User-originated (echoed back on the stream after server processes them)
+    "user.message",
+    "user.interrupt",
+    "user.custom_tool_result",
+    "user.tool_confirmation",
+];
+/**
+ * Generate a UUIDv7 — time-ordered 128-bit ID with a 48-bit millisecond
+ * timestamp prefix. Used so lexical sort = chronological sort, which makes
+ * `WHERE id > ? ORDER BY id` a valid cursor scan in SQLite.
+ *
+ * Strict intra-process monotonicity via **counter-based** scheme (RFC 9562
+ * §6.2 Method 1, with random seeding per Method 3): when multiple IDs are
+ * minted in the same millisecond, a 12-bit counter in `rand_a` advances
+ * deterministically. This preserves real-clock fidelity in the embedded `ms`
+ * field — code-review MEDIUM 4 finding fixed (no more timestamp inflation).
+ *
+ * Layout (per RFC 9562 §5.7):
+ *   bits  0-47   unix_ts_ms (48-bit ms)
+ *   bits 48-51   ver (constant 0b0111)
+ *   bits 52-63   counter (12-bit monotonic within an ms)
+ *   bits 64-65   var (constant 0b10)
+ *   bits 66-127  random (62 bits)
+ *
+ * Counter behavior:
+ *   - When `ms` advances: counter seeded with random 0..2047 (leaves 2048
+ *     increments of headroom within the ms; mitigates cross-process collisions)
+ *   - When `ms` is equal or earlier (clock tied or rewound): counter bumps;
+ *     if it overflows 0xFFF we borrow 1ms (this is the only path that inflates
+ *     timestamps, and only by 1ms per 4096-ID burst within a single ms)
+ *
+ * Spec: https://datatracker.ietf.org/doc/rfc9562/ §5.7 + §6.2
+ */
+let lastMs = 0n;
+let lastCounter = 0;
+export function uuidv7() {
+    let ms = BigInt(Date.now());
+    let counter;
+    if (ms > lastMs) {
+        lastMs = ms;
+        // Seed counter with random 0..2047 (top bit clear → 2048 increments
+        // available before counter overflow within the same ms).
+        counter = crypto.getRandomValues(new Uint16Array(1))[0] & 0x07ff;
+        lastCounter = counter;
+    }
+    else {
+        // Same ms (or rewound clock). Reuse lastMs; bump counter.
+        ms = lastMs;
+        lastCounter += 1;
+        if (lastCounter > 0x0fff) {
+            // 12-bit counter overflow. Borrow 1ms (only timestamp-inflation path).
+            lastMs += 1n;
+            ms = lastMs;
+            counter = crypto.getRandomValues(new Uint16Array(1))[0] & 0x07ff;
+            lastCounter = counter;
+        }
+        else {
+            counter = lastCounter;
+        }
+    }
+    const random = crypto.getRandomValues(new Uint8Array(8));
+    const b0 = Number((ms >> 40n) & 0xffn);
+    const b1 = Number((ms >> 32n) & 0xffn);
+    const b2 = Number((ms >> 24n) & 0xffn);
+    const b3 = Number((ms >> 16n) & 0xffn);
+    const b4 = Number((ms >> 8n) & 0xffn);
+    const b5 = Number(ms & 0xffn);
+    // version 7 (high nibble) | top 4 bits of 12-bit counter (low nibble)
+    const b6 = 0x70 | ((counter >> 8) & 0x0f);
+    // low 8 bits of 12-bit counter
+    const b7 = counter & 0xff;
+    // variant 0b10 (high 2 bits) | 6 random bits
+    const b8 = 0x80 | (random[0] & 0x3f);
+    const b9 = random[1];
+    const tail = random.slice(2); // 6 random bytes
+    const hex = (n) => n.toString(16).padStart(2, "0");
+    return [
+        hex(b0) + hex(b1) + hex(b2) + hex(b3),
+        hex(b4) + hex(b5),
+        hex(b6) + hex(b7),
+        hex(b8) + hex(b9),
+        [...tail].map(hex).join(""),
+    ].join("-");
+}
+/** Convenience: prefixed event ID. */
+export function newEventId() {
+    return `sevt_${uuidv7()}`;
+}

package/dist/src/types/files.js

@@ -0,0 +1 @@
+export {};