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

package/dist/agent/agent-history.js

@@ -0,0 +1,340 @@
+/*
+ * 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 } from "@bufbuild/protobuf";
+import { TimestampSchema } from "@bufbuild/protobuf/wkt";
+import { AgentHistoryCursorSchema, AgentHistoryEntrySchema, } from "@spine-event-engine/proto/agent";
+import { AgentHistoryKeys, } from "@spine-event-engine/storage/provider";
+const bindings = new WeakMap();
+/**
+ * Binds protected Agent history reads to repository storage.
+ */
+export const AgentHistoryReads = Object.freeze({
+    /**
+     * Attaches one mandatory storage handle to a restored Agent.
+     *
+     * @typeParam Id Typed Agent identifier.
+     * @param entity Restored Agent.
+     * @param binding Repository history binding.
+     */
+    bind(entity, binding) {
+        bindings.set(entity, binding);
+    },
+    withJournal(entity, journal) {
+        const binding = bindings.get(entity);
+        if (binding === undefined)
+            throw new Error("Agent history is available only from repository execution.");
+        bindings.set(entity, { ...binding, journal });
+        return () => {
+            bindings.set(entity, binding);
+        };
+    },
+    /**
+     * Persists the exact genuine System envelope before an Agent handler runs.
+     *
+     * @param entity Restored Agent.
+     * @param event Original System Event envelope.
+     * @returns Completion after append.
+     */
+    appendSystem(entity, event) {
+        const binding = bindings.get(entity);
+        if (binding === undefined)
+            throw new Error("Agent history is available only from repository execution.");
+        if (event.context?.timestamp === undefined)
+            throw new Error("Agent System Event requires its original timestamp.");
+        return binding.storage.append(binding.entityId, create(AgentHistoryEntrySchema, {
+            occurredAt: event.context.timestamp,
+            item: { case: "systemEvent", value: event },
+        }));
+    },
+    /**
+     * Reads all categories, newest first.
+     *
+     * @param entity Restored Agent.
+     * @param request Page request.
+     * @returns Complete entries and continuation.
+     */
+    full(entity, request) {
+        return this.read(entity, { kind: "full" }, request);
+    },
+    /**
+     * Reads one explicit conversation, newest first.
+     *
+     * @param entity Restored Agent.
+     * @param request Conversation and page request.
+     * @returns Conversation records and continuation.
+     */
+    async conversation(entity, request) {
+        const conversation = request.conversation;
+        if (conversation === null ||
+            typeof conversation !== "object" ||
+            !("value" in conversation) ||
+            typeof conversation.value !== "string" ||
+            conversation.value.length === 0)
+            throw new TypeError("Agent conversation history requires a ConversationId.");
+        const page = await this.read(entity, { kind: "conversation", conversation: request.conversation }, request);
+        return {
+            items: page.items.map((entry) => {
+                if (entry.item.case !== "conversationRecord")
+                    throw new Error("Agent history provider returned the wrong category.");
+                return entry.item.value;
+            }),
+            ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+        };
+    },
+    /**
+     * Reads System Event envelopes, newest first.
+     *
+     * @param entity Restored Agent.
+     * @param request Page request.
+     * @returns Original Event envelopes and continuation.
+     */
+    async system(entity, request) {
+        const page = await this.read(entity, { kind: "system" }, request);
+        return {
+            items: page.items.map((entry) => {
+                if (entry.item.case !== "systemEvent")
+                    throw new Error("Agent history provider returned the wrong category.");
+                return entry.item.value;
+            }),
+            ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+        };
+    },
+    /**
+     * Reads emitted domain Event envelopes, newest first.
+     *
+     * @param entity Restored Agent.
+     * @param request Page request.
+     * @returns Original Event envelopes and continuation.
+     */
+    async domain(entity, request) {
+        const page = await this.read(entity, { kind: "domain" }, request);
+        return {
+            items: page.items.map((entry) => {
+                if (entry.item.case !== "domainEvent")
+                    throw new Error("Agent history provider returned the wrong category.");
+                return entry.item.value;
+            }),
+            ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+        };
+    },
+    /**
+     * Validates the cursor before asking the indexed provider for a page.
+     *
+     * @param entity Restored Agent.
+     * @param view Indexed history view.
+     * @param request Page request.
+     * @returns Complete entries and continuation.
+     */
+    async read(entity, view, request) {
+        const binding = bindings.get(entity);
+        if (binding === undefined)
+            throw new Error("Agent history is available only from repository execution.");
+        return this.readBound(binding, view, request);
+    },
+    /**
+     * Reads a bounded provider page or reuses the page saved by the active handler.
+     *
+     * @typeParam Id Typed Agent identifier supplied by the repository binding.
+     * @param binding Repository storage, identity and optional handler journal.
+     * @param view Indexed category and optional conversation filter.
+     * @param request Page size and opaque continuation from a previous page.
+     * @returns Retained entries with the next cursor when older entries remain.
+     */
+    async readBound(binding, view, request) {
+        if (!Number.isSafeInteger(request.pageSize) || request.pageSize <= 0)
+            throw new RangeError("Agent history pageSize must be a positive safe integer.");
+        const maxBytes = AgentHistoryPages.limit(binding.maxBytes);
+        const after = AgentHistoryCursorValues.decode(request.cursor?.value, binding.scope, view, maxBytes);
+        const live = () => AgentHistoryPages.load(binding, view, request, after, maxBytes);
+        const page = binding.journal === undefined
+            ? await live()
+            : await binding.journal(binding.scope, view, request, live, maxBytes);
+        return AgentHistoryPages.present(binding.scope, view, page);
+    },
+});
+/**
+ * Loads and presents complete provider pages at the protected read boundary.
+ */
+const AgentHistoryPages = Object.freeze({
+    /**
+     * Loads a scoped provider page after validating the request.
+     *
+     * @typeParam Id Typed Agent identifier.
+     * @param binding Repository storage binding.
+     * @param view Indexed history view.
+     * @param request Public read request.
+     * @param after Validated continuation key.
+     * @param maxBytes Response byte limit.
+     * @returns Complete provider page.
+     */
+    load(binding, view, request, after, maxBytes) {
+        return binding.storage.read({
+            entityId: binding.entityId,
+            view,
+            ...(after === undefined ? {} : { after }),
+            count: request.pageSize,
+            ...(maxBytes === undefined ? {} : { maxBytes }),
+        });
+    },
+    /**
+     * Validates a supplied byte budget before live or journaled reads.
+     *
+     * @param configured Optional runtime byte limit.
+     * @returns Validated byte limit.
+     */
+    limit(configured) {
+        if (configured !== undefined && (!Number.isSafeInteger(configured) || configured <= 0))
+            throw new RangeError("Agent history maxBytes must be a positive safe integer.");
+        return configured;
+    },
+    /**
+     * Converts the complete page into the public cursor shape.
+     *
+     * @param scope Exact Agent repository scope.
+     * @param view Indexed history view.
+     * @param page Complete provider page.
+     * @returns Public page with a bound continuation cursor.
+     */
+    present(scope, view, page) {
+        const last = page.entries.at(-1);
+        if (page.hasMore && last === undefined)
+            throw new Error("Agent history provider returned an empty continuation.");
+        return {
+            items: page.entries,
+            ...(page.hasMore && last !== undefined
+                ? {
+                    nextCursor: create(AgentHistoryCursorSchema, {
+                        value: AgentHistoryCursorValues.encode(scope, view, AgentHistoryKeys.fromEntry(last)),
+                    }),
+                }
+                : {}),
+        };
+    },
+});
+/**
+ * Encodes the complete existing-key continuation without allocating a position.
+ */
+const AgentHistoryCursorValues = Object.freeze({
+    /**
+     * Returns an opaque versioned cursor for one view and scope.
+     *
+     * @param scope Exact repository and Agent scope.
+     * @param view Indexed history view.
+     * @param key Complete last key.
+     * @returns Opaque cursor bytes.
+     */
+    encode(scope, view, key) {
+        const payload = {
+            version: 1,
+            scope,
+            method: view.kind,
+            conversation: view.kind === "conversation" ? view.conversation.value : null,
+            seconds: key.occurredAt.seconds.toString(),
+            nanos: key.occurredAt.nanos,
+            category: key.category,
+            recordId: key.recordId,
+        };
+        return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+    },
+    /**
+     * Rejects malformed and cross-scope cursors before a provider read.
+     *
+     * @param value Cursor bytes, when continuing.
+     * @param scope Exact repository and Agent scope.
+     * @param view Indexed history view.
+     * @param maxBytes Maximum serialized page bytes.
+     * @returns Complete last key, when continuing.
+     */
+    decode(value, scope, view, maxBytes) {
+        if (value === undefined)
+            return undefined;
+        try {
+            if (maxBytes !== undefined && value.length > this.maxLength(scope, view, maxBytes))
+                throw new Error();
+            const cursor = this.parse(value);
+            if (cursor.version !== 1 ||
+                cursor.method !== view.kind ||
+                cursor.conversation !== (view.kind === "conversation" ? view.conversation.value : null) ||
+                JSON.stringify(cursor.scope) !== JSON.stringify(scope))
+                throw new Error();
+            const key = this.key(cursor);
+            if (view.kind !== "full" && key.category !== view.kind)
+                throw new Error();
+            return key;
+        }
+        catch {
+            throw new TypeError("Invalid Agent history cursor for this repository view.");
+        }
+    },
+    /**
+     * Calculates a bound for a full byte-budget key, JSON escapes, and the actual scope.
+     *
+     * @param scope Exact repository and Agent scope.
+     * @param view Indexed history view.
+     * @param maxBytes Maximum serialized page bytes.
+     * @returns Maximum encoded cursor character count.
+     */
+    maxLength(scope, view, maxBytes) {
+        const scopeBytes = Buffer.byteLength(JSON.stringify(scope), "utf8");
+        const conversation = view.kind === "conversation" ? view.conversation.value : null;
+        const viewBytes = Buffer.byteLength(JSON.stringify(conversation), "utf8");
+        const rawBytes = maxBytes * 6 + scopeBytes + viewBytes + 256;
+        return Math.min(Number.MAX_SAFE_INTEGER, Math.ceil(rawBytes / 3) * 4);
+    },
+    /**
+     * Decodes exact versioned payload fields.
+     *
+     * @param value Opaque cursor bytes.
+     * @returns Parsed cursor fields.
+     */
+    parse(value) {
+        if (!/^[A-Za-z0-9_-]+$/.test(value))
+            throw new Error();
+        const raw = Buffer.from(value, "base64url").toString("utf8");
+        if (Buffer.from(raw, "utf8").toString("base64url") !== value)
+            throw new Error();
+        const data = JSON.parse(raw);
+        if (data === null || typeof data !== "object")
+            throw new Error();
+        const cursor = data;
+        if (Object.keys(cursor).sort().join(",") !==
+            "category,conversation,method,nanos,recordId,scope,seconds,version")
+            throw new Error();
+        return cursor;
+    },
+    /**
+     * Restores and validates the complete continuation key.
+     *
+     * @param cursor Parsed cursor fields.
+     * @returns Complete continuation key.
+     */
+    key(cursor) {
+        if (typeof cursor.seconds !== "string" ||
+            !/^-?(0|[1-9][0-9]*)$/.test(cursor.seconds) ||
+            typeof cursor.nanos !== "number" ||
+            typeof cursor.recordId !== "string" ||
+            (cursor.category !== "conversation" &&
+                cursor.category !== "system" &&
+                cursor.category !== "domain"))
+            throw new Error();
+        const key = {
+            occurredAt: create(TimestampSchema, { seconds: BigInt(cursor.seconds), nanos: cursor.nanos }),
+            category: cursor.category,
+            recordId: cursor.recordId,
+        };
+        AgentHistoryKeys.indexValue(key);
+        return key;
+    },
+});
+//# sourceMappingURL=agent-history.js.map

