evolcore 0.0.25 → 0.0.26

package/dist/core/handoff/runtime.js

@@ -11,6 +11,8 @@ const HANDOFF_STALE_WARN_MS = 72 * 60 * 60 * 1000;
 const HANDOFF_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 const HANDOFF_LARGE_AGGREGATE_COUNT = 10;
 const HANDOFF_LARGE_AGGREGATE_CHARS = 50_000;
+/** Keep origin-side context bounded; the persisted handoff remains complete. */
+const HANDOFF_ORIGIN_REQUEST_MAX_CHARS = 800;
 export class HandoffTargetBlockedError extends Error {
     blockingHandoffId;
     attentionReason;
@@ -93,6 +95,8 @@ export class HandoffRuntime {
         }, undefined, input.to, targetChatType, origin.baseagent, input.selfAid, 'aun', targetChatType === 'group' ? 'group' : 'agent');
         throwIfAborted(input.signal);
         if (target.id === origin.id) {
+            if (input.handoffContext !== undefined)
+                throw new Error('handoff context requires a different target session');
             return { crossSession: false, targetSession: target };
         }
         if (!input.explicitReturnPolicy)
@@ -119,6 +123,7 @@ export class HandoffRuntime {
                 payload: input.payload,
                 encrypt: input.encrypt,
                 contextOnly: input.contextOnly,
+                handoffContext: input.handoffContext,
                 delivery: targetChatType === 'group'
                     ? { chatType: 'group', groupId: input.to }
                     : { chatType: 'private' },
@@ -193,28 +198,108 @@ export class HandoffRuntime {
     }
     async returnHandoff(input) {
         const returnCausation = deriveCausation(normalizeCausation(input.causation) ?? createRootCausation());
-        const response = this.store.returnHandoff({ ...input, returnCausation });
+        const response = await this.mutexes.forKey(this.returnKey(input.selfAid, input.handoffId ?? input.currentSessionId))
+            .runExclusive(async () => this.store.returnHandoff({ ...input, returnCausation }));
         if (response.ok && !response.idempotent) {
             recordCausationSpan(returnCausation, 'handoff.response', {
                 status: 'completed',
-                refs: { handoffId: response.handoff_id, sessionId: input.currentSessionId },
+                refs: {
+                    handoffId: response.handoff_id,
+                    sessionId: input.currentSessionId,
+                    ...(response.result_id ? { resultId: response.result_id } : {}),
+                },
+            });
+        }
+        if (response.ok && !response.idempotent && response.result_id) {
+            void this.enqueueOrigin(input.selfAid, response.handoff_id, response.result_id);
+        }
+        else if (response.ok && !response.idempotent && response.state === 'origin_queued') {
+            void this.enqueueOrigin(input.selfAid, response.handoff_id);
+        }
+        return response;
+    }
+    /** Recover a return from the original owner session after target-session replacement. */
+    async recoverReturnHandoff(input) {
+        const instance = this.store.get(input.selfAid, input.handoffId);
+        if (!instance || instance.origin_session_id !== input.recoverySessionId) {
+            return {
+                ok: false,
+                code: 'HANDOFF_NOT_FOUND',
+                error: 'handoff is not owned by the recovery session',
+                handoff_id: input.handoffId,
+            };
+        }
+        const recovery = {
+            actorId: input.actorId,
+            recoverySessionId: input.recoverySessionId,
+        };
+        const returnCausation = deriveCausation(normalizeCausation(input.causation) ?? createRootCausation());
+        const response = await this.mutexes.forKey(this.returnKey(input.selfAid, input.handoffId))
+            .runExclusive(async () => this.store.returnHandoff({
+            selfAid: input.selfAid,
+            currentSessionId: input.recoverySessionId,
+            handoffId: input.handoffId,
+            content: input.content,
+            returnCausation,
+            recovery,
+        }));
+        if (response.ok && !response.idempotent) {
+            recordCausationSpan(returnCausation, 'handoff.response', {
+                status: 'completed',
+                refs: {
+                    handoffId: response.handoff_id,
+                    sessionId: input.recoverySessionId,
+                    ...(response.result_id ? { resultId: response.result_id } : {}),
+                },
             });
         }
-        if (response.ok && !response.idempotent && response.state === 'origin_queued') {
+        if (response.ok && !response.idempotent && response.result_id) {
+            void this.enqueueOrigin(input.selfAid, response.handoff_id, response.result_id);
+        }
+        else if (response.ok && !response.idempotent && response.state === 'origin_queued') {
             void this.enqueueOrigin(input.selfAid, response.handoff_id);
         }
         return response;
     }
-    async enqueueOrigin(selfAid, handoffId) {
+    async enqueueOrigin(selfAid, handoffId, resultId) {
+        const operationSequence = ++this.lifecycleSequence;
+        await this.mutexes.forKey(this.returnKey(selfAid, handoffId)).runExclusive(async () => {
+            await this.enqueueOriginUnlocked(selfAid, handoffId, resultId, operationSequence);
+        });
+    }
+    async enqueueOriginUnlocked(selfAid, handoffId, resultId, operationSequence) {
         const instance = this.store.get(selfAid, handoffId);
-        if (!instance || instance.state !== 'origin_queued' || !instance.return_content)
+        const result = resultId
+            ? instance?.return_results?.find(item => item.result_id === resultId)
+            : instance?.return_results?.find(item => item.state === 'origin_queued');
+        const resultStream = Array.isArray(instance?.return_results);
+        if (resultStream) {
+            if (!instance || !result || result.state !== 'origin_queued' || !result.content)
+                return;
+        }
+        else if (!instance || instance.state !== 'origin_queued' || !instance.return_content)
+            return;
+        const deliveryContent = result?.content ?? instance?.return_content;
+        if (!instance || !deliveryContent)
             return;
         const origin = await this.sessionManager.getSessionById(instance.origin_session_id);
         if (!origin) {
-            this.store.recordOriginEnqueueFailed(selfAid, handoffId, 'origin session not found');
+            if (result)
+                this.store.recordOriginResultEnqueueFailed(selfAid, handoffId, result.result_id, 'origin session not found');
+            else
+                this.store.recordOriginEnqueueFailed(selfAid, handoffId, 'origin session not found');
+            return;
+        }
+        if ((this.sessionDiscardSequence.get(this.sessionKey(selfAid, instance.origin_session_id)) ?? 0) > operationSequence) {
             return;
         }
-        const messageId = `origin-deliver:${handoffId}:${origin.id}`;
+        const deliverable = this.store.get(selfAid, handoffId);
+        const deliveryResultId = result?.result_id ?? resultId;
+        if (!this.isOriginDeliveryPending(deliverable, deliveryResultId))
+            return;
+        const messageId = result
+            ? `origin-deliver:${handoffId}:${result.result_id}:${origin.id}`
+            : `origin-deliver:${handoffId}:${origin.id}`;
         const message = {
             channel: origin.channel,
             channelType: origin.channelType,
@@ -226,21 +311,24 @@ export class HandoffRuntime {
             peerId: origin.channelId,
             peerName: origin.metadata?.peerName || origin.channelId,
             peerType: origin.metadata?.peerType,
-            content: instance.return_content,
+            content: deliveryContent,
             messageId,
             timestamp: Date.now(),
             source: 'handoff',
             groupId: origin.chatType === 'group' ? (origin.metadata?.groupId || origin.channelId) : undefined,
             replyContext: replyContextFromSession(origin),
             boundSessionId: origin.id,
-            causation: instance.return_causation
-                ? deriveCausation(instance.return_causation)
-                : instance.causation
-                    ? deriveCausation(instance.causation)
-                    : undefined,
+            causation: result?.return_causation
+                ? deriveCausation(result.return_causation)
+                : instance.return_causation
+                    ? deriveCausation(instance.return_causation)
+                    : instance.causation
+                        ? deriveCausation(instance.causation)
+                        : undefined,
             handoffDelivery: {
                 direction: 'origin',
                 handoffId,
+                ...(result ? { resultId: result.result_id } : {}),
                 ...(instance.origin_authorization
                     ? { originAuthorization: { ...instance.origin_authorization } }
                     : {}),
@@ -255,19 +343,42 @@ export class HandoffRuntime {
                 sessionKeyField: origin.sessionKey,
                 selfAID: origin.selfAID,
                 onPersisted: () => {
-                    if (this.store.get(selfAid, handoffId)?.state !== 'origin_queued') {
-                        throw new Error(`handoff is no longer deliverable: ${handoffId}`);
+                    const current = this.store.get(selfAid, handoffId);
+                    if (result) {
+                        if (!this.isOriginDeliveryPending(current, result.result_id)) {
+                            throw new Error(`handoff result is no longer deliverable: ${handoffId}/${result.result_id}`);
+                        }
+                        this.store.recordOriginResultEnqueued(selfAid, handoffId, result.result_id, messageId);
+                    }
+                    else {
+                        if (current?.state !== 'origin_queued') {
+                            throw new Error(`handoff is no longer deliverable: ${handoffId}`);
+                        }
+                        this.store.recordOriginEnqueued(selfAid, handoffId, messageId);
                     }
-                    this.store.recordOriginEnqueued(selfAid, handoffId, messageId);
                 },
             });
         }
         catch (error) {
-            if (this.store.get(selfAid, handoffId)?.state === 'origin_queued') {
+            const current = this.store.get(selfAid, handoffId);
+            if (result) {
+                if (current?.return_results?.find(item => item.result_id === result.result_id)?.state === 'origin_queued') {
+                    this.store.recordOriginResultEnqueueFailed(selfAid, handoffId, result.result_id, error instanceof Error ? error.message : String(error));
+                }
+            }
+            else if (current?.state === 'origin_queued') {
                 this.store.recordOriginEnqueueFailed(selfAid, handoffId, error instanceof Error ? error.message : String(error));
             }
         }
     }
+    isOriginDeliveryPending(instance, resultId) {
+        if (!instance || instance.state === 'discarded' || instance.state === 'failed')
+            return false;
+        if (resultId) {
+            return instance.return_results?.find(item => item.result_id === resultId)?.state === 'origin_queued';
+        }
+        return instance.state === 'origin_queued' && !!instance.return_content;
+    }
     buildPromptItem(message, fallbackPeerRole) {
         return this.buildPromptItems(message, fallbackPeerRole)[0] ?? null;
     }
@@ -297,6 +408,17 @@ export class HandoffRuntime {
                 if (instance.state !== expectedState)
                     continue;
             }
+            else if (Array.isArray(instance.return_results)) {
+                const resultIds = delivery.resultIds?.length
+                    ? delivery.resultIds
+                    : (delivery.resultId ? [delivery.resultId] : []);
+                const results = resultIds
+                    .map(resultId => instance.return_results.find(result => result.result_id === resultId))
+                    .filter((result) => !!result && result.state === 'origin_delivered');
+                if (results.length === 0)
+                    continue;
+                instance.__deliveryResults = results;
+            }
             else if (instance.state !== 'origin_delivered') {
                 continue;
             }
@@ -307,6 +429,13 @@ export class HandoffRuntime {
         if (delivery.direction === 'origin') {
             this.warnIfLargeAggregate(message, instances, 'origin');
             const first = instances[0];
+            const deliveryResultRefs = instances.flatMap(instance => ((instance.__deliveryResults ?? [])
+                .map(result => ({ handoffId: instance.handoff_id, resultId: result.result_id, result }))));
+            const originRequestSummaries = new Map();
+            const originRequestShown = new Set();
+            for (const instance of instances) {
+                originRequestSummaries.set(instance.handoff_id, this.originRequestSummary(instance));
+            }
             return [{
                     kind: 'handoff',
                     peerId: message.peerId,
@@ -329,11 +458,26 @@ export class HandoffRuntime {
                         kind: 'response_to_origin',
                         handoffId: first.handoff_id,
                         handoffIds: instances.map(instance => instance.handoff_id),
-                        originEntries: instances.map(instance => ({
-                            previousContent: this.requestSummary(instance),
-                            responseContent: instance.return_content ?? '',
-                            previousMessageId: instance.target_message_id,
-                        })),
+                        ...(deliveryResultRefs.length > 0
+                            ? {
+                                resultIds: deliveryResultRefs.map(({ result }) => result.result_id),
+                                resultRefs: deliveryResultRefs.map(({ handoffId, result }) => ({ handoffId, resultId: result.result_id })),
+                            }
+                            : {}),
+                        originEntries: deliveryResultRefs.length > 0
+                            ? deliveryResultRefs.map(({ result, handoffId }) => ({
+                                previousContent: originRequestShown.has(handoffId)
+                                    ? '[同一 handoff 的后续结果，原请求见上方]'
+                                    : (originRequestShown.add(handoffId), originRequestSummaries.get(handoffId) ?? this.originRequestSummary(first)),
+                                responseContent: result.content,
+                                previousMessageId: (instances.find(instance => instance.handoff_id === handoffId) ?? first).target_message_id,
+                                resultId: result.result_id,
+                            }))
+                            : instances.map(instance => ({
+                                previousContent: originRequestSummaries.get(instance.handoff_id) ?? this.originRequestSummary(instance),
+                                responseContent: instance.return_content ?? '',
+                                previousMessageId: instance.target_message_id,
+                            })),
                         previousContent: this.requestSummary(first),
                         previousMessageId: first.target_message_id,
                         returnPolicy: first.return_policy,
@@ -385,9 +529,14 @@ export class HandoffRuntime {
                 },
             }];
     }
-    completeOriginContext(selfAid, handoffId) {
+    completeOriginContext(selfAid, handoffId, resultId) {
         const instance = this.store.get(selfAid, handoffId);
-        if (instance?.state === 'origin_delivered')
+        if (resultId) {
+            if (instance?.return_results?.some(result => result.result_id === resultId && result.state === 'origin_delivered')) {
+                this.store.completeOriginResult(selfAid, handoffId, resultId);
+            }
+        }
+        else if (instance?.state === 'origin_delivered')
             this.store.completeOriginContext(selfAid, handoffId);
     }
     completeTargetContext(selfAid, handoffId) {
@@ -535,6 +684,11 @@ export class HandoffRuntime {
                 else if (instance.state === 'origin_queued') {
                     originEnqueues.push(this.enqueueOrigin(selfAid, instance.handoff_id));
                 }
+                else if (Array.isArray(instance.return_results)) {
+                    for (const result of instance.return_results.filter(item => item.state === 'origin_queued')) {
+                        originEnqueues.push(this.enqueueOrigin(selfAid, instance.handoff_id, result.result_id));
+                    }
+                }
             }
         }
         await Promise.all(originEnqueues);
@@ -559,10 +713,20 @@ export class HandoffRuntime {
         return true;
     }
     async cancelOriginDelivery(instance) {
+        const resultDeliveries = instance.return_results?.filter(result => (result.state === 'origin_queued' || result.state === 'origin_delivered')) ?? [];
+        if (resultDeliveries.length > 0) {
+            for (const result of resultDeliveries) {
+                await this.cancelOriginMessage(instance, result.origin_delivery_message_id
+                    ?? `origin-deliver:${instance.handoff_id}:${result.result_id}:${instance.origin_session_id}`);
+            }
+            return;
+        }
         if (instance.state !== 'origin_queued' && instance.state !== 'origin_delivered')
             return;
-        const messageId = instance.origin_delivery_message_id
-            ?? `origin-deliver:${instance.handoff_id}:${instance.origin_session_id}`;
+        await this.cancelOriginMessage(instance, instance.origin_delivery_message_id
+            ?? `origin-deliver:${instance.handoff_id}:${instance.origin_session_id}`);
+    }
+    async cancelOriginMessage(instance, messageId) {
         const queue = this.messageQueue;
         try {
             const queued = queue.cancelMessageByIdInSession?.(instance.origin_session_id, messageId) ?? false;
@@ -592,6 +756,9 @@ export class HandoffRuntime {
     sessionKey(selfAid, sessionId) {
         return `${selfAid}\u0000${sessionId}`;
     }
+    returnKey(selfAid, handoffOrSessionId) {
+        return `${selfAid}\u0000handoff-return\u0000${handoffOrSessionId}`;
+    }
     warnIfLargeAggregate(message, instances, direction) {
         const chars = message.content.length
             + instances.reduce((total, instance) => total + this.requestSummary(instance).length, 0);
@@ -606,7 +773,18 @@ export class HandoffRuntime {
             + ` count=${instances.length} chars=${chars} responseMessage=${message.messageId ?? '<none>'}`);
     }
     requestSummary(instance) {
-        return classifyAunPayloadForLog(instance.request.payload).content || '[payload]';
+        const sent = classifyAunPayloadForLog(instance.request.payload).content || '[payload]';
+        return instance.request.context ? `${sent}\n\n[本地交接上下文]\n${instance.request.context}` : sent;
+    }
+    originRequestSummary(instance) {
+        const content = this.requestSummary(instance);
+        if (content.length <= HANDOFF_ORIGIN_REQUEST_MAX_CHARS)
+            return content;
+        const marker = `\n\n[原请求过长，回流提示仅保留首尾；完整内容共 ${content.length} 字，已省略 ${content.length - HANDOFF_ORIGIN_REQUEST_MAX_CHARS} 字]\n\n`;
+        const available = HANDOFF_ORIGIN_REQUEST_MAX_CHARS - marker.length;
+        const head = Math.ceil(available * 0.6);
+        const tail = available - head;
+        return `${content.slice(0, head)}${marker}${content.slice(-tail)}`;
     }
 }
 function throwIfAborted(signal) {

package/dist/core/handoff/store.js

@@ -33,6 +33,9 @@ function normalizeReturnContent(content) {
 function contentHash(content) {
     return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
 }
+function newReturnResultId() {
+    return `hr-${crypto.randomBytes(8).toString('hex')}`;
+}
 function boundedQueryLimit(limit) {
     if (typeof limit !== 'number' || !Number.isInteger(limit))
         return HANDOFF_QUERY_DEFAULT_LIMIT;
@@ -111,6 +114,9 @@ export class HandoffStore {
         fs.renameSync(pendingPath, filePath);
     }
     create(input) {
+        if (input.handoffContext !== undefined && (typeof input.handoffContext !== 'string'
+            || !input.handoffContext.trim() || input.handoffContext.length > 64 * 1024))
+            throw new Error('invalid handoff context');
         const now = input.now ?? Date.now();
         const handoffId = newHandoffId();
         const instance = {
@@ -123,6 +129,7 @@ export class HandoffStore {
                 payload: clonePayload(input.payload),
                 encrypt: input.encrypt,
                 ...(input.contextOnly ? { contextOnly: true } : {}),
+                ...(input.handoffContext ? { context: input.handoffContext } : {}),
                 ...(input.delivery ? { delivery: input.delivery } : {}),
             },
             ...(input.originAuthorization
@@ -143,6 +150,7 @@ export class HandoffStore {
             return_content: null,
             return_content_hash: null,
             origin_delivery_message_id: null,
+            ...((input.returnPolicy ?? 'required') === 'required' && !input.contextOnly ? { return_results: [] } : {}),
             attention_required: false,
             attention_reason: null,
             version: 1,
@@ -401,7 +409,12 @@ export class HandoffStore {
         if ('ok' in selected)
             return selected;
         const { instance, selectedBy } = selected;
-        if (instance.target_session_id !== input.currentSessionId || instance.consumed_target_session_id !== input.currentSessionId) {
+        const directSessionMatch = instance.target_session_id === input.currentSessionId
+            && instance.consumed_target_session_id === input.currentSessionId;
+        const recoveryAuthorized = !!input.recovery
+            && input.recovery.recoverySessionId === input.currentSessionId
+            && input.recovery.actorId === instance.origin_authorization?.actorId;
+        if (!directSessionMatch && !recoveryAuthorized) {
             return {
                 ok: false,
                 code: 'HANDOFF_TARGET_SESSION_MISMATCH',
@@ -430,6 +443,110 @@ export class HandoffStore {
             };
         }
         const hash = contentHash(normalized);
+        const previousState = instance.state;
+        // New required handoffs expose an append-only result stream. The parent
+        // remains return_pending while each result is delivered and consumed.
+        if (instance.return_policy === 'required' && Array.isArray(instance.return_results)) {
+            if (instance.state !== 'return_pending' && instance.state !== 'completed') {
+                const existing = instance.return_results.find(result => result.content_hash === hash);
+                if (existing) {
+                    return {
+                        ok: true,
+                        code: 'HANDOFF_RETURN_ALREADY_APPLIED',
+                        handoff_id: instance.handoff_id,
+                        selected_by: selectedBy,
+                        previous_state: instance.state,
+                        state: instance.state,
+                        idempotent: true,
+                        result_id: existing.result_id,
+                    };
+                }
+                return {
+                    ok: false,
+                    code: 'HANDOFF_NOT_RETURNABLE',
+                    error: 'handoff is not return_pending',
+                    handoff_id: instance.handoff_id,
+                    state: instance.state,
+                };
+            }
+            if (!normalized.trim()) {
+                return {
+                    ok: false,
+                    code: 'HANDOFF_RETURN_CONTENT_REQUIRED',
+                    error: 'return content is required',
+                    handoff_id: instance.handoff_id,
+                    state: instance.state,
+                };
+            }
+            const existing = instance.return_results.find(result => result.content_hash === hash);
+            if (existing) {
+                return {
+                    ok: true,
+                    code: 'HANDOFF_RETURN_ALREADY_APPLIED',
+                    handoff_id: instance.handoff_id,
+                    selected_by: selectedBy,
+                    previous_state: instance.state,
+                    state: instance.state,
+                    idempotent: true,
+                    result_id: existing.result_id,
+                };
+            }
+            const now = input.now ?? Date.now();
+            const previousVersion = instance.version;
+            const result = {
+                result_id: newReturnResultId(),
+                seq: instance.return_results.reduce((max, item) => Math.max(max, item.seq), 0) + 1,
+                content: normalized,
+                content_hash: hash,
+                state: 'origin_queued',
+                origin_delivery_message_id: null,
+                return_causation: normalizeCausation(input.returnCausation),
+                created_at: now,
+                updated_at: now,
+                completed_at: null,
+            };
+            instance.return_results.push(result);
+            instance.return_causation = result.return_causation;
+            instance.version++;
+            instance.updated_at = now;
+            try {
+                this.appendEvent(input.selfAid, 'return_accepted', instance.handoff_id, {
+                    operationKey: `handoff-return:${instance.handoff_id}:${result.result_id}`,
+                    fromVersion: previousVersion,
+                    toVersion: instance.version,
+                    details: {
+                        return_policy: instance.return_policy,
+                        result_id: result.result_id,
+                        seq: result.seq,
+                        ...(recoveryAuthorized
+                            ? { recovery: true, recovery_session_id: input.currentSessionId, recovery_actor_id: input.recovery?.actorId }
+                            : {}),
+                    },
+                    now,
+                });
+                this.write(input.selfAid, instance);
+            }
+            catch {
+                return {
+                    ok: false,
+                    code: 'HANDOFF_STORE_WRITE_FAILED',
+                    error: 'failed to persist handoff return',
+                    handoff_id: instance.handoff_id,
+                    state: previousState,
+                    retryable: true,
+                };
+            }
+            return {
+                ok: true,
+                code: 'HANDOFF_RETURN_ACCEPTED',
+                handoff_id: instance.handoff_id,
+                selected_by: selectedBy,
+                previous_state: previousState,
+                state: instance.state,
+                idempotent: false,
+                result_id: result.result_id,
+            };
+        }
         if (instance.state !== 'return_pending') {
             if (instance.return_content_hash) {
                 if (instance.return_content_hash === hash) {
@@ -469,7 +586,6 @@ export class HandoffStore {
             };
         }
         const now = input.now ?? Date.now();
-        const previousState = instance.state;
         const previousVersion = instance.version;
         instance.state = instance.return_policy === 'none' ? 'completed' : 'origin_queued';
         instance.return_content = instance.return_policy === 'none' ? null : normalized;
@@ -483,7 +599,12 @@ export class HandoffStore {
                 operationKey: `handoff-return:${instance.handoff_id}`,
                 fromVersion: previousVersion,
                 toVersion: instance.version,
-                details: { return_policy: instance.return_policy },
+                details: {
+                    return_policy: instance.return_policy,
+                    ...(recoveryAuthorized
+                        ? { recovery: true, recovery_session_id: input.currentSessionId, recovery_actor_id: input.recovery?.actorId }
+                        : {}),
+                },
                 now,
             });
             this.write(input.selfAid, instance);
@@ -524,6 +645,31 @@ export class HandoffStore {
         this.write(selfAid, instance);
         return instance;
     }
+    recordOriginResultEnqueued(selfAid, handoffId, resultId, messageId, now = Date.now()) {
+        const instance = this.get(selfAid, handoffId);
+        if (!instance)
+            throw new Error('handoff not found');
+        const result = instance.return_results?.find(item => item.result_id === resultId);
+        if (!result)
+            throw new Error('handoff result not found');
+        if (result.state !== 'origin_queued')
+            throw new Error(`handoff result state ${result.state}, expected origin_queued`);
+        const previous = instance.version;
+        result.state = 'origin_delivered';
+        result.origin_delivery_message_id = messageId;
+        result.updated_at = now;
+        instance.version++;
+        instance.updated_at = now;
+        this.appendEvent(selfAid, 'origin_enqueue_succeeded', handoffId, {
+            operationKey: messageId,
+            fromVersion: previous,
+            toVersion: instance.version,
+            details: { result_id: resultId },
+            now,
+        });
+        this.write(selfAid, instance);
+        return instance;
+    }
     recordOriginEnqueueFailed(selfAid, handoffId, error, now = Date.now()) {
         const instance = this.requireState(selfAid, handoffId, 'origin_queued');
         this.appendEvent(selfAid, 'origin_enqueue_failed', handoffId, {
@@ -532,6 +678,19 @@ export class HandoffStore {
             now,
         });
     }
+    recordOriginResultEnqueueFailed(selfAid, handoffId, resultId, error, now = Date.now()) {
+        const instance = this.get(selfAid, handoffId);
+        if (!instance)
+            throw new Error('handoff not found');
+        if (!instance.return_results?.some(item => item.result_id === resultId)) {
+            throw new Error('handoff result not found');
+        }
+        this.appendEvent(selfAid, 'origin_enqueue_failed', handoffId, {
+            operationKey: `origin-deliver:${handoffId}:${resultId}:${instance.origin_session_id}`,
+            details: { error, result_id: resultId },
+            now,
+        });
+    }
     completeOriginContext(selfAid, handoffId, now = Date.now()) {
         const instance = this.requireState(selfAid, handoffId, 'origin_delivered');
         const previous = instance.version;
@@ -548,6 +707,35 @@ export class HandoffStore {
         this.write(selfAid, instance);
         return instance;
     }
+    completeOriginResult(selfAid, handoffId, resultId, now = Date.now()) {
+        const instance = this.get(selfAid, handoffId);
+        if (!instance)
+            throw new Error('handoff not found');
+        const result = instance.return_results?.find(item => item.result_id === resultId);
+        if (!result)
+            throw new Error('handoff result not found');
+        if (result.state !== 'origin_delivered')
+            throw new Error(`handoff result state ${result.state}, expected origin_delivered`);
+        const previous = instance.version;
+        result.state = 'completed';
+        result.updated_at = now;
+        result.completed_at = now;
+        if (instance.return_results.every(item => item.state === 'completed')) {
+            instance.state = 'completed';
+            instance.completed_at = now;
+        }
+        instance.version++;
+        instance.updated_at = now;
+        this.appendEvent(selfAid, 'origin_context_consumed', handoffId, {
+            operationKey: result.origin_delivery_message_id ?? undefined,
+            fromVersion: previous,
+            toVersion: instance.version,
+            details: { result_id: resultId },
+            now,
+        });
+        this.write(selfAid, instance);
+        return instance;
+    }
     discard(selfAid, handoffId, reason, details = {}, now = Date.now()) {
         const instance = this.get(selfAid, handoffId);
         if (!instance)
@@ -617,7 +805,8 @@ export class HandoffStore {
         };
     }
     requestSummary(instance) {
-        return classifyAunPayloadForLog(instance.request.payload).content || '[payload]';
+        const sent = classifyAunPayloadForLog(instance.request.payload).content || '[payload]';
+        return instance.request.context ? `${sent}\n\n[本地交接上下文]\n${instance.request.context}` : sent;
     }
     selectReturnCandidate(input) {
         if (input.handoffId) {