@spine-event-engine/server 2.0.0-snapshot.24 → 2.0.0-snapshot.26

package/dist/agent/agent-live-interaction-events.d.ts

@@ -0,0 +1,46 @@
+import { type MessageShape } from "@bufbuild/protobuf";
+import { type MessageSchema } from "@spine-event-engine/core";
+import { type MessageId, type Event } from "@spine-event-engine/proto";
+import { type AgentOperationRef } from "@spine-event-engine/proto/agent";
+import type { SignalMetadata } from "../runtime/signal-metadata.js";
+import type { AgentLiveInvocation, AgentLiveModel, AgentOperationIdentity } from "./agent-live-inputs.js";
+/**
+ * Validation and envelope construction for one live Agent operation.
+ */
+interface LiveInteractionEvents {
+    /**
+     * Returns the original typed source without changing its payload URL.
+     *
+     * @param invocation Captured live Agent invocation.
+     * @returns The original typed Command or Event source reference.
+     */
+    sourceRef(invocation: AgentLiveInvocation): MessageId;
+    /**
+     * Creates a typed reference without a durable execution journal.
+     *
+     * @param invocation Captured live Agent invocation.
+     * @param operation Current AI operation identity.
+     * @param selected Models or selection retained for this invocation.
+     * @param stateSchema Generated Entity state schema.
+     * @returns The typed reference for this live AI operation.
+     */
+    operationRef(invocation: AgentLiveInvocation, operation: AgentOperationIdentity, stateSchema: MessageSchema, selected: AgentLiveModel): AgentOperationRef;
+    /**
+     * Creates one original System Event after validating its typed payload.
+     *
+     * @typeParam Schema Generated schema of the original System fact.
+     * @param agentId Typed Agent identifier.
+     * @param invocation Captured live Agent invocation.
+     * @param metadata Captured signal metadata.
+     * @param payload Typed serialized payload.
+     * @param schema Generated Protobuf schema for the payload.
+     * @returns The original System Event envelope for the validated payload.
+     */
+    envelope<Schema extends MessageSchema>(invocation: AgentLiveInvocation, metadata: SignalMetadata, agentId: AgentLiveInvocation["recipientId"], schema: Schema, payload: MessageShape<Schema>): Event;
+}
+/**
+ * Builds validated source and System-event facts without an execution journal.
+ */
+export declare const AgentLiveInteractionEvents: LiveInteractionEvents;
+export {};
+//# sourceMappingURL=agent-live-interaction-events.d.ts.map

package/dist/agent/agent-live-interaction-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-live-interaction-events.d.ts","sourceRoot":"","sources":["../../src/agent/agent-live-interaction-events.ts"],"names":[],"mappings":"AAcA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAiC,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,KAAK,EACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACvB,MAAM,wBAAwB,CAAC;AAEhC;;GAEG;AACH,UAAU,qBAAqB;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,UAAU,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAEtD;;;;;;;;OAQG;IACH,YAAY,CACV,UAAU,EAAE,mBAAmB,EAC/B,SAAS,EAAE,sBAAsB,EACjC,WAAW,EAAE,aAAa,EAC1B,QAAQ,EAAE,cAAc,GACvB,iBAAiB,CAAC;IAErB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,SAAS,aAAa,EACnC,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,mBAAmB,CAAC,aAAa,CAAC,EAC3C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAC5B,KAAK,CAAC;CACV;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,qBAiGvC,CAAC"}

