open-managed-agents 0.1.0

package/dist/src/control-plane/egress/vendor/tls-terminate-proxy.js

@@ -0,0 +1,269 @@
+/**
+ * In-process TLS termination for HTTPS traffic through the forward proxy.
+ *
+ * When a MitmCA is configured, the forward proxy hands CONNECT requests here
+ * instead of opening an opaque byte tunnel. We terminate the client's TLS
+ * with a per-host leaf cert (see mitm-leaf.ts), parse the decrypted stream
+ * as HTTP/1.1, and re-issue each request upstream over a real TLS
+ * connection. The optional `filterRequest` callback runs on each parsed
+ * request before it is forwarded.
+ */
+import { createServer as createHttpsServer, request as httpsRequest, } from 'node:https';
+import { connect, isIP } from 'node:net';
+import { unlink } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { logForDebugging } from "../utils/debug.js";
+import { decideAndRespond, } from "./request-filter.js";
+import { mintLeafCert, secureContextFor } from "./mitm-leaf.js";
+import { stripHopByHop } from "./parent-proxy.js";
+/**
+ * True if `buf` starts with a TLS Handshake record header.
+ *
+ * Three bytes: content type 0x16 (Handshake) + legacy_record_version
+ * 0x03,0x00–0x03. RFC 8446 §5.1 froze the record-layer version (TLS 1.3+
+ * negotiate via the supported_versions extension, the wire header stays
+ * ≤0x0303), so this holds for current and future TLS. Same predicate as
+ * mitmproxy `starts_like_tls_record`; nginx `ssl_preread` routes on byte 0
+ * alone and HAProxy `req.ssl_hello_type` reads 9 bytes to also extract the
+ * handshake type — 3 is the established middle ground for "is this TLS".
+ *
+ * Routing heuristic, not a security check: a non-TLS stream that happens to
+ * start 16 03 0x is handed to the TLS server, which then rejects it properly.
+ */
+export function looksLikeClientHello(buf) {
+    return (buf.length >= 3 && buf[0] === 0x16 && buf[1] === 0x03 && buf[2] <= 0x03);
+}
+/**
+ * Wait for the client's first post-CONNECT bytes and report whether they look
+ * like a TLS ClientHello. The caller must already have written the
+ * `200 Connection Established` line — clients don't send until they see it.
+ *
+ * Any bytes consumed here are returned in `.head` so the caller can forward
+ * them to whichever downstream (terminate or opaque tunnel) it picks. The
+ * socket is left paused so further bytes buffer until the downstream
+ * `pipe()` resumes it.
+ */
+export function peekForClientHello(socket, head) {
+    if (head.length >= 3) {
+        return Promise.resolve({ isTLS: looksLikeClientHello(head), head });
+    }
+    return new Promise(resolve => {
+        let buf = head;
+        const done = () => {
+            socket.removeListener('data', onData);
+            socket.removeListener('close', done);
+            resolve({ isTLS: looksLikeClientHello(buf), head: buf });
+        };
+        const onData = (chunk) => {
+            // Pause synchronously so anything after this chunk buffers for the
+            // downstream pipe() rather than being dropped in flowing mode.
+            socket.pause();
+            buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+            if (buf.length >= 3)
+                return done();
+            socket.resume();
+        };
+        socket.on('data', onData);
+        socket.once('close', done);
+    });
+}
+/**
+ * Terminate the client's TLS on `socket`, parse the decrypted HTTP/1.1
+ * stream, and forward each request to `target` over a fresh upstream TLS
+ * connection.
+ *
+ * Preconditions: the caller has already validated `target` against the
+ * domain allowlist; this function does not re-check it.
+ *
+ * Implementation: we stand up a short-lived https.Server on a unix socket
+ * and pipe the client socket through it. The Node-idiomatic alternative —
+ * feeding the raw socket to a non-listening server via
+ * `emit('connection', socket)` — is not implemented by Bun's https.Server,
+ * and SRT runs under both runtimes. A per-connection server lets the
+ * request handler close over `target` (which carries the originally-
+ * requested host:port) without socket-keyed lookups.
+ */
+export function terminateAndForward(ca, filterRequest, mutateHeaders, socket, head, target) {
+    // ALPN advertises HTTP/1.1 only — terminating HTTP/2 would require a frame
+    // parser; clients negotiate down. The base secureContext covers clients
+    // that don't send SNI; SNICallback covers everyone else.
+    const baseLeaf = mintLeafCert(ca, target.hostname);
+    const inner = createHttpsServer({
+        ALPNProtocols: ['http/1.1'],
+        cert: baseLeaf.certPem,
+        key: baseLeaf.keyPem,
+        SNICallback: (servername, cb) => {
+            try {
+                cb(null, secureContextFor(ca, servername || target.hostname));
+            }
+            catch (err) {
+                cb(err);
+            }
+        },
+    });
+    inner.on('request', (req, res) => {
+        // OMA: fail closed — an unexpected throw inside the forward path (e.g. a
+        // hook) must kill this exchange, not become an unhandled rejection.
+        forwardUpstream(filterRequest, mutateHeaders, req, res, target).catch((err) => {
+            logForDebugging(`[tls-terminate] forward failed for ${target.hostname}: ${err.message}`, { level: 'error' });
+            res.destroy();
+        });
+    });
+    inner.on('tlsClientError', (err, sock) => {
+        logForDebugging(`[tls-terminate] client TLS error for ${target.hostname}: ${err.message}`, { level: 'error' });
+        sock.destroy();
+    });
+    inner.on('upgrade', (_req, sock) => {
+        // WebSocket / non-HTTP over TLS — out of scope for now.
+        logForDebugging('[tls-terminate] upgrade request refused', {
+            level: 'warn',
+        });
+        sock.destroy();
+    });
+    const sockPath = innerSocketPath();
+    const cleanup = () => {
+        inner.close();
+        unlink(sockPath, () => { });
+    };
+    inner.on('error', err => {
+        logForDebugging(`[tls-terminate] inner server listen failed: ${err.message}`, { level: 'error' });
+        socket.destroy();
+        cleanup();
+    });
+    inner.listen(sockPath, () => {
+        const loop = connect({ path: sockPath });
+        loop.on('error', err => {
+            logForDebugging(`[tls-terminate] inner loopback failed: ${err.message}`, {
+                level: 'error',
+            });
+            socket.destroy();
+            cleanup();
+        });
+        loop.once('connect', () => {
+            // The caller wrote `200 Connection Established` before sniffing for the
+            // ClientHello; `head` holds whatever the sniff consumed.
+            if (head.length)
+                loop.write(head);
+            socket.pipe(loop);
+            loop.pipe(socket);
+        });
+        socket.on('error', () => loop.destroy());
+        socket.once('close', () => {
+            loop.destroy();
+            cleanup();
+        });
+        loop.once('close', () => socket.destroy());
+    });
+    inner.unref();
+}
+async function forwardUpstream(filterRequest, mutateHeaders, req, res, target) {
+    // req.url is the request-target verbatim. Inside a CONNECT tunnel almost
+    // every client sends origin-form (`/path?q`), but RFC 7230 §5.3.2 also
+    // permits absolute-form (`https://host/path`) and servers MUST accept it.
+    // Normalize to origin-form so concatenating onto `https://${host}` below
+    // yields a well-formed URL, and discard any client-supplied authority so
+    // the CONNECT-verified target stays authoritative (same rationale as the
+    // Host-header note below).
+    const path = originFormPath(req.url);
+    let body = req;
+    if (filterRequest) {
+        const ac = new AbortController();
+        res.once('close', () => ac.abort());
+        // Build the URL passed to filterRequest from the CONNECT target,
+        // NOT from `req.headers.host`. The Host header is supplied by the
+        // sandboxed client and can be spoofed: a sandboxed process can
+        // CONNECT to allowlisted host A and then send a decrypted request
+        // with `Host: B` (where B is some other allowlisted host). If we
+        // built the filterRequest URL from req.headers.host the callback
+        // would see "host=B" while the request is actually delivered to A.
+        // A consumer using filterRequest for per-host method gating (e.g.
+        // "POST allowed only to inference endpoints") would be bypassed —
+        // the agent could spoof Host: api.example.com on a CONNECT to a
+        // different allowlisted host, get the POST allowed, and have it
+        // delivered to the CONNECT target instead.
+        //
+        // Always derive the URL from the verified CONNECT target so
+        // filterRequest sees the actual upstream destination.
+        const host = target.port === 443
+            ? target.hostname
+            : `${target.hostname}:${target.port}`;
+        const out = await decideAndRespond(filterRequest, req, res, `https://${host}${path}`, ac.signal, { leg: 'terminated' });
+        if (out === null)
+            return;
+        body = out;
+    }
+    // Bun's https.request verifies the upstream cert against headers.host
+    // verbatim (including ":port"), which never matches a SAN. Drop the host
+    // header and let the runtime derive it from {host, port} — same wire value,
+    // correct verification under both Node and Bun.
+    const fwdHeaders = stripHopByHop(req.headers);
+    delete fwdHeaders.host;
+    // Header mutation runs after the allow decision and before httpsRequest.
+    // The upstream TLS handshake (rejectUnauthorized defaults to true)
+    // completes before any HTTP bytes are written, so mutated headers never
+    // reach an unverified server.
+    // OMA: pass request context so injection can be path/method-scoped
+    // (ADR 0016 §6). method/path come from the decrypted request; port from the
+    // CONNECT-verified target (never the spoofable Host header).
+    mutateHeaders?.(fwdHeaders, target.hostname, {
+        method: req.method ?? 'GET',
+        path,
+        port: target.port,
+    });
+    // TODO(terminating-tls): honour parentProxy for the upstream leg.
+    const upstream = httpsRequest({
+        host: target.hostname,
+        port: target.port,
+        path,
+        method: req.method,
+        headers: fwdHeaders,
+        // We're a TLS-terminating proxy, not a trust boundary for the upstream
+        // server's identity — let the runtime do normal verification against
+        // system roots (and NODE_EXTRA_CA_CERTS). servername must match the
+        // host the client intended; SNI cannot carry an IP literal, and Bun's
+        // https.request treats `servername: undefined` differently from
+        // omitting the key, so spread conditionally.
+        ...(isIP(target.hostname) ? {} : { servername: target.hostname }),
+        ...(target.upstreamCA ? { ca: target.upstreamCA } : {}),
+        ...(target.lookup ? { lookup: target.lookup } : {}), // OMA: connect-to-pinned-IP
+        // No global agent: a proxy's outbound leg shouldn't share a connection
+        // pool keyed on the proxy process. Also works around a Bun quirk where
+        // the first request's `ca:` value is cached on the global agent and
+        // subsequent calls with a different `ca:` are silently ignored.
+        agent: false,
+    }, upRes => {
+        res.writeHead(upRes.statusCode ?? 502, stripHopByHop(upRes.headers));
+        upRes.pipe(res);
+    });
+    upstream.on('error', err => {
+        logForDebugging(`[tls-terminate] upstream ${target.hostname}:${target.port} failed: ${err.message}`, { level: 'error' });
+        if (!res.headersSent) {
+            res.writeHead(502, { 'Content-Type': 'text/plain' });
+            res.end('Bad Gateway');
+        }
+        else {
+            res.destroy();
+        }
+    });
+    res.on('close', () => upstream.destroy());
+    body.pipe(upstream);
+}
+function originFormPath(reqUrl) {
+    const raw = reqUrl ?? '/';
+    if (raw.startsWith('/'))
+        return raw;
+    try {
+        const u = new URL(raw);
+        return `${u.pathname}${u.search}` || '/';
+    }
+    catch {
+        // asterisk-form (`OPTIONS *`) or anything else non-absolute — pass through.
+        return raw;
+    }
+}
+let sockSeq = 0;
+function innerSocketPath() {
+    // Keep it short — macOS sun_path is 104 bytes.
+    return join(tmpdir(), `srt-tt-${process.pid}-${(sockSeq++).toString(36)}.sock`);
+}

