@spine-event-engine/server 2.0.0-snapshot.21 → 2.0.0-snapshot.23

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

@@ -0,0 +1,125 @@
+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 { AgentNamedOperation } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { AgentExecutionSession } from "./agent-execution-session.js";
+/**
+ * Result of checking a persisted tool intent before any physical send.
+ */
+export type AgentMcpIntent = {
+    /**
+     * Identifies an admitted intent that has not dispatched.
+     */
+    readonly kind: "new";
+    /**
+     * Durable logical call identity.
+     */
+    readonly callId: string;
+} | {
+    /**
+     * Identifies a saved completed call.
+     */
+    readonly kind: "replay";
+    /**
+     * Original saved tool response.
+     */
+    readonly response: ToolResponse;
+} | {
+    /**
+     * Identifies a write whose physical outcome cannot be proven.
+     */
+    readonly kind: "unknown";
+    /**
+     * Safe refusal to resend the original write.
+     */
+    readonly response: ToolResponse;
+};
+/**
+ * Single budget and fenced journal authority supplied to the MCP runtime.
+ */
+export interface AgentMcpHost {
+    /**
+     * Accepted actor, source, Bounded Context, and tenant.
+     */
+    readonly scope: AiScope;
+    /**
+     * Registered MCP server definitions.
+     */
+    readonly registry: AiRegistry;
+    /**
+     * Selected backend with an optional MCP protocol factory.
+     */
+    readonly backend: AiBackendDefinition;
+    /**
+     * Saved named operation for this tool chain.
+     */
+    readonly operation: AgentNamedOperation;
+    /**
+     * Fenced invocation journal.
+     */
+    readonly session: AgentExecutionSession;
+    /**
+     * Cancellation signal for the active claim.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Original absolute operation deadline.
+     */
+    readonly deadlineEpochMs?: number;
+    /**
+     * Persists full shared input/output credit before an MCP physical send.
+     *
+     * @param server Configured MCP server identifier.
+     * @param request Physical protocol message and byte bounds.
+     * @returns Fenced ticket for the physical send.
+     */
+    reserveMessage(server: string, request: AiMcpMessageRequest): Promise<AiMcpMessageTicket>;
+    /**
+     * Checks a received chunk synchronously against its persisted credit.
+     *
+     * @param ticketId Saved physical-message ticket.
+     * @param bytes Newly decoded response bytes.
+     */
+    onReceived(ticketId: string, bytes: number): void;
+    /**
+     * Persists known receipt; uncertain credits remain charged.
+     *
+     * @param ticketId Saved physical-message ticket.
+     * @param receivedBytes Complete decoded response size, when known.
+     * @returns When the receipt is persisted.
+     */
+    finishMessage(ticketId: string, receivedBytes?: number): Promise<void>;
+    /**
+     * Checks shared tool count and persists intent before a write dispatch.
+     *
+     * @param invocation Model proposal and provider call identity.
+     * @param request Vetted server, tool, arguments, and effect.
+     * @returns Saved or newly allocated tool intent.
+     */
+    journalToolIntent(invocation: AiToolInvocation, request: Pick<ToolRequest, "server" | "tool" | "argumentsJson" | "effect">): Promise<AgentMcpIntent>;
+    /**
+     * Persists the physical-dispatch boundary under the current claim.
+     *
+     * @param callId Saved logical tool-call identity.
+     * @returns When the dispatch marker is persisted.
+     */
+    markToolDispatched(callId: string): Promise<void>;
+    /**
+     * Persists a complete tool response before model continuation.
+     *
+     * @param callId Saved logical tool-call identity.
+     * @param response Bounded tool result.
+     * @param history Typed conversation row retained with the result.
+     * @returns When the fenced result and history are persisted.
+     */
+    finishTool(callId: string, response: ToolResponse, history: AgentHistoryEntry): Promise<void>;
+    /**
+     * Persists a safe nonterminal diagnostic before returning it to an adapter.
+     *
+     * @param code Safe failure category.
+     * @param retryableByNewSignal Whether a later signal may retry the logical work.
+     * @returns Persisted diagnostic identity and category.
+     */
+    recordFailure(code: AiFailure["code"], retryableByNewSignal: boolean): Promise<AiFailure>;
+}
+//# sourceMappingURL=agent-mcp-host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-mcp-host.d.ts","sourceRoot":"","sources":["../../src/agent/agent-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;AAEpG,OAAO,KAAK,EACV,mBAAmB,EACpB,MAAM,+EAA+E,CAAC;AACvF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB;IACE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC,GACD;IACE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;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,mBAAmB,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;;;;;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,iBAAiB,CACf,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC,GACzE,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;;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

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=agent-mcp-host.js.map

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

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