package/dist/agent/agent-history.js.map

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

package/dist/agent/agent-interaction-audit.d.ts

@@ -0,0 +1,58 @@
+import { type MessageShape } from "@bufbuild/protobuf";
+import { type MessageSchema } from "@spine-event-engine/core";
+import { type Event } from "@spine-event-engine/proto";
+import { AiModelKind, type AgentHistoryEntry, type AgentOperationRef } from "@spine-event-engine/proto/agent";
+import { type AgentAcceptedInvocation, type AgentExecutionRecord, type AgentNamedOperation } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { SignalMetadata } from "../runtime/signal-metadata.js";
+import { AgentExecutionSession } from "./agent-execution-session.js";
+/**
+ * Saves one original Agent interaction Event and posts it to the System Context.
+ */
+export declare class AgentInteractionAudit {
+    private readonly session;
+    private readonly accepted;
+    private readonly stateSchema;
+    private readonly metadata;
+    private readonly onRegisterSchema;
+    private readonly onPublish;
+    /**
+     * Binds interaction evidence to one accepted Agent invocation.
+     *
+     * @param session Fenced execution journal and history writer.
+     * @param accepted Original accepted signal and recipient.
+     * @param stateSchema Generated Agent state descriptor.
+     * @param metadata Canonical signal metadata service.
+     * @param onRegisterSchema Registers a System event payload descriptor.
+     * @param onPublish Persists the System Context copy of an original Event.
+     */
+    constructor(session: AgentExecutionSession, accepted: AgentAcceptedInvocation, stateSchema: MessageSchema, metadata: SignalMetadata, onRegisterSchema: (schema: MessageSchema) => void, onPublish: (event: Event) => Promise<void>);
+    /**
+     * Creates a named call reference with its model fixed at invocation start.
+     *
+     * @param operation Saved named operation.
+     * @param kind Selected generation or decision kind.
+     * @returns Reference with the accepted Agent, source, and model identities.
+     */
+    reference(operation: AgentNamedOperation, kind: AiModelKind): AgentOperationRef;
+    /**
+     * Calculates an original typed System row size with this invocation's full scope.
+     *
+     * @typeParam Schema Generated System event payload descriptor.
+     * @param schema Payload descriptor.
+     * @param payload Matching typed event payload.
+     * @returns Encoded provider history-row size in bytes.
+     */
+    historyBytes<Schema extends MessageSchema>(schema: Schema, payload: MessageShape<Schema>): number;
+    /**
+     * Writes the original Event with its journal change before publication.
+     *
+     * @typeParam Schema Generated System event payload descriptor.
+     * @param schema Payload descriptor.
+     * @param payload Matching typed event payload.
+     * @param change Journal mutation guarded by the current claim.
+     * @param history Conversation rows included in the same fenced mutation.
+     * @returns When the journal and System Context publication both complete.
+     */
+    save<Schema extends MessageSchema>(schema: Schema, payload: MessageShape<Schema>, change: (record: AgentExecutionRecord) => AgentExecutionRecord, history?: readonly AgentHistoryEntry[]): Promise<void>;
+}
+//# sourceMappingURL=agent-interaction-audit.d.ts.map

