@aventara/core 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/protocol/http-request.decoder.d.ts

@@ -1,15 +1,16 @@
-import type { FrameworkContracts } from "../compiler/contract.compiler.js";
-import type { ClientOperationRequest } from "../runtime/operation-request.js";
-import type { ClientTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { RemoteRequestOrigin } from "../config/config-layer.js";
+import type { RemoteOperationRequest } from "../runtime/operation-request.js";
+import type { AgentTransactionRequest, ClientTransactionRequest } from "../transactions/transaction-request.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
 /** One HTTP request as a host hands it to the protocol. */
 export type AvProtocolRequest = {
     /** The HTTP method as received. Anything but `POST` on a framework route is `A2012`. */
     readonly method: string;
     /**
-     * The request path RELATIVE to the configured entrypoint, as received (not yet
-     * URL-decoded): `/_resources/users/find/many`, `/_transactions`, `/_contract` —
-     * the space `protocol.surface()`'s paths live in.
+     * The request path relative to the configured `api` mount path, as received (not yet
+     * URL-decoded): `/_resources/users/find/many`, `/_transactions`, `/_contract`,
+     * in the same form as the paths `protocol.surface()` returns.
      */
     readonly path: string;
     /**
@@ -19,8 +20,8 @@ export type AvProtocolRequest = {
      */
     readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
     /**
-     * The body, in one of two explicitly named arms — the decoder never guesses which
-     * one it was given:
+     * The body, in one of two explicitly named arms, so the decoder never guesses
+     * which one it was given:
      */
     readonly body: {
         readonly kind: "raw";
@@ -45,19 +46,22 @@ type Decoded<Request> = {
     readonly response: AvProtocolResponse;
     readonly requestId: string;
 };
-/** What `protocol.decodeOperation` answers. */
-export type DecodedOperation = Decoded<ClientOperationRequest>;
+/**
+ * What `protocol.decodeOperation` answers: a client-origin request, or an
+ * agent-origin one from a binding made with `{ origin: "agent" }`.
+ */
+export type DecodedOperation = Decoded<RemoteOperationRequest>;
 /** `protocol.decodeOperation`'s success value: the request `framework.execute` takes. */
 export type DecodedOperationRequest = Extract<DecodedOperation, {
     ok: true;
 }>;
 /** What `protocol.decodeTransaction` answers. */
-export type DecodedTransaction = Decoded<ClientTransactionRequest>;
+export type DecodedTransaction = Decoded<ClientTransactionRequest | AgentTransactionRequest>;
 /**
  * `protocol.decodeOperation(request)` — one operation route's HTTP request as
  * the client-origin request `framework.execute` takes, or its answer.
  */
-export declare function decodeOperationRequest(contracts: FrameworkContracts, received: AvProtocolRequest): DecodedOperation;
+export declare function decodeOperationRequest(contracts: AvContracts, received: AvProtocolRequest, origin?: RemoteRequestOrigin): DecodedOperation;
 /**
  * `protocol.decodeTransaction(request)` — the `/_transactions` request as the client-
  * origin plan request `framework.executeTransaction` takes, or its answer. The same
@@ -66,7 +70,7 @@ export declare function decodeOperationRequest(contracts: FrameworkContracts, re
  * the plan then runs under ClientContract rules: the plan is client origin and cannot
  * say otherwise. The body is the plan verbatim.
  */
-export declare function decodeTransactionRequest(contracts: FrameworkContracts, received: AvProtocolRequest): DecodedTransaction;
+export declare function decodeTransactionRequest(contracts: AvContracts, received: AvProtocolRequest, origin?: RemoteRequestOrigin): DecodedTransaction;
 /**
  * Whether `value` is a body this decoder parsed from raw content. Only the protocol's
  * own shortcuts ask, about a request they have just decoded, before any host code

package/dist/protocol/http-request.decoder.js

@@ -2,21 +2,21 @@ import { checkOperationRoute, checkTransactionsRoute, } from "./absent-route.res
 import { readRequest } from "./http-request.reader.js";
 import { transportFailure, } from "./protocol-failure.js";
 import { headerValue } from "./protocol-headers.js";
-export function decodeOperationRequest(contracts, received) {
+export function decodeOperationRequest(contracts, received, origin = "client") {
     const read = readRequest(received);
     if (!read.ok) {
         return read;
     }
-    const route = checkOperationRoute(contracts, read);
+    const route = checkOperationRoute(contracts, read, origin);
     if (!route.ok) {
         return refused(route.response, read.requestId);
     }
-    const body = readBody(read, contracts);
+    const body = readBody(read, contracts, origin);
     return body.ok
         ? {
             ok: true,
             request: {
-                origin: "client",
+                origin,
                 requestId: read.requestId,
                 resource: route.resource,
                 ...route.operation,
@@ -28,21 +28,21 @@ export function decodeOperationRequest(contracts, received) {
         }
         : refused(body.response, read.requestId);
 }
-export function decodeTransactionRequest(contracts, received) {
+export function decodeTransactionRequest(contracts, received, origin = "client") {
     const read = readRequest(received);
     if (!read.ok) {
         return read;
     }
-    const route = checkTransactionsRoute(contracts, read);
+    const route = checkTransactionsRoute(contracts, read, origin);
     if (!route.ok) {
         return refused(route.response, read.requestId);
     }
-    const body = readBody(read, contracts);
+    const body = readBody(read, contracts, origin);
     return body.ok
         ? {
             ok: true,
             request: {
-                origin: "client",
+                origin,
                 requestId: read.requestId,
                 protocol: route.protocol,
                 transport: transportOf(read),
@@ -58,8 +58,8 @@ function refused(response, requestId) {
 function transportOf(read) {
     return { method: "POST", headers: read.headers };
 }
-function readBody(read, contracts) {
-    const code = bodyValue(read.request.body, headerValue(read.headers, "content-type"), contracts.client.limits.maxRequestBytes);
+function readBody(read, contracts, origin) {
+    const code = bodyValue(read.request.body, headerValue(read.headers, "content-type"), contracts[origin].limits.maxRequestBytes);
     return typeof code === "string"
         ? { ok: false, response: transportFailure(code, read.requestId) }
         : { ok: true, value: code.value };

package/dist/protocol/http-request.reader.d.ts

@@ -2,9 +2,9 @@ import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
 import type { OperationRouteSegments } from "./absent-route.responder.js";
 import type { AvProtocolRequest } from "./http-request.decoder.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
-/** `POST <entrypoint>/_transactions`. */
+/** `POST <api>/_transactions`. */
 export declare const TRANSACTIONS_ROUTE = "/_transactions";
-/** `GET <entrypoint>/_contract`. */
+/** `GET <api>/_contract`. */
 export declare const CONTRACT_ROUTE = "/_contract";
 /** The methods an operation or `/_transactions` route accepts: `POST`, only. */
 export declare const POST_ONLY: readonly string[];
@@ -12,7 +12,7 @@ export declare const POST_ONLY: readonly string[];
 export declare const GET_ONLY: readonly string[];
 /**
  * Whether a path lies in the protocol's namespace: underscore-prefixed paths beneath
- * the entrypoint are reserved for framework facilities; every other path is the
+ * the `api` mount path are reserved for framework facilities; every other path is the
  * host's.
  */
 export declare function isProtocolPath(path: string): boolean;

package/dist/protocol/http-response.encoder.d.ts

@@ -1,5 +1,5 @@
-import { type OperationResponse } from "../runtime/operation-response.js";
-import type { TransactionResponse } from "../transactions/transaction-response.js";
+import { type AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 /**
  * One HTTP response as the protocol hands it to a host: what the encoders
  * (`protocol.encodeOperation` / `encodeTransaction`) and `protocol.failure`
@@ -28,7 +28,7 @@ export type UnencodableReport = (error: unknown, operation?: number) => void;
  * `requestId` is echoed as `Aventara-Request-Id` — pass the id the request ran under,
  * which the decoder supplies.
  */
-export declare function encodeOperationResponse(response: OperationResponse, requestId: string, report?: UnencodableReport): AvProtocolResponse;
+export declare function encodeOperationResponse(response: AvOperationResponse, requestId: string, report?: UnencodableReport): AvProtocolResponse;
 /**
  * `protocol.encodeTransaction(response, requestId)`: the same for a plan's response. A
  * committed plan is `200 A1009` — even when it created something — with each
@@ -37,4 +37,4 @@ export declare function encodeOperationResponse(response: OperationResponse, req
  * status. A step whose result cannot be encoded answers `A3003` → 500 naming that step
  * as `cause.operation`, as every internal failure inside a plan does.
  */
-export declare function encodeTransactionResponse(response: TransactionResponse, requestId: string, report?: UnencodableReport): AvProtocolResponse;
+export declare function encodeTransactionResponse(response: AvTransactionResponse, requestId: string, report?: UnencodableReport): AvProtocolResponse;

package/dist/protocol/http-response.encoder.js

@@ -1,16 +1,16 @@
 import { encodeBase64, WIRE_SCALAR_PATTERNS, } from "../contracts/wire-scalar-format.js";
-import { Decimal } from "../runtime/decimal.js";
+import { AvDecimal } from "../runtime/decimal.js";
 import { SERIALIZATION_FAILURE_MESSAGE } from "../runtime/error-boundary.js";
 import { operationFailure, } from "../runtime/operation-response.js";
 import { httpStatus } from "./http-status.table.js";
 import { headers } from "./protocol-headers.js";
 export function encodeOperationResponse(response, requestId, report) {
     try {
-        return written(response, toWire(response.data, new Set()), requestId);
+        return written(response, toWireText(response.data), requestId);
     }
     catch (error) {
         report?.(error);
-        return written(serializationFailure(), null, requestId);
+        return written(serializationFailure(), "null", requestId);
     }
 }
 export function encodeTransactionResponse(response, requestId, report) {
@@ -25,13 +25,16 @@ export function encodeTransactionResponse(response, requestId, report) {
         }
         const steps = [];
         for (step = 0; step < data.length; step += 1) {
-            steps.push(toWireElement(data, step, new Set()));
+            if (!Object.hasOwn(data, step)) {
+                throw unencodable(data);
+            }
+            steps.push(toWireText(data[step]));
         }
-        return written(response, steps, requestId);
+        return written(response, `[${steps.join(",")}]`, requestId);
     }
     catch (error) {
         report?.(error, step);
-        return written(serializationFailure(step), null, requestId);
+        return written(serializationFailure(step), "null", requestId);
     }
 }
 function serializationFailure(operation) {
@@ -51,82 +54,118 @@ function written(response, wireData, requestId) {
             "Content-Type": "application/json",
             [headers.requestId]: requestId,
         },
-        body: JSON.stringify({ data: wireData, code, cause }),
+        body: `{"data":${wireData},${JSON.stringify({ code, cause }).slice(1)}`,
     };
 }
 function unencodable(value) {
     return new TypeError("A result value has no wire form.", { cause: value });
 }
-function toWire(value, ancestors) {
+function toWireText(value) {
+    const output = [];
+    const ancestors = new Set();
+    const stack = [{ kind: "value", value }];
+    while (stack.length > 0) {
+        const task = stack.pop();
+        if (task.kind === "text") {
+            output.push(task.text);
+            continue;
+        }
+        if (task.kind === "leave") {
+            ancestors.delete(task.container);
+            continue;
+        }
+        const current = task.value;
+        const scalar = scalarWireText(current);
+        if (scalar !== undefined) {
+            output.push(scalar);
+            continue;
+        }
+        const container = current;
+        if (ancestors.has(container)) {
+            throw unencodable(container);
+        }
+        ancestors.add(container);
+        stack.push({ kind: "leave", container });
+        if (Array.isArray(container)) {
+            pushList(stack, container);
+        }
+        else {
+            pushRecord(stack, container);
+        }
+    }
+    return output.join("");
+}
+function pushList(stack, list) {
+    const tasks = [{ kind: "text", text: "[" }];
+    for (let index = 0; index < list.length; index += 1) {
+        if (!Object.hasOwn(list, index)) {
+            throw unencodable(list);
+        }
+        if (index > 0) {
+            tasks.push({ kind: "text", text: "," });
+        }
+        tasks.push({ kind: "value", value: list[index] });
+    }
+    tasks.push({ kind: "text", text: "]" });
+    pushReversed(stack, tasks);
+}
+function pushRecord(stack, record) {
+    const prototype = Object.getPrototypeOf(record);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw unencodable(record);
+    }
+    const tasks = [{ kind: "text", text: "{" }];
+    for (const key of Object.keys(record)) {
+        const member = record[key];
+        if (member === undefined) {
+            continue;
+        }
+        tasks.push({
+            kind: "text",
+            text: `${tasks.length > 1 ? "," : ""}${JSON.stringify(key)}:`,
+        });
+        tasks.push({ kind: "value", value: member });
+    }
+    tasks.push({ kind: "text", text: "}" });
+    pushReversed(stack, tasks);
+}
+function pushReversed(stack, tasks) {
+    for (let index = tasks.length - 1; index >= 0; index -= 1) {
+        stack.push(tasks[index]);
+    }
+}
+function scalarWireText(value) {
     switch (typeof value) {
         case "string":
         case "boolean":
-            return value;
+            return JSON.stringify(value);
         case "number":
             if (Number.isFinite(value)) {
-                return value;
+                return JSON.stringify(value);
             }
             throw unencodable(value);
         case "bigint":
-            return value.toString(10);
+            return JSON.stringify(value.toString(10));
         case "object":
             break;
         default:
             throw unencodable(value);
     }
     if (value === null) {
-        return null;
+        return "null";
     }
     if (value instanceof Date) {
         const wire = Number.isNaN(value.getTime()) ? "" : value.toISOString();
         if (!WIRE_SCALAR_PATTERNS.datetime.test(wire)) {
             throw unencodable(value);
         }
-        return wire;
+        return JSON.stringify(wire);
     }
-    if (value instanceof Decimal) {
-        return value.toString();
+    if (value instanceof AvDecimal) {
+        return JSON.stringify(value.toString());
     }
     if (value instanceof Uint8Array) {
-        return encodeBase64(value);
-    }
-    if (ancestors.has(value)) {
-        throw unencodable(value);
-    }
-    ancestors.add(value);
-    try {
-        return Array.isArray(value)
-            ? toWireList(value, ancestors)
-            : toWireRecord(value, ancestors);
-    }
-    finally {
-        ancestors.delete(value);
-    }
-}
-function toWireList(list, ancestors) {
-    const wire = [];
-    for (let index = 0; index < list.length; index += 1) {
-        wire.push(toWireElement(list, index, ancestors));
-    }
-    return wire;
-}
-function toWireElement(list, index, ancestors) {
-    if (!Object.hasOwn(list, index)) {
-        throw unencodable(list);
-    }
-    return toWire(list[index], ancestors);
-}
-function toWireRecord(record, ancestors) {
-    const prototype = Object.getPrototypeOf(record);
-    if (prototype !== Object.prototype && prototype !== null) {
-        throw unencodable(record);
-    }
-    const members = [];
-    for (const key of Object.keys(record)) {
-        const member = record[key];
-        if (member !== undefined) {
-            members.push([key, toWire(member, ancestors)]);
-        }
+        return JSON.stringify(encodeBase64(value));
     }
-    return Object.fromEntries(members);
+    return undefined;
 }

package/dist/protocol/http-status.table.d.ts

@@ -1,7 +1,7 @@
-import type { OperationCode } from "../runtime/operation-response.js";
+import type { AvOperationCode } from "../runtime/operation-response.js";
 /**
  * `AvProtocol.httpStatus` — the HTTP status each A-code carries, as passive data.
  */
 export declare const httpStatus: {
-    readonly [C in OperationCode]: number;
+    readonly [C in AvOperationCode]: number;
 };

package/dist/protocol/operation-response.guard.d.ts

@@ -1,5 +1,5 @@
-import { type OperationResponse } from "../runtime/operation-response.js";
+import { type AvOperationResponse } from "../runtime/operation-response.js";
 /**
  * The HTTP status plays no part — a code is read even at an unexpected status.
  */
-export declare function isOperationResponse(value: unknown): value is OperationResponse;
+export declare function isOperationResponse(value: unknown): value is AvOperationResponse;

package/dist/protocol/protocol-surface.d.ts

@@ -1,5 +1,5 @@
-import type { ClientContract } from "../contracts/contract.js";
-import { type OperationIdentity } from "../operations/operation-identity.js";
+import type { AvContractClient } from "../contracts/contract.js";
+import { type AvOperationIdentity } from "../operations/operation-identity.js";
 /**
  * One route of the protocol surface: a route a host mounts for the bound
  * ClientContract, tagged by `kind`.
@@ -9,7 +9,7 @@ export type SurfaceRoute = ({
     readonly method: "POST";
     readonly path: `/_resources/${string}`;
     readonly resource: string;
-} & OperationIdentity) | {
+} & AvOperationIdentity) | {
     readonly kind: "contract";
     readonly method: "GET";
     readonly path: "/_contract";
@@ -24,4 +24,4 @@ export type SurfaceRoute = ({
  * order, then `GET /_contract`, then `POST /_transactions` when, and only when,
  * `transactions === "interactive"`.
  */
-export declare function surfaceOf(client: ClientContract): readonly SurfaceRoute[];
+export declare function surfaceOf(client: AvContractClient): readonly SurfaceRoute[];

package/dist/protocol/protocol.binder.d.ts

@@ -1,6 +1,7 @@
-import type { Framework } from "../framework/framework.js";
-import type { OperationResponse } from "../runtime/operation-response.js";
-import type { TransactionResponse } from "../transactions/transaction-response.js";
+import type { AvFramework } from "../framework/framework.js";
+import type { AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvState } from "../runtime/request-state.js";
+import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 import { type AvProtocolRequest, type DecodedOperation, type DecodedOperationRequest, type DecodedTransaction } from "./http-request.decoder.js";
 import { type AvProtocolResponse } from "./http-response.encoder.js";
 import { transportFailure } from "./protocol-failure.js";
@@ -11,49 +12,51 @@ import { type SurfaceRoute } from "./protocol-surface.js";
  */
 export type AvProtocolBinding = {
     /**
-     * Every route a host mounts for the bound ClientContract, from one list, each
+     * Every route a host mounts for the bound Contract (the Client Contract, or the
+     * Agent Contract under `{ origin: "agent" }`), from one list, each
      * tagged by `kind`: one `POST` `operation` route per `(resource, family, variant)`
-     * it advertises — nothing it does not — then the `contract` route `GET /_contract`
+     * it advertises and no other, then the `contract` route `GET /_contract`
      * (always), then the `transactions` route `POST /_transactions` exactly when its
      * `transactions` is `"interactive"`. Each path is relative to
-     * `framework.entrypoint`. Read once at bind time: every call answers the same
+     * `framework.api`. Read once at bind time: every call answers the same
      * deep-frozen list, which is passive data a host may serialize.
      */
     readonly surface: () => readonly SurfaceRoute[];
     /**
-     * An operation route's HTTP request → the client-origin request
+     * An operation route's HTTP request → the client-origin (or the binding's
+     * agent-origin) request
      * `framework.execute` takes, or the framework response that answers it instead,
      * with the request id either way. Answers absence for an unadvertised triple
      * without executing it, so a catch-all host is safe. Raw body: size, content type,
-     * JSON and shape enforced; parsed body: shape only — the rest was the host's
-     * parser's.
+     * JSON and shape enforced; parsed body: shape only, since the rest was the
+     * host's parser's job.
      */
     readonly decodeOperation: (request: AvProtocolRequest) => DecodedOperation;
     /**
-     * The same for `/_transactions` → the client-origin plan request
-     * `framework.executeTransaction` takes; absent unless the ClientContract's
+     * The same for `/_transactions` → the binding's origin's plan request
+     * `framework.executeTransaction` takes; absent unless the bound Contract's
      * transactions are `"interactive"`.
      */
     readonly decodeTransaction: (request: AvProtocolRequest) => DecodedTransaction;
     /**
-     * One operation's framework response — what `framework.execute` answered — as the
+     * One operation's framework response (what `framework.execute` answered) as the
      * HTTP response a host writes: the code's status, `data` in wire forms, `Aventara-
      * Request-Id` echoed. A result with no wire form answers `A3003` → 500. A
      * diagnostic of one operation names it (`resource`, `family`, `variant`), so the
-     * `A3003` reaches the diagnostics sink only when the host passes `decoded` —
-     * `decodeOperation`'s success value — as `handleOperation` does; without it the
+     * `A3003` reaches the diagnostics sink only when the host passes `decoded`
+     * (`decodeOperation`'s success value), as `handleOperation` does; without it the
      * answer is the same and nothing is reported.
      */
-    readonly encodeOperation: (response: OperationResponse, requestId: string, decoded?: DecodedOperationRequest) => AvProtocolResponse;
+    readonly encodeOperation: (response: AvOperationResponse, requestId: string, decoded?: DecodedOperationRequest) => AvProtocolResponse;
     /**
-     * The same for `/_transactions` — what `framework.executeTransaction` answered. An
+     * The same for `/_transactions`: what `framework.executeTransaction` answered. An
      * `A3003` is reported to the Framework's diagnostics sink as a `"transaction"`
-     * diagnostic — client origin, this `requestId`, the step it blames as `operation` —
+     * diagnostic (client origin, this `requestId`, the step it blames as `operation`)
      * with the value that had no wire form (or what its getter threw) as `error`.
      */
-    readonly encodeTransaction: (response: TransactionResponse, requestId: string) => AvProtocolResponse;
+    readonly encodeTransaction: (response: AvTransactionResponse, requestId: string) => AvProtocolResponse;
     /**
-     * A transport code — `A2000`, `A2010`, `A2011` or `A2012` — as the complete
+     * A transport code (`A2000`, `A2010`, `A2011` or `A2012`) as the complete
      * framework response. For a host that parses the body itself and must answer
      * its parser's failure. `A2012` requires the methods its route allows, so
      * every 405 carries `Allow`.
@@ -67,20 +70,30 @@ export type AvProtocolBinding = {
      * host hands it: one that is not an `AvProtocolRequest` answers `400 A2000`; it
      * never rejects.
      */
-    readonly handleOperation: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
+    readonly handleOperation: (request: AvProtocolRequest, options?: {
+        /**
+         * Seeds the request's `ctx.$state` (a host reads its platform request
+         * here, Passport's `req.user`, say). Called once, after decoding; a
+         * throw is answered like any developer failure. Omitted, the state is `{}`.
+         */
+        readonly state?: () => AvState | Promise<AvState>;
+    }) => Promise<AvProtocolResponse>;
     /**
      * The same for `/_transactions`: `decodeTransaction` →
      * `framework.executeTransaction` → `encodeTransaction`. Every step runs under
      * ClientContract rules; a committed plan is `200 A1009`, a rolled-back one its
      * failing step's own status.
      */
-    readonly handleTransaction: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
+    readonly handleTransaction: (request: AvProtocolRequest, options?: {
+        /** Seeds the plan's one `ctx.$state`, as for `handleOperation`. */
+        readonly state?: () => AvState | Promise<AvState>;
+    }) => Promise<AvProtocolResponse>;
     /**
      * The `GET /_contract` responder: the bound ClientContract's JCS-canonical bytes,
      * `ETag` its quoted hash, `Cache-Control: no-cache`, and `304` with no body when
      * `If-None-Match` matches (weak comparison, a list, `*`). Requires no identity
-     * header; any other method is `405 A2012` with `Allow: GET`. The bytes are written
-     * once, at bind time.
+     * header; any other method is `405 A2012` with `Allow: GET`. The bytes are the ones
+     * the Contract's hash was taken over, written once, at construction.
      */
     readonly encodeContract: (request: AvProtocolRequest) => AvProtocolResponse;
     /**
@@ -91,12 +104,22 @@ export type AvProtocolBinding = {
      * `undefined` for a path outside the protocol's namespace, which the host
      * answers itself. An operation or `/_transactions` route answered `500 A3000`
      * is also reported once to the Framework's diagnostics sink, as an
-     * `UnmountedRouteError` naming the route the host did not mount.
+     * `AvUnmountedRouteError` naming the route the host did not mount.
      */
     readonly answerAbsent: (request: AvProtocolRequest) => AvProtocolResponse | undefined;
 };
 /**
- * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract
- * once and returns the bound members, frozen.
+ * `AvProtocol.bind(framework, options?)`: reads the instance's compiled Client
+ * Contract (or, with `{ origin: "agent" }`, its Agent Contract) once and returns
+ * the bound members, frozen. Every request decoded through it runs under that
+ * origin.
  */
-export declare function bind(framework: Framework): AvProtocolBinding;
+export declare function bind(framework: AvFramework, options?: {
+    /**
+     * The origin every request through this binding runs under: `"client"`
+     * (the default: the Client Contract, `/_contract`'s document) or `"agent"`
+     * (the Agent Contract, its hash and its layer's pipelines), for a host
+     * that serves an AI agent — an MCP server.
+     */
+    readonly origin?: "client" | "agent";
+}): AvProtocolBinding;

package/dist/protocol/protocol.binder.js

@@ -7,13 +7,16 @@ import { encodeOperationResponse, encodeTransactionResponse, } from "./http-resp
 import { handleOperationRequest, handleTransactionRequest, operationUnencodableReport, planUnencodableReport, } from "./protocol.handler.js";
 import { transportFailure } from "./protocol-failure.js";
 import { surfaceOf } from "./protocol-surface.js";
-export function bind(framework) {
+export function bind(framework, options) {
     const { contracts } = framework;
-    const surface = surfaceOf(contracts.client);
-    const document = contractDocumentOf(contracts.client);
+    const origin = options?.origin === "agent" ? "agent" : "client";
+    const contract = contracts[origin];
+    const surface = surfaceOf(contract);
+    const document = contractDocumentOf(contract);
     const sink = diagnosticsSinkOf(framework);
     const handler = {
         contracts,
+        origin,
         execute: (request) => framework.execute(request),
         executeTransaction: (request) => framework.executeTransaction(request),
         owned: ownedExecutionOf(framework),
@@ -21,16 +24,16 @@ export function bind(framework) {
     };
     return Object.freeze({
         surface: () => surface,
-        decodeOperation: (request) => decodeOperationRequest(contracts, request),
-        decodeTransaction: (request) => decodeTransactionRequest(contracts, request),
+        decodeOperation: (request) => decodeOperationRequest(contracts, request, origin),
+        decodeTransaction: (request) => decodeTransactionRequest(contracts, request, origin),
         encodeOperation: (response, requestId, decoded) => encodeOperationResponse(response, requestId, decoded === undefined
             ? undefined
             : operationUnencodableReport(sink, decoded.request)),
-        encodeTransaction: (response, requestId) => encodeTransactionResponse(response, requestId, planUnencodableReport(sink, requestId)),
+        encodeTransaction: (response, requestId) => encodeTransactionResponse(response, requestId, planUnencodableReport(sink, requestId, origin)),
         failure: transportFailure,
-        handleOperation: (request) => handleOperationRequest(handler, request),
-        handleTransaction: (request) => handleTransactionRequest(handler, request),
+        handleOperation: (request, options) => handleOperationRequest(handler, request, options),
+        handleTransaction: (request, options) => handleTransactionRequest(handler, request, options),
         encodeContract: (request) => encodeContractRequest(document, request),
-        answerAbsent: (request) => answerAbsentRequest(contracts, request, sink),
+        answerAbsent: (request) => answerAbsentRequest(contracts, request, sink, origin),
     });
 }