evolcore 0.0.32 → 0.0.33

package/dist/agents/ecagent-runner.js

@@ -1,4 +1,4 @@
-import { getRunnerCatalog, catalogEfforts, assertCatalogSelectable, TRANSPORT_EFFORTS, resolveCatalogModel, } from '../core/model/model-catalog.js';
+import { getRunnerCatalog, catalogEfforts, assertCatalogSelectable, } from '../core/model/model-catalog.js';
 // Ecagent/OpenAI API 不认识 Claude Code SDK 的窗口后缀，必须传入基础模型 ID。
 import { stripContextWindowSuffix } from '../core/model/context-window-suffix.js';
 import fs from 'fs';
@@ -762,15 +762,7 @@ export class EcagentRunner {
         return catalog.models.map(m => m.id);
     }
     async getAvailableEfforts(model) {
-        const catalog = await this.getModelCatalog();
-        const efforts = catalogEfforts(catalog, model, 'ecagent');
-        if (efforts.length > 0)
-            return efforts;
-        // The embedded transport advertises reasoning support for every model it
-        // constructs. Older gateways may omit reasoningLevels from /models; keep
-        // menu.options aligned with the actual runner capability in that case.
-        const entry = catalog.models.find(item => item.id === resolveCatalogModel(catalog, model));
-        return entry && entry.reasoningLevels === undefined ? [...TRANSPORT_EFFORTS.ecagent] : efforts;
+        return catalogEfforts(await this.getModelCatalog(), model, 'ecagent');
     }
     registerStream(key, stream) { this.activeStreams.set(key, stream); }
     cleanupStream(key) {
@@ -917,7 +909,7 @@ export class EcagentRunner {
                     if (pauseResult === 'cancelled')
                         return { block: true, reason: '工具调用已取消' };
                 }
-                const decision = await this.authorizeTool(request.sessionId, request.projectPath, permissionMode, event.toolName, event.input);
+                const decision = await this.authorizeTool(request.sessionId, request.projectPath, permissionMode, event.toolName, event.input, stats.numTurns + 1);
                 return lifecycle.cancelled || signal?.aborted ? { block: true, reason: '工具调用已取消' } : decision;
             });
             const unsubscribe = harness.subscribe(event => this.mapHarnessEvent(queue, event, stats, model, effort));
@@ -1175,7 +1167,7 @@ export class EcagentRunner {
             model: model.id, effort,
         };
     }