package/dist/src/control-plane/environments/routes.js

@@ -0,0 +1,54 @@
+import { Hono } from "hono";
+import { parseJsonBody, parseLimit } from "../http.js";
+import { workspaceIdFrom } from "../workspace.js";
+import { environmentNetworkingPresetCatalog, validateEnvironmentNetworkingHosts, } from "../egress/presets.js";
+import { invalidRequest } from "../errors.js";
+const NO_EGRESS_CAPABILITY = {
+    provider: null,
+    egress_supported: false,
+    reason: "This deployment has no Docker-local egress sidecar configured.",
+};
+export function environmentsRoutes(service, networking = NO_EGRESS_CAPABILITY) {
+    const app = new Hono();
+    app.post("/", async (c) => {
+        const body = await parseJsonBody(c.req);
+        const environment = service.create(workspaceIdFrom(c), body);
+        return c.json(environment, 200);
+    });
+    app.get("/", (c) => {
+        const limit = parseLimit(c.req.query("limit"));
+        const page = c.req.query("page") || undefined;
+        const includeArchived = parseBoolean(c.req.query("include_archived"));
+        return c.json(service.list(workspaceIdFrom(c), {
+            ...(limit === undefined ? {} : { limit }),
+            ...(page === undefined ? {} : { page }),
+            ...(includeArchived === undefined ? {} : { includeArchived }),
+        }), 200);
+    });
+    app.get("/networking-presets", (c) => {
+        return c.json(environmentNetworkingPresetCatalog(networking), 200);
+    });
+    app.post("/networking-presets/validate", async (c) => {
+        const body = await parseJsonBody(c.req);
+        return c.json(validateEnvironmentNetworkingHosts(body), 200);
+    });
+    app.post("/:id/archive", (c) => {
+        return c.json(service.archive(workspaceIdFrom(c), c.req.param("id")), 200);
+    });
+    app.delete("/:id", (c) => {
+        return c.json(service.delete(workspaceIdFrom(c), c.req.param("id")), 200);
+    });
+    app.get("/:id", (c) => {
+        return c.json(service.retrieve(workspaceIdFrom(c), c.req.param("id")), 200);
+    });
+    return app;
+}
+function parseBoolean(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw invalidRequest("`include_archived` must be `true` or `false`");
+}

