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

package/dist/agent/agent-execution-session.js

@@ -0,0 +1,238 @@
+/*
+ * 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 { clone, create, toBinary } from "@bufbuild/protobuf";
+import { EmptySchema } from "@bufbuild/protobuf/wkt";
+import { AiModelKind, ModelPreferenceSchema, ModelRefSchema, } from "@spine-event-engine/proto/agent";
+import { AgentExecutionRecordSchema, } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { AgentExecutionFault } from "./agent-execution-fault.js";
+/**
+ * Serializes one claimed Agent record's journal and lease images.
+ */
+export class AgentExecutionSession {
+    storage;
+    token;
+    #controller = new AbortController();
+    #record;
+    #initialPreferences;
+    #preferences;
+    #queue = Promise.resolve();
+    /**
+     * Creates a serialized mutation boundary for one exact provider claim.
+     *
+     * @param storage Provider methods for this Agent repository.
+     * @param record Record returned by the successful claim.
+     * @param token Exclusive token required by later provider writes.
+     * @param preferences Per-instance selections observed at claim time.
+     */
+    constructor(storage, record, token, preferences = []) {
+        this.storage = storage;
+        this.token = token;
+        if (record.accepted?.key === undefined || record.claimToken !== token)
+            throw new Error("Agent execution session requires its exact claimed record.");
+        this.#record = record;
+        this.#initialPreferences = preferences;
+        this.#preferences = [...this.#initialPreferences];
+    }
+    /**
+     * Cancels callbacks after provider authority is lost.
+     *
+     * @returns Cancellation signal shared with scoped work.
+     */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /**
+     * Returns a defensive copy of the last provider-confirmed image.
+     *
+     * @returns Independent execution record image.
+     */
+    record() {
+        return clone(AgentExecutionRecordSchema, this.#record);
+    }
+    /**
+     * Returns per-instance selections observed at the claim boundary.
+     *
+     * @returns Current staged selections in a separate array.
+     */
+    preferences() {
+        return [...this.#preferences];
+    }
+    /**
+     * Returns selections fixed when this invocation claimed its Agent.
+     *
+     * @returns Claim-time selections in a separate array.
+     */
+    initialPreferences() {
+        return [...this.#initialPreferences];
+    }
+    /**
+     * Sets one per-kind selection for conditional completion of this signal.
+     *
+     * @param kind Generation or decision kind being selected.
+     * @param model Chosen deployment, or undefined to inherit the repository default.
+     */
+    stagePreference(kind, model) {
+        if (this.signal.aborted)
+            throw new Error("Agent execution claim is no longer active.");
+        if (kind !== AiModelKind.GENERATION && kind !== AiModelKind.DECISION)
+            throw new TypeError("Agent model preference requires a supported kind.");
+        const selection = model === undefined
+            ? { case: "inheritRepositoryDefault", value: create(EmptySchema) }
+            : { case: "model", value: clone(ModelRefSchema, model) };
+        const next = create(ModelPreferenceSchema, { kind, selection });
+        const index = this.#preferences.findIndex((entry) => entry.kind === kind);
+        if (index < 0)
+            this.#preferences.push(next);
+        else
+            this.#preferences[index] = next;
+    }
+    /**
+     * Restores claim-time selections after a draft is rejected before completion.
+     */
+    discardPreferenceChanges() {
+        this.#preferences.splice(0, this.#preferences.length, ...this.#initialPreferences);
+    }
+    /**
+     * Returns fixed provider payload bounds for pre-dispatch reservations.
+     *
+     * @returns Provider capacity for the current Agent repository.
+     */
+    capacity() {
+        return this.storage.capacity;
+    }
+    /**
+     * Updates the journal against the latest provider-confirmed image.
+     *
+     * @param makeNext Pure transformation of the last confirmed record.
+     * @param historyEntries Conversation and System records saved with this update.
+     * @returns Independent image confirmed by the provider write.
+     */
+    update(makeNext, historyEntries = []) {
+        return this.#enqueue(async () => {
+            const current = this.record();
+            const expectedRecordBytes = toBinary(AgentExecutionRecordSchema, current);
+            const next = makeNext(current);
+            const key = current.accepted?.key;
+            if (key === undefined)
+                throw new Error("Claimed Agent record lost its accepted key.");
+            await this.storage.update({
+                key,
+                token: this.token,
+                expectedRecordBytes,
+                next,
+                historyEntries,
+            });
+            this.#record = next;
+            return this.record();
+        });
+    }
+    /**
+     * Updates the claim expiry and reloads the provider image before later fenced writes.
+     *
+     * @param expiresAt Requested later claim expiry.
+     * @returns Reloaded provider-confirmed record image.
+     */
+    renew(expiresAt) {
+        return this.#enqueue(async () => {
+            const key = this.#record.accepted?.key;
+            if (key === undefined)
+                throw new Error("Claimed Agent record lost its accepted key.");
+            if (!(await this.storage.renew(key, this.token, expiresAt)))
+                throw new Error("Agent execution lost its provider claim during renewal.");
+            const refreshed = await this.storage.read(key);
+            if (refreshed?.claimToken !== this.token)
+                throw new Error("Agent execution lost its provider claim after renewal.");
+            this.#record = refreshed;
+            return this.record();
+        });
+    }
+    /**
+     * Commits Entity and execution results under the same serialized fence.
+     *
+     * @param makeNext Pure transformation of the last confirmed record.
+     * @param historyEntries History records committed with the Entity transition.
+     * @param entityCommit Conditional state and output commit, when supplied.
+     * @returns Independent image confirmed by the atomic completion.
+     */
+    complete(makeNext, historyEntries, entityCommit) {
+        return this.#enqueue(async () => {
+            const current = this.record();
+            const expectedRecordBytes = toBinary(AgentExecutionRecordSchema, current);
+            const key = current.accepted?.key;
+            if (key === undefined)
+                throw new Error("Claimed Agent record lost its accepted key.");
+            const next = makeNext(current);
+            await this.storage.complete({
+                key,
+                token: this.token,
+                expectedRecordBytes,
+                next,
+                historyEntries,
+                ...(entityCommit === undefined ? {} : { entityCommit }),
+            });
+            this.#record = next;
+            return this.record();
+        });
+    }
+    /**
+     * Marks saved output IDs delivered and reloads the provider image.
+     *
+     * @param signals Original output IDs accepted by normal delivery.
+     * @returns Reloaded provider-confirmed record image.
+     */
+    markDelivered(signals) {
+        return this.#enqueue(async () => {
+            const current = this.record();
+            const key = current.accepted?.key;
+            if (key === undefined)
+                throw new Error("Claimed Agent record lost its accepted key.");
+            await this.storage.markDelivered(key, this.token, toBinary(AgentExecutionRecordSchema, current), signals);
+            const refreshed = await this.storage.read(key);
+            if (refreshed === undefined)
+                throw new Error("Agent output record disappeared after delivery.");
+            this.#record = refreshed;
+            return this.record();
+        });
+    }
+    /**
+     * Stops later queued mutations from using this claim.
+     */
+    stop() {
+        this.#controller.abort();
+    }
+    /**
+     * Serializes one fenced provider operation after preceding writes settle.
+     *
+     * @typeParam Result Result returned by the provider operation.
+     * @param work Provider mutation to run while the session remains active.
+     * @returns Mutation result or a claim-loss rejection.
+     */
+    #enqueue(work) {
+        const task = this.#queue.then(async () => {
+            if (this.signal.aborted)
+                throw new Error("Agent execution claim is no longer active.");
+            try {
+                return await work();
+            }
+            catch (error) {
+                if (!(error instanceof AgentExecutionFault))
+                    this.stop();
+                throw error;
+            }
+        });
+        this.#queue = task.then(() => undefined, () => undefined);
+        return task;
+    }
+}
+//# sourceMappingURL=agent-execution-session.js.map