package/dist/agent/agent-interaction-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-interaction-audit.d.ts","sourceRoot":"","sources":["../../src/agent/agent-interaction-audit.ts"],"names":[],"mappings":"AAcA,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAEL,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,+EAA+E,CAAC;AAEvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;GAEG;AACH,qBAAa,qBAAqB;IAY9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAhB5B;;;;;;;;;OASG;gBAEgB,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,uBAAuB,EACjC,WAAW,EAAE,aAAa,EAC1B,QAAQ,EAAE,cAAc,EACxB,gBAAgB,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,EACjD,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC;IAG7D;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,mBAAmB,EAAE,IAAI,EAAE,WAAW,GAAG,iBAAiB;IAW/E;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,SAAS,aAAa,EACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAC5B,MAAM;IAuBT;;;;;;;;;OASG;IACG,IAAI,CAAC,MAAM,SAAS,aAAa,EACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,EAC7B,MAAM,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,oBAAoB,EAC9D,OAAO,GAAE,SAAS,iBAAiB,EAAO,GACzC,OAAO,CAAC,IAAI,CAAC;CAsBjB"}

package/dist/agent/agent-interaction-audit.js

@@ -0,0 +1,114 @@
+/*
+ * 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 } from "@bufbuild/protobuf";
+import {} from "@spine-event-engine/core";
+import {} from "@spine-event-engine/proto";
+import { AgentHistoryEntrySchema, AiModelKind, } from "@spine-event-engine/proto/agent";
+import {} from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { AgentExecutionSizes } from "@spine-event-engine/storage/provider";
+import { AgentExecutionSession } from "./agent-execution-session.js";
+import { AgentInteractionEvents } from "./agent-interaction-events.js";
+/**
+ * Saves one original Agent interaction Event and posts it to the System Context.
+ */
+export class AgentInteractionAudit {
+    session;
+    accepted;
+    stateSchema;
+    metadata;
+    onRegisterSchema;
+    onPublish;
+    /**
+     * Binds interaction evidence to one accepted Agent invocation.
+     *
+     * @param session Fenced execution journal and history writer.
+     * @param accepted Original accepted signal and recipient.
+     * @param stateSchema Generated Agent state descriptor.
+     * @param metadata Canonical signal metadata service.
+     * @param onRegisterSchema Registers a System event payload descriptor.
+     * @param onPublish Persists the System Context copy of an original Event.
+     */
+    constructor(session, accepted, stateSchema, metadata, onRegisterSchema, onPublish) {
+        this.session = session;
+        this.accepted = accepted;
+        this.stateSchema = stateSchema;
+        this.metadata = metadata;
+        this.onRegisterSchema = onRegisterSchema;
+        this.onPublish = onPublish;
+    }
+    /**
+     * Creates a named call reference with its model fixed at invocation start.
+     *
+     * @param operation Saved named operation.
+     * @param kind Selected generation or decision kind.
+     * @returns Reference with the accepted Agent, source, and model identities.
+     */
+    reference(operation, kind) {
+        const selected = this.session.record().started?.models.find((item) => item.kind === kind);
+        if (selected === undefined)
+            throw new Error("Agent audit requires a saved selected model.");
+        return AgentInteractionEvents.operationRef(this.accepted, operation, this.stateSchema, selected);
+    }
+    /**
+     * Calculates an original typed System row size with this invocation's full scope.
+     *
+     * @typeParam Schema Generated System event payload descriptor.
+     * @param schema Payload descriptor.
+     * @param payload Matching typed event payload.
+     * @returns Encoded provider history-row size in bytes.
+     */
+    historyBytes(schema, payload) {
+        const scope = this.accepted.key?.scope;
+        const id = this.accepted.recipientId;
+        if (scope === undefined || id === undefined)
+            throw new Error("Agent audit sizing requires accepted scope and recipient.");
+        const event = AgentInteractionEvents.envelope(this.accepted, this.metadata, id, schema, payload);
+        const occurredAt = event.context?.timestamp;
+        if (occurredAt === undefined)
+            throw new Error("Agent audit sizing requires Time.");
+        return AgentExecutionSizes.history(scope, create(AgentHistoryEntrySchema, {
+            occurredAt,
+            item: { case: "systemEvent", value: event },
+        }));
+    }
+    /**
+     * Writes the original Event with its journal change before publication.
+     *
+     * @typeParam Schema Generated System event payload descriptor.
+     * @param schema Payload descriptor.
+     * @param payload Matching typed event payload.
+     * @param change Journal mutation guarded by the current claim.
+     * @param history Conversation rows included in the same fenced mutation.
+     * @returns When the journal and System Context publication both complete.
+     */
+    async save(schema, payload, change, history = []) {
+        const id = this.accepted.recipientId;
+        if (id === undefined)
+            throw new Error("Agent audit requires a typed recipient.");
+        const event = AgentInteractionEvents.envelope(this.accepted, this.metadata, id, schema, payload);
+        const occurredAt = event.context?.timestamp;
+        if (occurredAt === undefined)
+            throw new Error("Agent audit Event requires Time.");
+        this.onRegisterSchema(schema);
+        await this.session.update(change, [
+            ...history,
+            create(AgentHistoryEntrySchema, {
+                occurredAt,
+                item: { case: "systemEvent", value: event },
+            }),
+        ]);
+        await this.onPublish(event);
+    }
+}
+//# sourceMappingURL=agent-interaction-audit.js.map

