@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

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 scope, 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;
     /**
@@ -89,12 +102,24 @@ export type AvProtocolBinding = {
      * `A2005`, `A2001`, `A2002` or `A2012` (with `Allow`) as the operation routes
      * would, `500 A3000` for a mounted route reached with its own method, and
      * `undefined` for a path outside the protocol's namespace, which the host
-     * answers itself.
+     * answers itself. An operation or `/_transactions` route answered `500 A3000`
+     * is also reported once to the Framework's diagnostics sink, as an
+     * `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

@@ -1,4 +1,5 @@
 import { diagnosticsSinkOf } from "../runtime/diagnostics-reporter.js";
+import { ownedExecutionOf } from "../runtime/owned-execution.registry.js";
 import { answerAbsentRequest } from "./absent-route.responder.js";
 import { contractDocumentOf, encodeContractRequest, } from "./contract-document.responder.js";
 import { decodeOperationRequest, decodeTransactionRequest, } from "./http-request.decoder.js";
@@ -6,29 +7,33 @@ 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),
         sink,
     };
     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),
+        answerAbsent: (request) => answerAbsentRequest(contracts, request, sink, origin),
     });
 }

package/dist/protocol/protocol.handler.d.ts

@@ -1,34 +1,47 @@
-import type { FrameworkContracts } from "../compiler/contract.compiler.js";
-import type { Framework } from "../framework/framework.js";
-import { type FrameworkDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
-import type { ClientOperationRequest } from "../runtime/operation-request.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { RemoteRequestOrigin } from "../config/config-layer.js";
+import type { AvFramework } from "../framework/framework.js";
+import { type AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
+import type { RemoteOperationRequest } from "../runtime/operation-request.js";
+import type { OwnedExecution } from "../runtime/owned-execution.registry.js";
+import type { AvState } from "../runtime/request-state.js";
 import { type AvProtocolRequest } from "./http-request.decoder.js";
 import { type AvProtocolResponse, type UnencodableReport } from "./http-response.encoder.js";
 /**
  * What the shortcuts read off the bound Framework: its compiled Contracts, its
- * execution entry points and its configured diagnostics sink.
+ * execution entry points — the public ones, and the owned ones that run a body this
+ * decoder parsed without copying it again (absent for anything but a
+ * constructed Framework) — and its configured diagnostics sink.
  */
 export type HandlerContext = {
-    readonly contracts: FrameworkContracts;
-    readonly execute: Framework["execute"];
-    readonly executeTransaction: Framework["executeTransaction"];
-    readonly sink: FrameworkDiagnosticsSink | undefined;
+    readonly contracts: AvContracts;
+    /** The origin every request the binding decodes runs under. */
+    readonly origin: RemoteRequestOrigin;
+    readonly execute: AvFramework["execute"];
+    readonly executeTransaction: AvFramework["executeTransaction"];
+    readonly owned: OwnedExecution | undefined;
+    readonly sink: AvDiagnosticsSink | undefined;
+};
+/** What a host passes beside one protocol request. */
+export type ProtocolCallOptions = {
+    /** Seeds the request's `ctx.$state`; called once, after decoding. Omitted, the state is `{}`. */
+    readonly state?: () => AvState | Promise<AvState>;
 };
 /**
  * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a `"transaction"`
- * diagnostic — client scope, the request id the plan ran under, and the step the
+ * diagnostic — client origin, the request id the plan ran under, and the step the
  * encoder blames as `operation` when it blames one. One spelling for both
  * `protocol.encodeTransaction` and `protocol.handleTransaction`.
  */
-export declare function planUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, requestId: string): UnencodableReport;
+export declare function planUnencodableReport(sink: AvDiagnosticsSink | undefined, requestId: string, origin?: RemoteRequestOrigin): UnencodableReport;
 /**
  * Where one operation's `A3003` goes: the Framework's diagnostics sink, as an
  * `"operation"` diagnostic carrying the decoded request's identity and id — the shape
- * the public `OperationDiagnostic` already has. One spelling for
+ * the public `AvOperationDiagnostic` already has. One spelling for
  * `protocol.handleOperation` and for `protocol.encodeOperation` given the decoded
  * request.
  */
-export declare function operationUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, request: ClientOperationRequest): UnencodableReport;
+export declare function operationUnencodableReport(sink: AvDiagnosticsSink | undefined, request: RemoteOperationRequest): UnencodableReport;
 /**
  * `protocol.handleOperation(request)`: the three steps a host would otherwise spell
  * out — `decodeOperation` → `framework.execute` → `encodeOperation` — in one call,
@@ -36,7 +49,7 @@ export declare function operationUnencodableReport(sink: FrameworkDiagnosticsSin
  * itself (a transport failure, an identity mismatch, an unadvertised route) is
  * answered without executing.
  */