package/dist/agent/agent-mcp-runtime.d.ts

@@ -0,0 +1,199 @@
+import type { AiToolRef } from "@spine-event-engine/ai";
+import type { AiMcpAdvertisedTool, AiToolInvocation } from "@spine-event-engine/ai/spi/adapter";
+import { type ToolResponse } from "@spine-event-engine/proto/agent";
+import type { AgentMcpHost } from "./agent-mcp-host.js";
+/**
+ * Executes one selected MCP catalog and its calls under the shared Agent journal.
+ */
+export declare class AgentMcpRuntime {
+    private readonly host;
+    private readonly allowedTools;
+    /**
+     * Connected protocol sessions indexed by registered server ID.
+     */
+    private readonly sessions;
+    /**
+     * Cancellation for all callbacks and protocol sessions in this invocation.
+     */
+    private readonly closed;
+    /**
+     * Shared discovery result for concurrent prepare callers.
+     */
+    private prepared?;
+    /**
+     * Shared completion for all callers closing this invocation.
+     */
+    private closing?;
+    /**
+     * Binds one accepted capability tool list to the active fenced operation.
+     *
+     * @param host Shared budget, session and diagnostic authority.
+     * @param allowedTools Capability tools in declared order.
+     */
+    constructor(host: AgentMcpHost, allowedTools: readonly AiToolRef[]);
+    /**
+     * Prepares the exact configured catalog before a model request is prepared.
+     *
+     * @returns Immutable descriptions and schemas in capability order.
+     */
+    prepare(): Promise<readonly AiMcpAdvertisedTool[]>;
+    /**
+     * Validates and executes one model-proposed call through persisted intent.
+     *
+     * @param invocation Correlated model proposal with canonical arguments.
+     * @returns Saved or newly journaled bounded tool response.
+     */
+    call(invocation: AiToolInvocation): Promise<ToolResponse>;
+    /**
+     * Checks one registered tool authorization callback before intent is saved.
+     *
+     * @param call Model-proposed tool call.
+     * @param policy Registered tool policy.
+     * @param argumentsObject Parsed JSON object arguments.
+     * @returns Allowed, denied or unavailable authorization state.
+     */
+    private authorize;
+    /**
+     * Cancels pending work and attempts bounded cleanup of connected protocol sessions.
+     *
+     * @returns Shared completion, rejecting if cleanup fails or exceeds the deadline.
+     */
+    close(): Promise<void>;
+    /**
+     * Cancels callbacks and bounds the wait for connected protocol sessions.
+     *
+     * @returns Shared cleanup completion or a safe rejection.
+     */
+    private closeSessions;
+    /**
+     * Lists registry-approved servers without making a connection.
+     *
+     * @returns Exact servers and configured tools.
+     */
+    private selected;
+    /**
+     * Prepares every selected server under bounded authorization.
+     *
+     * @returns Catalog in capability order.
+     */
+    private prepareAll;
+    /**
+     * Checks discovered definitions against configured names without advertising extras.
+     *
+     * @param id Registered server ID.
+     * @param allowed Configured tool names.
+     * @param found Bounded discovery result.
+     * @param definitions Accumulated exact catalog.
+     */
+    private collectDefinitions;
+    /**
+     * Returns the exact discovered catalog in capability order.
+     *
+     * @param definitions Checked descriptions and schemas by configured reference.
+     * @returns Immutable catalog in capability order.
+     */
+    private orderedCatalog;
+    /**
+     * Connects one authorized server and checks its credential-free identity.
+     *
+     * @param server Registered server configuration.
+     * @returns Scoped protocol session.
+     */
+    private connect;
+    /**
+     * Rejects identity drift after attempting bounded cleanup of the session.
+     *
+     * @param server Registered server configuration.
+     * @param session Newly connected protocol session.
+     * @param timeout Local callback timeout in milliseconds.
+     * @returns Completion after identity verification.
+     */
+    private checkConnectionIdentity;
+    /**
+     * Resolves scoped credentials without adding them to recorded identity.
+     *
+     * @param server Registered server configuration.
+     * @returns Headers or child environment for connection construction.
+     */
+    private resolve;
+    /**
+     * Reads the finite callback bound from application registration.
+     *
+     * @returns Callback timeout in milliseconds.
+     */
+    private hookTimeout;
+    /**
+     * Binds protocol reservations and receipts to the shared budget.
+     *
+     * @param server Registered server ID.
+     * @param control Bounded connection control.
+     * @returns Protocol controls scoped to this operation.
+     */
+    private protocol;
+    /**
+     * Checks whether the capability listed this exact tool reference.
+     *
+     * @param call Model-proposed tool reference.
+     * @returns Whether the tool is in the configured allowlist.
+     */
+    private isAllowed;
+    /**
+     * Finds a registered server by ID.
+     *
+     * @param id Registered server ID.
+     * @returns Server definition, or absence for an unknown ID.
+     */
+    private serverFor;
+    /**
+     * Records intent, dispatches once and persists the resulting response.
+     *
+     * @param call Correlated model proposal.
+     * @param session Checked protocol session.
+     * @param policy Registered tool policy.
+     * @returns Saved or newly persisted response.
+     */
+    private dispatch;
+    /**
+     * Performs a bounded call and preserves uncertainty for failed writes.
+     *
+     * @param call Correlated model proposal.
+     * @param session Checked protocol session.
+     * @param policy Registered tool policy.
+     * @param callId Runtime-allocated tool call ID.
+     * @returns Supported result or recorded safe failure.
+     */
+    private perform;
+    /**
+     * Converts supported text and structured JSON with the MCP error flag.
+     *
+     * @param callId Runtime-allocated tool call ID.
+     * @param result Bounded protocol result.
+     * @returns Domain tool response.
+     */
+    private response;
+    /**
+     * Records a failed proposal without fabricating an authorized request.
+     *
+     * @param code Safe failure category.
+     * @returns Failed response with a persisted diagnostic reference.
+     */
+    private rejected;
+    /**
+     * Creates response history for one completed tool intent.
+     *
+     * @param response Persisted tool response.
+     * @returns Conversation record wrapped as an Agent history entry.
+     */
+    private history;
+    /**
+     * Executes one callback within the operation and local deadline.
+     *
+     * @typeParam T Callback result type.
+     * @param run Callback with a child cancellation control.
+     * @param limitMs Configured local timeout in milliseconds.
+     * @param onLate Cleanup for a resource created after cancellation.
+     * @returns Callback result before the deadline.
+     */
+    private bounded;
+}
+//# sourceMappingURL=agent-mcp-runtime.d.ts.map