package/dist/agent/agent-interaction-audit.js.map

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

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

@@ -0,0 +1,40 @@
+import { type MessageShape } from "@bufbuild/protobuf";
+import { type Any } from "@bufbuild/protobuf/wkt";
+import { type MessageSchema } from "@spine-event-engine/core";
+import { type Event } from "@spine-event-engine/proto";
+import { type AgentOperationRef } from "@spine-event-engine/proto/agent";
+import { type AgentAcceptedInvocation, type AgentNamedOperation, type AgentSelectedModel } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { SignalMetadata } from "../runtime/signal-metadata.js";
+/**
+ * Creates references and typed envelopes for Agent interaction events.
+ */
+interface AgentInteractionEventFactory {
+    /**
+     * Creates a reference to accepted work and its selected model.
+     *
+     * @param accepted Durable accepted invocation.
+     * @param operation Named model operation.
+     * @param stateSchema Generated Agent state descriptor.
+     * @param selected Selected deployment for this operation kind.
+     * @returns Complete operation reference.
+     */
+    operationRef(accepted: AgentAcceptedInvocation, operation: AgentNamedOperation, stateSchema: MessageSchema, selected: AgentSelectedModel): AgentOperationRef;
+    /**
+     * Wraps a typed System-event payload with the original causal context.
+     *
+     * @typeParam Schema Generated System-event descriptor.
+     * @param accepted Durable source Command, Event, or rejection.
+     * @param metadata Spine ID, Time, and origin metadata provider.
+     * @param agentId Original typed Agent identifier.
+     * @param schema Generated System-event descriptor.
+     * @param payload Matching typed System-event message.
+     * @returns Fresh Event envelope.
+     */
+    envelope<Schema extends MessageSchema>(accepted: AgentAcceptedInvocation, metadata: SignalMetadata, agentId: Any, schema: Schema, payload: MessageShape<Schema>): Event;
+}
+/**
+ * Creates immutable System-event facts from accepted Agent work.
+ */
+export declare const AgentInteractionEvents: AgentInteractionEventFactory;
+export {};
+//# sourceMappingURL=agent-interaction-events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-interaction-events.d.ts","sourceRoot":"","sources":["../../src/agent/agent-interaction-events.ts"],"names":[],"mappings":"AAcA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAa,KAAK,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAmC,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC/F,OAAO,EAKL,KAAK,KAAK,EACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,+EAA+E,CAAC;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAuCpE;;GAEG;AACH,UAAU,4BAA4B;IACpC;;;;;;;;OAQG;IACH,YAAY,CACV,QAAQ,EAAE,uBAAuB,EACjC,SAAS,EAAE,mBAAmB,EAC9B,WAAW,EAAE,aAAa,EAC1B,QAAQ,EAAE,kBAAkB,GAC3B,iBAAiB,CAAC;IAErB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,SAAS,aAAa,EACnC,QAAQ,EAAE,uBAAuB,EACjC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAC5B,KAAK,CAAC;CACV;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,4BAkFnC,CAAC"}