package/dist/agent/agent-live-interaction-events.js

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { create, equals } from "@bufbuild/protobuf";
+import { AnySchema } from "@bufbuild/protobuf/wkt";
+import { AnyPacker, TypeUrls, Validate } from "@spine-event-engine/core";
+import { CommandIdSchema, EventIdSchema, EventSchema, MessageIdSchema, } from "@spine-event-engine/proto";
+import { AgentOperationRefSchema, AiModelKind, ModelRefSchema, } from "@spine-event-engine/proto/agent";
+/**
+ * Builds validated source and System-event facts without an execution journal.
+ */
+export const AgentLiveInteractionEvents = Object.freeze({
+    /**
+     * Correlates one live AI call with the original typed source and selected model.
+     * @param invocation Original source, Agent ID, and state type.
+     * @param operation Required operation and conversation IDs.
+     * @param stateSchema Generated Agent state descriptor.
+     * @param selected Authorized model and connection.
+     * @returns Validated operation reference.
+     */
+    operationRef(invocation, operation, stateSchema, selected) {
+        if (invocation.stateType !== stateSchema.typeName)
+            throw new TypeError("Agent interaction state type does not match accepted work.");
+        if (!invocation.recipientId.typeUrl.trim())
+            throw new TypeError("Agent interaction requires typed Agent ID.");
+        if (!operation.operation.value.trim() || !operation.conversation.value.trim())
+            throw new TypeError("Agent interaction requires operation and conversation IDs.");
+        const kind = Reflect.get(selected, "kind");
+        if (kind !== AiModelKind.GENERATION && kind !== AiModelKind.DECISION)
+            throw new TypeError("Agent interaction requires a selected model and kind.");
+        Validate.check(ModelRefSchema, selected.model);
+        const sourceSignal = this.sourceRef(invocation);
+        return Validate.check(AgentOperationRefSchema, create(AgentOperationRefSchema, {
+            operation: operation.operation,
+            agent: create(MessageIdSchema, {
+                id: invocation.recipientId,
+                typeUrl: TypeUrls.derive(stateSchema),
+            }),
+            sourceSignal,
+            model: selected.model,
+            kind: selected.kind,
+            conversation: operation.conversation,
+        }));
+    },
+    /**
+     * Wraps one typed System payload with the original source and Agent producer.
+     * @typeParam Schema Generated System payload descriptor.
+     * @param invocation Original source and typed recipient.
+     * @param metadata Signal ID, Time, and causal context provider.
+     * @param agentId Typed producer Agent ID.
+     * @param schema Generated System payload descriptor.
+     * @param payload Typed System payload.
+     * @returns Validated original Event envelope.
+     */
+    envelope(invocation, metadata, agentId, schema, payload) {
+        if (!agentId.typeUrl.trim() || !equals(AnySchema, invocation.recipientId, agentId))
+            throw new TypeError("Agent interaction producer differs from accepted recipient.");
+        this.sourceRef(invocation);
+        Validate.check(schema, payload);
+        const source = invocation.source;
+        const origin = source.case === "command"
+            ? metadata.eventFromCommand(source.value, {})
+            : metadata.eventFromEvent(source.value, {});
+        origin.context.producerId = agentId;
+        return Validate.check(EventSchema, create(EventSchema, {
+            id: origin.id,
+            context: origin.context,
+            message: AnyPacker.pack(schema, payload),
+        }));
+    },
+    /**
+     * Requires a typed source ID and preserves its concrete payload URL.
+     */
+    sourceRef(invocation) {
+        const source = invocation.source;
+        if (source.case === "command") {
+            const id = source.value.id;
+            if (!id?.uuid.trim())
+                throw new TypeError("Agent interaction requires source Command ID.");
+            const typeUrl = source.value.message?.typeUrl;
+            if (!typeUrl?.trim())
+                throw new TypeError("Agent interaction requires source payload type.");
+            return create(MessageIdSchema, { id: AnyPacker.pack(CommandIdSchema, id), typeUrl });
+        }
+        const id = source.value.id;
+        if (!id?.value.trim())
+            throw new TypeError("Agent interaction requires source Event ID.");
+        const typeUrl = source.value.message?.typeUrl;
+        if (!typeUrl?.trim())
+            throw new TypeError("Agent interaction requires source payload type.");
+        return create(MessageIdSchema, { id: AnyPacker.pack(EventIdSchema, id), typeUrl });
+    },
+});
+//# sourceMappingURL=agent-live-interaction-events.js.map

package/dist/agent/agent-live-interaction-events.js.map

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