package/dist/src/control-plane/environments/service.js

@@ -0,0 +1,112 @@
+import { newEnvironmentId } from "../ids.js";
+import { conflict, invalidRequest, notFound } from "../errors.js";
+import { canonicalizeNetworkingConfig, EgressPolicyError, } from "../egress/policy.js";
+import { isJsonObject, isJsonValue } from "../../types/json.js";
+export class DefaultEnvironmentService {
+    store;
+    sessions;
+    constructor(store, sessions) {
+        this.store = store;
+        this.sessions = sessions;
+    }
+    create(workspaceId, input) {
+        const req = parseCreateEnvironment(input);
+        const now = new Date().toISOString();
+        const row = {
+            id: newEnvironmentId(),
+            workspace_id: workspaceId,
+            type: "environment",
+            name: req.name,
+            config: req.config,
+            created_at: now,
+            updated_at: now,
+            archived_at: null,
+        };
+        return toManagedEnvironment(this.store.create({ row }));
+    }
+    retrieve(workspaceId, environmentId) {
+        const row = this.store.retrieveAny(workspaceId, environmentId);
+        if (!row) {
+            throw notFound(`Environment ${environmentId} not found`);
+        }
+        return toManagedEnvironment(row);
+    }
+    list(workspaceId, opts = {}) {
+        const page = this.store.list(workspaceId, opts);
+        return {
+            data: page.data.map(toManagedEnvironment),
+            has_more: page.has_more,
+            next_page: page.next_page,
+        };
+    }
+    archive(workspaceId, environmentId) {
+        const row = this.store.archive(workspaceId, environmentId, new Date().toISOString());
+        if (!row) {
+            throw notFound(`Environment ${environmentId} not found`);
+        }
+        return toManagedEnvironment(row);
+    }
+    delete(workspaceId, environmentId) {
+        const existing = this.store.retrieveAny(workspaceId, environmentId);
+        if (!existing) {
+            throw notFound(`Environment ${environmentId} not found`);
+        }
+        if (!this.sessions) {
+            throw conflict("Environment deletion is unavailable without session reference checks");
+        }
+        if (this.sessions.hasEnvironmentReference(workspaceId, environmentId)) {
+            throw conflict("Environment cannot be deleted while sessions reference it");
+        }
+        this.store.delete(workspaceId, environmentId);
+        return { type: "environment_deleted", id: environmentId };
+    }
+}
+function parseCreateEnvironment(input) {
+    const obj = objectInput(input);
+    const name = stringField(obj, "name", { required: true });
+    const config = obj.config;
+    if (!isJsonObject(config)) {
+        throw invalidRequest("`config` must be a JSON object");
+    }
+    if (!isJsonValue(config)) {
+        throw invalidRequest("`config` must be JSON-compatible");
+    }
+    let canonicalConfig;
+    try {
+        // Validate before the row is built or handed to the store. This keeps
+        // unsupported hosted shapes from becoming durable, silently inert config.
+        canonicalConfig = canonicalizeNetworkingConfig(config);
+    }
+    catch (error) {
+        if (error instanceof EgressPolicyError) {
+            throw invalidRequest(`Invalid environment networking config: ${error.message}`);
+        }
+        throw error;
+    }
+    return { name, config: canonicalConfig };
+}
+function toManagedEnvironment(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        name: row.name,
+        config: row.config,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        archived_at: row.archived_at,
+    };
+}
+function objectInput(input) {
+    if (!isJsonObject(input)) {
+        throw invalidRequest("Request body must be a JSON object");
+    }
+    return input;
+}
+function stringField(obj, field, opts = {}) {
+    const value = obj[field];
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value === undefined && opts.required !== true)
+        return "";
+    throw invalidRequest(`\`${field}\` must be a non-empty string`);
+}

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

