@aexhq/sdk 0.34.0 → 0.36.0

package/dist/_contracts/proxy-protocol.js

@@ -1,297 +0,0 @@
-// Wire format between the in-container runtime bridge (mounted at
-// `/mnt/session/uploads/aex/aex`, invoked through `bun`) and
-// the hosted API's named proxy route
-// (`POST /api/runs/:runId/proxy/:endpointName`).
-//
-// This module is the single source of truth for the request shape, the
-// response shape, the error-code enum, and the protocol version header.
-// CLI and BFF both import from here; drift becomes a build-time type error.
-//
-/**
- * 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 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 const PROXY_PROTOCOL_VERSION_V2 = "2";
-export 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 const PROXY_RESP_STATUS_HEADER = "x-aex-proxy-status";
-export 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 const PROXY_RESP_TRUNCATED_HEADER = "x-aex-proxy-truncated";
-/** JSON object of lowercase upstream header names → values (mode-filtered). */
-export 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 const PROXY_DEFAULT_USER_AGENT = "aex-proxy/1.0 (+https://aex.dev/contact)";
-export const PROXY_METHOD_HEADER = "x-aex-method";
-export const PROXY_PATH_HEADER = "x-aex-path";
-export const PROXY_QUERY_HEADER = "x-aex-query";
-export const PROXY_HEADERS_HEADER = "x-aex-headers";
-export const PROXY_RESPONSE_MODE_HEADER = "x-aex-response-mode";
-export const PROXY_ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
-export const PROXY_RESPONSE_MODES = ["status_only", "headers_only", "full"];
-export const PROXY_RETRY_JITTERS = ["full", "none"];
-export const PROXY_RETRY_POLICY_DEFAULTS = {
-    maxAttempts: 3,
-    initialDelayMs: 250,
-    maxDelayMs: 5000,
-    jitter: "full",
-    retryOnStatuses: [408, 425, 429, 500, 502, 503, 504],
-    retryOnMethods: ["GET", "HEAD"],
-    respectRetryAfter: true
-};
-export function resolveProxyRetryPolicy(policy) {
-    return {
-        maxAttempts: policy.maxAttempts ?? PROXY_RETRY_POLICY_DEFAULTS.maxAttempts,
-        initialDelayMs: policy.initialDelayMs ?? PROXY_RETRY_POLICY_DEFAULTS.initialDelayMs,
-        maxDelayMs: policy.maxDelayMs ?? PROXY_RETRY_POLICY_DEFAULTS.maxDelayMs,
-        jitter: policy.jitter ?? PROXY_RETRY_POLICY_DEFAULTS.jitter,
-        retryOnStatuses: policy.retryOnStatuses ?? PROXY_RETRY_POLICY_DEFAULTS.retryOnStatuses,
-        retryOnMethods: policy.retryOnMethods ?? PROXY_RETRY_POLICY_DEFAULTS.retryOnMethods,
-        respectRetryAfter: policy.respectRetryAfter ?? PROXY_RETRY_POLICY_DEFAULTS.respectRetryAfter
-    };
-}
-/**
- * Narrowing order: a request may only narrow below the policy ceiling.
- * `status_only` is narrowest, `full` is widest. The BFF computes
- * `narrowest(policyMode, headerMode)` and ignores escalation attempts,
- * auditing them as `mode_clamped`.
- */
-const RESPONSE_MODE_WIDTH = {
-    status_only: 0,
-    headers_only: 1,
-    full: 2
-};
-/**
- * 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 function narrowResponseMode(policy, requested) {
-    return RESPONSE_MODE_WIDTH[requested] < RESPONSE_MODE_WIDTH[policy] ? requested : policy;
-}
-/**
- * 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 const PROXY_ERROR_CODES = [
-    "unsupported_protocol",
-    "unauthorized",
-    "endpoint_not_found",
-    "policy_denied",
-    "rate_limited",
-    "ssrf_denied",
-    "upstream_timeout",
-    "upstream_error",
-    "exceeded_cap",
-    "bad_request",
-    "internal_error"
-];
-/**
- * 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 const PROXY_ENDPOINT_DEFAULTS = {
-    allowHeaders: [],
-    responseMode: "headers_only",
-    // 10 MiB. The body is buffered in the hosted API to enforce this cap, while the
-    // launch default fits practical multimodal/tool POSTs without every endpoint
-    // needing an override.
-    maxRequestBytes: 10 * 1024 * 1024,
-    // Unlimited (0). The request body is buffered to enforce its cap, so that
-    // stays finite; the response is streamed, so it does not need one.
-    maxResponseBytes: 0,
-    // 5 minutes. Long-running upstream tool/model calls should not fail under a
-    // development-oriented 10s ceiling; endpoints can still set a smaller value.
-    timeoutMs: 5 * 60 * 1000
-};
-/**
- * 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 function buildProxyIndexFile(input) {
-    const endpoints = input.endpoints ?? [];
-    const base = input.proxyPublicBaseUrl?.trim() ?? "";
-    const haveBase = base.length > 0;
-    const proxyBaseUrl = endpoints.length > 0 && haveBase
-        ? `${base.replace(/\/+$/, "")}/api/runs/${input.runId}/proxy`
-        : null;
-    return {
-        protocolVersion: PROXY_PROTOCOL_VERSION,
-        runId: input.runId,
-        proxyBaseUrl,
-        endpoints: endpoints.map((e) => ({
-            name: e.name,
-            baseUrl: e.baseUrl,
-            authShape: e.authShape,
-            allowMethods: e.allowMethods,
-            allowPathPrefixes: e.allowPathPrefixes,
-            allowHeaders: e.allowHeaders ?? PROXY_ENDPOINT_DEFAULTS.allowHeaders,
-            responseMode: e.responseMode ?? PROXY_ENDPOINT_DEFAULTS.responseMode,
-            maxRequestBytes: e.maxRequestBytes ?? PROXY_ENDPOINT_DEFAULTS.maxRequestBytes,
-            maxResponseBytes: e.maxResponseBytes ?? PROXY_ENDPOINT_DEFAULTS.maxResponseBytes,
-            timeoutMs: e.timeoutMs ?? PROXY_ENDPOINT_DEFAULTS.timeoutMs,
-            ...(e.retry !== undefined ? { retry: resolveProxyRetryPolicy(e.retry) } : {})
-        }))
-    };
-}
-/**
- * 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 function authShapeHeaderName(shape) {
-    switch (shape.type) {
-        case "bearer":
-        case "basic":
-            return "authorization";
-        case "header":
-            return shape.name.toLowerCase();
-        case "query":
-        case "none":
-            return undefined;
-    }
-}
-/**
- * Query-string key that an upstream query-based auth shape uses as its
- * carrier. Returns `undefined` for non-query shapes (including "none").
- */
-export function authShapeQueryName(shape) {
-    return shape.type === "query" ? shape.name : 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 const PROXY_STRIPPED_INBOUND_HEADERS = new Set([
-    // credential carriers
-    "authorization",
-    "x-api-key",
-    "cookie",
-    "proxy-authorization",
-    // hop-by-hop (RFC 7230 §6.1)
-    "connection",
-    "keep-alive",
-    "transfer-encoding",
-    "te",
-    "trailer",
-    "upgrade",
-    "expect",
-    "proxy-authenticate",
-    "proxy-connection",
-    // routing primitives a runner could spoof
-    "host",
-    "content-length",
-    "x-forwarded-for",
-    "x-forwarded-host",
-    "x-forwarded-proto",
-    "x-forwarded-port",
-    "x-real-ip",
-    "forwarded"
-]);
-/**
- * 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 const PROXY_ERROR_HTTP_STATUS = {
-    unsupported_protocol: 426,
-    unauthorized: 401,
-    endpoint_not_found: 404,
-    policy_denied: 403,
-    rate_limited: 429,
-    ssrf_denied: 403,
-    upstream_timeout: 504,
-    upstream_error: 502,
-    exceeded_cap: 502,
-    bad_request: 400,
-    internal_error: 500
-};
-//# sourceMappingURL=proxy-protocol.js.map

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

@@ -1,19 +0,0 @@
-import type { PlatformProxyEndpoint, PlatformProxyEndpointAuth } from "./submission.js";
-/**
- * Cross-validate a `proxyEndpoints` policy list against a
- * `secrets.proxyEndpointAuth` value list. Throws on the first mismatch
- * with an actionable, field-named error message.
- *
- * Mirrors the BFF's authoritative validator so misconfigured submissions
- * fail fast in the SDK/CLI before going over the wire.
- */
-export declare function validateProxyAuth(endpoints: readonly PlatformProxyEndpoint[], auth: readonly PlatformProxyEndpointAuth[] | undefined): void;
-/**
- * Build an `allowedHosts` list for `environment.network` that includes
- * the aex proxy host (and optionally Anthropic's MCP host) when the
- * caller is hand-rolling networking.
- */
-export declare function buildPlatformAllowedHosts(input: {
-    readonly baseUrl: string;
-    readonly extraHosts?: readonly string[];
-}): readonly string[];

package/dist/_contracts/proxy-validation.js

@@ -1,51 +0,0 @@
-/**
- * Cross-validate a `proxyEndpoints` policy list against a
- * `secrets.proxyEndpointAuth` value list. Throws on the first mismatch
- * with an actionable, field-named error message.
- *
- * Mirrors the BFF's authoritative validator so misconfigured submissions
- * fail fast in the SDK/CLI before going over the wire.
- */
-export function validateProxyAuth(endpoints, auth) {
-    const authList = auth ?? [];
-    const endpointNames = new Set(endpoints.map((e) => e.name));
-    const authNames = new Set();
-    for (const entry of authList) {
-        if (authNames.has(entry.name)) {
-            throw new Error(`secrets.proxyEndpointAuth contains duplicate name '${entry.name}'`);
-        }
-        authNames.add(entry.name);
-        if (!endpointNames.has(entry.name)) {
-            throw new Error(`secrets.proxyEndpointAuth[].name='${entry.name}' has no matching proxyEndpoints[].name`);
-        }
-    }
-    for (const endpoint of endpoints) {
-        const match = authList.find((a) => a.name === endpoint.name);
-        if (!match) {
-            throw new Error(`proxyEndpoints[].name='${endpoint.name}' is missing a matching secrets.proxyEndpointAuth entry`);
-        }
-        if (match.value.type !== endpoint.authShape.type) {
-            throw new Error(`secrets.proxyEndpointAuth[name='${endpoint.name}'].value.type='${match.value.type}' does not match proxyEndpoints[name='${endpoint.name}'].authShape.type='${endpoint.authShape.type}'`);
-        }
-    }
-}
-/**
- * Build an `allowedHosts` list for `environment.network` that includes
- * the aex proxy host (and optionally Anthropic's MCP host) when the
- * caller is hand-rolling networking.
- */
-export function buildPlatformAllowedHosts(input) {
-    const result = [];
-    try {
-        result.push(new URL(input.baseUrl).host);
-    }
-    catch {
-        throw new Error("buildPlatformAllowedHosts: baseUrl must be an absolute URL");
-    }
-    for (const host of input.extraHosts ?? []) {
-        if (!result.includes(host))
-            result.push(host);
-    }
-    return result;
-}
-//# sourceMappingURL=proxy-validation.js.map

package/dist/data-tools.d.ts

@@ -1,82 +0,0 @@
-/**
- * Data-source chat tools — turn the SDK's sessions read surface into LLM tool
- * definitions.
- *
- * `createDataTools(client)` returns a small, PROVIDER-AGNOSTIC tool set (plain
- * JSON-Schema `input_schema`, the Anthropic/OpenAI tool shape) plus an
- * `execute(name, input)` dispatcher. A chat backend wires `tools` into its
- * Messages loop and calls `execute` on each `tool_use`. There is no LLM-vendor
- * dependency here: the executor only ever calls public `AgentExecutor` session
- * methods, so a chat built on these tools can reach a workspace's sessions and
- * outputs and NOTHING else — internal/operator data is unreachable by construction.
- *
- * The tools follow search-then-fetch: `list_sessions` / `list_outputs` return
- * lean references and metadata; only `read_output` returns file content, and it
- * is byte-capped so a large deliverable never floods the context window.
- */
-import type { AgentExecutor } from "./client.js";
-import type { SessionListQuery } from "./_contracts/index.js";
-/** JSON Schema for a tool's input — the subset every major LLM tool API accepts. */
-export interface DataChatToolSchema {
-    readonly type: "object";
-    readonly properties: Record<string, unknown>;
-    readonly required?: readonly string[];
-    readonly additionalProperties?: boolean;
-}
-/** One tool definition in the vendor-neutral `{ name, description, input_schema }` shape. */
-export interface DataChatTool {
-    readonly name: string;
-    readonly description: string;
-    readonly input_schema: DataChatToolSchema;
-}
-/** The tool set plus its dispatcher, returned by {@link createDataTools}. */
-export interface DataTools {
-    /** Tool definitions to pass to the model. */
-    readonly tools: readonly DataChatTool[];
-    /** A system-prompt fragment that teaches the model to search-then-fetch. */
-    readonly instructions: string;
-    /**
-     * Run one tool by name with the model's arguments. Returns a JSON-serializable
-     * result (never raw bytes). Throws `DataToolError` for an unknown tool or
-     * invalid arguments — surface that text back to the model as the tool result.
-     */
-    execute(name: string, input: Record<string, unknown>): Promise<unknown>;
-}
-export interface CreateDataToolsOptions {
-    /** Default `max_bytes` for `read_output` when the model omits it. Default 50_000. */
-    readonly defaultReadBytes?: number;
-}
-/**
- * Scopes a chat to a fixed set of sessions. Either pin explicit `sessionIds`
- * (the primary path — needs only `sessions.get` / `sessions.outputs(id).read`,
- * no `sessions.list`), or supply a `filter`
- * (status/since/limit) resolved to a concrete allow-list via `sessions.list`
- * (owner-gated). Every corpus read tool refuses a session outside the resolved
- * set.
- */
-export interface ChatCorpus {
-    /** Explicit session-id allow-list. */
-    readonly sessionIds?: readonly string[];
-    /** Resolve the corpus from a `sessions.list` query (status / since / limit). */
-    readonly filter?: SessionListQuery;
-}
-/** Thrown by `DataTools.execute` for an unknown tool or malformed arguments. */
-export declare class DataToolError extends Error {
-    constructor(message: string);
-}
-export declare const DATA_TOOLS_INSTRUCTIONS: string;
-/**
- * Build the data-source chat tool set bound to one {@link AgentExecutor}.
- * Everything the tools can reach is scoped to the client's workspace token.
- */
-export declare function createDataTools(client: AgentExecutor, options?: CreateDataToolsOptions): DataTools;
-/**
- * Build a corpus-scoped variant of {@link createDataTools}: identical tools, but
- * every read tool is fenced to the sessions in `corpus`. A `get_session`/
- * `list_outputs`/`read_output` for a session outside the corpus throws a
- * {@link DataToolError} ("session <id> is not in this chat's corpus");
- * `list_sessions` returns only corpus sessions; `search_outputs` is auto-scoped
- * to the corpus. This is a client-side guard on top of the server-side
- * workspace-token data scope.
- */
-export declare function createCorpusTools(client: AgentExecutor, corpus: ChatCorpus, options?: CreateDataToolsOptions): DataTools;