package/dist/agent/agent-live-mcp-controls.d.ts

@@ -0,0 +1,129 @@
+import type { AiFailure, AiRegistry, AiScope } from "@spine-event-engine/ai";
+import type { AiBackendDefinition, AiMcpMessageRequest, AiMcpMessageTicket, AiToolInvocation } from "@spine-event-engine/ai/spi/adapter";
+import { type AgentHistoryEntry, type ToolRequest, type ToolResponse } from "@spine-event-engine/proto/agent";
+import type { AgentLiveAiAudit } from "./agent-live-ai-audit.js";
+import { AgentLiveBudget } from "./agent-live-budget.js";
+import type { AgentLiveMcpHost } from "./agent-live-mcp-host.js";
+import type { AgentOperationIdentity } from "./agent-live-inputs.js";
+/**
+ * Invocation-local MCP admissions and measured physical credit.
+ */
+export declare class AgentLiveMcpControls implements AgentLiveMcpHost {
+    #private;
+    private readonly input;
+    /**
+     * Binds one selected catalog to its live invocation budget and audit.
+     *
+     * @param input Typed input for this operation.
+     */
+    constructor(input: {
+        scope: AiScope;
+        registry: AiRegistry;
+        backend: AiBackendDefinition;
+        operation: AgentOperationIdentity;
+        signal: AbortSignal;
+        deadlineEpochMs?: number;
+        budget: AgentLiveBudget;
+        audit: AgentLiveAiAudit;
+        maxToolCalls?: number;
+        onProposal: (invocation: AiToolInvocation) => void;
+    });
+    /**
+     * Returns the selected AI scope.
+     *
+     * @returns The selected AI scope for this invocation.*/ get scope(): AiScope;
+    /**
+     * Returns the registered backends and MCP catalog.
+     *
+     * @returns The configured backend and MCP registry.*/ get registry(): AiRegistry;
+    /**
+     * Returns the selected backend definition.
+     *
+     * @returns The selected backend definition.*/ get backend(): AiBackendDefinition;
+    /**
+     * Returns the current operation identity.
+     *
+     * @returns The current typed AI operation identity.*/ get operation(): AgentOperationIdentity;
+    /**
+     * Returns the fenced invocation signal.
+     *
+     * @returns The cancellation signal for this invocation.*/ get signal(): AbortSignal;
+    /**
+     * Returns the absolute invocation deadline.
+     *
+     * @returns The absolute deadline, when configured.*/ get deadlineEpochMs(): number | undefined;
+    /**
+     * Acquires complete protocol response credit before a physical send.
+     *
+     * @param request Typed request for the current operation.
+     * @param server Configured MCP server registration.
+     * @returns A physical protocol ticket with complete response credit.
+     */
+    reserveMessage(server: string, request: AiMcpMessageRequest): Promise<AiMcpMessageTicket>;
+    /**
+     * Performs synchronous admission before returning a protocol ticket.
+     *
+     * @param request Typed request for the current operation.
+     * @param server Configured MCP server registration.
+     * @returns The admitted protocol ticket before asynchronous work begins.
+     */
+    private reservePhysicalMessage;
+    /**
+     * Checks decoded chunks against the reserved physical response credit.
+     *
+     * @param bytes Measured serialized byte count.
+     * @param ticketId Reserved physical attempt identifier.
+     */
+    onReceived(ticketId: string, bytes: number): void;
+    /**
+     * Completes a known receipt; unknown outcomes retain full reserved credit.
+     *
+     * @param receivedBytes Measured received payload bytes.
+     * @param ticketId Reserved physical attempt identifier.
+     * @returns Completion after a known protocol receipt is accounted for.
+     */
+    finishMessage(ticketId: string, receivedBytes?: number): Promise<void>;
+    /**
+     * Admits a model-proposed call before asynchronous audit or dispatch.
+     *
+     * @param facts Complete audit facts for the operation.
+     * @param invocation Captured live Agent invocation.
+     * @returns The unique live call identifier for an authorized tool.
+     */
+    admitTool(invocation: AiToolInvocation, facts: Pick<ToolRequest, "server" | "tool" | "argumentsJson" | "effect">): Promise<string>;
+    /**
+     * Marks the exact pre-send boundary once.
+     *
+     * @param callId Exact MCP tool call identifier.
+     */
+    markToolDispatched(callId: string): void;
+    /**
+     * Writes a completed tool result and conversation before continuation.
+     *
+     * @param callId Exact MCP tool call identifier.
+     * @param history Retained history entries or history port.
+     * @param response Typed response from the provider.
+     * @returns Completion after the tool result and conversation are saved.
+     */
+    finishTool(callId: string, response: ToolResponse, history: AgentHistoryEntry): Promise<void>;
+    /**
+     * Returns a safe invocation-local diagnostic reference.
+     *
+     * @param code Recorded failure code.
+     * @param retryableByNewSignal Whether a fresh signal may retry this failure.
+     * @returns A safe local diagnostic reference for the failed operation.
+     */
+    recordFailure(code: AiFailure["code"], retryableByNewSignal: boolean): Promise<AiFailure>;
+    /**
+     * Returns the active physical reservation or rejects a stale ticket.
+     *
+     * @param id Typed identifier of the requested item.
+     * @returns The active physical ticket for the requested message ID.
+     */
+    private message;
+    /**
+     * Rejects callbacks after handler cancellation.
+     */
+    private requireActive;
+}
+//# sourceMappingURL=agent-live-mcp-controls.d.ts.map