package/dist/agent/agent-mcp-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-mcp-runtime.d.ts","sourceRoot":"","sources":["../../src/agent/agent-mcp-runtime.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAqB,SAAS,EAAuB,MAAM,wBAAwB,CAAC;AAMhG,OAAO,KAAK,EACV,mBAAmB,EAInB,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAYL,KAAK,YAAY,EAClB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA6BxD;;GAEG;AACH,qBAAa,eAAe;IA4BxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY;IA5B/B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IAEpE;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAEhD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,CAA0C;IAE3D;;OAEG;IACH,OAAO,CAAC,OAAO,CAAC,CAAgB;IAEhC;;;;;OAKG;gBAEgB,IAAI,EAAE,YAAY,EAClB,YAAY,EAAE,SAAS,SAAS,EAAE;IAGrD;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC;IAMlD;;;;;OAKG;IACG,IAAI,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IA4B/D;;;;;;;OAOG;YACW,SAAS;IAwBvB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB;;;;OAIG;YACW,aAAa;IA8B3B;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAiBhB;;;;OAIG;YACW,UAAU;IAwBxB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;OAKG;YACW,OAAO;IA0BrB;;;;;;;OAOG;YACW,uBAAuB;IAmBrC;;;;;OAKG;YACW,OAAO;IAoBrB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAgBhB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;;OAOG;YACW,QAAQ;IA8BtB;;;;;;;;OAQG;YACW,OAAO;IAoCrB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAYhB;;;;;OAKG;YACW,QAAQ;IAWtB;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAkBf;;;;;;;;OAQG;YACW,OAAO;CA8BtB"}