@@ -0,0 +1,132 @@
+import { DatabaseSync } from "node:sqlite";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS environments (
+  id            TEXT PRIMARY KEY,
+  workspace_id  TEXT NOT NULL,
+  type          TEXT NOT NULL,
+  name          TEXT NOT NULL,
+  config        TEXT NOT NULL,
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL,
+  archived_at   TEXT
+);
+CREATE INDEX IF NOT EXISTS environments_by_workspace ON environments (workspace_id, id);
+`;
+export class SqliteEnvironmentStore {
+    db;
+    insertStmt;
+    retrieveActiveStmt;
+    retrieveAnyStmt;
+    archiveStmt;
+    deleteStmt;
+    listActiveStmt;
+    listAllStmt;
+    listActiveSinceStmt;
+    listAllSinceStmt;
+    constructor(db) {
+        this.db = db;
+        this.db.exec(SCHEMA);
+        this.insertStmt = this.db.prepare(`INSERT INTO environments (
+        id, workspace_id, type, name, config, created_at, updated_at, archived_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        this.retrieveActiveStmt = this.db.prepare(`SELECT * FROM environments
+       WHERE workspace_id = ? AND id = ? AND archived_at IS NULL`);
+        this.retrieveAnyStmt = this.db.prepare(`SELECT * FROM environments WHERE workspace_id = ? AND id = ?`);
+        this.archiveStmt = this.db.prepare(`UPDATE environments
+       SET archived_at = COALESCE(archived_at, ?),
+           updated_at = CASE WHEN archived_at IS NULL THEN ? ELSE updated_at END
+       WHERE workspace_id = ? AND id = ?`);
+        this.deleteStmt = this.db.prepare(`DELETE FROM environments WHERE workspace_id = ? AND id = ?`);
+        this.listActiveStmt = this.db.prepare(`SELECT * FROM environments
+       WHERE workspace_id = ? AND archived_at IS NULL
+       ORDER BY id ASC
+       LIMIT ?`);
+        this.listAllStmt = this.db.prepare(`SELECT * FROM environments
+       WHERE workspace_id = ?
+       ORDER BY id ASC
+       LIMIT ?`);
+        this.listActiveSinceStmt = this.db.prepare(`SELECT * FROM environments
+       WHERE workspace_id = ? AND id > ? AND archived_at IS NULL
+       ORDER BY id ASC
+       LIMIT ?`);
+        this.listAllSinceStmt = this.db.prepare(`SELECT * FROM environments
+       WHERE workspace_id = ? AND id > ?
+       ORDER BY id ASC
+       LIMIT ?`);
+    }
+    static open(path = ":memory:") {
+        return new SqliteEnvironmentStore(new DatabaseSync(path));
+    }
+    create(record) {
+        const e = record.row;
+        this.insertStmt.run(e.id, e.workspace_id, e.type, e.name, JSON.stringify(e.config), e.created_at, e.updated_at, e.archived_at);
+        return e;
+    }
+    retrieve(workspaceId, environmentId) {
+        const row = this.retrieveActiveStmt.get(workspaceId, environmentId);
+        return row ? deserialize(row) : undefined;
+    }
+    retrieveAny(workspaceId, environmentId) {
+        const row = this.retrieveAnyStmt.get(workspaceId, environmentId);
+        return row ? deserialize(row) : undefined;
+    }
+    archive(workspaceId, environmentId, archivedAt) {
+        this.archiveStmt.run(archivedAt, archivedAt, workspaceId, environmentId);
+        return this.retrieveAny(workspaceId, environmentId);
+    }
+    delete(workspaceId, environmentId) {
+        const existing = this.retrieveAny(workspaceId, environmentId);
+        if (!existing)
+            return undefined;
+        this.deleteStmt.run(workspaceId, environmentId);
+        return existing;
+    }
+    list(workspaceId, opts = {}) {
+        if (opts.page === "") {
+            return { data: [], has_more: false, next_page: null };
+        }
+        const limit = normalizeLimit(opts.limit);
+        const queryLimit = limit + 1;
+        const includeArchived = opts.includeArchived ?? false;
+        // Environments list is ASC-only in B.1; sessions carry order because SDK examples use it.
+        const rows = this.listStmt(includeArchived, opts.page !== undefined).all(...selectListArgs(workspaceId, queryLimit, opts.page));
+        const pageRows = rows.slice(0, limit);
+        const data = pageRows.map(deserialize);
+        return {
+            data,
+            has_more: rows.length > limit,
+            next_page: rows.length > limit ? data[data.length - 1]?.id ?? null : null,
+        };
+    }
+    close() {
+        this.db.close();
+    }
+    listStmt(includeArchived, hasPage) {
+        if (includeArchived) {
+            return hasPage ? this.listAllSinceStmt : this.listAllStmt;
+        }
+        return hasPage ? this.listActiveSinceStmt : this.listActiveStmt;
+    }
+}
+function selectListArgs(workspaceId, limit, page) {
+    return page === undefined ? [workspaceId, limit] : [workspaceId, page, limit];
+}
+function normalizeLimit(limit) {
+    if (limit === undefined)
+        return 20;
+    if (!Number.isSafeInteger(limit) || limit <= 0)
+        return 20;
+    return Math.min(limit, 100);
+}
+function deserialize(row) {
+    return {
+        id: row.id,
+        workspace_id: row.workspace_id,
+        type: "environment",
+        name: row.name,
+        config: JSON.parse(row.config),
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        archived_at: row.archived_at,
+    };
+}

