evolcore 0.0.1 → 0.0.3

package/dist/core/handoff/runtime.js

@@ -0,0 +1,324 @@
+import { formatChannelKey } from '../channel-loader.js';
+import { classifyAunPayloadForLog } from '../message/message-log.js';
+import { HandoffDispatcher } from './dispatcher.js';
+import { KeyedFairMutex } from './mutex.js';
+import { HandoffStore } from './store.js';
+import { createRootCausation, deriveCausation, normalizeCausation } from '../causation/context.js';
+import { recordCausationSpan } from '../causation/audit.js';
+export class HandoffTargetBlockedError extends Error {
+    blockingHandoffId;
+    attentionReason;
+    code = 'HANDOFF_TARGET_BLOCKED';
+    constructor(blockingHandoffId, attentionReason) {
+        super(`target handoff queue is blocked by ${blockingHandoffId} (${attentionReason})`);
+        this.blockingHandoffId = blockingHandoffId;
+        this.attentionReason = attentionReason;
+        this.name = 'HandoffTargetBlockedError';
+    }
+}
+export class HandoffDeliveryFailedError extends Error {
+    handoffId;
+    code = 'HANDOFF_DELIVERY_FAILED';
+    constructor(handoffId) {
+        super(`handoff delivery failed after retries: ${handoffId}`);
+        this.handoffId = handoffId;
+        this.name = 'HandoffDeliveryFailedError';
+    }
+}
+export class HandoffRuntime {
+    sessionManager;
+    messageQueue;
+    store;
+    mutexes = new KeyedFairMutex();
+    dispatcher;
+    now;
+    constructor(sessionManager, messageQueue, sender, store = new HandoffStore(), options = {}) {
+        this.sessionManager = sessionManager;
+        this.messageQueue = messageQueue;
+        this.store = store;
+        this.now = options.now;
+        this.dispatcher = new HandoffDispatcher(store, this.mutexes, sender, options);
+    }
+    async createOutbound(input) {
+        throwIfAborted(input.signal);
+        const origin = await this.sessionManager.getSessionById(input.originSessionId);
+        throwIfAborted(input.signal);
+        if (!origin || origin.selfAID !== input.selfAid)
+            throw new Error('origin session not found');
+        const targetChannelKey = formatChannelKey({ type: 'aun', selfAID: input.selfAid, name: 'main' });
+        const targetChatType = input.targetChatType ?? 'private';
+        const target = await this.sessionManager.getOrCreateSession(targetChannelKey, input.to, origin.projectPath, input.thread, {
+            channelKey: targetChannelKey,
+            peerId: input.to,
+            ...(targetChatType === 'group' ? { groupId: input.to } : {}),
+        }, undefined, input.to, targetChatType, origin.baseagent, input.selfAid, 'aun', targetChatType === 'group' ? 'group' : 'agent');
+        throwIfAborted(input.signal);
+        if (target.id === origin.id) {
+            return { crossSession: false, targetSession: target };
+        }
+        await this.dispatcher.expireTargetQueued(input.selfAid, target.id);
+        throwIfAborted(input.signal);
+        const head = this.store.listByTarget(input.selfAid, target.id, 'queued')[0];
+        if (head?.attention_required) {
+            throw new HandoffTargetBlockedError(head.handoff_id, head.attention_reason ?? 'UNKNOWN_ATTENTION');
+        }
+        const handoffCausation = deriveCausation(normalizeCausation(input.causation) ?? createRootCausation());
+        const handoff = this.store.create({
+            selfAid: input.selfAid,
+            originSessionId: origin.id,
+            originMessageId: input.originMessageId,
+            targetSessionId: target.id,
+            payload: input.payload,
+            encrypt: input.encrypt,
+            returnPolicy: input.explicitReturnPolicy ?? 'required',
+            originAuthorization: input.originAuthorization,
+            causation: handoffCausation,
+            now: this.now?.(),
+        });
+        recordCausationSpan(handoffCausation, 'handoff.request', {
+            status: 'started',
+            refs: { handoffId: handoff.handoff_id, sessionId: origin.id, messageId: input.originMessageId },
+        });
+        await this.dispatcher.drain(input.selfAid, target.id);
+        const dispatched = this.store.get(input.selfAid, handoff.handoff_id) ?? handoff;
+        if (dispatched.state === 'failed') {
+            throw new HandoffDeliveryFailedError(dispatched.handoff_id);
+        }
+        if (dispatched.attention_required) {
+            throw new HandoffTargetBlockedError(dispatched.handoff_id, dispatched.attention_reason ?? 'UNKNOWN_ATTENTION');
+        }
+        return { crossSession: true, handoff: dispatched, targetSession: target };
+    }
+    hasOpenTarget(selfAid, targetSessionId) {
+        return this.store.listByTarget(selfAid, targetSessionId)
+            .some(instance => instance.state === 'target_sent' || instance.state === 'return_pending');
+    }
+    async bindReply(input) {
+        const key = `${input.selfAid}\u0000${input.targetSessionId}`;
+        return this.mutexes.forKey(key).runExclusive(async () => {
+            if (!this.hasOpenTarget(input.selfAid, input.targetSessionId))
+                return { candidate: false };
+            input.persistReply();
+            const attached = this.store.attachSessionContext({
+                selfAid: input.selfAid,
+                targetSessionId: input.targetSessionId,
+                responseMessageId: input.responseMessageId,
+                refMessageId: input.refMessageId,
+            });
+            const handoffIds = attached.map(instance => instance.handoff_id);
+            return {
+                candidate: handoffIds.length > 0,
+                ...(handoffIds[0] ? { handoffId: handoffIds[0], handoffIds } : {}),
+            };
+        });
+    }
+    markBindingIncomplete(selfAid, handoffId) {
+        const instance = this.store.get(selfAid, handoffId);
+        if (instance && !instance.attention_required) {
+            this.store.markAttention(selfAid, handoffId, 'REPLY_BINDING_INCOMPLETE');
+        }
+    }
+    async returnHandoff(input) {
+        const returnCausation = deriveCausation(normalizeCausation(input.causation) ?? createRootCausation());
+        const response = this.store.returnHandoff({ ...input, returnCausation });
+        if (response.ok && !response.idempotent) {
+            recordCausationSpan(returnCausation, 'handoff.response', {
+                status: 'completed',
+                refs: { handoffId: response.handoff_id, sessionId: input.currentSessionId },
+            });
+        }
+        if (response.ok && !response.idempotent && response.state === 'origin_queued') {
+            void this.enqueueOrigin(input.selfAid, response.handoff_id);
+        }
+        return response;
+    }
+    async enqueueOrigin(selfAid, handoffId) {
+        const instance = this.store.get(selfAid, handoffId);
+        if (!instance || instance.state !== 'origin_queued' || !instance.return_content)
+            return;
+        const origin = await this.sessionManager.getSessionById(instance.origin_session_id);
+        if (!origin) {
+            this.store.recordOriginEnqueueFailed(selfAid, handoffId, 'origin session not found');
+            return;
+        }
+        const messageId = `origin-deliver:${handoffId}:${origin.id}`;
+        const message = {
+            channel: origin.channel,
+            channelType: origin.channelType,
+            channelId: origin.channelId,
+            selfAID: origin.selfAID,
+            baseagent: origin.baseagent,
+            threadId: origin.threadId || undefined,
+            chatType: origin.chatType === 'group' ? 'group' : 'private',
+            peerId: origin.channelId,
+            peerName: origin.metadata?.peerName || origin.channelId,
+            peerType: origin.metadata?.peerType,
+            content: instance.return_content,
+            messageId,
+            timestamp: Date.now(),
+            source: 'handoff',
+            causation: instance.return_causation
+                ? deriveCausation(instance.return_causation)
+                : instance.causation
+                    ? deriveCausation(instance.causation)
+                    : undefined,
+            handoffDelivery: {
+                direction: 'origin',
+                handoffId,
+                ...(instance.origin_authorization
+                    ? { originAuthorization: { ...instance.origin_authorization } }
+                    : {}),
+            },
+        };
+        try {
+            await this.messageQueue.enqueuePersisted(origin.id, message, origin.projectPath, {
+                interruptible: false,
+                interruptSamePeer: false,
+                agentName: selfAid,
+                role: origin.chatType === 'group' ? (origin.identity?.role ?? 'none') : undefined,
+                sessionKeyField: origin.sessionKey,
+                selfAID: origin.selfAID,
+                onPersisted: () => this.store.recordOriginEnqueued(selfAid, handoffId, messageId),
+            });
+        }
+        catch (error) {
+            this.store.recordOriginEnqueueFailed(selfAid, handoffId, error instanceof Error ? error.message : String(error));
+        }
+    }
+    buildPromptItem(message) {
+        const delivery = message.handoffDelivery;
+        const selfAid = message.selfAID;
+        if (!delivery || !selfAid)
+            return null;
+        const instance = this.store.get(selfAid, delivery.handoffId);
+        if (!instance)
+            return null;
+        if (delivery.direction === 'target' && instance.state !== 'return_pending')
+            return null;
+        if (delivery.direction === 'origin' && instance.state !== 'origin_delivered')
+            return null;
+        return {
+            kind: 'handoff',
+            peerId: message.peerId,
+            peerName: message.peerName,
+            peerType: message.peerType,
+            content: message.content,
+            timestamp: message.timestamp,
+            causation: message.causation,
+            handoff: {
+                kind: delivery.direction === 'target' ? 'request_to_target' : 'response_to_origin',
+                handoffId: instance.handoff_id,
+                previousContent: this.requestSummary(instance),
+                previousMessageId: instance.target_message_id,
+                returnPolicy: instance.return_policy,
+            },
+        };
+    }
+    buildPromptItems(message) {
+        const delivery = message.handoffDelivery;
+        if (!delivery)
+            return [];
+        const ids = delivery.handoffIds?.length ? delivery.handoffIds : [delivery.handoffId];
+        const items = [];
+        for (const handoffId of ids) {
+            const item = this.buildPromptItem({
+                ...message,
+                handoffDelivery: { direction: delivery.direction, handoffId },
+            });
+            if (item)
+                items.push(item);
+        }
+        return items;
+    }
+    completeOriginContext(selfAid, handoffId) {
+        const instance = this.store.get(selfAid, handoffId);
+        if (instance?.state === 'origin_delivered')
+            this.store.completeOriginContext(selfAid, handoffId);
+    }
+    status(selfAid, handoffId) {
+        return this.store.status(selfAid, handoffId);
+    }
+    listHandoffs(input) {
+        return {
+            ok: true,
+            handoffs: this.store.query(input.selfAid, input).map(instance => ({
+                handoff_id: instance.handoff_id,
+                state: instance.state,
+                origin_session_id: instance.origin_session_id,
+                target_session_id: instance.target_session_id,
+                return_policy: instance.return_policy,
+                created_at: instance.created_at,
+                updated_at: instance.updated_at,
+                attention_required: instance.attention_required,
+                attention_reason: instance.attention_reason,
+            })),
+        };
+    }
+    traceHandoff(selfAid, handoffId, limit) {
+        const events = this.store.trace(selfAid, handoffId, limit);
+        return events ? { ok: true, handoff_id: handoffId, events } : null;
+    }
+    pauseAgent(selfAid) {
+        this.dispatcher.pauseAgent(selfAid);
+    }
+    drainAgent(selfAid, timeoutMs) {
+        return this.dispatcher.drainAgent(selfAid, timeoutMs);
+    }
+    resumeAgent(selfAid) {
+        this.dispatcher.resumeAgent(selfAid);
+    }
+    expireQueued(selfAids) {
+        let expired = 0;
+        for (const selfAid of selfAids)
+            expired += this.dispatcher.expireQueued(selfAid).length;
+        return expired;
+    }
+    async recover(selfAids) {
+        const originEnqueues = [];
+        for (const selfAid of selfAids) {
+            this.expireQueued([selfAid]);
+            const events = this.store.events(selfAid);
+            const lastSendEvent = new Map();
+            for (const event of events) {
+                if (event.handoff_id && event.event_type.startsWith('target_send_')) {
+                    lastSendEvent.set(event.handoff_id, event.event_type);
+                }
+            }
+            for (const instance of this.store.list(selfAid)) {
+                const versionedEvents = events.filter(event => event.handoff_id === instance.handoff_id && event.to_version !== undefined);
+                const latestEventVersion = versionedEvents.reduce((latest, event) => Math.max(latest, event.to_version ?? 0), 0);
+                if (latestEventVersion !== instance.version) {
+                    if (!instance.attention_required) {
+                        this.store.markAttention(selfAid, instance.handoff_id, 'STORE_CONFLICT');
+                    }
+                    this.dispatcher.notify(selfAid, instance.target_session_id);
+                    continue;
+                }
+                if (instance.state === 'queued') {
+                    if (instance.attention_required) {
+                        this.dispatcher.notify(selfAid, instance.target_session_id);
+                    }
+                    else if (lastSendEvent.get(instance.handoff_id) === 'target_send_started') {
+                        this.store.markAttention(selfAid, instance.handoff_id, 'TARGET_SEND_OUTCOME_UNKNOWN');
+                        this.dispatcher.notify(selfAid, instance.target_session_id);
+                    }
+                    else {
+                        this.dispatcher.notify(selfAid, instance.target_session_id);
+                    }
+                }
+                else if (instance.state === 'origin_queued') {
+                    originEnqueues.push(this.enqueueOrigin(selfAid, instance.handoff_id));
+                }
+            }
+        }
+        await Promise.all(originEnqueues);
+    }
+    requestSummary(instance) {
+        return classifyAunPayloadForLog(instance.request.payload).content || '[payload]';
+    }
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw signal.reason instanceof Error ? signal.reason : new Error('handoff creation cancelled');
+}