package/dist/agent/agent-live-mcp-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-live-mcp-controls.d.ts","sourceRoot":"","sources":["../../src/agent/agent-live-mcp-controls.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAQrE;;GAEG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;;IAezD,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB;;;;OAIG;gBAEgB,KAAK,EAAE;QACtB,KAAK,EAAE,OAAO,CAAC;QACf,QAAQ,EAAE,UAAU,CAAC;QACrB,OAAO,EAAE,mBAAmB,CAAC;QAC7B,SAAS,EAAE,sBAAsB,CAAC;QAClC,MAAM,EAAE,WAAW,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,MAAM,EAAE,eAAe,CAAC;QACxB,KAAK,EAAE,gBAAgB,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,IAAI,CAAC;KACpD;IAGH;;;4DAGwD,CAAC,IAAI,KAAK,IAAI,OAAO,CAE5E;IAED;;;0DAGsD,CAAC,IAAI,QAAQ,IAAI,UAAU,CAEhF;IAED;;;kDAG8C,CAAC,IAAI,OAAO,IAAI,mBAAmB,CAEhF;IAED;;;0DAGsD,CAAC,IAAI,SAAS,IAAI,sBAAsB,CAE7F;IAED;;;8DAG0D,CAAC,IAAI,MAAM,IAAI,WAAW,CAEnF;IAED;;;yDAGqD,CAAC,IAAI,eAAe,IAAI,MAAM,GAAG,SAAS,CAE9F;IAED;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAUzF;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAatE;;;;;;OAMG;IACG,SAAS,CACb,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC,GACvE,OAAO,CAAC,MAAM,CAAC;IAqBlB;;;;OAIG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQxC;;;;;;;OAOG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAahB;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,oBAAoB,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAIzF;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAMf;;OAEG;IACH,OAAO,CAAC,aAAa;CAGtB"}

package/dist/agent/agent-live-mcp-controls.js