-    async authorizeTool(sessionId, projectPath, mode, toolName, input) {
+    async authorizeTool(sessionId, projectPath, mode, toolName, input, turn) {
         const permissionContext = this.permissionContexts.get(sessionId);
         if (mode === 'fullaccess') {
             return hasTrustedFullAccessContext(permissionContext)
@@ -1220,7 +1212,7 @@ export class EcagentRunner {
                 logger.warn(`[EcagentRunner] failed to record blocked operation: session=${sessionId} tool=${toolName} code=${policyCode} error=${error instanceof Error ? error.message : String(error)}`);
             }
         };
-        const policy = permissionContext?.policyHook?.(toolName, input);
+        const policy = permissionContext?.policyHook?.(toolName, input, { turn });
         if (policy?.block) {
             await recordBlockedOperation(policy.policyCode ?? 'session_policy_hook');
             return { block: true, reason: policy.reason || '当前会话策略拒绝此工具调用' };

package/dist/aun/group/operations.js

@@ -117,7 +117,6 @@ async function tryDaemonGroupSend(args, payload, runtimeContext, file) {
         mentions: args.mentions,
         encrypt: args.encrypt,
         thread,
-        returnPolicy: args.returnPolicy,
         originSessionId: runtimeContext.sessionId,
         originMessageId: runtimeContext.messageId,
         delegationToken: readDelegationCredential(),

package/dist/aun/msg/history.js

@@ -171,6 +171,7 @@ function readHistoryScopes(input) {
         .filter(({ entry, sessionIds }) => sessionIds === undefined
         || (typeof entry.sessionId === 'string' && sessionIds.has(entry.sessionId)))
         .filter(({ entry }) => input.direction === 'all' || entry.dir === input.direction)
+        .filter(({ entry }) => input.args.threadId === undefined || entry.threadId === input.args.threadId)
         .filter(({ entry }) => input.args.after === undefined || entry.ts > input.args.after)
         .filter(({ entry }) => input.args.before === undefined || entry.ts < input.args.before)
         .sort((left, right) => left.entry.ts - right.entry.ts || left.scope - right.scope)

package/dist/aun/msg/p2p.js

@@ -134,7 +134,6 @@ async function tryDaemonMsgSend(args, payload, runtimeContext, file) {
         ...(payload ? { payload } : { file }),
         encrypt: args.encrypt,
         thread,
-        returnPolicy: args.returnPolicy,
         handoffContext: args.handoffContext,
         originSessionId: runtimeContext.sessionId,
         originMessageId: runtimeContext.messageId,

package/dist/aun/outbox.js

@@ -64,6 +64,24 @@ function isExpired(entry) {
         return false;
     return Date.now() - entry.ts > entry.ttl;
 }
+/**
+ * A process-scoped entry whose enqueuing process is gone. Replaying it would
+ * deliver stale live feedback — typically the "restarting, back in ~5s" notice
+ * that a successful restart has already superseded with its own confirmation.
+ *
+ * A stale entry is not `isExpired()`: it needs `drainOnce` to retire it with a
+ * reason of its own, otherwise the send log would report a semantic drop as a
+ * timeout.
+ */
+export function isStaleProcessScoped(entry) {
+    if (!entry.processScoped)
+        return false;
+    // A record without a pid cannot prove same-process ownership. Treat it as
+    // replayable so the ordinary route/expiry rules stay in charge.
+    if (typeof entry.enqueuedByPid !== 'number')
+        return false;
+    return entry.enqueuedByPid !== process.pid;
+}
 export function isDeliveryForChannel(value, channelId) {
     return isDeliveryTargetForChannel(value, channelId);
 }
@@ -129,6 +147,7 @@ export function enqueue(aid, opts) {
         delivery,
         dedupeKey: opts.dedupeKey,
         critical: opts.critical,
+        ...(opts.processScoped ? { processScoped: true, enqueuedByPid: process.pid } : {}),
         type: opts.type,
         contentKind: opts.contentKind,
         payload: opts.payload,
@@ -273,6 +292,19 @@ function markExpired(entry) {
         code: entry.lastErrorCode,
     };
 }
+/**
+ * Drop a process-scoped entry left behind by a previous process. The terminal
+ * record is retained so the send log still shows why it never went out.
+ */
+function markSupersededProcessScoped(entry) {
+    entry.lastError = 'process-scoped delivery superseded by a new daemon process';
+    entry.lastErrorCode = 'OUTBOX_PROCESS_SUPERSEDED';
+    entry.terminal = {
+        at: Date.now(),
+        error: entry.lastError,
+        code: entry.lastErrorCode,
+    };
+}
 /** Mark a durable entry terminal while keeping its reason for diagnostics. */
 export function markTerminal(aid, id, failure, submitted, queue = submitted ? entryQueue(submitted) : 'default') {
     const entries = readEntries(aid, queue);
@@ -336,6 +368,7 @@ async function drainOnce(aid, sender, queue) {
     let expired = 0;
     let failed = 0;
     let permanent = 0;
+    let superseded = 0;
     const remaining = [];
     for (const entry of entries) {
         // Cancellation or another sender may have changed an
@@ -350,6 +383,16 @@ async function drainOnce(aid, sender, queue) {
             }
             Object.assign(entry, currentEntry);
         }
+        if (isStaleProcessScoped(entry)) {
+            // Deliberately not counted as `expired`: this is a semantic drop, not a
+            // timeout, and the drained-line diagnostic should not conflate them.
+            // The terminal record also retires the entry from `hasPending()`, so a
+            // later drain does not rediscover it.
+            superseded++;
+            markSupersededProcessScoped(entry);
+            remaining.push(entry);
+            continue;
+        }
         if (isExpired(entry)) {
             expired++;
             markExpired(entry);
@@ -457,7 +500,13 @@ async function drainOnce(aid, sender, queue) {
             }];
     });
     writeEntries(aid, retained, queue);
-    return { sent, expired, failed, ...(permanent > 0 ? { permanent } : {}) };
+    return {
+        sent,
+        expired,
+        failed,
+        ...(permanent > 0 ? { permanent } : {}),
+        ...(superseded > 0 ? { superseded } : {}),
+    };
 }
 export async function drain(aid, sender, queue = 'default') {
     const drainKey = `${queue}:${aid}`;

package/dist/channels/aun.js

@@ -4413,6 +4413,9 @@ export class AUNChannel {
         };
         if (evolCommand)
             base.ext = { evolCommand };
+        // Same diagnostic dictionary as text payloads (sessionId/agentSessionId/model).
+        if (context?.debug)
+            base.debug = { ...context.debug, sentAt: localTimestamp() };
         return withAunAttention(base);
     }
     async sendReliableStructured(channelId, payload, context, logText) {
@@ -4496,6 +4499,9 @@ export class AUNChannel {
             delivery,
             dedupeKey: operationId,
             critical: routedContext.metadata?.criticalDelivery === true,
+            // Live feedback about the running process (for example the pre-restart
+            // notice) must never be replayed by the process that replaces it.
+            processScoped: routedContext.metadata?.processScopedDelivery === true,
             type: 'text',
             text: finalText,
             context: routedContext,
@@ -4565,6 +4571,16 @@ export class AUNChannel {
         };
     }
     /** Daemon-side transport for `ec msg send` running inside an agent task. */
+    /**
+     * Agent 经 CLI 委托发送（ec msg send / ec group send）时占用本轮序号，
+     * 与回复路径共用 sentCount，保证同一轮内 seqInTurn 连续。
+     */
+    nextSeqInTurn(channelId, threadId) {
+        const turnKey = `${channelId}\0${threadId ?? ''}`;
+        const seqInTurn = (this.sentCount.get(turnKey) || 0) + 1;
+        this.sentCount.set(turnKey, seqInTurn);
+        return seqInTurn;
+    }
     async sendDaemonMsg(args) {
         if (!args.to) {
             return { ok: false, error: 'aun-msg-send requires a private target', code: 'UNSUPPORTED_TARGET' };
@@ -5271,6 +5287,9 @@ export class AUNChannel {
             delete payloadWithChatmode.thread_id;
         if (context?.threadId && !payloadWithChatmode.thread_id)
             payloadWithChatmode.thread_id = context.threadId;
+        // Same diagnostic dictionary as text payloads (sessionId/agentSessionId/model).
+        if (context?.debug)
+            payloadWithChatmode.debug = { ...context.debug, sentAt: localTimestamp() };
         const params = {
             context: { type: 'task', id: taskId },
             payload: this.limitThoughtPayload(payloadWithChatmode),
@@ -5847,8 +5866,12 @@ export class AUNChannel {
                 }
                 return { status: 'permanent', error: `unsupported outbox entry type: ${entry.type}`, code: 'UNSUPPORTED_OUTBOX_TYPE' };
             }, queue);
-            if (result.sent > 0 || result.expired > 0 || result.permanent) {
-                logger.info(`${this.logPrefix()} ${queue} outbox drained: sent=${result.sent} expired=${result.expired} failed=${result.failed} permanent=${result.permanent ?? 0}`);
+            if (result.sent > 0 || result.expired > 0 || result.permanent || result.superseded) {
+                const superseded = result.superseded ? ` superseded=${result.superseded}` : '';
+                logger.info(`${this.logPrefix()} ${queue} outbox drained: sent=${result.sent} expired=${result.expired} failed=${result.failed} permanent=${result.permanent ?? 0}${superseded}`);
+            }
+            if (result.superseded) {
+                logger.info(`${this.logPrefix()} ${queue} outbox: dropped ${result.superseded} process-scoped entr${result.superseded === 1 ? 'y' : 'ies'} left by a previous daemon process`);
             }
         };
         await drainQueue('default');
@@ -5962,6 +5985,9 @@ export class AUNChannel {
             statusPayload.chatmode = context.metadata.chatmode;
         if (context?.replyToMessageId)
             statusPayload.ref_message_id = context.replyToMessageId;
+        // Same diagnostic dictionary as text payloads (sessionId/agentSessionId/model).
+        if (context?.debug)
+            statusPayload.debug = { ...context.debug, sentAt: localTimestamp() };
         const notifyOptions = { ttlMs: 60_000 };
         if (delivery.chatType === 'group')
             notifyOptions.groupId = delivery.groupId;

package/dist/channels/daemon.js

@@ -1,3 +1,4 @@
+import { appendExpireEntry, recordNextLaunchCleanup, cleanupPreviousByKind, runExpireCleanup, cleanupSessionRecord, } from '../core/background-session/session-cleanup.js';
 import { ExecutionTimeoutError } from '../utils/error-utils.js';
 import { normalizeExecutionMode } from '../trigger/validation.js';
 import { resolvePeerRoleDetail } from '../config/peer-role-resolver.js';
@@ -17,6 +18,7 @@ export class DaemonChannel {
         thread: true,
     };
     pending = new Map();
+    bgPending = new Map();
     watchdogMs;
     totalExecutionMs;
     constructor(sessionManager, messageQueue, opts = {}) {
@@ -26,6 +28,8 @@ export class DaemonChannel {
         this.totalExecutionMs = normalizeTotalExecutionMs(opts.totalExecutionMs);
     }
     async converse(prompt, ctx) {
+        // 启动前跑一次 expire 扫描（成本低，只读少量小文件）
+        void runExpireCleanup(this.sessionManager).catch(() => { });
         const runId = ctx.runId;
         const pendingId = ctx.attemptId ?? runId;
         const messageId = pendingId;
@@ -41,6 +45,11 @@ export class DaemonChannel {
                 ? undefined
                 : setTimeout(() => this.totalExecutionTimeout(pendingId, remainingExecutionMs), remainingExecutionMs);
             totalExecutionTimer?.unref?.();
+            // trigger 清理策略：once → expire(3天)，其他 → expire(30天)
+            const isOnce = ctx.trigger.source?.type === 'once';
+            const triggerCleanupPolicy = isOnce
+                ? { mode: 'expire', ttlMs: 3 * 24 * 3600 * 1000 }
+                : { mode: 'expire', ttlMs: 30 * 24 * 3600 * 1000 };
             this.pending.set(pendingId, {
                 resolve,
                 startedAt,
@@ -52,6 +61,11 @@ export class DaemonChannel {
                 abortSignal: ctx.signal,
                 runId,
                 acc: { text: '', files: [], anomalies: [], toolCallCount: 0, seenToolCallIds: new Set() },
+                cleanupPolicy: triggerCleanupPolicy,
+                channelId: ctx.session.channelId,
+                agentAid: ctx.trigger.agentAid,
+                kind: `trigger:${ctx.trigger.id}`,
+                sessionId: ctx.session.id,
             });
         });
         const message = {
@@ -85,8 +99,13 @@ export class DaemonChannel {
                 originChannelKey: ctx.trigger.origin?.channelKey,
                 originChannelType: ctx.trigger.origin?.channelType
                     ?? (ctx.trigger.origin?.channelKey ? channelTypeFromKey(ctx.trigger.origin.channelKey) : undefined),
+                originChatType: ctx.trigger.origin?.delivery?.chatType,
+                originConversationId: ctx.trigger.origin?.delivery?.chatType === 'group'
+                    ? ctx.trigger.origin.channelId
+                    : ctx.trigger.origin?.peerId,
                 originControl: ctx.trigger.origin?.channelKey === 'daemon',
                 authorizedBy: ctx.trigger.authorizedBy,
+                labels: ctx.trigger.labels,
             },
         };
         const onAbort = () => {
@@ -128,6 +147,15 @@ export class DaemonChannel {
         return promise;
     }
     async send(envelope, payload) {
+        // bg-session 路径：优先查 bgPending
+        const bgRunId = this.bgRunIdFromEnvelope(envelope);
+        if (bgRunId) {
+            const bgSlot = this.bgPending.get(bgRunId);
+            if (bgSlot && !bgSlot.terminated) {
+                this.handleBgSessionPayload(bgRunId, bgSlot, payload);
+                return;
+            }
+        }
         const runId = this.runIdFromEnvelope(envelope);
         if (!runId)
             return;
@@ -270,6 +298,11 @@ export class DaemonChannel {
         const pendingId = metadata?.triggerAttemptId ?? metadata?.triggerRunId;
         return typeof pendingId === 'string' ? pendingId : undefined;
     }
+    bgRunIdFromEnvelope(envelope) {
+        const metadata = envelope.replyContext?.metadata;
+        const runId = metadata?.bgSessionRunId;
+        return typeof runId === 'string' ? runId : undefined;
+    }
     recordToolCall(slot, callId) {
         if (typeof callId !== 'string' || !callId) {
             slot.acc.toolCallCount += 1;
@@ -290,13 +323,14 @@ export class DaemonChannel {
             ?? (origin.channelKey ? channelTypeFromKey(origin.channelKey) : undefined);
         if (!channelType)
             return undefined;
+        const chatType = origin.delivery?.chatType ?? 'private';
         return resolvePeerRoleDetail({
             selfAid: trigger.agentAid,
             channelKey: origin.channelKey,
             channelType,
-            chatType: 'private',
+            chatType,
             actorId: origin.peerId,
-            conversationId: origin.peerId,
+            conversationId: chatType === 'group' ? origin.channelId : origin.peerId,
         }).effectiveRole ?? undefined;
     }
     finish(runId, status, metadata) {
@@ -346,6 +380,29 @@ export class DaemonChannel {
                 toolCallCount: Math.max(slot.acc.toolCallCount, completedToolCallCount),
             },
         });
+        // trigger 清理策略
+        const policy = slot.cleanupPolicy;
+        if (policy.mode === 'immediate') {
+            void cleanupSessionRecord({ sessionId: slot.sessionId, channelId: slot.channelId, agentAid: slot.agentAid }, this.sessionManager);
+        }
+        else if (policy.mode === 'on_next_launch') {
+            recordNextLaunchCleanup(slot.kind, {
+                channelId: slot.channelId,
+                sessionId: slot.sessionId,
+                agentAid: slot.agentAid,
+                recordedAt: Date.now(),
+            });
+        }
+        else if (policy.mode === 'expire') {
+            appendExpireEntry({
+                expireAt: Date.now() + policy.ttlMs,
+                sessionId: slot.sessionId,
+                channelId: slot.channelId,
+                kind: slot.kind,
+                agentAid: slot.agentAid,
+            });
+        }
+        // 'keep' 模式：不做任何处理
     }
     fail(runId, reason, text) {
         const slot = this.pending.get(runId);
@@ -412,6 +469,204 @@ export class DaemonChannel {
         }
         queue.cancelActive?.(messageId);
     }
+    // ── bg-session 生命周期 ──
+    handleBgSessionPayload(runId, slot, payload) {
+        if (slot.terminated)
+            return;
+        switch (payload.kind) {
+            case 'result.text':
+                if (payload.isFinal)
+                    slot.text = payload.text;
+                else
+                    slot.text += payload.text;
+                break;
+            case 'status.completed':
+                this.finishBgSession(runId, slot, 'completed');
+                break;
+            case 'result.error':
+                this.finishBgSession(runId, slot, 'error', payload.text ?? payload.reason ?? 'unknown error');
+                break;
+            case 'system.error':
+                this.finishBgSession(runId, slot, 'error', payload.text ?? payload.subtype ?? 'unknown error');
+                break;
+            case 'status.error':
+                this.finishBgSession(runId, slot, 'error', payload.metadata?.message ?? 'status error');
+                break;
+            case 'status.interrupted':
+                {
+                    const reason = typeof payload.metadata?.reason === 'string'
+                        ? payload.metadata.reason
+                        : 'interrupted';
+                    const outcome = slot.abortSignal?.aborted ? 'cancelled' : 'interrupted';
+                    this.finishBgSession(runId, slot, outcome, reason);
+                }
+                break;
+            case 'status.timeout':
+                this.finishBgSession(runId, slot, 'error', 'bg-session watchdog timeout');
+                break;
+            default:
+                break;
+        }
+    }
+    finishBgSession(runId, slot, outcome, error) {
+        if (slot.terminated)
+            return;
+        slot.terminated = true;
+        if (slot.watchdogTimer)
+            clearTimeout(slot.watchdogTimer);
+        if (slot.abortListener)
+            slot.abortSignal?.removeEventListener('abort', slot.abortListener);
+        this.bgPending.delete(runId);
+        // 会话结束后按清理策略处理
+        const policy = slot.cleanupPolicy;
+        if (policy.mode === 'immediate') {
+            void cleanupSessionRecord({ sessionId: slot.sessionId, channelId: slot.channelId, agentAid: slot.agentAid }, this.sessionManager);
+        }
+        else if (policy.mode === 'on_next_launch') {
+            recordNextLaunchCleanup(slot.kind, {
+                channelId: slot.channelId,
+                sessionId: slot.sessionId,
+                agentAid: slot.agentAid,
+                recordedAt: Date.now(),
+            });
+        }
+        else if (policy.mode === 'expire') {
+            appendExpireEntry({
+                expireAt: Date.now() + policy.ttlMs,
+                sessionId: slot.sessionId,
+                channelId: slot.channelId,
+                kind: slot.kind,
+                agentAid: slot.agentAid,
+            });
+        }
+        // 'keep' 模式：不做任何处理
+        slot.resolve({
+            sessionId: slot.sessionId,
+            outcome,
+            ...(slot.text ? { text: slot.text } : {}),
+            ...(error ? { error } : {}),
+        });
+    }
+    /**
+     * 拉起一个独立后台会话。会话创建、首条消息入队后即返回 handle；
+     * 会话结束由 handle.result 通知。实现 BackgroundSessionLauncher 接口。
+     * 详见 docs/background-session/background-session-launcher.md
+     */
+    async launchBackgroundSession(spec) {
+        const runId = `bg-${spec.kind}-${spec.instanceId}`;
+        const channelId = `bg:${spec.kind}:${spec.instanceId}`;
+        const cleanupPolicy = spec.cleanupPolicy ?? { mode: 'on_next_launch' };
+        // 启动前清理：on_next_launch 清理同 kind 历史，expire 扫描到期条目
+        if (cleanupPolicy.mode === 'on_next_launch') {
+            await cleanupPreviousByKind(spec.kind, this.sessionManager);
+        }
+        else if (cleanupPolicy.mode !== 'keep') {
+            // immediate 和 expire 模式都在启动时跑一次 expire 扫描
+            await runExpireCleanup(this.sessionManager);
+        }
+        const session = await this.sessionManager.getOrCreateSession(this.channelName, channelId, spec.projectPath, channelId, // threadId，每次独立，保证 by_run 语义
+        {
+            channelKey: this.channelKey,
+            peerId: `bg:${spec.kind}`,
+            peerName: spec.kind,
+            peerType: 'system',
+            bgKind: spec.kind,
+            bgInstanceId: spec.instanceId,
+            ...(spec.metadata ?? {}),
+        }, spec.kind, undefined, 'private', spec.baseagent, spec.agentAid, this.channelName, 'system');
+        const promise = new Promise((resolve) => {
+            const slot = {
+                resolve,
+                sessionId: session.id,
+                channelId,
+                kind: spec.kind,
+                startedAt: Date.now(),
+                abortSignal: spec.signal,
+                text: '',
+                terminated: false,
+                cleanupPolicy,
+                agentAid: spec.agentAid,
+                watchdogTimer: setTimeout(() => {
+                    this.finishBgSession(runId, slot, 'error', 'bg-session watchdog timeout');
+                }, this.watchdogMs),
+            };
+            slot.watchdogTimer?.unref?.();
+            if (spec.signal) {
+                const onAbort = () => {
+                    void this.cancelDelivery(runId).catch(() => { });
+                };
+                slot.abortListener = onAbort;
+                spec.signal.addEventListener('abort', onAbort, { once: true });
+                if (spec.signal.aborted)
+                    onAbort();
+            }
+            this.bgPending.set(runId, slot);
+        });
+        const message = {
+            channel: this.channelName,
+            channelType: this.channelName,
+            channelId: session.channelId,
+            selfAID: spec.agentAid,
+            baseagent: spec.baseagent,
+            threadId: session.threadId || '',
+            chatType: 'private',
+            peerId: `bg:${spec.kind}`,
+            peerName: spec.kind,
+            peerType: 'system',
+            content: spec.prompt,
+            messageId: runId,
+            timestamp: Date.now(),
+            source: 'bg-session',
+            bgSessionMeta: {
+                kind: spec.kind,
+                runId,
+                instanceId: spec.instanceId,
+                boundSessionId: session.id,
+            },
+            replyContext: {
+                metadata: { bgSessionRunId: runId },
+            },
+        };
+        void this.messageQueue.enqueue?.(session.id, message, spec.projectPath, {
+            interruptible: false,
+            agentName: spec.agentAid,
+            sessionKeyField: session.sessionKey,
+            selfAID: spec.agentAid,
+        });
+        let settled = false;
+        void promise.then(() => { settled = true; });
+        const sessionId = session.id;
+        return {
+            sessionId,
+            result: promise,
+            waitForAgentSessionId: (opts) => this.waitForAgentSessionId(sessionId, () => settled, opts),
+        };
+    }
+    /**
+     * 轮询 session 记录，等 runner 写入 agentSessionId。
+     * 会话刚创建时只有 evolcore sessionId，agentSessionId 要等 runner 初始化并开始第一轮才写入。
+     * 会话结束后再读一次即停止，避免对已结束的会话空等到超时。
+     */
+    async waitForAgentSessionId(sessionId, isSettled, opts = {}) {
+        const deadline = Date.now() + (opts.timeoutMs ?? 10_000);
+        const interval = opts.intervalMs ?? 250;
+        while (true) {
+            const settledBeforeRead = isSettled();
+            try {
+                const id = (await this.sessionManager.getSessionById(sessionId))?.agentSessionId;
+                if (id)
+                    return id;
+            }
+            catch { /* 会话记录写到一半，下一轮再读 */ }
+            if (settledBeforeRead || Date.now() >= deadline)
+                return undefined;
+            await new Promise(r => setTimeout(r, interval));
+        }
+    }
+    /** 实现 BackgroundSessionLauncher 接口 */
+    launch(spec) {
+        return this.launchBackgroundSession(spec);
+    }
 }
 function isObject(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);