package/dist/agent/agent-execution-session.js.map

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

package/dist/agent/agent-history.d.ts

@@ -0,0 +1,148 @@
+import type { ConversationHistoryRead, HistoryPage, HistoryRead } from "@spine-event-engine/ai";
+import type { Event } from "@spine-event-engine/proto";
+import { type AgentHistoryEntry, type ConversationRecord } from "@spine-event-engine/proto/agent";
+import { type AgentHistoryPage, type AgentHistoryStorage, type AgentHistoryView } from "@spine-event-engine/storage/provider";
+/**
+ * Identifies the exact repository and Agent instance for a continuation.
+ */
+export interface AgentHistoryScope {
+    /**
+     * Bounded Context name in the active repository.
+     */
+    readonly context: string;
+    /**
+     * Complete tenant identity encoding.
+     */
+    readonly tenant: string;
+    /**
+     * Registered Entity state type.
+     */
+    readonly repository: string;
+    /**
+     * Canonical typed Agent ID key.
+     */
+    readonly entity: string;
+}
+/**
+ * Returns a saved complete page or delegates to a live provider read.
+ *
+ * @param scope Exact repository and Agent scope.
+ * @param view Indexed history view.
+ * @param request Public read request.
+ * @param live Loads the current provider page only when needed.
+ * @param maxBytes Optional response-byte ceiling for this read.
+ * @returns The saved or newly loaded complete provider page.
+ */
+export type AgentHistoryJournal = (scope: AgentHistoryScope, view: AgentHistoryView, request: HistoryRead, live: () => Promise<AgentHistoryPage>, maxBytes: number | undefined) => Promise<AgentHistoryPage>;
+/**
+ * Repository binding for an Agent's mandatory indexed history.
+ *
+ * @typeParam Id Typed Agent identifier.
+ */
+export interface AgentHistoryBinding<Id> {
+    /**
+     * Mandatory provider handle.
+     */
+    readonly storage: AgentHistoryStorage<Id>;
+    /**
+     * Typed Agent ID.
+     */
+    readonly entityId: Id;
+    /**
+     * Full cursor and journal scope.
+     */
+    readonly scope: AgentHistoryScope;
+    /**
+     * Optional durable read replay interceptor.
+     */
+    readonly journal?: AgentHistoryJournal;
+    /**
+     * Optional maximum serialized entry bytes in one response.
+     */
+    readonly maxBytes?: number;
+}
+/**
+ * Internal accessors shared by the Agent base and repository runtime.
+ */
+export interface AgentHistoryReadAccess {
+    /**
+     * Attaches one mandatory storage handle to a restored Agent.
+     *
+     * @typeParam Id Typed Agent identifier.
+     * @param entity Restored Agent.
+     * @param binding Repository history binding.
+     */
+    bind<Id>(entity: object, binding: AgentHistoryBinding<Id>): void;
+    /**
+     * Binds a journal that records and replays this handler's history reads.
+     *
+     * @param entity Agent with an existing repository history binding.
+     * @param journal Intercepts history reads during the handler.
+     * @returns Callback that restores the original history binding after the handler finishes.
+     */
+    withJournal(entity: object, journal: AgentHistoryJournal): () => void;
+    /**
+     * Reads all categories.
+     *
+     * @param entity Agent instance.
+     * @param request Page request.
+     * @returns Complete entries and continuation.
+     */
+    full(entity: object, request: HistoryRead): Promise<HistoryPage<AgentHistoryEntry>>;
+    /**
+     * Reads one conversation.
+     *
+     * @param entity Agent instance.
+     * @param request Conversation and page request.
+     * @returns Conversation records and continuation.
+     */
+    conversation(entity: object, request: ConversationHistoryRead): Promise<HistoryPage<ConversationRecord>>;
+    /**
+     * Reads System Events.
+     *
+     * @param entity Agent instance.
+     * @param request Page request.
+     * @returns Original Event envelopes and continuation.
+     */
+    system(entity: object, request: HistoryRead): Promise<HistoryPage<Event>>;
+    /**
+     * Reads emitted domain Events.
+     *
+     * @param entity Agent instance.
+     * @param request Page request.
+     * @returns Original Event envelopes and continuation.
+     */
+    domain(entity: object, request: HistoryRead): Promise<HistoryPage<Event>>;
+    /**
+     * Validates a cursor and reads one provider page.
+     *
+     * @param entity Agent instance.
+     * @param view Indexed history view.
+     * @param request Page request.
+     * @returns Complete entries and continuation.
+     */
+    read(entity: object, view: AgentHistoryView, request: HistoryRead): Promise<HistoryPage<AgentHistoryEntry>>;
+    /**
+     * Applies the same opaque cursor contract to a testing repository binding.
+     *
+     * @typeParam Id Typed Agent identifier supplied by the repository binding.
+     * @param binding Exact Agent repository and tenant storage scope.
+     * @param view Indexed history view.
+     * @param request Public page request.
+     * @returns Retained entries and opaque continuation.
+     */
+    readBound<Id>(binding: AgentHistoryBinding<Id>, view: AgentHistoryView, request: HistoryRead): Promise<HistoryPage<AgentHistoryEntry>>;
+    /**
+     * Persists a genuine framework System Event.
+     *
+     * @param entity Agent instance.
+     * @param event Original System Event envelope.
+     * @returns Completion after append.
+     */
+    appendSystem(entity: object, event: Event): Promise<void>;
+}
+/**
+ * Binds protected Agent history reads to repository storage.
+ */
+export declare const AgentHistoryReads: AgentHistoryReadAccess;
+//# sourceMappingURL=agent-history.d.ts.map

package/dist/agent/agent-history.d.ts.map

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