@@ -0,0 +1,228 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { randomUUID } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import { AiToolCallIdSchema as ToolCallIdSchema, ToolRequestSchema, } from "@spine-event-engine/proto/agent";
+import { Validate } from "@spine-event-engine/core";
+import { AgentLiveBudget } from "./agent-live-budget.js";
+/**
+ * Invocation-local MCP admissions and measured physical credit.
+ */
+export class AgentLiveMcpControls {
+    input;
+    #messages = new Map();
+    #tools = new Map();
+    #proposals = new Set();
+    #toolCount = 0;
+    /**
+     * Binds one selected catalog to its live invocation budget and audit.
+     *
+     * @param input Typed input for this operation.
+     */
+    constructor(input) {
+        this.input = input;
+    }
+    /**
+     * Returns the selected AI scope.
+     *
+     * @returns The selected AI scope for this invocation.*/ get scope() {
+        return this.input.scope;
+    }
+    /**
+     * Returns the registered backends and MCP catalog.
+     *
+     * @returns The configured backend and MCP registry.*/ get registry() {
+        return this.input.registry;
+    }
+    /**
+     * Returns the selected backend definition.
+     *
+     * @returns The selected backend definition.*/ get backend() {
+        return this.input.backend;
+    }
+    /**
+     * Returns the current operation identity.
+     *
+     * @returns The current typed AI operation identity.*/ get operation() {
+        return this.input.operation;
+    }
+    /**
+     * Returns the fenced invocation signal.
+     *
+     * @returns The cancellation signal for this invocation.*/ get signal() {
+        return this.input.signal;
+    }
+    /**
+     * Returns the absolute invocation deadline.
+     *
+     * @returns The absolute deadline, when configured.*/ get deadlineEpochMs() {
+        return this.input.deadlineEpochMs;
+    }
+    /**
+     * Acquires complete protocol response credit before a physical send.
+     *
+     * @param request Typed request for the current operation.
+     * @param server Configured MCP server registration.
+     * @returns A physical protocol ticket with complete response credit.
+     */
+    reserveMessage(server, request) {
+        try {
+            return Promise.resolve(this.reservePhysicalMessage(server, request));
+        }
+        catch (error) {
+            return Promise.reject(error instanceof Error ? error : new Error("MCP admission failed", { cause: error }));
+        }
+    }
+    /**
+     * Performs synchronous admission before returning a protocol ticket.
+     *
+     * @param request Typed request for the current operation.
+     * @param server Configured MCP server registration.
+     * @returns The admitted protocol ticket before asynchronous work begins.
+     */
+    reservePhysicalMessage(server, request) {
+        this.requireActive();
+        if (!server.trim() || !request.method.trim())
+            throw new TypeError("MCP message identity is empty.");
+        if (request.phase === "call" && !this.#tools.get(request.toolCallId ?? "")?.dispatched)
+            throw new Error("MCP tool has not been dispatched.");
+        const reservation = this.input.budget.reservePhysical(request.inputBytes, request.maxOutputBytes, "protocol");
+        const id = randomUUID();
+        this.#messages.set(id, reservation);
+        return {
+            id,
+            signal: this.signal,
+            ...(this.deadlineEpochMs === undefined ? {} : { deadlineEpochMs: this.deadlineEpochMs }),
+            ...(reservation.maxOutputBytes === undefined
+                ? {}
+                : { maxOutputBytes: reservation.maxOutputBytes }),
+        };
+    }
+    /**
+     * Checks decoded chunks against the reserved physical response credit.
+     *
+     * @param bytes Measured serialized byte count.
+     * @param ticketId Reserved physical attempt identifier.
+     */
+    onReceived(ticketId, bytes) {
+        this.input.budget.onReceived(this.message(ticketId), bytes);
+    }
+    /**
+     * Completes a known receipt; unknown outcomes retain full reserved credit.
+     *
+     * @param receivedBytes Measured received payload bytes.
+     * @param ticketId Reserved physical attempt identifier.
+     * @returns Completion after a known protocol receipt is accounted for.
+     */
+    finishMessage(ticketId, receivedBytes) {
+        try {
+            const ticket = this.message(ticketId);
+            if (receivedBytes !== undefined)
+                this.input.budget.settlePhysical(ticket, receivedBytes);
+            this.#messages.delete(ticketId);
+            return Promise.resolve();
+        }
+        catch (error) {
+            return Promise.reject(error instanceof Error ? error : new Error("MCP receipt failed", { cause: error }));
+        }
+    }
+    /**
+     * Admits a model-proposed call before asynchronous audit or dispatch.
+     *
+     * @param facts Complete audit facts for the operation.
+     * @param invocation Captured live Agent invocation.
+     * @returns The unique live call identifier for an authorized tool.
+     */
+    async admitTool(invocation, facts) {
+        this.requireActive();
+        this.input.onProposal(invocation);
+        const proposal = `${invocation.ticketId}\u0000${invocation.providerCallId}`;
+        if (this.#proposals.has(proposal))
+            throw new Error("MCP model proposal was already admitted.");
+        if (this.input.maxToolCalls !== undefined && this.#toolCount >= this.input.maxToolCalls)
+            throw new Error("Agent tool call budget is exhausted.");
+        this.input.budget.reserveToolCall();
+        this.#toolCount++;
+        this.#proposals.add(proposal);
+        const id = randomUUID();
+        this.#tools.set(id, { proposal, dispatched: false, finished: false });
+        const request = create(ToolRequestSchema, {
+            ...facts,
+            call: create(ToolCallIdSchema, { value: id }),
+        });
+        Validate.check(ToolRequestSchema, request);
+        await this.input.audit.toolStarted(invocation, request);
+        return id;
+    }
+    /**
+     * Marks the exact pre-send boundary once.
+     *
+     * @param callId Exact MCP tool call identifier.
+     */
+    markToolDispatched(callId) {
+        const claim = this.#tools.get(callId);
+        if (claim === undefined || claim.dispatched)
+            throw new Error("MCP tool is missing or already dispatched.");
+        this.requireActive();
+        claim.dispatched = true;
+    }
+    /**
+     * Writes a completed tool result and conversation before continuation.
+     *
+     * @param callId Exact MCP tool call identifier.
+     * @param history Retained history entries or history port.
+     * @param response Typed response from the provider.
+     * @returns Completion after the tool result and conversation are saved.
+     */
+    async finishTool(callId, response, history) {
+        const claim = this.#tools.get(callId);
+        if (claim === undefined ||
+            !claim.dispatched ||
+            claim.finished ||
+            response.call?.value !== callId)
+            throw new Error("MCP tool completion does not match its dispatch.");
+        await this.input.audit.toolFinished(response, history);
+        claim.finished = true;
+    }
+    /**
+     * Returns a safe invocation-local diagnostic reference.
+     *
+     * @param code Recorded failure code.
+     * @param retryableByNewSignal Whether a fresh signal may retry this failure.
+     * @returns A safe local diagnostic reference for the failed operation.
+     */
+    recordFailure(code, retryableByNewSignal) {
+        return Promise.resolve({ code, retryableByNewSignal, diagnosticId: randomUUID() });
+    }
+    /**
+     * Returns the active physical reservation or rejects a stale ticket.
+     *
+     * @param id Typed identifier of the requested item.
+     * @returns The active physical ticket for the requested message ID.
+     */
+    message(id) {
+        const ticket = this.#messages.get(id);
+        if (ticket === undefined)
+            throw new Error("MCP physical ticket is no longer active.");
+        return ticket;
+    }
+    /**
+     * Rejects callbacks after handler cancellation.
+     */
+    requireActive() {
+        if (this.signal.aborted)
+            throw new Error("MCP invocation is closed.");
+    }
+}
+//# sourceMappingURL=agent-live-mcp-controls.js.map

package/dist/agent/agent-live-mcp-controls.js.map

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

package/dist/agent/agent-live-mcp-host.d.ts

@@ -0,0 +1,88 @@
+import type { AiFailure, AiRegistry, AiScope } from "@spine-event-engine/ai";
+import type { AiBackendDefinition, AiMcpMessageRequest, AiMcpMessageTicket, AiToolInvocation } from "@spine-event-engine/ai/spi/adapter";
+import type { AgentHistoryEntry, ToolRequest, ToolResponse } from "@spine-event-engine/proto/agent";
+import type { AgentOperationIdentity } from "./agent-live-inputs.js";
+/**
+ * Invocation-local controls used by one selected MCP catalog.
+ */
+export interface AgentLiveMcpHost {
+    /**
+     * Selected AI scope for this invocation.
+     */
+    readonly scope: AiScope;
+    /**
+     * Registered backend and MCP catalog.
+     */
+    readonly registry: AiRegistry;
+    /**
+     * Selected backend definition.
+     */
+    readonly backend: AiBackendDefinition;
+    /**
+     * Current typed AI operation identity.
+     */
+    readonly operation: AgentOperationIdentity;
+    /**
+     * Cancellation fence for the invocation.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Absolute invocation deadline, when configured.
+     */
+    readonly deadlineEpochMs: number | undefined;
+    /**
+     * Acquires complete physical request and response credit before an MCP send.
+     *
+     * @param request Typed request for the current operation.
+     * @param server Configured MCP server registration.
+     * @returns A physical protocol ticket with complete response credit.
+     */
+    reserveMessage(server: string, request: AiMcpMessageRequest): Promise<AiMcpMessageTicket>;
+    /**
+     * Checks decoded chunks against their already reserved ticket.
+     *
+     * @param bytes Measured serialized byte count.
+     * @param ticketId Reserved physical attempt identifier.
+     */
+    onReceived(ticketId: string, bytes: number): void;
+    /**
+     * Completes a known receipt, retaining full credit for unknown outcomes.
+     *
+     * @param receivedBytes Measured received payload bytes.
+     * @param ticketId Reserved physical attempt identifier.
+     * @returns Completion after a known protocol receipt is accounted for.
+     */
+    finishMessage(ticketId: string, receivedBytes?: number): Promise<void>;
+    /**
+     * Admits one vetted model-proposed tool and returns its unique live call ID.
+     *
+     * @param invocation Captured live Agent invocation.
+     * @param request Typed request for the current operation.
+     * @returns The unique live call identifier for an authorized tool.
+     */
+    admitTool(invocation: AiToolInvocation, request: Pick<ToolRequest, "server" | "tool" | "argumentsJson" | "effect">): Promise<string>;
+    /**
+     * Marks the pre-send boundary so the same write cannot be dispatched twice.
+     *
+     * @param callId Exact MCP tool call identifier.
+     */
+    markToolDispatched(callId: string): void;
+    /**
+     * Writes the result and original conversation row before model continuation.
+     *
+     * @param callId Exact MCP tool call identifier.
+     * @param history Retained history entries or history port.
+     * @param response Typed response from the provider.
+     * @returns Completion after the tool result and conversation are saved.
+     */
+    finishTool(callId: string, response: ToolResponse, history: AgentHistoryEntry): Promise<void>;
+    /**
+     * Creates a safe local diagnostic for a failed tool or protocol operation.
+     *
+     * @param code Recorded failure code.
+     * @param retryableByNewSignal Whether a fresh signal may retry this failure.
+     * @returns A safe local diagnostic reference for the failed operation.
+     */
+    recordFailure(code: AiFailure["code"], retryableByNewSignal: boolean): Promise<AiFailure>;
+}
+//# sourceMappingURL=agent-live-mcp-host.d.ts.map

package/dist/agent/agent-live-mcp-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-live-mcp-host.d.ts","sourceRoot":"","sources":["../../src/agent/agent-live-mcp-host.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAE7C;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE1F;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;;OAMG;IACH,SAAS,CACP,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC,GACzE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;OAIG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9F;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,oBAAoB,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3F"}

package/dist/agent/{agent-mcp-host.js → agent-live-mcp-host.js}

@@ -12,4 +12,4 @@
  * the License.
  */
 export {};
-//# sourceMappingURL=agent-mcp-host.js.map
+//# sourceMappingURL=agent-live-mcp-host.js.map

package/dist/agent/agent-live-mcp-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-live-mcp-host.js","sourceRoot":"","sources":["../../src/agent/agent-live-mcp-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}