@aexhq/sdk 0.34.0 → 0.36.0

package/dist/retry.js

@@ -0,0 +1,320 @@
+/**
+ * Built-in transport resilience for the aex SDK.
+ *
+ * Every BFF-bound request the SDK makes goes through one {@link FetchLike}. This
+ * module wraps that fetch so a transient failure — an HTTP 429 (rate limited),
+ * a 500/502/503/504 (server hiccup), a 529 (upstream overloaded), or a network
+ * error — is retried with BOUNDED exponential backoff + full jitter, honoring
+ * the server's `Retry-After` header when present. Non-retryable 4xx responses
+ * (400/401/403/404/…) fail fast — retrying them only wastes the caller's time.
+ *
+ * Retries are SAFE to enable by default because the billable submits
+ * (`createSession` / `sendSessionMessage`) carry a stable `Idempotency-Key`
+ * header: re-sending the identical request de-duplicates server-side, so a retry
+ * never creates a duplicate billable turn.
+ *
+ * When retries are exhausted on a rate-limit / overloaded status the wrapper
+ * surfaces an {@link AexRateLimitError} — a structured, non-leaky throttle error
+ * carrying the parsed `retryAfterMs`, the attempt count, and (when the runtime
+ * supplies it) an upstream {@link ProviderFault}. All other exhausted retries
+ * fall through to the transport's usual `AexApiError` / network rejection.
+ */
+import { AexApiError } from "./_contracts/index.js";
+/**
+ * HTTP statuses that are transient and worth retrying. The billable submits
+ * carry an idempotency key, so re-issuing them is safe. Everything not in this
+ * set (400/401/403/404/409/422/…) is a definitive client error and fails fast.
+ */
+export const RETRYABLE_STATUS = [429, 500, 502, 503, 504, 529];
+/**
+ * The subset of {@link RETRYABLE_STATUS} the platform / upstream provider uses to
+ * say "slow down": 429 rate-limit, 503 unavailable, 529 overloaded. When retries
+ * for one of these run out, the wrapper raises an {@link AexRateLimitError}.
+ */
+export const RATE_LIMIT_STATUS = [429, 503, 529];
+const DEFAULT_RETRY = {
+    maxAttempts: 4,
+    initialDelayMs: 500,
+    maxDelayMs: 20_000,
+    maxElapsedMs: 120_000
+};
+/** Resolve caller options over the defaults, clamping to sane bounds. */
+export function resolveRetryConfig(options) {
+    const maxAttempts = Math.max(1, Math.floor(options?.maxAttempts ?? DEFAULT_RETRY.maxAttempts));
+    const initialDelayMs = Math.max(0, options?.initialDelayMs ?? DEFAULT_RETRY.initialDelayMs);
+    const maxDelayMs = Math.max(initialDelayMs, options?.maxDelayMs ?? DEFAULT_RETRY.maxDelayMs);
+    const maxElapsedMs = Math.max(0, options?.maxElapsedMs ?? DEFAULT_RETRY.maxElapsedMs);
+    return { maxAttempts, initialDelayMs, maxDelayMs, maxElapsedMs };
+}
+export function isRetryableStatus(status) {
+    return RETRYABLE_STATUS.includes(status);
+}
+export function isRateLimitStatus(status) {
+    return RATE_LIMIT_STATUS.includes(status);
+}
+/**
+ * Parse an HTTP `Retry-After` header into milliseconds. Per RFC 7231 the value
+ * is either a non-negative integer number of seconds or an HTTP-date; both are
+ * handled. Returns `undefined` for a missing or unparseable value.
+ */
+export function parseRetryAfterMs(headerValue, now = Date.now()) {
+    if (headerValue === null || headerValue === undefined)
+        return undefined;
+    const trimmed = headerValue.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - now);
+    }
+    return undefined;
+}
+/**
+ * Full-jitter exponential backoff (AWS-style): the nominal wait doubles per
+ * retry up to `maxDelayMs`, and the actual wait is a uniform sample in
+ * `[0, nominal]` to de-correlate concurrent clients. `attemptNumber` is the
+ * 1-based number of the attempt that just failed.
+ */
+export function computeBackoffDelayMs(config, attemptNumber, random) {
+    const exponent = Math.max(0, attemptNumber - 1);
+    const nominal = Math.min(config.maxDelayMs, config.initialDelayMs * 2 ** exponent);
+    return Math.round(random() * nominal);
+}
+/** Combine the server's `Retry-After` (a floor) with our jittered backoff. */
+function nextDelayMs(config, attemptNumber, random, retryAfterMs) {
+    const backoff = computeBackoffDelayMs(config, attemptNumber, random);
+    return retryAfterMs === undefined ? backoff : Math.max(retryAfterMs, backoff);
+}
+const THROTTLE_KINDS = new Set(["rate_limit", "overloaded", "quota_exceeded"]);
+/** True when a {@link ProviderFault} represents a "back off and retry" signal. */
+export function isThrottleFault(fault) {
+    return THROTTLE_KINDS.has(fault.kind);
+}
+/**
+ * Structured throttle error. Extends {@link AexApiError} so existing
+ * `catch (err instanceof AexApiError)` sites keep working, while callers that
+ * want the details narrow with {@link isRateLimited} and read `retryAfterMs`,
+ * `attempts`, `source`, and `providerFault`. The `message` is a fixed,
+ * non-leaky summary — it never echoes the raw error body (which is still
+ * available, redacted, on `.body`).
+ */
+export class AexRateLimitError extends AexApiError {
+    /** Milliseconds the server/provider asked us to wait, when known. */
+    retryAfterMs;
+    /** How many attempts were made before giving up. */
+    attempts;
+    /** Whether the throttle came from the aex API plane or the upstream provider. */
+    source;
+    /** The upstream provider fault, when the throttle originated there. */
+    providerFault;
+    constructor(args) {
+        super(args.status, args.message ?? defaultThrottleMessage(args), args.body);
+        this.attempts = args.attempts;
+        this.source = args.source ?? "api";
+        if (args.retryAfterMs !== undefined)
+            this.retryAfterMs = args.retryAfterMs;
+        if (args.providerFault !== undefined)
+            this.providerFault = args.providerFault;
+    }
+}
+/** Type guard for {@link AexRateLimitError}. */
+export function isRateLimited(err) {
+    return err instanceof AexRateLimitError;
+}
+function defaultThrottleMessage(args) {
+    const who = args.source === "provider" ? "upstream provider" : "aex API";
+    const label = args.status === 529 ? "overloaded" : "rate limit reached";
+    const attempts = `${args.attempts} attempt${args.attempts === 1 ? "" : "s"}`;
+    const wait = args.retryAfterMs !== undefined
+        ? `; retry after ~${Math.ceil(args.retryAfterMs / 1000)}s`
+        : "";
+    return `${who} ${label} (HTTP ${args.status}) after ${attempts}${wait}`;
+}
+/**
+ * Best-effort parse of an unknown value into a {@link ProviderFault}. Tolerant
+ * of two shapes so the SDK consumes the runtime fault the moment it starts
+ * emitting one, without a contracts change:
+ *
+ *   1. The canonical `{ provider?, kind, status?, retryAfterMs?, message? }`
+ *      (optionally nested under a `providerFault` key), OR
+ *   2. A raw upstream error `{ type: "rate_limit_error" | "overloaded_error"
+ *      | ..., message?, retry_after? | retryAfter? }` — `type` maps to `kind`
+ *      and `retry_after` (seconds) maps to `retryAfterMs`.
+ *
+ * Returns `undefined` when the value carries no recognizable fault.
+ */
+export function parseProviderFault(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const nested = record.providerFault ?? record.provider_fault;
+    if (nested !== undefined && nested !== value) {
+        const fromNested = parseProviderFault(nested);
+        if (fromNested)
+            return fromNested;
+    }
+    const kind = coerceFaultKind(record.kind ?? record.type ?? record.code);
+    if (kind === undefined)
+        return undefined;
+    const provider = typeof record.provider === "string" ? record.provider : undefined;
+    const status = coerceStatus(record.status ?? record.statusCode ?? record.httpStatus);
+    const retryAfterMs = coerceRetryAfterMs(record.retryAfterMs ?? record.retry_after_ms ?? record.retryAfter ?? record.retry_after);
+    const message = typeof record.message === "string" ? record.message : undefined;
+    return {
+        kind,
+        ...(provider !== undefined ? { provider } : {}),
+        ...(status !== undefined ? { status } : {}),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(message !== undefined ? { message } : {})
+    };
+}
+function coerceFaultKind(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const value = raw.toLowerCase();
+    if (value.includes("rate_limit") || value.includes("rate limit") || value === "429")
+        return "rate_limit";
+    if (value.includes("overload") || value === "529")
+        return "overloaded";
+    if (value.includes("quota") || value.includes("insufficient"))
+        return "quota_exceeded";
+    if (value.includes("provider_error") || value.includes("provider error") || value.includes("api_error")) {
+        return "provider_error";
+    }
+    return undefined;
+}
+function coerceStatus(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim()))
+        return Number(raw.trim());
+    return undefined;
+}
+/** Accept a ms number, a `<digits>` string, or seconds under a `retry_after` alias. */
+function coerceRetryAfterMs(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        // Heuristic: small integers are seconds (the upstream convention), large
+        // ones are already milliseconds.
+        return raw > 0 && raw < 1000 ? raw * 1000 : raw;
+    }
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim())) {
+        const n = Number(raw.trim());
+        return n > 0 && n < 1000 ? n * 1000 : n;
+    }
+    return undefined;
+}
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+function isAbortError(err) {
+    return err instanceof Error && err.name === "AbortError";
+}
+async function drain(response) {
+    try {
+        if (response.body && typeof response.body.cancel === "function") {
+            await response.body.cancel();
+            return;
+        }
+        await response.text();
+    }
+    catch {
+        // Draining is best-effort; a discarded retryable response never surfaces.
+    }
+}
+async function readBodyForError(response) {
+    try {
+        const text = await response.text();
+        if (text.length === 0)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { raw: text };
+        }
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Wrap a {@link FetchLike} with the bounded-retry loop. `retry === false`
+ * disables the layer entirely (the input fetch is returned unchanged). Otherwise
+ * the returned fetch retries transient failures per {@link RetryOptions} and, on
+ * an exhausted rate-limit/overloaded status, throws {@link AexRateLimitError}.
+ */
+export function withRetry(fetchImpl, retry, deps = {}) {
+    if (retry === false)
+        return fetchImpl;
+    const config = resolveRetryConfig(retry);
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const now = deps.now ?? Date.now;
+    return async (input, init) => {
+        const startedAt = now();
+        const signal = init?.signal ?? undefined;
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            let response;
+            try {
+                response = await fetchImpl(input, init);
+            }
+            catch (err) {
+                // A caller-initiated abort is terminal, never transient.
+                if (isAbortError(err))
+                    throw err;
+                if (attempt >= config.maxAttempts)
+                    throw err;
+                const delay = computeBackoffDelayMs(config, attempt, random);
+                if (now() - startedAt + delay > config.maxElapsedMs)
+                    throw err;
+                await sleep(delay, signal ?? undefined);
+                continue;
+            }
+            // Success or a definitive (non-retryable) response — hand straight back so
+            // the transport reads/throws exactly as it does without the retry layer.
+            if (!isRetryableStatus(response.status)) {
+                return response;
+            }
+            const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"), now());
+            const willRetry = attempt < config.maxAttempts &&
+                now() - startedAt + nextDelayMs(config, attempt, random, retryAfterMs) <= config.maxElapsedMs;
+            if (willRetry) {
+                await drain(response);
+                await sleep(nextDelayMs(config, attempt, random, retryAfterMs), signal ?? undefined);
+                continue;
+            }
+            // Retries exhausted (or budget spent). A rate-limit/overloaded status
+            // becomes a structured throttle error; any other transient status falls
+            // through to the transport's normal AexApiError.
+            if (isRateLimitStatus(response.status)) {
+                const body = await readBodyForError(response);
+                throw new AexRateLimitError({
+                    status: response.status,
+                    attempts: attempt,
+                    source: "api",
+                    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+                    body
+                });
+            }
+            return response;
+        }
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

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

package/dist/secret.d.ts

@@ -12,7 +12,7 @@ export type SecretEnvSubmissionEntry = {
 };
 /**
  * Minimal client surface `secret.upload` needs to promote an ephemeral secret
- * into the workspace store. `AgentExecutor` satisfies it via its `secrets`
+ * into the workspace store. `Aex` satisfies it via its `secrets`
  * client; defined structurally here so `secret.ts` does not import `client.ts`
  * (which would be circular — `client.ts` imports `Secret`). Mirrors
  * {@link SkillUploader}.
@@ -88,7 +88,7 @@ export declare class Secret {
 /**
  * Split `secretEnv: Record<envName, Secret>` into the value-free declarations
  * (`submission.secretEnv`) and the per-run vaulted values
- * (`secrets.envSecrets`). Mirrors {@link splitProxyEndpoints}: declarations ride
+ * (`secrets.envSecrets`). Secret declarations ride
  * the hashed submission, ephemeral values ride the secrets channel
  * (hash-excluded). Refs contribute only a declaration.
  *

package/dist/secret.js

@@ -116,7 +116,7 @@ export class Secret {
 /**
  * Split `secretEnv: Record<envName, Secret>` into the value-free declarations
  * (`submission.secretEnv`) and the per-run vaulted values
- * (`secrets.envSecrets`). Mirrors {@link splitProxyEndpoints}: declarations ride
+ * (`secrets.envSecrets`). Secret declarations ride
  * the hashed submission, ephemeral values ride the secrets channel
  * (hash-excluded). Refs contribute only a declaration.
  *

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export declare const SDK_VERSION = "0.34.0";
+export declare const SDK_VERSION = "0.36.0";

package/dist/version.js

@@ -6,5 +6,5 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export const SDK_VERSION = "0.34.0";
+export const SDK_VERSION = "0.36.0";
 //# sourceMappingURL=version.js.map

package/docs/concepts/composition.md

@@ -14,11 +14,11 @@ runtime before the first agent turn.
 | Agent instructions | `AgentsMd.fromPath`, `AgentsMd.fromContent` |
 | Reference files and folders | `File.fromPath`, `File.fromBytes` |
 | Remote tools | `McpServer.remote`, `McpServer.fromId` |
-| Credentialed HTTP APIs | `ProxyEndpoint.none`, `bearer`, `basic`, `header`, `query` |
 | Non-secret runtime settings | `environment.variables`, `environment.packages`, `environment.networking` |
+| Runtime secrets for your code | `Secret.value`, `Secret.ref`, `environment.secrets` |
 
 ```ts
-import { AgentsMd, File, McpServer, Models, ProxyEndpoint, Tools } from "@aexhq/sdk";
+import { AgentsMd, File, McpServer, Models, Secret, Tools } from "@aexhq/sdk";
 
 await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
@@ -27,20 +27,14 @@ await aex.run({
   files: [await File.fromPath("./input")],
   tools: [await Tools.fromSkillDir("./skills/report-writer", { name: "report-writer" })],
   mcpServers: [McpServer.remote({ name: "github", url: "https://example.com/mcp" })],
-  proxyEndpoints: [
-    ProxyEndpoint.bearer({
-      name: "internal-api",
-      baseUrl: "https://api.example.com",
-      token: process.env.INTERNAL_API_TOKEN!,
-      allowMethods: ["GET"],
-      allowPathPrefixes: ["/v1/"]
-    })
-  ],
+  environment: {
+    secrets: { INTERNAL_API_TOKEN: Secret.value(process.env.INTERNAL_API_TOKEN!) },
+    networking: { mode: "limited", allowedHosts: ["api.example.com"] }
+  },
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
 Secrets stay out of reusable configs. Provider keys go in the top-level `apiKeys`
-map; MCP auth rides on each `McpServer` instance and proxy auth on each
-`ProxyEndpoint` instance — the SDK splits them into the vaulted secrets channel
-server-side, so they never live in a shareable config object.
+map; reusable or per-run values for your own code go in `environment.secrets`.
+Your code then makes normal HTTP calls with the standard client for that service.

package/docs/credentials.md

@@ -4,142 +4,100 @@ title: Credentials
 
 # Credentials
 
-aex treats provider keys, MCP credentials, and proxy endpoint auth as per-run
-credentials. Reusable env secrets are documented separately in
-[Secrets](secrets.md).
+aex uses explicit, per-session credentials:
 
-The caller passes a workspace-scoped SDK token and the provider key inline on every `openSession` / `run` call. aex holds the bundle in run-scoped custody for the session lifecycle and attempts terminal cleanup/revocation for the aex-controlled references. MCP credentials and proxy endpoint auth values travel the same way.
+- `AEX_API_TOKEN` authenticates the SDK or CLI to aex.
+- `apiKeys` carries BYOK provider keys for the model provider.
+- `McpServer.remote(..., { headers })` carries MCP auth when a remote MCP server needs it.
+- `environment.secrets` carries runtime secrets for your own code.
 
-A session selects one upstream `provider` (default `anthropic`) and must carry a BYOK
-key for it. Keys are supplied per-provider so a session can also hold keys for the
-**other** providers its subagents may use:
+Secrets never belong in reusable run config, files, prompts, or examples.
 
-| Field | Required secret |
-| --- | --- |
-| Provider API keys | `apiKeys` (top-level, keyed by provider) |
+## Provider keys
+
+A session selects one upstream provider and must carry a BYOK key for it. Include
+additional provider keys only when subagents may use those providers.
 
 ```ts
-// The session's own provider key, plus extra keys its subagents can use.
-apiKeys: {
-  anthropic: process.env.ANTHROPIC_API_KEY!, // the session's provider
-  deepseek: process.env.DEEPSEEK_API_KEY!     // for a cross-provider subagent
-}
+const result = await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "Write a short report and save it as a file.",
+  apiKeys: {
+    anthropic: process.env.ANTHROPIC_API_KEY!
+  }
+});
 ```
 
-A `subagent` spawned with a different-family model **inherits the parent's keys
-server-side** from the session's vaulted bundle — the keys never transit the
-container. If the parent holds no key for the child's provider, the child is
-rejected with `parent_missing_provider_key`.
-
-MCP credential types:
-
-- `static_bearer`;
-- `oauth_access_token`.
+Provider keys are used by the managed runtime for model calls. They are not saved
+as client defaults.
 
-Unsupported:
+## Runtime secrets
 
-- arbitrary headers;
-- OAuth refresh;
-- persisted aex vault.
-
-For managed-runtime runs, aex injects the matching BYOK provider key at the hosted provider-proxy. Provider-side sessions and data remain subject to the selected provider account's retention and deletion policies.
-
-## Proxy endpoints (per-run custom HTTP credentials)
-
-Some skills need to call non-MCP HTTP services (e.g. Stripe, internal APIs). Embedding the credential in the skill content puts the raw secret on disk in the agent container and in the model's context — both prompt-injection-readable.
-
-The platform's managed HTTP proxy is the agent-first alternative. Declare each endpoint with a `ProxyEndpoint.*` constructor: the instance carries the non-secret **policy** (hashed for idempotency) and its **auth token** together at the call site. The SDK splits the token into the vaulted secrets channel server-side (not hashed, so key rotation does not collapse onto a stale run), and the raw credential value never enters the container.
+Use `environment.secrets` for credentials your code needs at runtime. The value
+can be ephemeral with `Secret.value(...)` or a workspace secret reference with
+`Secret.ref(...)`.
 
 ```ts
-import { Aex, Models, ProxyEndpoint } from "@aexhq/sdk";
+import { Aex, Models, Secret } from "@aexhq/sdk";
 
-const aex = new Aex({
-  apiToken: "ant_..."
-});
-
-const stripe = ProxyEndpoint.bearer({
-  name: "stripe",
-  baseUrl: "https://api.stripe.com",
-  token: process.env.STRIPE_API_KEY!,
-  allowMethods: ["GET", "POST"],
-  allowPathPrefixes: ["/v1/charges", "/v1/refunds"],
-  maxRequestBytes: 65_536,
-  maxResponseBytes: 65_536,
-  timeoutMs: 10_000,
-  responseMode: "headers_only",
-  retry: {
-    maxAttempts: 3,
-    initialDelayMs: 250,
-    maxDelayMs: 5000,
-    jitter: "full",
-    retryOnStatuses: [408, 425, 429, 500, 502, 503, 504],
-    retryOnMethods: ["GET", "HEAD"],
-    respectRetryAfter: true
-  }
-});
+const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
 
 await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  message: "…",
-  proxyEndpoints: [stripe],
+  message: "Call https://api.example.com/v1/status with INTERNAL_API_TOKEN and summarize it.",
+  environment: {
+    secrets: {
+      INTERNAL_API_TOKEN: Secret.value(process.env.INTERNAL_API_TOKEN!)
+    },
+    networking: {
+      mode: "limited",
+      allowedHosts: ["api.example.com"]
+    }
+  },
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
-The five constructors — `ProxyEndpoint.none` / `bearer` / `header` / `basic` / `query` — put the auth secret on the same call as the policy, so any drift (wrong `responseMode`, misnamed auth field) is a TypeScript error at the call site instead of an HTTP 400 a round-trip later.
-
-Inside the run container, every session has the platform CLI mounted at `/mnt/session/uploads/aex/aex` (a Bun-compatible ESM bundle) and a manifest at `/mnt/session/uploads/aex/index.json` describing the declared endpoints. The skill invokes the CLI through `bun` (the mount has no execute permission so direct invocation fails with `bad interpreter: Permission denied`):
+Inside the run, use normal HTTP code for the service:
 
 ```bash
-bun /mnt/session/uploads/aex/aex proxy stripe \
-  --method GET \
-  --path /v1/charges/ch_123 \
-  --response-mode headers_only
+curl -sS \
+  -H "Authorization: Bearer $INTERNAL_API_TOKEN" \
+  https://api.example.com/v1/status
 ```
 
-The CLI reads the per-run bearer from `/mnt/session/uploads/aex/run-token`, attaches the `X-Aex-Proxy-Protocol` header, and the hosted proxy injects the bearer/header/query/basic credential before dispatching the outbound call. Only the response (subject to `responseMode` and `maxResponseBytes`) reaches the container. `--response-mode` can only narrow below the policy ceiling.
+## Workspace secrets
 
-Retries are declaration-based. Add `retry` to the endpoint policy when safe for that upstream; runs without `retry` keep single-attempt behavior. `maxAttempts` counts the initial request, and defaults apply only when `retry` is present: `maxAttempts: 3`, `initialDelayMs: 250`, `maxDelayMs: 5000`, `jitter: "full"`, `retryOnStatuses: [408, 425, 429, 500, 502, 503, 504]`, `retryOnMethods: ["GET", "HEAD"]`, and `respectRetryAfter: true`. There are no per-call `aex proxy` retry flags.
-
-#### Keyless upstreams (`authShape: { type: "none" }`)
-
-For public APIs that take no credential (Wikimedia Commons, Internet Archive, Library of Congress, NASA Images, NARA, GDELT, etc.), declare the endpoint with `ProxyEndpoint.none(...)` — it produces only a declaration, no auth token:
+Store reusable values once, then reference them by name:
 
 ```ts
-import { ProxyEndpoint } from "@aexhq/sdk";
-
-const wikimedia = ProxyEndpoint.none({
-  name: "wikimedia",
-  baseUrl: "https://commons.wikimedia.org",
-  allowMethods: ["GET"],
-  allowPathPrefixes: ["/wiki/", "/w/api.php"]
+await aex.secrets.set({
+  name: "internal-api-token",
+  value: process.env.INTERNAL_API_TOKEN!
 });
 
 await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  message: "…",
-  proxyEndpoints: [wikimedia],
+  message: "Use INTERNAL_API_TOKEN for the status request.",
+  environment: {
+    secrets: {
+      INTERNAL_API_TOKEN: Secret.ref("internal-api-token")
+    }
+  },
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
-The keyless endpoint still routes through the aex managed proxy: every call is allow-listed, audited, and redacted. The hosted proxy injects no `Authorization` header and no query-string credential.
+Secret reads return metadata only; they never return the stored value.
 
-`bun /mnt/session/uploads/aex/aex --help` reads endpoint details from `/mnt/session/uploads/aex/index.json`. Runs that do not declare any `proxyEndpoints` still have the CLI and an empty manifest mounted, so agents never need to introspect whether the surface exists.
+## Networking
 
-### Networking
-
-Networking is open by default. When a run explicitly uses `limited` networking,
-the platform host must appear in `allowed_hosts`. aex injects it
-automatically; for advance validation use:
-
-```ts
-const allowedHosts = buildPlatformAllowedHosts({
-  baseUrl: "https://api.aex.dev",
-  extraHosts: ["api.stripe.com"]
-});
-```
+Networking is open by default. Use `environment.networking.mode: "limited"` with
+`allowedHosts` when you want a run to reach only named public hosts. See
+[Networking](networking.md).
 
-### Secrets are always explicit at the call site
+## Explicit call-site rule
 
-There is no `defaultSecrets` and no client-held secret state. Every `openSession` / `run` call carries its own credentials at the call site: the top-level `apiKeys` map (one provider key, plus any subagent keys), MCP auth on each `McpServer` instance, and proxy auth on each `ProxyEndpoint` instance. This is the agent-first invariant: the credentials being used on any given call are visible in the same code that opens the session.
+There is no `defaultSecrets` and no client-held secret state. Each
+`openSession(...)` or `run(...)` call should show the provider keys, MCP auth, and
+runtime secrets needed for that call.

package/docs/defaults.md

@@ -39,14 +39,6 @@ For the hard ceilings and who can raise them, see
 | MCP connect timeout (register + initialize + discover) | 30 seconds | Per-port via `connectTimeoutMs`. | `RUN_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
 | MCP `tools/call` timeout | 30 minutes | Per-port via `callTimeoutMs`. | `RUN_DEFAULT_MCP_CALL_TIMEOUT_MS` |
 
-## Proxy endpoints
-
-| Option | Default | How to override | Source |
-| --- | --- | --- | --- |
-| `maxRequestBytes` | 10 MiB | Per-endpoint via the endpoint's `maxRequestBytes`. | `REQUEST_PROXY_DEFAULT_MAX_REQUEST_BYTES` |
-| `maxResponseBytes` | `0` (unlimited — the response is streamed unbuffered) | Per-endpoint via the endpoint's `maxResponseBytes`. | `REQUEST_PROXY_DEFAULT_MAX_RESPONSE_BYTES` |
-| `timeoutMs` (upstream) | 5 minutes | Per-endpoint via the endpoint's `timeoutMs`. | `REQUEST_PROXY_DEFAULT_TIMEOUT_MS` |
-
 ## Links (signed URLs and tickets)
 
 | Option | Default | How to override | Source |