@aexhq/sdk 0.34.0 → 0.36.0

package/examples/feature-tour.ts

@@ -0,0 +1,284 @@
+/**
+ * SDK feature tour: one managed session that uses typed model/runtime constants,
+ * inline AGENTS.md guidance, uploaded files, a custom tool bundle, selected
+ * built-in tools, runtime env vars/secrets, streamed events, output reads, and
+ * a follow-up session turn.
+ *
+ * Run from the repository root after building the workspace package:
+ *
+ *   AEX_API_TOKEN=... DEEPSEEK_API_KEY=... bun packages/sdk/examples/feature-tour.ts
+ *
+ * Optional:
+ *
+ *   AEX_API_URL=https://api.aex.dev
+ *   AEX_FEATURE_TOUR_DOWNLOAD=./feature-tour-session.zip
+ *   AEX_DEMO_RUNTIME_SECRET=...       # mounted as a runtime secret; never printed
+ *   AEX_DEMO_MCP_URL=https://...      # declares an optional remote MCP server
+ *   AEX_DEMO_MCP_TOKEN=...            # optional bearer auth for that MCP server
+ */
+import {
+  AgentsMd,
+  Aex,
+  BuiltinTools,
+  File,
+  isRateLimited,
+  isTextMessage,
+  McpServer,
+  Models,
+  Providers,
+  Secret,
+  Sizes,
+  Tool
+} from "@aexhq/sdk";
+
+process.on("uncaughtException", handleFatal);
+process.on("unhandledRejection", handleFatal);
+
+const apiToken = required("AEX_API_TOKEN");
+const deepseekKey = required("DEEPSEEK_API_KEY");
+const apiUrl = process.env.AEX_API_URL;
+const demoMcpUrl = process.env.AEX_DEMO_MCP_URL;
+const demoMcpToken = process.env.AEX_DEMO_MCP_TOKEN;
+const demoRuntimeSecret = process.env.AEX_DEMO_RUNTIME_SECRET;
+const downloadPath = process.env.AEX_FEATURE_TOUR_DOWNLOAD;
+const textEncoder = new TextEncoder();
+
+const aex = new Aex({
+  apiToken,
+  ...(apiUrl ? { baseUrl: apiUrl } : {}),
+  retry: {
+    maxAttempts: 4,
+    initialDelayMs: 500,
+    maxDelayMs: 10_000,
+    maxElapsedMs: 90_000
+  }
+});
+
+const metricLookup = await Tool.fromFiles({
+  name: "metric_lookup",
+  description: "Looks up normalized demo metrics for one product line.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      product: {
+        type: "string",
+        enum: ["atlas", "beacon", "cinder"],
+        description: "Product line to inspect."
+      }
+    },
+    required: ["product"]
+  },
+  entry: "index.js",
+  files: {
+    "index.js": `
+const DATA = {
+  atlas: { customerCount: 118, activationHealthPct: 72.4, supportTickets: 11 },
+  beacon: { customerCount: 74, activationHealthPct: 65.1, supportTickets: 19 },
+  cinder: { customerCount: 43, activationHealthPct: 58.8, supportTickets: 7 }
+};
+
+export default async function ({ input }) {
+  const key = String(input.product ?? "").toLowerCase();
+  const row = DATA[key];
+  if (!row) {
+    return { content: [{ type: "text", text: \`unknown product: \${key}\` }], is_error: true };
+  }
+  return { content: [{ type: "text", text: JSON.stringify({ product: key, ...row }) }] };
+}
+`
+  }
+});
+
+const demoCsv = [
+  "product,region,q1_revenue_usd,q2_revenue_usd,activation_rate",
+  "atlas,na,120000,139500,0.84",
+  "beacon,emea,98000,104300,0.79",
+  "cinder,apac,67000,81000,0.91"
+].join("\n");
+
+const attachedFile = await File.fromBytes({
+  name: "quarterly-metrics.csv",
+  bytes: textEncoder.encode(`${demoCsv}\n`),
+  mountPath: "/workspace/input"
+});
+
+const runRules = await AgentsMd.fromContent(
+  [
+    "# Feature tour rules",
+    "- Use `/workspace/input/quarterly-metrics.csv` as the source table.",
+    "- Call `metric_lookup` for atlas, beacon, and cinder before writing conclusions.",
+    "- Write final artifacts under `/workspace/outputs`.",
+    "- Never print runtime secret values or provider keys."
+  ].join("\n"),
+  { name: "feature-tour-rules" }
+);
+
+const mcpServers = demoMcpUrl
+  ? [
+      McpServer.remote({
+        name: "demo-mcp",
+        url: demoMcpUrl,
+        ...(demoMcpToken
+          ? { headers: { Authorization: `Bearer ${demoMcpToken}` } }
+          : {})
+      })
+    ]
+  : [];
+
+const environmentSecrets = demoRuntimeSecret
+  ? { DEMO_RUNTIME_SECRET: Secret.value(demoRuntimeSecret) }
+  : undefined;
+
+console.log("creating feature-tour session...");
+console.log(`optional mcp: ${mcpServers.length > 0 ? "enabled" : "disabled"}`);
+console.log(`optional runtime secret: ${environmentSecrets ? "enabled" : "disabled"}`);
+
+const session = await aex.openSession({
+  provider: Providers.DEEPSEEK,
+  model: Models.DEEPSEEK_V4_FLASH,
+  system: [
+    "You are a concise analytics agent.",
+    "Prefer exact calculations and write durable files for the caller."
+  ].join(" "),
+  agentsMd: [runRules],
+  files: [attachedFile],
+  includeBuiltinTools: false,
+  tools: [
+    BuiltinTools.read_file,
+    BuiltinTools.write_file,
+    BuiltinTools.bash,
+    BuiltinTools.grep,
+    BuiltinTools.code_execution,
+    metricLookup
+  ],
+  mcpServers,
+  environment: {
+    networking: { mode: "open" },
+    variables: {
+      FEATURE_TOUR: "true",
+      REPORT_DIR: "/workspace/outputs"
+    },
+    ...(environmentSecrets ? { secrets: environmentSecrets } : {})
+  },
+  outputs: {
+    allowedDirs: ["/workspace/outputs"],
+    deniedDirs: ["*.tmp"],
+    maxFiles: 10,
+    maxFileBytes: 1_000_000
+  },
+  outputMode: "stream",
+  runtime: Sizes.SHARED_0_25X_1GB,
+  metadata: {
+    example: "sdk-feature-tour",
+    sdkSurface: "public"
+  },
+  overrides: {
+    idleTtl: "5m",
+    timeout: "10m",
+    maxSpendUsd: 2
+  },
+  apiKeys: { deepseek: deepseekKey }
+});
+
+console.log(`session: ${session.id}`);
+
+const prompt = [
+  "Analyze the attached quarterly metrics.",
+  "Call metric_lookup for atlas, beacon, and cinder.",
+  "Create /workspace/outputs/feature-tour-report.md with a short table, a ranking by q2_revenue_usd, and two risks.",
+  "Create /workspace/outputs/summary.json with keys topProduct, totalQ2RevenueUsd, highestActivationProduct, and riskCount."
+].join(" ");
+
+const firstTurn = session.send(prompt);
+const firstTurnIterator = firstTurn[Symbol.asyncIterator]();
+let result: Awaited<ReturnType<typeof firstTurn.done>> | undefined;
+for (;;) {
+  const next = await firstTurnIterator.next();
+  if (next.done) {
+    result = next.value as Awaited<ReturnType<typeof firstTurn.done>>;
+    break;
+  }
+  const event = next.value;
+  if (isTextMessage(event)) {
+    process.stdout.write(event.data.text);
+  } else if (event.type === "TOOL_CALL_START") {
+    const name = typeof event.data.name === "string" ? event.data.name : "tool";
+    process.stdout.write(`\n[tool:start] ${name}\n`);
+  } else if (event.type === "TOOL_CALL_RESULT") {
+    process.stdout.write("[tool:result]\n");
+  }
+}
+
+if (!result) {
+  throw new Error("first turn stream ended without a result");
+}
+console.log(`\nfirst turn parked with status: ${result.status}`);
+
+const followUp = await session
+  .send("Read summary.json back and answer with one sentence confirming the top product and total Q2 revenue.")
+  .done();
+console.log(`follow-up status: ${followUp.status}`);
+if (followUp.text) {
+  console.log(`follow-up text: ${followUp.text.trim()}`);
+}
+
+const parked = await session.wait({ timeoutMs: 60_000, intervalMs: 2_000 });
+console.log(`settled session status: ${parked.status}`);
+
+const messages = await session.messages().list();
+console.log(`assistant messages: ${messages.length}`);
+
+const events = await session.events().list();
+console.log(`captured events: ${events.length}`);
+
+const outputs = await session.outputs().list();
+console.log("outputs:");
+for (const output of outputs) {
+  console.log(`- ${output.filename ?? output.id} (${output.contentType ?? "unknown"})`);
+}
+
+const summary = await session.outputs().read(
+  { path: "summary.json", match: "suffix" },
+  { maxBytes: 20_000 }
+);
+console.log("summary.json:");
+console.log(summary.text);
+
+const report = await session.outputs().findOne({
+  filename: "feature-tour-report.md"
+});
+if (report) {
+  const reportPreview = await session.outputs().read(report, {
+    maxBytes: 4_000,
+    grep: "risk"
+  });
+  console.log("report risk lines:");
+  console.log(reportPreview.text || "(no risk lines found)");
+}
+
+const reopenedOutputs = await aex.sessions.outputs(session.id).list();
+console.log(`outputs via aex.sessions.outputs(...): ${reopenedOutputs.length}`);
+
+if (downloadPath) {
+  const bytes = await session.download({ to: downloadPath });
+  console.log(`downloaded session archive: ${downloadPath} (${bytes.byteLength} bytes)`);
+}
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`Missing env var ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function handleFatal(err: unknown): void {
+  if (isRateLimited(err)) {
+    console.error(`rate limited after ${err.attempts} attempts; retry after ${err.retryAfterMs ?? "unknown"}ms`);
+    process.exit(1);
+  }
+  console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {

package/dist/_contracts/proxy-protocol.d.ts

@@ -1,305 +0,0 @@
-/**
- * Wire-protocol version. Bumped on any breaking change to the request or
- * response shape. The CLI sends this in the `X-Aex-Proxy-Protocol`
- * header on every request; the BFF rejects mismatches with HTTP 426
- * `unsupported_protocol`.
- *
- * Bumps are coordinated: CLI and BFF release together, the hosted API
- * bundles the matching CLI artifact, and the e2e suite runs both with
- * the new version.
- */
-export declare const PROXY_PROTOCOL_VERSION: "1";
-/**
- * Streaming named-proxy protocol. A client that sends `"2"` in
- * {@link PROXY_PROTOCOL_HEADER} opts into the streamed response path: the
- * hosted API pipes the upstream body back unbuffered (no base64, no
- * full-body JSON envelope) and carries the envelope metadata
- * in the `x-aex-proxy-*` response headers below instead of a JSON envelope.
- *
- * Additive: `"1"` stays valid and keeps the buffered
- * {@link ProxyResponseEnvelope}. Old runners keep working; new runners
- * stream. The version is on the request header so the hosted API can serve
- * both shapes without a coordinated CLI/BFF release.
- */
-export declare const PROXY_PROTOCOL_VERSION_V2: "2";
-export declare const PROXY_PROTOCOL_HEADER = "x-aex-proxy-protocol";
-/**
- * Response headers for the streamed (v2) named-proxy path. The hosted API sets
- * these BEFORE it starts streaming the upstream body, so the client can
- * reconstruct the same fields the v1 {@link ProxyResponseEnvelope} carried
- * without buffering. All values are plain strings; numeric fields are
- * decimal, booleans are `"true"`/`"false"`.
- */
-export declare const PROXY_RESP_STATUS_HEADER = "x-aex-proxy-status";
-export declare const PROXY_RESP_MODE_HEADER = "x-aex-proxy-effective-mode";
-/**
- * `"true"` when the cap forced truncation, `"false"` when the full body
- * fit, `"unknown"` when the upstream omitted `content-length` and the body
- * happened to reach the cap (can't distinguish exact-fit from over-cap
- * without buffering). See the streaming byte-cap note in proxy-routes.ts.
- */
-export declare const PROXY_RESP_TRUNCATED_HEADER = "x-aex-proxy-truncated";
-/** JSON object of lowercase upstream header names → values (mode-filtered). */
-export declare const PROXY_RESP_UPSTREAM_HEADERS_HEADER = "x-aex-proxy-upstream-headers";
-/**
- * Default `User-Agent` the proxy attaches to every outbound request when
- * the caller did not supply one via `allowHeaders`. Some upstreams reject
- * requests that arrive without a meaningful UA — notably the Wikimedia
- * family (Wikidata, Wikipedia, Wikimedia Commons), whose policy requires
- * a contactable identifier and otherwise returns HTTP 403 with a
- * `Please identify your user agent` body.
- *
- * Callers can override per request by listing `user-agent` in their
- * endpoint's `allowHeaders` and setting it on the proxy call; the
- * default only fires when nothing was forwarded.
- *
- * See <https://meta.wikimedia.org/wiki/User-Agent_policy>.
- */
-export declare const PROXY_DEFAULT_USER_AGENT = "aex-proxy/1.0 (+https://aex.dev/contact)";
-export declare const PROXY_METHOD_HEADER = "x-aex-method";
-export declare const PROXY_PATH_HEADER = "x-aex-path";
-export declare const PROXY_QUERY_HEADER = "x-aex-query";
-export declare const PROXY_HEADERS_HEADER = "x-aex-headers";
-export declare const PROXY_RESPONSE_MODE_HEADER = "x-aex-response-mode";
-export declare const PROXY_ALLOWED_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
-export type ProxyMethod = (typeof PROXY_ALLOWED_METHODS)[number];
-export declare const PROXY_RESPONSE_MODES: readonly ["status_only", "headers_only", "full"];
-export type ProxyResponseMode = (typeof PROXY_RESPONSE_MODES)[number];
-export declare const PROXY_RETRY_JITTERS: readonly ["full", "none"];
-export type ProxyRetryJitter = (typeof PROXY_RETRY_JITTERS)[number];
-export interface ProxyRetryPolicy {
-    /** Total attempts, including the initial request. */
-    readonly maxAttempts?: number;
-    readonly initialDelayMs?: number;
-    readonly maxDelayMs?: number;
-    readonly jitter?: ProxyRetryJitter;
-    readonly retryOnStatuses?: readonly number[];
-    readonly retryOnMethods?: readonly ProxyMethod[];
-    readonly respectRetryAfter?: boolean;
-}
-export type ResolvedProxyRetryPolicy = Required<ProxyRetryPolicy>;
-export declare const PROXY_RETRY_POLICY_DEFAULTS: ResolvedProxyRetryPolicy;
-export declare function resolveProxyRetryPolicy(policy: ProxyRetryPolicy): ResolvedProxyRetryPolicy;
-/**
- * Returns the narrower of the two response modes (lower width wins).
- * Pure function so the CLI and BFF can both call it without import cycles.
- */
-export declare function narrowResponseMode(policy: ProxyResponseMode, requested: ProxyResponseMode): ProxyResponseMode;
-/**
- * Error codes returned by the proxy route. Stable strings — the CLI
- * matches against them in scripts. Adding a new code is non-breaking;
- * removing or renaming an existing code requires a protocol bump.
- */
-export declare const PROXY_ERROR_CODES: readonly ["unsupported_protocol", "unauthorized", "endpoint_not_found", "policy_denied", "rate_limited", "ssrf_denied", "upstream_timeout", "upstream_error", "exceeded_cap", "bad_request", "internal_error"];
-export type ProxyErrorCode = (typeof PROXY_ERROR_CODES)[number];
-/**
- * Shape of the JSON written to the per-run manifest mounted inside
- * the container (`/mnt/session/uploads/aex/index.json`).
- *
- * Always present (every run), regardless of whether any proxy endpoints
- * were declared. With zero endpoints, `endpoints` is `[]` and
- * `proxyBaseUrl` is `null` — this keeps `aex --help` working
- * uniformly and makes the always-on surface observable in tests.
- *
- * Auth values NEVER appear in this file. The file is mounted into the
- * container; treat it as world-readable from the agent's perspective.
- */
-export interface ProxyIndexFile {
-    readonly protocolVersion: typeof PROXY_PROTOCOL_VERSION;
-    readonly runId: string;
-    readonly proxyBaseUrl: string | null;
-    readonly endpoints: readonly ProxyIndexEntry[];
-}
-export interface ProxyIndexEntry {
-    readonly name: string;
-    readonly baseUrl: string;
-    readonly authShape: ProxyAuthShape;
-    readonly allowMethods: readonly ProxyMethod[];
-    readonly allowPathPrefixes: readonly string[];
-    readonly allowHeaders: readonly string[];
-    readonly responseMode: ProxyResponseMode;
-    readonly maxRequestBytes: number;
-    readonly maxResponseBytes: number;
-    readonly timeoutMs: number;
-    readonly retry?: ResolvedProxyRetryPolicy;
-}
-/**
- * Default caps for a proxy endpoint when the submission doesn't specify one.
- * Lives in the protocol module (next to the index-file shape) so
- * {@link buildProxyIndexFile} can fill every optional cap with a concrete
- * value; the submission parser re-exports it.
- *
- * `maxResponseBytes: 0` means UNLIMITED — the v2 path streams the upstream body
- * unbuffered (O(1) memory regardless of size), so there is no cap to apply by
- * default. A customer can opt into a per-response truncation cap by setting a
- * positive value. There is no cumulative per-run call/byte budget: it needed a
- * per-call counter on the hot path and only existed to bound memory, which
- * streaming already does. The platform records named-proxy request bytes,
- * response bytes, attempts, and retries as run-log usage telemetry only; no
- * pricing/charging model is derived here.
- */
-export declare const PROXY_ENDPOINT_DEFAULTS: {
-    readonly allowHeaders: readonly string[];
-    readonly responseMode: ProxyResponseMode;
-    readonly maxRequestBytes: number;
-    readonly maxResponseBytes: 0;
-    readonly timeoutMs: number;
-};
-/**
- * Non-secret endpoint policy the index builder consumes. Structurally a
- * subset of `PlatformProxyEndpoint` (submission.ts) — declared here so the
- * protocol module stays free of an import cycle with the submission parser.
- */
-export interface ProxyEndpointPolicy {
-    readonly name: string;
-    readonly baseUrl: string;
-    readonly authShape: ProxyAuthShape;
-    readonly allowMethods: readonly ProxyMethod[];
-    readonly allowPathPrefixes: readonly string[];
-    readonly allowHeaders?: readonly string[];
-    readonly responseMode?: ProxyResponseMode;
-    readonly maxRequestBytes?: number;
-    readonly maxResponseBytes?: number;
-    readonly timeoutMs?: number;
-    readonly retry?: ProxyRetryPolicy;
-}
-export interface BuildProxyIndexFileInput {
-    readonly runId: string;
-    /**
-     * Hosted API origin that serves `/api/runs/:runId/proxy/:endpointName`.
-     * When unset
-     * (or empty) the run has no reachable proxy plane and `proxyBaseUrl`
-     * resolves to `null`.
-     */
-    readonly proxyPublicBaseUrl?: string;
-    readonly endpoints?: readonly ProxyEndpointPolicy[];
-}
-/**
- * Build the per-run {@link ProxyIndexFile} mounted into the container at
- * `/mnt/session/uploads/aex/index.json`. Pure: applies
- * {@link PROXY_ENDPOINT_DEFAULTS} so every optional cap is concrete, and
- * carries ONLY the non-secret endpoint policy — auth values never appear.
- *
- * ALWAYS emits a file (the always-on surface). With zero endpoints OR no
- * `proxyPublicBaseUrl`, `proxyBaseUrl` is `null` and `endpoints` is `[]`.
- * Otherwise `proxyBaseUrl` is `<trimmed base>/api/runs/<runId>/proxy`, the
- * prefix the in-container runtime bridge appends `/<endpointName>` to (proxy.ts).
- */
-export declare function buildProxyIndexFile(input: BuildProxyIndexFileInput): ProxyIndexFile;
-/**
- * Structural description of how the upstream endpoint expects auth.
- * The actual auth value lives in the run's Vault bundle under
- * `secrets.proxyEndpointAuth[i].value` and is never reflected back
- * into the container or index file.
- *
- * The `none` variant declares an upstream that takes no auth (public
- * APIs like Wikimedia Commons or NASA Images). It still routes through
- * the proxy for unified egress and audit, but
- * carries no `proxyEndpointAuth[]` entry and the BFF injects no
- * header or query value.
- */
-export type ProxyAuthShape = {
-    readonly type: "none";
-} | {
-    readonly type: "bearer";
-} | {
-    readonly type: "basic";
-} | {
-    readonly type: "header";
-    readonly name: string;
-} | {
-    readonly type: "query";
-    readonly name: string;
-};
-export type ProxyAuthType = ProxyAuthShape["type"];
-/**
- * Header name (lowercase) that an upstream auth shape uses as its
- * carrier. Returns `undefined` for query-based and keyless auth.
- *
- * Used by the submission parser to forbid `allowHeaders` from listing
- * the auth header (avoids leaks via caller-supplied headers), and by
- * the proxy route to strip any caller header that would collide with
- * the auth carrier at request time.
- */
-export declare function authShapeHeaderName(shape: ProxyAuthShape): string | undefined;
-/**
- * Query-string key that an upstream query-based auth shape uses as its
- * carrier. Returns `undefined` for non-query shapes (including "none").
- */
-export declare function authShapeQueryName(shape: ProxyAuthShape): string | undefined;
-/**
- * Inbound request headers every Aex proxy plane STRIPS before
- * forwarding a runtime/runner request upstream. Three categories:
- *
- *   - Credential carriers (`authorization`, `x-api-key`, `cookie`,
- *     `proxy-authorization`) — these belong to Aex's own auth gate
- *     (the per-run bearer) or to the caller, never the upstream. The
- *     legitimate upstream credential is injected server-side from the
- *     run's Vault bundle / endpoint auth shape AFTER this strip, so it is
- *     never sourced from an inbound header.
- *   - Hop-by-hop fields (RFC 7230 §6.1: `connection`, `keep-alive`,
- *     `transfer-encoding`, `te`, `trailer`, `upgrade`, `expect`,
- *     `proxy-authenticate`, `proxy-connection`) — must not survive a
- *     proxy hop.
- *   - Routing primitives a compromised runner could spoof to bypass an
- *     upstream's IP allowlist / rate-limit (`host`, `content-length`,
- *     `x-forwarded-*`, `x-real-ip`, `forwarded`).
- *
- * The platform API provider-proxy and the dashboard MCP proxy strip exactly
- * this set (both inject upstream auth separately — the provider key, or the
- * Vault MCP-bundle headers, applied AFTER the strip). The dashboard
- * customer HTTP proxy hard-denies this set MINUS `x-api-key`, because a
- * customer endpoint may legitimately declare `x-api-key` as its auth
- * carrier; it derives from this constant so the hop-by-hop + routing
- * entries never drift. Keeping the membership here is the single source of
- * truth that stops those surfaces diverging.
- */
-export declare const PROXY_STRIPPED_INBOUND_HEADERS: ReadonlySet<string>;
-/**
- * JSON body returned on a successful proxy call. The actual HTTP
- * response from the BFF to the CLI is always 200 once the BFF accepts
- * the request; the upstream's status/headers/body are reflected inside
- * this envelope so the CLI can decide what to write to stdout/stderr.
- */
-export interface ProxyResponseEnvelope {
-    readonly endpointName: string;
-    readonly upstreamStatus: number;
-    /** Lowercase header names → values. Allowlist-filtered by the BFF. */
-    readonly upstreamHeaders: Readonly<Record<string, string>>;
-    /**
-     * Base64-encoded upstream body. Present only when the effective
-     * response mode is `full`. Truncated to `maxResponseBytes`; if the
-     * upstream exceeded the cap, `truncated` is `true`.
-     */
-    readonly upstreamBodyBase64?: string;
-    readonly truncated?: boolean;
-    /**
-     * Echoed back so the CLI can warn the agent when its requested mode
-     * was clamped against the policy ceiling.
-     */
-    readonly effectiveResponseMode: ProxyResponseMode;
-    readonly modeClamped: boolean;
-}
-/**
- * JSON body returned on any error. The CLI emits this verbatim on
- * stderr and exits non-zero. Audit row carries the same `code`.
- */
-export interface ProxyErrorBody {
-    readonly error: ProxyErrorCode;
-    /** Human-readable message. Never includes auth values. */
-    readonly message: string;
-    /**
-     * Optional diagnostic fields. Always safe to surface — auth values
-     * and full URLs are stripped at the BFF.
-     */
-    readonly endpointName?: string;
-    readonly upstreamStatus?: number;
-    /** Server-supplied protocol version on `unsupported_protocol`. */
-    readonly serverProtocolVersion?: string;
-}
-/**
- * Status code → error code mapping used by the BFF to ensure the audit
- * row's error code and the HTTP response line up. Kept here so callers
- * can do a sanity check in tests.
- */
-export declare const PROXY_ERROR_HTTP_STATUS: Record<ProxyErrorCode, number>;