@aexhq/sdk 1.0.5-canary → 1.0.7-canary

package/dist/_contracts/schemas/wire.js

@@ -131,6 +131,18 @@ export function errorFromZod(error) {
 }
 /** Parse `input` against `schema`, throwing the family's own error text on failure. */
 export function parseWire(schema, input) {
+    const meta = wireObjectMeta.get(schema);
+    if (meta && input !== null && typeof input === "object" && !Array.isArray(input)) {
+        // Zod deliberately skips `__proto__` while collecting unknown keys so a
+        // plain-object output cannot have its prototype replaced. That safety
+        // rule must not turn an attacker-controlled field into an accepted field;
+        // recover the strict wire-object diagnostic before Zod sees the input.
+        const unknownKey = Object.keys(input).find((key) => !meta.permitted.includes(key));
+        if (unknownKey !== undefined) {
+            const diagnostic = meta.unknownKey(meta.resolvePath([]), unknownKey, meta.permitted);
+            throw typeof diagnostic === "string" ? new Error(diagnostic) : diagnostic;
+        }
+    }
     const result = z.safeParse(schema, input);
     if (!result.success) {
         throw structuredError(schema, result.error) ?? errorFromZod(result.error);

package/dist/_contracts/testing/response-bindings.d.ts

@@ -0,0 +1,45 @@
+import type { ResponseSchemaBinding } from "./wire-conformance.js";
+/**
+ * Turn a dispatch RegExp into a MATCH pattern for
+ * {@link import("./wire-conformance.js").pathMatches}.
+ *
+ * Deliberately not the OpenAPI path form: `pathMatches` only asks whether a
+ * segment is a `{…}` placeholder, so naming the parameter would be decoration
+ * that has to agree with a second implementation. Cross-reference to the
+ * generated document goes through the operation NAME, which both sides carry.
+ */
+export declare function routeMatchTemplate(pattern: RegExp): string;
+export interface UnschemadRoute {
+    readonly name: string;
+    readonly reason: string;
+}
+/**
+ * Data-plane routes with NO response schema, and why not.
+ *
+ * Every entry is here because a JSON response schema cannot describe what the
+ * route returns, or because the shape belongs to another package. None is here
+ * because it was awkward: an empty schema that asserts nothing would be worse
+ * than this list, since it would inflate the "validated" count with routes
+ * nothing was checked on.
+ */
+export declare const ROUTES_WITHOUT_RESPONSE_SCHEMA: readonly UnschemadRoute[];
+/**
+ * Routes that HAVE a schema but that no client in this repository can produce.
+ *
+ * They will appear in `unexercised` on every run, forever, and that is not a
+ * gap in test coverage — there is no call site to add a test to. Stated so a
+ * reader of the report is not misled in the other direction from a false green.
+ */
+export declare const ROUTES_OFF_THE_SDK_SEAM: readonly UnschemadRoute[];
+/** Every data-plane route that has a response schema, bound to it. */
+export declare const DATA_PLANE_RESPONSE_SCHEMAS: readonly ResponseSchemaBinding[];
+/**
+ * Render the STATIC coverage picture — what could be checked, before a single
+ * response arrives.
+ *
+ * Complements `formatWireConformanceReport`, which renders what actually was.
+ * Both belong in a suite's output: the dynamic report alone cannot tell a reader
+ * whether the 40 operations it validated are most of the surface or a third of
+ * it.
+ */
+export declare function formatResponseSchemaCoverage(): string;

package/dist/_contracts/testing/response-bindings.js

@@ -0,0 +1,256 @@
+import { AUTHENTICATED_API_ROUTE_DESCRIPTORS } from "../api-routes.js";
+import { NoContentResponseSchema } from "../schemas/response-common.js";
+import { AssetFinalizeResponseSchema, AssetMpuAbortResponseSchema, AssetMpuPresignPartsResponseSchema, AssetPresignResponseSchema } from "../schemas/response-assets.js";
+import { AdminBillingAccountTypeResponseSchema, AdminBillingPaymentMethodResponseSchema, AdminBillingTopupResponseSchema, BillingAutoTopupResponseSchema, BillingHostedSessionResponseSchema, BillingLedgerResponseSchema, BillingStatementListResponseSchema, BillingSummaryResponseSchema } from "../schemas/response-billing.js";
+import { WhoAmIResponseSchema } from "../schemas/response-identity.js";
+import { McpServerListResponseSchema, McpServerResponseSchema } from "../schemas/response-mcp-servers.js";
+import { SecretListResponseSchema, SecretResponseSchema } from "../schemas/response-secrets.js";
+import { AcknowledgedResponseSchema, CoordinatorTicketResponseSchema, EventArchiveLinkResponseSchema, SessionChildrenResponseSchema, SessionDeleteResponseSchema, SessionEnvelopeResponseSchema, SessionEventsPageResponseSchema, SessionFileLinkResponseSchema, SessionFilesResponseSchema, SessionListResponseSchema, SessionMessageAcceptedResponseSchema, SessionMessagesPageResponseSchema, SessionWebhookDeliveriesResponseSchema } from "../schemas/response-sessions.js";
+import { ChildFinalizeResponseSchema, ChildResultResponseSchema, SessionOtlpResponseSchema } from "../schemas/response-sessions-internal.js";
+import { WebhookSigningSecretResponseSchema, WorkspaceWebhookDeliveriesResponseSchema } from "../schemas/response-webhooks.js";
+import { WorkspaceEraseResponseSchema, WorkspaceFilePageResponseSchema, WorkspaceFileResponseSchema, WorkspaceInstructionPageResponseSchema, WorkspaceInstructionResponseSchema, WorkspaceSkillPageResponseSchema, WorkspaceSkillResponseSchema, WorkspaceToolPageResponseSchema, WorkspaceToolResponseSchema } from "../schemas/response-workspace.js";
+/**
+ * Turn a dispatch RegExp into a MATCH pattern for
+ * {@link import("./wire-conformance.js").pathMatches}.
+ *
+ * Deliberately not the OpenAPI path form: `pathMatches` only asks whether a
+ * segment is a `{…}` placeholder, so naming the parameter would be decoration
+ * that has to agree with a second implementation. Cross-reference to the
+ * generated document goes through the operation NAME, which both sides carry.
+ */
+export function routeMatchTemplate(pattern) {
+    const source = pattern.source
+        .replace(/^\^/, "")
+        .replace(/\$$/, "")
+        // Collapse variable segments BEFORE unescaping: `[^/]+` contains a literal
+        // `/`, so unescaping first tears the class in two.
+        .replace(/\[\^\\?\/\]\+/g, "{param}")
+        .replace(/\\\//g, "/");
+    return source;
+}
+/**
+ * The path the harness sees, which is NOT the path the route table declares.
+ *
+ * `api-routes.ts` describes the surface as the lambda dispatches it (`/sessions`);
+ * every client reaches it under an `/api` prefix, and `HttpClient` reports
+ * `url.pathname`. The generated OpenAPI document applies the same prefix.
+ */
+const API_PREFIX = "/api";
+/**
+ * Operation name -> the schema its 2xx JSON body must satisfy.
+ *
+ * Keyed by name so this table and the route table are joined by the identifier
+ * both already carry, rather than by a re-stated method and path.
+ */
+const RESPONSE_SCHEMA_BY_OPERATION = {
+    whoami: WhoAmIResponseSchema,
+    // Sessions — every state change answers a `{ session }` envelope.
+    "sessions.create": SessionEnvelopeResponseSchema,
+    "sessions.get": SessionEnvelopeResponseSchema,
+    "sessions.suspend": SessionEnvelopeResponseSchema,
+    "sessions.cancel": SessionEnvelopeResponseSchema,
+    "sessions.resume": SessionEnvelopeResponseSchema,
+    "sessions.requestApproval": SessionEnvelopeResponseSchema,
+    "sessions.approve": SessionEnvelopeResponseSchema,
+    "sessions.deny": SessionEnvelopeResponseSchema,
+    "sessions.list": SessionListResponseSchema,
+    "sessions.sendMessage": SessionMessageAcceptedResponseSchema,
+    "sessions.delete": SessionDeleteResponseSchema,
+    "sessions.listMessages": SessionMessagesPageResponseSchema,
+    "sessions.listEvents": SessionEventsPageResponseSchema,
+    "sessions.eventsTicket": CoordinatorTicketResponseSchema,
+    "sessions.listChildren": SessionChildrenResponseSchema,
+    "sessions.eventArchiveLink": EventArchiveLinkResponseSchema,
+    "sessions.listFiles": SessionFilesResponseSchema,
+    "sessions.fileLink": SessionFileLinkResponseSchema,
+    "sessions.listWebhookDeliveries": SessionWebhookDeliveriesResponseSchema,
+    "sessions.redeliverWebhook": AcknowledgedResponseSchema,
+    "sessions.otel": SessionOtlpResponseSchema,
+    "sessions.childResult": ChildResultResponseSchema,
+    "sessions.finalize": ChildFinalizeResponseSchema,
+    // Assets.
+    "assets.presign": AssetPresignResponseSchema,
+    "assets.finalize": AssetFinalizeResponseSchema,
+    "assets.mpuPresignParts": AssetMpuPresignPartsResponseSchema,
+    "assets.mpuAbort": AssetMpuAbortResponseSchema,
+    "assets.delete": NoContentResponseSchema,
+    // Versioned workspace resources.
+    "workspace.files.publish": WorkspaceFileResponseSchema,
+    "workspace.files.get": WorkspaceFileResponseSchema,
+    "workspace.files.list": WorkspaceFilePageResponseSchema,
+    "workspace.files.delete": NoContentResponseSchema,
+    "workspace.skills.publish": WorkspaceSkillResponseSchema,
+    "workspace.skills.get": WorkspaceSkillResponseSchema,
+    "workspace.skills.list": WorkspaceSkillPageResponseSchema,
+    "workspace.skills.delete": NoContentResponseSchema,
+    "workspace.tools.publish": WorkspaceToolResponseSchema,
+    "workspace.tools.get": WorkspaceToolResponseSchema,
+    "workspace.tools.list": WorkspaceToolPageResponseSchema,
+    "workspace.tools.delete": NoContentResponseSchema,
+    "workspace.instructions.publish": WorkspaceInstructionResponseSchema,
+    "workspace.instructions.get": WorkspaceInstructionResponseSchema,
+    "workspace.instructions.list": WorkspaceInstructionPageResponseSchema,
+    "workspace.instructions.delete": NoContentResponseSchema,
+    // Workspace secret store.
+    "secrets.create": SecretResponseSchema,
+    "secrets.get": SecretResponseSchema,
+    "secrets.rotate": SecretResponseSchema,
+    "secrets.list": SecretListResponseSchema,
+    "secrets.delete": NoContentResponseSchema,
+    // Workspace MCP server config.
+    "mcpServers.create": McpServerResponseSchema,
+    "mcpServers.get": McpServerResponseSchema,
+    "mcpServers.list": McpServerListResponseSchema,
+    "mcpServers.delete": NoContentResponseSchema,
+    // Billing.
+    "billing.get": BillingSummaryResponseSchema,
+    "billing.ledger": BillingLedgerResponseSchema,
+    "billing.topupCheckout": BillingHostedSessionResponseSchema,
+    "billing.autoTopup": BillingAutoTopupResponseSchema,
+    "billing.statements": BillingStatementListResponseSchema,
+    "billing.portal": BillingHostedSessionResponseSchema,
+    "adminBilling.topup": AdminBillingTopupResponseSchema,
+    "adminBilling.paymentMethod": AdminBillingPaymentMethodResponseSchema,
+    "adminBilling.accountType": AdminBillingAccountTypeResponseSchema,
+    // Workspace webhooks and GDPR erase.
+    "webhook.signingSecret": WebhookSigningSecretResponseSchema,
+    "webhook.listDeliveries": WorkspaceWebhookDeliveriesResponseSchema,
+    "workspaces.erase": WorkspaceEraseResponseSchema
+};
+/**
+ * Data-plane routes with NO response schema, and why not.
+ *
+ * Every entry is here because a JSON response schema cannot describe what the
+ * route returns, or because the shape belongs to another package. None is here
+ * because it was awkward: an empty schema that asserts nothing would be worse
+ * than this list, since it would inflate the "validated" count with routes
+ * nothing was checked on.
+ */
+export const ROUTES_WITHOUT_RESPONSE_SCHEMA = [
+    {
+        name: "sessions.downloadFile",
+        reason: "Not JSON on success: a small file is 200 raw bytes with the FILE's own content-type, " +
+            "a large one is a 302 to presigned storage."
+    },
+    {
+        name: "sessions.archiveInternal",
+        reason: "Not JSON on success: 302 with an empty body and content-type application/zip."
+    },
+    {
+        name: "runtime.writerAuthority",
+        reason: "204 with no body and no headers at all, and writer-token only — it is a liveness probe " +
+            "for the writer baton, not a bearer/SDK surface."
+    },
+    {
+        name: "runtime.journalCommit",
+        reason: "Writer-token only, and its 200 body is the platform's journal control-item shape " +
+            "(lambda-runtime-contracts), not a shape this package declares. Three of its six ops " +
+            "answer 204 with no body."
+    },
+    {
+        name: "billing.statement",
+        reason: "Not always JSON: the single statement is content-negotiated — `application/pdf` and " +
+            "`text/plain` renders of the same document alongside the JSON default — and the JSON " +
+            "body's `document` is the platform's stored render, not a shape this package declares. " +
+            "The LIST at `billing.statements` is plain JSON and IS bound."
+    }
+];
+/**
+ * Routes that HAVE a schema but that no client in this repository can produce.
+ *
+ * They will appear in `unexercised` on every run, forever, and that is not a
+ * gap in test coverage — there is no call site to add a test to. Stated so a
+ * reader of the report is not misled in the other direction from a false green.
+ */
+export const ROUTES_OFF_THE_SDK_SEAM = [
+    {
+        name: "sessions.otel",
+        reason: "`getSessionOtlpPage` reads the body through `HttpClient.download()`, which reports only " +
+            "its FAILURES to the wire observer — its 2xx body is handed back as a `Response` for the " +
+            "caller to read, and reporting it would mean cloning every download. Its error envelope " +
+            "IS checked; its success body is what stays unobserved."
+    },
+    {
+        name: "sessions.childResult",
+        reason: "Writer-token only; called by the in-container subagent runtime, not by `HttpClient`."
+    },
+    {
+        name: "sessions.finalize",
+        reason: "Writer-token only; the child-settle hop, called from inside the runtime."
+    },
+    {
+        name: "mcpServers.create",
+        reason: "No client function exists in `operations.ts` — the dashboard BFF reaches it directly."
+    },
+    { name: "mcpServers.list", reason: "No client function exists in `operations.ts`." },
+    { name: "mcpServers.get", reason: "No client function exists in `operations.ts`." },
+    { name: "mcpServers.delete", reason: "No client function exists in `operations.ts`." },
+    {
+        name: "webhook.listDeliveries",
+        reason: "No client function exists in `operations.ts`; only the session-scoped " +
+            "`sessions.listWebhookDeliveries` has one."
+    },
+    {
+        name: "billing.statements",
+        reason: "No client function exists in `operations.ts`. The descriptor is what makes the route " +
+            "reachable at all — the platform 404s an undeclared path before its handler ladder runs — " +
+            "and the dashboard reaches it directly."
+    },
+    { name: "adminBilling.topup", reason: "Operator route; no client function in `operations.ts`." },
+    {
+        name: "adminBilling.paymentMethod",
+        reason: "Operator route; no client function in `operations.ts`."
+    },
+    {
+        name: "adminBilling.accountType",
+        reason: "Operator route; no client function in `operations.ts`."
+    },
+    {
+        name: "workspaces.erase",
+        reason: "No DATA-plane client function. `deleteWorkspace()` in `operations.ts` calls the " +
+            "identically-shaped CONTROL-plane path — see the plane-collision note above."
+    }
+];
+function bindingFor(descriptor) {
+    const schema = RESPONSE_SCHEMA_BY_OPERATION[descriptor.name];
+    if (schema === undefined) {
+        return undefined;
+    }
+    return {
+        method: descriptor.method.toUpperCase(),
+        path: `${API_PREFIX}${routeMatchTemplate(descriptor.pattern)}`,
+        name: descriptor.name,
+        schema
+    };
+}
+/** Every data-plane route that has a response schema, bound to it. */
+export const DATA_PLANE_RESPONSE_SCHEMAS = AUTHENTICATED_API_ROUTE_DESCRIPTORS.flatMap((descriptor) => {
+    const binding = bindingFor(descriptor);
+    return binding === undefined ? [] : [binding];
+});
+/**
+ * Render the STATIC coverage picture — what could be checked, before a single
+ * response arrives.
+ *
+ * Complements `formatWireConformanceReport`, which renders what actually was.
+ * Both belong in a suite's output: the dynamic report alone cannot tell a reader
+ * whether the 40 operations it validated are most of the surface or a third of
+ * it.
+ */
+export function formatResponseSchemaCoverage() {
+    const total = AUTHENTICATED_API_ROUTE_DESCRIPTORS.length;
+    const bound = DATA_PLANE_RESPONSE_SCHEMAS.length;
+    const lines = [
+        `response schemas: ${bound}/${total} data-plane route(s) have one`,
+        `  NO SCHEMA (${ROUTES_WITHOUT_RESPONSE_SCHEMA.length}):`
+    ];
+    for (const route of ROUTES_WITHOUT_RESPONSE_SCHEMA) {
+        lines.push(`    - ${route.name}: ${route.reason}`);
+    }
+    lines.push(`  SCHEMA BUT UNREACHABLE from any client in this repo — expect these in ` +
+        `"NOT EXERCISED" forever (${ROUTES_OFF_THE_SDK_SEAM.length}):`);
+    for (const route of ROUTES_OFF_THE_SDK_SEAM) {
+        lines.push(`    - ${route.name}: ${route.reason}`);
+    }
+    return lines.join("\n");
+}

package/dist/_contracts/testing/wire-conformance-entry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The minimal C4 entrypoint copied into the SDK's private inlined contracts.
+ *
+ * Keep the broader `@aexhq/contracts/testing` kit out of customer packages;
+ * live user tests only need the response schemas and observer installer.
+ */
+export { installWireConformance, formatWireConformanceReport, mergeWireConformanceReports, pathMatches, wireOrigin } from "./wire-conformance.js";
+export type { ResponseSchemaBinding, WireConformanceOptions, WireConformanceReport, WireConformanceViolation } from "./wire-conformance.js";
+export { DATA_PLANE_RESPONSE_SCHEMAS, ROUTES_WITHOUT_RESPONSE_SCHEMA, ROUTES_OFF_THE_SDK_SEAM, formatResponseSchemaCoverage } from "./response-bindings.js";
+export type { UnschemadRoute } from "./response-bindings.js";

package/dist/_contracts/testing/wire-conformance-entry.js

@@ -0,0 +1,8 @@
+/**
+ * The minimal C4 entrypoint copied into the SDK's private inlined contracts.
+ *
+ * Keep the broader `@aexhq/contracts/testing` kit out of customer packages;
+ * live user tests only need the response schemas and observer installer.
+ */
+export { installWireConformance, formatWireConformanceReport, mergeWireConformanceReports, pathMatches, wireOrigin } from "./wire-conformance.js";
+export { DATA_PLANE_RESPONSE_SCHEMAS, ROUTES_WITHOUT_RESPONSE_SCHEMA, ROUTES_OFF_THE_SDK_SEAM, formatResponseSchemaCoverage } from "./response-bindings.js";

package/dist/_contracts/testing/wire-conformance.d.ts

@@ -0,0 +1,169 @@
+/**
+ * C4 — the wire-conformance harness.
+ *
+ * Validates the bytes a real server actually returned against the response
+ * schemas. This is the only gate in the contract pipeline that observes reality
+ * rather than comparing two of our own artefacts to each other, and it is the
+ * one the plan flags as easiest to skip and most costly to skip.
+ *
+ * It attaches to `HttpClient` through {@link observeWireResponses}, so every
+ * response the live and user-test suites already receive is checked — no new
+ * suite, no new requests, no server changes.
+ *
+ * **Coverage is reported, not assumed.** A green run over 12 of 120 routes is
+ * not a verified surface, and calling it one is the specific failure this
+ * harness exists to prevent. {@link WireConformanceReport} names the routes that
+ * were checked, the routes that have a schema but were never exercised, the
+ * responses that arrived with no schema to check them against, and the responses
+ * that were deliberately skipped because they came from another plane.
+ *
+ * ## What it checks, and what it used to miss
+ *
+ * - **2xx bodies** against the operation's response schema.
+ * - **non-2xx bodies** against {@link ApiErrorEnvelopeSchema}. Every generated
+ *   operation declares that envelope, and until `HttpClient` learned to report
+ *   before it throws, nothing had ever checked it.
+ *
+ * ## The plane collision, and how it is closed
+ *
+ * A PATH does not identify a route. The control plane serves different bodies at
+ * two of the data plane's paths (`GET /api/whoami`,
+ * `DELETE /api/workspaces/{id}`), so a process driving both planes — the CLI
+ * does, `aex login` is control-plane — would validate a control-plane body
+ * against a data-plane schema and report a violation that is not one.
+ * {@link WireResponse} therefore carries the ORIGIN it came from, and
+ * {@link WireConformanceOptions.origin} says which plane the bindings describe.
+ * Responses from anywhere else are counted and named under
+ * {@link WireConformanceReport.offPlane} rather than silently dropped.
+ *
+ * Installing WITHOUT an origin is still allowed, because a data-plane-only suite
+ * has nothing to collide with — but the report says so in as many words, so a
+ * reader can tell a filtered run from an unfiltered one.
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/** A response schema bound to the route whose responses it describes. */
+export interface ResponseSchemaBinding {
+    /** Uppercase HTTP method. */
+    readonly method: string;
+    /**
+     * Path pattern with `{param}` placeholders, matched segment-wise:
+     * `/api/sessions/{sessionId}/messages`.
+     */
+    readonly path: string;
+    /** Operation id, used in the report. */
+    readonly name: string;
+    readonly schema: StandardSchemaV1;
+}
+export interface WireConformanceOptions {
+    /**
+     * The plane the bindings describe, as an origin or any URL on it —
+     * `https://dev-api.aex.dev`, or the `AEX_API_URL` the suite already reads.
+     *
+     * Responses from any other origin are recorded in
+     * {@link WireConformanceReport.offPlane} and NOT validated. Omit only when the
+     * process provably drives one plane; the report states which case it was.
+     */
+    readonly origin?: string | undefined;
+    /**
+     * Schema for non-2xx bodies. Defaults to {@link ApiErrorEnvelopeSchema} — the
+     * shape the generated document declares as every operation's `default`
+     * response. Pass `null` to stop checking error bodies, which throws away the
+     * only assertion that covers 68 declared-but-unchecked responses; there is no
+     * good reason to.
+     */
+    readonly errorEnvelope?: StandardSchemaV1 | null;
+}
+export interface WireConformanceViolation {
+    /**
+     * Which contract was broken: the operation's own 2xx schema, or the error
+     * envelope every operation declares.
+     */
+    readonly kind: "response" | "error-envelope";
+    /** Operation id, or `METHOD /path` when no binding matched. */
+    readonly name: string;
+    readonly method: string;
+    readonly origin: string;
+    readonly path: string;
+    readonly status: number;
+    readonly issues: readonly string[];
+    /**
+     * The body that failed, verbatim.
+     *
+     * Carried because a complaint without the bytes that caused it cannot be
+     * triaged — the reader has to be able to tell a server defect from a schema
+     * defect, and only the actual body settles that.
+     */
+    readonly body: unknown;
+}
+export interface WireConformanceReport {
+    /**
+     * The origin responses were required to come from, or `undefined` when the
+     * harness was installed without a plane filter.
+     */
+    readonly originFilter: string | undefined;
+    /** Operation ids whose 2xx responses were seen and validated. */
+    readonly validated: readonly string[];
+    /** Operation ids with a response schema that no request exercised. */
+    readonly unexercised: readonly string[];
+    /** `METHOD /path` for responses that arrived with no schema bound. */
+    readonly unschemad: readonly string[];
+    /** `METHOD /path -> status` for non-2xx bodies checked against the envelope. */
+    readonly errorsValidated: readonly string[];
+    /** `origin METHOD /path` for responses from a plane these bindings do not describe. */
+    readonly offPlane: readonly string[];
+    readonly violations: readonly WireConformanceViolation[];
+    /** Responses observed in total, including ones with no schema and off-plane ones. */
+    readonly observed: number;
+}
+/**
+ * Match a concrete path against a `{param}` pattern.
+ *
+ * Segment-wise rather than by regex so a placeholder cannot accidentally span a
+ * `/` and make two different routes look like one.
+ */
+export declare function pathMatches(pattern: string, actual: string): boolean;
+/**
+ * Reduce whatever the caller had to hand — a base URL, a URL with a path, a bare
+ * origin — to the origin `WireResponse` reports.
+ *
+ * Throws rather than falling back to "match everything": an unparseable
+ * `AEX_API_URL` that silently disabled the filter would reintroduce exactly the
+ * false violations the filter exists to prevent, and would do it quietly.
+ */
+export declare function wireOrigin(baseUrl: string): string;
+/**
+ * Start validating responses.
+ *
+ * Returns a handle carrying the report and a `stop()`. Validation is
+ * synchronous: a schema whose `~standard.validate` returns a promise is treated
+ * as unvalidatable and recorded as such rather than silently skipped, because
+ * `HttpClient` cannot await an observer without changing request timing.
+ */
+export declare function installWireConformance(bindings: readonly ResponseSchemaBinding[], options?: WireConformanceOptions): {
+    readonly report: () => WireConformanceReport;
+    readonly stop: () => void;
+};
+/**
+ * Fold reports from several processes into one.
+ *
+ * The suites that matter drive the SDK out of process — one bun child per
+ * scenario, one test process per file — so no single process sees the whole
+ * surface, and a per-process report would understate coverage by construction.
+ *
+ * `unexercised` is INTERSECTED, not concatenated: a name is unexercised overall
+ * only when every fragment failed to exercise it. Concatenating would report a
+ * route as unexercised because some other process did not happen to call it,
+ * which is the mirror image of the false-green this harness exists to prevent.
+ * That identity only holds when every fragment was produced from the same
+ * binding table; {@link installWireConformance} is the only producer.
+ */
+export declare function mergeWireConformanceReports(reports: readonly WireConformanceReport[]): WireConformanceReport;
+/**
+ * Render the report for a suite's output.
+ *
+ * Always prints the unexercised and unschemad lists, including when there are no
+ * violations — a run that reports only "0 violations" invites the reader to
+ * conclude the surface is verified. A violation always prints the BODY that
+ * caused it as well as the schema's complaint, because triage needs both.
+ */
+export declare function formatWireConformanceReport(report: WireConformanceReport): string;

package/dist/_contracts/testing/wire-conformance.js

@@ -0,0 +1,276 @@
+import { ApiErrorEnvelopeSchema } from "../schemas/response-common.js";
+import { observeWireResponses } from "../wire-observer.js";
+/**
+ * Match a concrete path against a `{param}` pattern.
+ *
+ * Segment-wise rather than by regex so a placeholder cannot accidentally span a
+ * `/` and make two different routes look like one.
+ */
+export function pathMatches(pattern, actual) {
+    const patternSegments = pattern.split("/");
+    const actualSegments = actual.split("/");
+    if (patternSegments.length !== actualSegments.length) {
+        return false;
+    }
+    return patternSegments.every((segment, index) => (segment.startsWith("{") && segment.endsWith("}")) || segment === actualSegments[index]);
+}
+/**
+ * Reduce whatever the caller had to hand — a base URL, a URL with a path, a bare
+ * origin — to the origin `WireResponse` reports.
+ *
+ * Throws rather than falling back to "match everything": an unparseable
+ * `AEX_API_URL` that silently disabled the filter would reintroduce exactly the
+ * false violations the filter exists to prevent, and would do it quietly.
+ */
+export function wireOrigin(baseUrl) {
+    try {
+        return new URL(baseUrl).origin;
+    }
+    catch (cause) {
+        throw new Error(`wire conformance: could not read an origin from ${JSON.stringify(baseUrl)} — ` +
+            `expected an absolute URL like "https://api.aex.dev"`, { cause });
+    }
+}
+function issuesOf(result) {
+    return (result.issues ?? []).map((issue) => {
+        const path = (issue.path ?? [])
+            .map((segment) => (typeof segment === "object" ? String(segment.key) : String(segment)))
+            .join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+}
+/**
+ * Which contract a status is judged against.
+ *
+ * The generated document is coarser than this — it declares `2XX` and a
+ * `default` that catches everything else — but judging a redirect against the
+ * error envelope would manufacture a violation out of an empty body, which is
+ * noise rather than a finding. A 3xx is recorded, named and not judged.
+ *
+ * In practice `fetch` follows redirects, so `HttpClient` sees the final
+ * response; this exists so that a caller who stops following them gets a
+ * comprehensible report rather than a wall of false failures.
+ */
+function contractFor(status) {
+    if (status < 300)
+        return "response";
+    if (status < 400)
+        return "redirect";
+    return "error-envelope";
+}
+/**
+ * Start validating responses.
+ *
+ * Returns a handle carrying the report and a `stop()`. Validation is
+ * synchronous: a schema whose `~standard.validate` returns a promise is treated
+ * as unvalidatable and recorded as such rather than silently skipped, because
+ * `HttpClient` cannot await an observer without changing request timing.
+ */
+export function installWireConformance(bindings, options = {}) {
+    const originFilter = options.origin === undefined ? undefined : wireOrigin(options.origin);
+    const errorEnvelope = options.errorEnvelope === undefined ? ApiErrorEnvelopeSchema : options.errorEnvelope;
+    const validated = new Set();
+    const unschemad = new Set();
+    const errorsValidated = new Set();
+    const offPlane = new Set();
+    const violations = [];
+    let observed = 0;
+    /** Validate `body`, recording a violation on failure. Returns false if async. */
+    const check = (schema, kind, name, response) => {
+        const result = schema["~standard"].validate(response.body);
+        if (result instanceof Promise) {
+            return false;
+        }
+        if (result.issues) {
+            violations.push({
+                kind,
+                name,
+                method: response.method.toUpperCase(),
+                origin: response.origin,
+                path: response.path,
+                status: response.status,
+                issues: issuesOf(result),
+                body: response.body
+            });
+        }
+        return true;
+    };
+    const stop = observeWireResponses((response) => {
+        observed += 1;
+        const method = response.method.toUpperCase();
+        if (originFilter !== undefined && response.origin !== originFilter) {
+            offPlane.add(`${response.origin} ${method} ${response.path}`);
+            return;
+        }
+        const contract = contractFor(response.status);
+        if (contract === "redirect") {
+            unschemad.add(`${method} ${response.path} -> ${response.status} (redirect — no declared body)`);
+            return;
+        }
+        if (contract === "error-envelope") {
+            // An error body is the SAME envelope whatever route produced it, so it is
+            // checked without needing a binding — which is the point: the routes with
+            // no 2xx schema still have their failures covered.
+            if (errorEnvelope === null) {
+                return;
+            }
+            if (check(errorEnvelope, "error-envelope", `${method} ${response.path}`, response)) {
+                errorsValidated.add(`${method} ${response.path} -> ${response.status}`);
+            }
+            else {
+                unschemad.add(`${method} ${response.path} -> ${response.status} (async schema — not validated)`);
+            }
+            return;
+        }
+        const binding = bindings.find((candidate) => candidate.method === method && pathMatches(candidate.path, response.path));
+        if (!binding) {
+            unschemad.add(`${method} ${response.path}`);
+            return;
+        }
+        if (!check(binding.schema, "response", binding.name, response)) {
+            unschemad.add(`${binding.name} (async schema — not validated)`);
+            return;
+        }
+        validated.add(binding.name);
+    });
+    return {
+        stop,
+        report: () => ({
+            originFilter,
+            validated: [...validated].sort(),
+            unexercised: bindings
+                .map((binding) => binding.name)
+                .filter((name) => !validated.has(name))
+                .sort(),
+            unschemad: [...unschemad].sort(),
+            errorsValidated: [...errorsValidated].sort(),
+            offPlane: [...offPlane].sort(),
+            violations,
+            observed
+        })
+    };
+}
+/**
+ * Fold reports from several processes into one.
+ *
+ * The suites that matter drive the SDK out of process — one bun child per
+ * scenario, one test process per file — so no single process sees the whole
+ * surface, and a per-process report would understate coverage by construction.
+ *
+ * `unexercised` is INTERSECTED, not concatenated: a name is unexercised overall
+ * only when every fragment failed to exercise it. Concatenating would report a
+ * route as unexercised because some other process did not happen to call it,
+ * which is the mirror image of the false-green this harness exists to prevent.
+ * That identity only holds when every fragment was produced from the same
+ * binding table; {@link installWireConformance} is the only producer.
+ */
+export function mergeWireConformanceReports(reports) {
+    const validated = new Set();
+    const unschemad = new Set();
+    const errorsValidated = new Set();
+    const offPlane = new Set();
+    const violations = [];
+    const originFilters = new Set();
+    let unexercised;
+    let observed = 0;
+    let anyUnfiltered = false;
+    for (const report of reports) {
+        observed += report.observed;
+        for (const name of report.validated)
+            validated.add(name);
+        for (const route of report.unschemad)
+            unschemad.add(route);
+        for (const route of report.errorsValidated)
+            errorsValidated.add(route);
+        for (const route of report.offPlane)
+            offPlane.add(route);
+        violations.push(...report.violations);
+        if (report.originFilter === undefined)
+            anyUnfiltered = true;
+        else
+            originFilters.add(report.originFilter);
+        unexercised =
+            unexercised === undefined
+                ? new Set(report.unexercised)
+                : new Set(report.unexercised.filter((name) => unexercised.has(name)));
+    }
+    return {
+        // One filter across every fragment is the only case that can be stated
+        // simply. A mixed run is reported as unfiltered so the formatter's warning
+        // fires rather than a filter being claimed that not every fragment applied.
+        originFilter: !anyUnfiltered && originFilters.size === 1 ? [...originFilters][0] : undefined,
+        validated: [...validated].sort(),
+        unexercised: [...(unexercised ?? new Set())].filter((name) => !validated.has(name)).sort(),
+        unschemad: [...unschemad].sort(),
+        errorsValidated: [...errorsValidated].sort(),
+        offPlane: [...offPlane].sort(),
+        violations,
+        observed
+    };
+}
+/** Render a body for a violation without letting one huge response bury the report. */
+function renderBody(body, limit = 2000) {
+    let text;
+    try {
+        text = JSON.stringify(body) ?? String(body);
+    }
+    catch {
+        text = String(body);
+    }
+    return text.length > limit ? `${text.slice(0, limit)}… (${text.length} bytes total)` : text;
+}
+/**
+ * Render the report for a suite's output.
+ *
+ * Always prints the unexercised and unschemad lists, including when there are no
+ * violations — a run that reports only "0 violations" invites the reader to
+ * conclude the surface is verified. A violation always prints the BODY that
+ * caused it as well as the schema's complaint, because triage needs both.
+ */
+export function formatWireConformanceReport(report) {
+    const lines = [
+        `wire conformance: ${report.observed} response(s) observed, ` +
+            `${report.validated.length} operation(s) validated, ` +
+            `${report.errorsValidated.length} error response(s) checked, ` +
+            `${report.violations.length} violation(s)`
+    ];
+    lines.push(report.originFilter === undefined
+        ? `  ORIGIN FILTER: none — every observed response was matched by PATH alone. ` +
+            `Sound only for a process that drives ONE plane; the control plane serves ` +
+            `different bodies at GET /api/whoami and DELETE /api/workspaces/{id}.`
+        : `  ORIGIN FILTER: ${report.originFilter}`);
+    if (report.offPlane.length > 0) {
+        lines.push(`  OFF-PLANE (other origin, not checked against these bindings):`);
+        for (const route of report.offPlane) {
+            lines.push(`    - ${route}`);
+        }
+    }
+    if (report.validated.length > 0) {
+        lines.push(`  VALIDATED (${report.validated.length}): ${report.validated.join(", ")}`);
+    }
+    if (report.errorsValidated.length > 0) {
+        lines.push(`  ERROR ENVELOPES CHECKED (${report.errorsValidated.length}):`);
+        for (const route of report.errorsValidated) {
+            lines.push(`    - ${route}`);
+        }
+    }
+    if (report.unexercised.length > 0) {
+        lines.push(`  NOT EXERCISED (schema exists, no response seen) (${report.unexercised.length}): ` +
+            `${report.unexercised.join(", ")}`);
+    }
+    if (report.unschemad.length > 0) {
+        lines.push(`  NO SCHEMA (response seen, nothing to check it against):`);
+        for (const route of report.unschemad) {
+            lines.push(`    - ${route}`);
+        }
+    }
+    for (const violation of report.violations) {
+        lines.push(`  VIOLATION [${violation.kind}] ${violation.name} ` +
+            `(${violation.method} ${violation.origin}${violation.path} -> ${violation.status}):`);
+        for (const issue of violation.issues) {
+            lines.push(`    - ${issue}`);
+        }
+        lines.push(`    body: ${renderBody(violation.body)}`);
+    }
+    return lines.join("\n");
+}

package/dist/cli.mjs

@@ -1782,6 +1782,14 @@ function errorFromZod(error) {
   return new Error(primaryIssue(error.issues)?.message ?? "invalid input");
 }
 function parseWire(schema, input) {
+  const meta2 = wireObjectMeta.get(schema);
+  if (meta2 && input !== null && typeof input === "object" && !Array.isArray(input)) {
+    const unknownKey = Object.keys(input).find((key) => !meta2.permitted.includes(key));
+    if (unknownKey !== void 0) {
+      const diagnostic = meta2.unknownKey(meta2.resolvePath([]), unknownKey, meta2.permitted);
+      throw typeof diagnostic === "string" ? new Error(diagnostic) : diagnostic;
+    }
+  }
   const result = safeParse(schema, input);
   if (!result.success) {
     throw structuredError(schema, result.error) ?? errorFromZod(result.error);

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-7c9ef23d338e4cb7205bf51f442ec53bec5b6c18c103e700b9ad4344fb9913a0  cli.mjs
+1f35333a7b3ceb4bbf8461214ae7a9b23cf985195b36e68b61e5e6a016f1f0c2  cli.mjs

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 = "1.0.5-canary";
+export declare const SDK_VERSION = "1.0.7-canary";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "1.0.5-canary",
+  "version": "1.0.7-canary",
   "description": "TypeScript SDK for autonomous agent sessions with managed Vercel AI Gateway model access.",
   "license": "Apache-2.0",
   "repository": {
@@ -55,6 +55,6 @@
     "zod": "4.4.3"
   },
   "aexRelease": {
-    "sourceSha": "3f747bd862826938ba13bba2304d9260e829efeb"
+    "sourceSha": "f7c6d5902c4594d166b1a5878be05a064b20c1ea"
   }
 }