-export declare function handleOperationRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;
+export declare function handleOperationRequest(context: HandlerContext, request: AvProtocolRequest, options?: ProtocolCallOptions): Promise<AvProtocolResponse>;
 /**
  * `protocol.handleTransaction(request)`: the same shortcut for `/_transactions` —
  * `decodeTransaction` → `framework.executeTransaction` → `encodeTransaction`. The
@@ -48,4 +61,4 @@ export declare function handleOperationRequest(context: HandlerContext, request:
  * handleOperationRequest} is; an `A3003` is reported through {@link
  * planUnencodableReport}.
  */
-export declare function handleTransactionRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;
+export declare function handleTransactionRequest(context: HandlerContext, request: AvProtocolRequest, options?: ProtocolCallOptions): Promise<AvProtocolResponse>;

package/dist/protocol/protocol.handler.js

@@ -1,10 +1,41 @@
 import { createDiagnosticsReporter, createReporter, } from "../runtime/diagnostics-reporter.js";
-import { decodeOperationRequest, decodeTransactionRequest, } from "./http-request.decoder.js";
+import { sanitizeOperationFailure } from "../runtime/error-boundary.js";
+import { decodeOperationRequest, decodeTransactionRequest, isParsedByDecoder, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
-export function planUnencodableReport(sink, requestId) {
+function operationEntry(context, request) {
+    return context.owned !== undefined && isParsedByDecoder(request.arguments)
+        ? context.owned.execute
+        : context.execute;
+}
+function transactionEntry(context, request) {
+    return context.owned !== undefined && isParsedByDecoder(request.plan)
+        ? context.owned.executeTransaction
+        : context.executeTransaction;
+}
+async function seededState(options, report, view) {
+    if (options?.state === undefined) {
+        return { ok: true, state: undefined };
+    }
+    try {
+        const state = await options.state();
+        return {
+            ok: true,
+            state: typeof state === "object" && state !== null && !Array.isArray(state)
+                ? state
+                : undefined,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            response: sanitizeOperationFailure(error, "runtime", report, view),
+        };
+    }
+}
+export function planUnencodableReport(sink, requestId, origin = "client") {
     return (error, operation) => createReporter(sink, {
         kind: "transaction",
-        scope: "client",
+        origin,
         requestId,
         ...(operation === undefined ? {} : { operation }),
     })(error, "A3003");
@@ -12,19 +43,33 @@ export function planUnencodableReport(sink, requestId) {
 export function operationUnencodableReport(sink, request) {
     return (error) => createDiagnosticsReporter(sink, request)(error, "A3003");
 }
-export async function handleOperationRequest(context, request) {
-    const decoded = decodeOperationRequest(context.contracts, request);
+export async function handleOperationRequest(context, request, options) {
+    const decoded = decodeOperationRequest(context.contracts, request, context.origin);
     if (!decoded.ok) {
         return decoded.response;
     }
-    const response = await context.execute(decoded.request);
+    const seeded = await seededState(options, createDiagnosticsReporter(context.sink, decoded.request), { path: ["arguments"], arguments: decoded.request.arguments });
+    const response = seeded.ok
+        ? await operationEntry(context, decoded.request)(seeded.state === undefined
+            ? decoded.request
+            : { ...decoded.request, state: seeded.state })
+        : seeded.response;
     return encodeOperationResponse(response, decoded.requestId, operationUnencodableReport(context.sink, decoded.request));
 }
-export async function handleTransactionRequest(context, request) {
-    const decoded = decodeTransactionRequest(context.contracts, request);
+export async function handleTransactionRequest(context, request, options) {
+    const decoded = decodeTransactionRequest(context.contracts, request, context.origin);
     if (!decoded.ok) {
         return decoded.response;
     }
-    const response = await context.executeTransaction(decoded.request);
-    return encodeTransactionResponse(response, decoded.requestId, planUnencodableReport(context.sink, decoded.requestId));
+    const seeded = await seededState(options, createReporter(context.sink, {
+        kind: "transaction",
+        origin: context.origin,
+        requestId: decoded.requestId,
+    }), { path: ["plan"], arguments: decoded.request.plan });
+    const response = seeded.ok
+        ? await transactionEntry(context, decoded.request)(seeded.state === undefined
+            ? decoded.request
+            : { ...decoded.request, state: seeded.state })
+        : seeded.response;
+    return encodeTransactionResponse(response, decoded.requestId, planUnencodableReport(context.sink, decoded.requestId, context.origin));
 }

package/dist/protocol/unmounted-route.error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What the diagnostics sink receives when `protocol.answerAbsent` is handed a
+ * request for a route the ClientContract advertises, with that route's own
+ * method: the host mounted only part of `protocol.surface()`. The caller's
+ * `500 A3000` is unchanged; this error names the route the host left out, so the
+ * server's diagnostics show it too. It is never sent to the caller.
+ */
+export declare class AvUnmountedRouteError extends Error {
+    /** What the ClientContract advertises: `resource.family.variant`, or `transactions`. */
+    readonly advertised: string;
+    /** The route as the request reached it: method and api-relative path. */
+    readonly route: string;
+    readonly name = "AvUnmountedRouteError";
+    constructor(
+    /** What the ClientContract advertises: `resource.family.variant`, or `transactions`. */
+    advertised: string, 
+    /** The route as the request reached it: method and api-relative path. */
+    route: string);
+}

package/dist/protocol/unmounted-route.error.js

@@ -0,0 +1,10 @@
+export class AvUnmountedRouteError extends Error {
+    advertised;
+    route;
+    name = "AvUnmountedRouteError";
+    constructor(advertised, route) {
+        super(`The ClientContract advertises ${advertised}, but the host mounted no route for ${route}, so protocol.answerAbsent answered it 500 A3000. Mount every protocol.surface() entry.`);
+        this.advertised = advertised;
+        this.route = route;
+    }
+}

package/dist/runtime/caller-data.copier.d.ts

@@ -0,0 +1,59 @@
+/** Why a caller value could not be copied. */
+export type CallerDataFailureKind = "unreadable-value" | "non-plain-value";
+/** A data location inside the copied value, from its root. */
+export type CallerDataPath = readonly (string | number)[];
+/**
+ * The curated failure of a door copy: what failed and where, relative to the copied
+ * root. Thrown by {@link copyCallerData} and caught by every door, which answers it as
+ * the caller's `A2004`/`V1001` at its own address. It never carries the value.
+ */
+export declare class AvCallerDataError extends Error {
+    readonly kind: CallerDataFailureKind;
+    readonly path: CallerDataPath;
+    /**
+     * The control mirror `path` starts from, when the failure is a mirror's
+     * tripwire read after the door; {@link locateCallerDataError} resolves it.
+     */
+    readonly within?: object | undefined;
+    readonly name = "AvCallerDataError";
+    constructor(kind: CallerDataFailureKind, path: CallerDataPath, 
+    /**
+     * The control mirror `path` starts from, when the failure is a mirror's
+     * tripwire read after the door; {@link locateCallerDataError} resolves it.
+     */
+    within?: object | undefined);
+}
+/**
+ * Objects a door keeps by identity rather than copying: values the framework built
+ * itself (a builder's `$ref` placeholder), or a request envelope's members, each
+ * copied by its own door. Never a caller's own object that a later reader reads.
+ * Asked about every object, arrays included, before anything else of it is read.
+ */
+export type CallerDataKeep = (value: object) => boolean;
+/**
+ * Objects a door mirrors by their descriptors rather than copying by value: a plan's
+ * `$ref` control objects (see {@link mirrorControlData}). Asked about every object
+ * the door does not keep, before anything else of it is read.
+ */
+export type CallerDataMirror = (value: object) => boolean;
+/** How a door treats the objects it meets; copying by value unless stated. */
+export type CallerDataPolicy = {
+    readonly keep?: CallerDataKeep;
+    readonly mirror?: CallerDataMirror;
+};
+/**
+ * Places a mirror tripwire's failure in the value the door copied: its path from the
+ * copy's root, where `error.path` started from the mirror. A failure that is not a
+ * tripwire's, or a mirror the copy does not hold, is returned as it is.
+ */
+export declare function locateCallerDataError(error: AvCallerDataError, copy: unknown): AvCallerDataError;
+/**
+ * Copies a caller's value into fresh plain data (see the module note), reading the
+ * caller's objects exactly once.
+ *
+ * @throws {@link AvCallerDataError} when a value cannot be read or is not plain data,
+ *   naming its path from `value`.
+ */
+export declare function copyCallerData(value: unknown, policy?: CallerDataPolicy): unknown;
+/** The `V1001` message a door answers a {@link AvCallerDataError} with. */
+export declare function callerDataFailureMessage(kind: CallerDataFailureKind): string;