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

package/dist/agent/agent-live-ai-runtime.d.ts

@@ -0,0 +1,300 @@
+import { type MessageShape } from "@bufbuild/protobuf";
+import { type MessageSchema } from "@spine-event-engine/core";
+import type { AgentAi, AiModel, AiRegistry, AiResult, AiScope, ModelRef } from "@spine-event-engine/ai";
+import { AiModelKind, ConversationIdSchema } from "@spine-event-engine/proto/agent";
+import type { RepositoryAiOptions } from "../repository/repository.js";
+import type { AgentLiveAudit } from "./agent-live-audit.js";
+import { AgentLiveBudget } from "./agent-live-budget.js";
+import type { AgentLiveModel } from "./agent-live-inputs.js";
+/**
+ * Executes named AI calls for one live handler without a recovery journal.
+ */
+export declare class AgentLiveAiRuntime implements AgentAi {
+    #private;
+    private readonly registry;
+    private readonly repository;
+    private readonly scope;
+    private readonly selected;
+    private readonly budget;
+    private readonly deadlineEpochMs;
+    private readonly onSelect;
+    private readonly audit;
+    private readonly checkSession;
+    /**
+     * Binds selected models and one invocation-wide local budget.
+     *
+     * @param audit Retained history audit for this invocation.
+     * @param budget Invocation-wide resource budget.
+     * @param checkSession Callback that validates the current execution session.
+     * @param deadlineEpochMs Absolute invocation deadline, when configured.
+     * @param onSelect Callback that stages a model selection.
+     * @param registry Registered AI models or MCP servers.
+     * @param repository Repository configured for this Entity.
+     * @param scope Captured invocation or tenant scope.
+     * @param selected Models or selection retained for this invocation.
+     * @param signal Signal or cancellation signal for this operation.
+     */
+    constructor(registry: AiRegistry, repository: RepositoryAiOptions, scope: AiScope, selected: ReadonlyMap<AiModelKind, AgentLiveModel>, budget: AgentLiveBudget, signal: AbortSignal, deadlineEpochMs: number | undefined, onSelect: (kind: AiModelKind, model: ModelRef | undefined) => void, audit: AgentLiveAudit<unknown>, checkSession?: () => Promise<void>);
+    /**
+     * Executes one validated registered capability and returns its fresh result.
+     *
+     * @typeParam I Generated input schema of the invoked capability.
+     * @typeParam O Generated output schema of the invoked capability.
+     * @param model Selected AI model for this invocation.
+     * @param request Typed request for the current operation.
+     * @returns The typed model result with its operation identifier.
+     */
+    invoke<I extends MessageSchema, O extends MessageSchema>(model: AiModel<I, O>, request: {
+        readonly call: string;
+        readonly conversation: MessageShape<typeof ConversationIdSchema>;
+        readonly input: MessageShape<I>;
+    }): Promise<AiResult<MessageShape<O>>>;
+    /**
+     * Prepares a checked model preference for a later accepted signal.
+     *
+     * @param kind Declared model or operation kind.
+     * @param model Selected AI model for this invocation.
+     */
+    select(kind: AiModelKind, model: ModelRef | undefined): void;
+    /**
+     * Rejects a handler that returned with a pending model operation.
+     */
+    finish(): void;
+    /**
+     * Cancels callbacks retained after the handler returns.
+     */
+    close(): void;
+    /**
+     * Rejects stale or cancelled handler capabilities.
+     */
+    private requireOpen;
+    /**
+     * Validates typed input and per-handler call identity before any external work.
+     *
+     * @typeParam I Generated schema for the supplied input.
+     * @typeParam O Generated schema for the declared output.
+     * @param model Selected AI model for this invocation.
+     * @param request Typed request for the current operation.
+     */
+    private validateRequest;
+    /**
+     * Connects the authenticated selected deployment and runs one backend operation.
+     *
+     * @typeParam I Generated input schema for the selected capability.
+     * @typeParam O Generated output schema for the selected capability.
+     * @param model Selected AI model for this invocation.
+     * @param operationId Typed AI operation identifier.
+     * @param request Typed request for the current operation.
+     * @returns The authenticated backend outcome for this operation.
+     */
+    private execute;
+    /**
+     * Executes the authorized model and closes its selected MCP sessions.
+     *
+     * @typeParam I Generated input schema of the authorized model.
+     * @typeParam O Generated output schema of the authorized model.
+     * @param audit Retained history audit for this invocation.
+     * @param backend Selected AI backend registration.
+     * @param deadline Operation deadline, when configured.
+     * @param identity Authorized provider connection identity.
+     * @param model Selected AI model for this invocation.
+     * @param operation Current AI operation identity.
+     * @param operationId Typed AI operation identifier.
+     * @param request Typed request for the current operation.
+     * @returns The authorized backend outcome after MCP cleanup.
+     */
+    private runAuthorized;
+    /**
+     * Records a safe setup failure without disguising unrelated errors.
+     *
+     * @param audit Retained history audit for this invocation.
+     * @param error Original operation or cleanup error.
+     * @returns The recorded safe failure for an MCP setup error.
+     */
+    private setupFailure;
+    /**
+     * Invokes the prepared backend and validates its result before audit.
+     *
+     * @typeParam I Generated input schema used for validation.
+     * @typeParam O Generated output schema validated before audit.
+     * @param advertised Tools advertised by the selected MCP session.
+     * @param attempts Physical attempt state for this invocation.
+     * @param audit Retained history audit for this invocation.
+     * @param backend Selected AI backend registration.
+     * @param deadline Operation deadline, when configured.
+     * @param identity Authorized provider connection identity.
+     * @param mcp Selected MCP session, when present.
+     * @param model Selected AI model for this invocation.
+     * @param operationId Typed AI operation identifier.
+     * @param request Typed request for the current operation.
+     * @returns The validated backend outcome after its audit is saved.
+     */
+    private runAndAudit;
+    /**
+     * Handles operation and cleanup failures while closing the selected protocol.
+     *
+     * @typeParam T Operation result retained through MCP cleanup.
+     * @param mcp Selected MCP session, when present.
+     * @param run Callback executed inside the guarded session.
+     * @returns The operation result after MCP cleanup succeeds.
+     */
+    private withMcp;
+    /**
+     * Binds the exact configured MCP catalog to this live operation.
+     *
+     * @param attempts Physical attempt state for this invocation.
+     * @param audit Retained history audit for this invocation.
+     * @param backend Selected AI backend registration.
+     * @param deadline Operation deadline, when configured.
+     * @param model Selected AI model for this invocation.
+     * @param operation Current AI operation identity.
+     * @returns The configured MCP runtime, or undefined when no server is selected.
+     */
+    private mcp;
+    /**
+     * Rejects a proposal absent from its completed physical model response.
+     *
+     * @param attempts Physical attempt state for this invocation.
+     * @param invocation Captured live Agent invocation.
+     */
+    private checkProposal;
+    /**
+     * Handles an operation failure together with MCP cleanup failure.
+     *
+     * @param failed Original failure retained through cleanup.
+     * @param mcp Selected MCP session, when present.
+     * @returns Completion after preserving any operation and MCP cleanup failures.
+     */
+    private closeMcp;
+    /**
+     * Executes a checked backend using the selected authenticated connection.
+     *
+     * @typeParam I Generated input schema sent to the backend.
+     * @typeParam O Generated output schema returned by the backend.
+     * @param advertised Tools advertised by the selected MCP session.
+     * @param backend Selected AI backend registration.
+     * @param control MCP execution controls for this invocation.
+     * @param deadline Operation deadline, when configured.
+     * @param identity Authorized provider connection identity.
+     * @param model Selected AI model for this invocation.
+     * @param operationId Typed AI operation identifier.
+     * @param request Typed request for the current operation.
+     * @returns The checked backend outcome from the authenticated connection.
+     */
+    private runConnected;
+    /**
+     * Calculates capability time at the invocation's sampled deadline.
+     *
+     * @param model Selected AI model for this invocation.
+     * @returns The effective epoch deadline, or undefined when no limit applies.
+     */
+    private operationDeadline;
+    /**
+     * Resolves the selected backend through current repository policy.
+     *
+     * @param model Selected AI model for this invocation.
+     * @returns The selected model and its registered backend.
+     */
+    private selectedBackend;
+    /**
+     * Checks authenticated nonsecret identity immediately before connection.
+     *
+     * @param backend Selected AI backend registration.
+     * @param deadline Operation deadline, when configured.
+     * @param selected Models or selection retained for this invocation.
+     * @returns The revalidated authenticated connection identity.
+     */
+    private authorize;
+    /**
+     * Returns credential-free fields from the validated selected connection.
+     *
+     * @param selected Models or selection retained for this invocation.
+     * @returns Credential-free fields from the selected connection.
+     */
+    private savedIdentity;
+    /**
+     * Compares all credential-free identity fields.
+     *
+     * @param left Earlier value in the comparison.
+     * @param right Later value in the comparison.
+     * @returns Whether all credential-free connection fields match.
+     */
+    private sameIdentity;
+    /**
+     * Creates physical tickets, validation, and local accounting to one backend.
+     *
+     * @param attempts Physical attempt state for this invocation.
+     * @param audit Retained history audit for this invocation.
+     * @param deadline Operation deadline, when configured.
+     * @param mcp Selected MCP session, when present.
+     * @param model Selected AI model for this invocation.
+     * @returns The controls for physical admission, validation, and accounting.
+     */
+    private control;
+    /**
+     * Checks cancellation and the selected operation deadline.
+     *
+     * @param deadline Operation deadline, when configured.
+     * @returns Whether the session remains active and before its deadline.
+     */
+    private hasAuthority;
+    /**
+     * Creates one fresh physical request with per-capability request count.
+     *
+     * @param _request Original request retained for callback compatibility.
+     * @param attempts Physical attempt state for this invocation.
+     * @param audit Retained history audit for this invocation.
+     * @param deadline Operation deadline, when configured.
+     * @param model Selected AI model for this invocation.
+     * @param number Physical attempt sequence number.
+     * @returns The admitted physical attempt or a safe failure.
+     */
+    private beginAttempt;
+    /**
+     * Sets a fresh transport ticket only after its start audit settles.
+     *
+     * @param attempts Physical attempt state for this invocation.
+     * @param deadline Operation deadline, when configured.
+     * @param id Typed identifier of the requested item.
+     * @param model Selected AI model for this invocation.
+     * @returns The reserved transport ticket after its start audit.
+     */
+    private newTicket;
+    /**
+     * Acquires full output credit before transport starts.
+     *
+     * @param attempts Physical attempt state for this invocation.
+     * @param bytes Measured serialized byte count.
+     * @param credit Reserved input and output byte credit.
+     * @param id Typed identifier of the requested item.
+     * @param model Selected AI model for this invocation.
+     * @returns The transport ticket with full response credit reserved.
+     */
+    private reserveTransport;
+    /**
+     * Gets one existing reservation for a physical receipt.
+     *
+     * @param attempts Physical attempt state for this invocation.
+     * @param id Typed identifier of the requested item.
+     * @returns The active physical reservation for the supplied ticket ID.
+     */
+    private ticket;
+    /**
+     * Completes measured response bytes without replay state.
+     *
+     * @param attempts Physical attempt state for this invocation.
+     * @param audit Retained history audit for this invocation.
+     * @param completion Completed provider attempt or operation.
+     * @returns Completion after response accounting and audit settle.
+     */
+    private finishAttempt;
+    /**
+     * Returns one safe local diagnostic without a durable execution record.
+     *
+     * @param code Recorded failure code.
+     * @param retryableByNewSignal Whether a fresh signal may retry this failure.
+     * @returns A safe local AI failure without persisted execution status.
+     */
+    private failure;
+}
+//# sourceMappingURL=agent-live-ai-runtime.d.ts.map

package/dist/agent/agent-live-ai-runtime.d.ts.map

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