package/dist/src/control-plane/environments/types.js

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

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

@@ -0,0 +1,81 @@
+import { newRequestId } from "./ids.js";
+export const API_ERROR_TYPES = [
+    "invalid_request_error",
+    "authentication_error",
+    "billing_error",
+    "permission_error",
+    "not_found_error",
+    "request_too_large",
+    "rate_limit_error",
+    "api_error",
+    "timeout_error",
+    "overloaded_error",
+];
+export class ApiError extends Error {
+    status;
+    type;
+    developerMessage;
+    retryAfterSeconds;
+    constructor(status, type, message, opts = {}) {
+        super(message, opts.cause === undefined ? undefined : { cause: opts.cause });
+        this.name = "ApiError";
+        this.status = status;
+        this.type = type;
+        this.developerMessage = opts.developerMessage;
+        if (opts.retryAfterSeconds !== undefined) {
+            this.retryAfterSeconds = opts.retryAfterSeconds;
+        }
+    }
+}
+// 0113 D9 admission rejections. Hosted Managed Agents documents 429 with a
+// retry-after header for rate limits; 529 uses the hosted "Overloaded"
+// message verbatim.
+export function rateLimited(message) {
+    return new ApiError(429, "rate_limit_error", message, {
+        retryAfterSeconds: 1,
+    });
+}
+export function overloaded() {
+    return new ApiError(529, "overloaded_error", "Overloaded");
+}
+export function invalidRequest(message, developerMessage) {
+    return new ApiError(400, "invalid_request_error", message, {
+        developerMessage,
+    });
+}
+// Hosted-identical envelope (0113 probe rows 1-5): one generic message for
+// missing and invalid keys, no key-existence leak.
+export function authenticationFailed() {
+    return new ApiError(401, "authentication_error", "Authentication failed");
+}
+export function notFound(message) {
+    return new ApiError(404, "not_found_error", message);
+}
+export function conflict(message) {
+    return new ApiError(409, "invalid_request_error", message);
+}
+export function requestTooLarge(message = "Request body is too large") {
+    return new ApiError(413, "request_too_large", message);
+}
+export function internalError(cause) {
+    return new ApiError(500, "api_error", "Internal server error", {
+        cause,
+        developerMessage: cause instanceof Error ? cause.message : String(cause),
+    });
+}
+export function requestId() {
+    return newRequestId();
+}
+export function toApiErrorBody(error, id = requestId()) {
+    return {
+        type: "error",
+        error: {
+            type: error.type,
+            message: error.message,
+        },
+        request_id: id,
+    };
+}
+export function ensureApiError(error) {
+    return error instanceof ApiError ? error : internalError(error);
+}