@downcity/agent 1.1.74 → 1.1.81

package/bin/session/Session.js

@@ -3,25 +3,18 @@
  *
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
- * - 统一收口消息落盘、session 级模型配置、prompt/subscribe/fork 等高层 API。
+ * - 对外保留稳定 Session facade，把状态、turn、view 逻辑下沉到独立 service。
  * - 内部继续复用 `Executor` / `JsonlSessionHistoryStore` / Composer 体系。
  */
-import { nanoid } from "nanoid";
 import { Executor } from "../executor/Executor.js";
 import { JsonlSessionHistoryComposer } from "../executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
 import { JsonlSessionHistoryStore } from "../executor/store/history/jsonl/JsonlSessionHistoryStore.js";
-import { extractTextFromUiMessage } from "../executor/messages/UIMessageTransformer.js";
-import { buildSessionSystemBlocks, SessionSystemBuilder, } from "../session/SessionSystemBuilder.js";
-import { buildSessionHistoryPage, buildSessionInfo, patchSessionModelLabel, readSessionMetadata, resolveSystemTimezone, writeSessionMetadata, } from "../session/index.js";
-import { getSdkAgentSessionArchiveDirPath, getSdkAgentSessionDirPath, } from "../session/index.js";
-import { mapAgentEventToSessionEvent, mapUiMessageChunkToAgentEvent, } from "../session/SessionEventMapper.js";
-import { persistSdkAssistantResult, touchSessionMetadata, } from "../session/index.js";
-import { createRuntimeSessionPort } from "../session/index.js";
-import { drainDeferredPersistedUserMessages } from "../executor/SessionRunScope.js";
+import { getSdkAgentSessionArchiveDirPath, getSdkAgentSessionDirPath, getSdkAgentSessionInflightPath, resolveSystemTimezone, createRuntimeSessionPort, } from "../session/index.js";
+import { SessionSystemBuilder } from "../session/SessionSystemBuilder.js";
 import { SessionEventHub } from "../session/runtime/SessionEventHub.js";
-import { SessionPromptRuntime } from "../session/runtime/SessionPromptRuntime.js";
-import { inferAgentModelLabel, normalizeAgentModel, } from "../model/CityModelAdapter.js";
-import { ensureSessionTitle } from "../session/SessionTitle.js";
+import { SessionStateService } from "../session/services/SessionStateService.js";
+import { SessionTurnService } from "../session/services/SessionTurnService.js";
+import { SessionViewService } from "../session/services/SessionViewService.js";
 /**
  * SDK 本地 Session。
  */
@@ -35,16 +28,15 @@ export class Session {
     getManagedPluginSystemBlocks;
     getPluginSystemBlocks;
     ensureConfiguredHook;
+    composers;
     historyStore;
     historyComposer;
     executor;
     eventHub = new SessionEventHub();
-    promptRuntime;
-    sessionConfig = {};
-    createdAt = Date.now();
-    timezone = resolveSystemTimezone();
-    initializePromise = null;
-    ensureConfiguredPromise = null;
+    localState;
+    stateService;
+    turnService;
+    viewService;
     runtimePort = null;
     constructor(options) {
         this.id = String(options.sessionId || "").trim();
@@ -56,6 +48,7 @@ export class Session {
         this.getManagedPluginSystemBlocks = options.getManagedPluginSystemBlocks;
         this.getPluginSystemBlocks = options.getPluginSystemBlocks;
         this.ensureConfiguredHook = options.ensureConfigured;
+        this.composers = options.composers;
         if (!this.id) {
             throw new Error("Session requires a non-empty sessionId");
         }
@@ -65,245 +58,172 @@ export class Session {
         if (!this.projectRoot) {
             throw new Error("Session requires a non-empty projectRoot");
         }
-        const sessionDirPath = getSdkAgentSessionDirPath(this.projectRoot, this.agentId, this.id);
-        const messagesDirPath = `${sessionDirPath}/messages`;
+        const session_dir_path = getSdkAgentSessionDirPath(this.projectRoot, this.agentId, this.id);
+        const messages_dir_path = `${session_dir_path}/messages`;
         this.historyStore = new JsonlSessionHistoryStore({
             rootPath: this.projectRoot,
             agentId: this.agentId,
             sessionId: this.id,
             paths: {
-                sessionDirPath,
-                messagesDirPath,
-                messagesFilePath: `${messagesDirPath}/messages.jsonl`,
-                metaFilePath: `${messagesDirPath}/meta.json`,
+                sessionDirPath: session_dir_path,
+                messagesDirPath: messages_dir_path,
+                messagesFilePath: `${messages_dir_path}/messages.jsonl`,
+                metaFilePath: `${messages_dir_path}/meta.json`,
                 archiveDirPath: getSdkAgentSessionArchiveDirPath(this.projectRoot, this.agentId, this.id),
+                inflightFilePath: getSdkAgentSessionInflightPath(this.projectRoot, this.agentId, this.id),
             },
         });
-        this.historyComposer = new JsonlSessionHistoryComposer({
+        this.localState = {
+            sessionConfig: {},
+            createdAt: Date.now(),
+            timezone: resolveSystemTimezone(),
+            initializePromise: null,
+            ensureConfiguredPromise: null,
+        };
+        const composer_context = this.create_composer_context();
+        this.historyComposer = this.resolve_composer(this.composers?.historyComposer, composer_context, () => new JsonlSessionHistoryComposer({
             store: this.historyStore,
-        });
+        }));
+        const system_composer = this.resolve_composer(this.composers?.systemComposer, composer_context, () => new SessionSystemBuilder({
+            agentId: this.agentId,
+            projectRoot: this.projectRoot,
+            getSessionCreatedAt: () => this.localState.createdAt,
+            getSessionTimezone: () => this.localState.timezone,
+            getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+            getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
+            getPluginSystemBlocks: this.getPluginSystemBlocks,
+        }));
+        const context_composer = this.resolve_optional_composer(this.composers?.contextComposer, composer_context);
+        const compaction_composer = this.resolve_optional_composer(this.composers?.compactionComposer, composer_context);
         this.executor = new Executor({
             sessionId: this.id,
             historyStore: this.historyStore,
             historyComposer: this.historyComposer,
-            getModel: () => this.sessionConfig.model,
+            getModel: () => this.localState.sessionConfig.model,
             logger: this.logger,
-            systemComposer: new SessionSystemBuilder({
-                agentId: this.agentId,
-                projectRoot: this.projectRoot,
-                getSessionCreatedAt: () => this.createdAt,
-                getSessionTimezone: () => this.timezone,
-                getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-                getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-                getPluginSystemBlocks: this.getPluginSystemBlocks,
-            }),
+            systemComposer: system_composer,
             getTools: () => this.tools,
+            ...(context_composer ? { contextComposer: context_composer } : {}),
+            ...(compaction_composer
+                ? { compactionComposer: compaction_composer }
+                : {}),
         });
-        this.promptRuntime = new SessionPromptRuntime({
-            sessionId: this.id,
-            publish: (event) => {
+        this.stateService = new SessionStateService({
+            agent_id: this.agentId,
+            project_root: this.projectRoot,
+            session_id: this.id,
+            history_store: this.historyStore,
+            executor: this.executor,
+            state: this.localState,
+            ensure_configured_hook: this.ensureConfiguredHook
+                ? async () => {
+                    await this.ensureConfiguredHook?.(this);
+                }
+                : undefined,
+            publish_event: (event) => {
                 this.eventHub.publish(event);
             },
-            createAndPersistUserMessage: async (input) => {
-                return await this.createAndPersistUserPromptMessage(input);
-            },
-            executeTurn: async ({ turnId, promptInput, onStepMerge }) => {
-                return await this.executePromptTurn({
-                    turnId,
-                    promptInput,
-                    onStepMerge,
-                });
+        });
+        this.turnService = new SessionTurnService({
+            session_id: this.id,
+            executor: this.executor,
+            state_service: this.stateService,
+            event_hub: this.eventHub,
+        });
+        this.viewService = new SessionViewService({
+            agent_id: this.agentId,
+            project_root: this.projectRoot,
+            session_id: this.id,
+            history_store: this.historyStore,
+            state_service: this.stateService,
+            is_executing: () => this.isExecuting(),
+            get_instruction_system_blocks: this.getInstructionSystemBlocks,
+            get_managed_plugin_system_blocks: this.getManagedPluginSystemBlocks,
+            get_plugin_system_blocks: this.getPluginSystemBlocks,
+            ...(this.composers?.systemComposer
+                ? { custom_system_composer: system_composer }
+                : {}),
+            create_fork_session: async (session_id) => {
+                const session = this.createChildSession(session_id);
+                await session.initialize();
+                return {
+                    session,
+                    history_store: session.historyStore,
+                    state_service: session.stateService,
+                };
             },
         });
     }
     /**
-     * 初始化当前 session 的 meta 信息与内存配置。
+     * 初始化当前 session。
      */
     async initialize() {
-        if (this.initializePromise) {
-            return await this.initializePromise;
-        }
-        this.initializePromise = (async () => {
-            const metadata = await readSessionMetadata({
-                projectRoot: this.projectRoot,
-                agentId: this.agentId,
-                sessionId: this.id,
-            });
-            const createdAt = typeof metadata.createdAt === "number" ? metadata.createdAt : Date.now();
-            const timezone = typeof metadata.timezone === "string" && metadata.timezone.trim()
-                ? metadata.timezone.trim()
-                : resolveSystemTimezone();
-            await writeSessionMetadata({
-                projectRoot: this.projectRoot,
-                agentId: this.agentId,
-                sessionId: this.id,
-                meta: {
-                    ...metadata,
-                    agentId: this.agentId,
-                    createdAt,
-                    timezone,
-                },
-            });
-            this.createdAt = createdAt;
-            this.timezone = timezone;
-            this.sessionConfig = {
-                ...(metadata.modelLabel
-                    ? { modelLabel: metadata.modelLabel }
-                    : {}),
-            };
-            return this;
-        })();
-        return await this.initializePromise;
+        await this.stateService.initialize();
+        return this;
     }
     /**
      * 读取当前 session 配置快照。
      */
     get config() {
-        return {
-            ...this.sessionConfig,
-        };
+        return this.stateService.get_config();
     }
     /**
      * 写入当前 session 默认配置。
      */
     async set(input) {
-        if (input.model) {
-            this.sessionConfig.model = normalizeAgentModel(input.model);
-            this.sessionConfig.modelLabel = inferAgentModelLabel(input.model);
-            this.executor.clearExecutor();
-        }
-        await patchSessionModelLabel({
-            projectRoot: this.projectRoot,
-            agentId: this.agentId,
-            sessionId: this.id,
-            model: this.sessionConfig.model,
-        });
+        await this.stateService.set(input);
     }
     /**
      * 追加一条新的 Session prompt。
-     *
-     * 关键点（中文）
-     * - 这是 Session actor 模型下唯一的输入入口。
-     * - 首条输入、运行中补充输入、排到下一轮的输入，调用方式完全一致。
      */
     async prompt(input) {
-        const query = String(input.query || "").trim();
-        if (!query) {
-            throw new Error("session.prompt requires a non-empty query");
-        }
-        await this.ensureRunnable();
-        return await this.promptRuntime.prompt({
-            query,
-        });
+        return await this.turnService.prompt(input);
     }
     /**
      * 订阅当前 Session 的未来事件。
-     *
-     * 关键点（中文）
-     * - 只广播订阅之后产生的事件。
-     * - 不做历史回放；历史仍通过 `history()` 读取。
      */
     subscribe(subscriber) {
-        return this.eventHub.subscribe(subscriber);
+        return this.turnService.subscribe(subscriber);
     }
     /**
      * 追加一条 user 文本消息。
      */
     async appendUserMessage(input) {
-        await this.executor.appendUserMessage({
+        await this.stateService.append_user_message({
             text: String(input.text || "").trim(),
         });
-        await this.ensureTitleFromHistory({ generate: true });
-        await this.touchMetadata();
     }
     /**
      * 追加一条 assistant 文本消息。
      */
     async appendAssistantMessage(input) {
-        await this.executor.appendAssistantMessage({
+        await this.stateService.append_assistant_message({
             fallbackText: String(input.text || "").trim(),
         });
-        await this.touchMetadata();
     }
     /**
      * 读取当前 session 详情。
      */
     async getInfo() {
-        const [metadata, messages] = await Promise.all([
-            readSessionMetadata({
-                projectRoot: this.projectRoot,
-                agentId: this.agentId,
-                sessionId: this.id,
-            }),
-            this.historyStore.list(),
-        ]);
-        const metadataWithTitle = metadata.title
-            ? metadata
-            : await ensureSessionTitle({
-                projectRoot: this.projectRoot,
-                agentId: this.agentId,
-                sessionId: this.id,
-                messages,
-            });
-        return buildSessionInfo({
-            projectRoot: this.projectRoot,
-            agentId: this.agentId,
-            sessionId: this.id,
-            metadata: metadataWithTitle,
-            messages,
-            executing: this.isExecuting(),
-        });
+        return await this.viewService.get_info();
     }
     /**
      * 读取当前 session 历史分页。
      */
     async history(input) {
-        const [session, messages] = await Promise.all([
-            this.getInfo(),
-            this.historyStore.list(),
-        ]);
-        return buildSessionHistoryPage({
-            session,
-            messages,
-            input,
-        });
+        return await this.viewService.history(input);
     }
     /**
-     * 读取当前 session 生效的 system prompt 文本集合。
-     *
-     * 关键点（中文）
-     * - 返回内容与实际 run 时使用的 SDK system composer 同源。
-     * - 包含 instruction/core、受托管 plugin system、显式注册 plugin system 与 session 上下文。
-     * - 返回结构化快照，不把 system prompt 写入会话历史。
+     * 读取当前 session 生效的 system 快照。
      */
     async system() {
-        const blocks = await buildSessionSystemBlocks({
-            agentId: this.agentId,
-            projectRoot: this.projectRoot,
-            sessionId: this.id,
-            createdAt: this.createdAt,
-            timezone: this.timezone,
-            getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-            getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-            getPluginSystemBlocks: this.getPluginSystemBlocks,
-        });
-        return {
-            sessionId: this.id,
-            session: {
-                agentId: this.agentId,
-                sessionId: this.id,
-                projectRoot: this.projectRoot,
-                createdAt: new Date(this.createdAt).toISOString(),
-                timezone: this.timezone,
-            },
-            blocks,
-        };
+        return await this.viewService.system();
     }
     /**
      * 返回当前 session 是否正在执行。
      */
     isExecuting() {
-        return this.promptRuntime.isActive() || this.executor.isExecuting();
+        return this.turnService.is_prompt_runtime_active() || this.executor.isExecuting();
     }
     /**
      * 清理当前 session 的执行器缓存。
@@ -315,41 +235,7 @@ export class Session {
      * 从当前 session 创建一个分叉会话。
      */
     async fork(input) {
-        const messageId = typeof input === "string"
-            ? String(input || "").trim() || undefined
-            : String(input?.messageId || "").trim() || undefined;
-        const messages = await this.historyStore.list();
-        const forkMessages = !messageId
-            ? messages
-            : (() => {
-                const targetIndex = messages.findIndex((message) => String(message.id || "").trim() === messageId);
-                if (targetIndex < 0) {
-                    throw new Error(`Cannot fork session "${this.id}": messageId "${messageId}" not found.`);
-                }
-                return messages.slice(0, targetIndex + 1);
-            })();
-        const forked = new Session({
-            agentId: this.agentId,
-            projectRoot: this.projectRoot,
-            sessionId: `fork-${Date.now()}-${nanoid(8)}`,
-            tools: this.tools,
-            logger: this.logger,
-            getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-            getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-            getPluginSystemBlocks: this.getPluginSystemBlocks,
-        });
-        await forked.initialize();
-        if (this.sessionConfig.model) {
-            await forked.set({
-                model: this.sessionConfig.model,
-            });
-        }
-        for (const message of forkMessages) {
-            await forked.historyStore.append(message);
-        }
-        await forked.ensureTitleFromHistory({ generate: true });
-        await forked.touchMetadata();
-        return forked;
+        return await this.viewService.fork(input);
     }
     /**
      * 返回供受托管 plugin 使用的 session 端口。
@@ -360,25 +246,19 @@ export class Session {
         this.runtimePort = createRuntimeSessionPort({
             sessionId: this.id,
             getExecutor: () => this.executor.getExecutor(),
-            prompt: async (input) => {
-                return await this.prompt(input);
-            },
-            subscribe: (subscriber) => {
-                return this.subscribe(subscriber);
-            },
+            prompt: async (input) => await this.prompt(input),
+            subscribe: (subscriber) => this.subscribe(subscriber),
             clearExecutor: () => {
                 this.executor.clearExecutor();
             },
             afterSessionUpdatedAsync: async () => {
                 await this.executor.afterSessionUpdatedAsync();
             },
-            appendUserMessage: async (messageParams) => {
-                await this.executor.appendUserMessage(messageParams);
-                await this.ensureTitleFromHistory({ generate: true });
-                await this.touchMetadata();
+            appendUserMessage: async (message_params) => {
+                await this.stateService.append_user_message(message_params);
             },
-            appendAssistantMessage: async (messageParams) => {
-                await this.executor.appendAssistantMessage(messageParams);
+            appendAssistantMessage: async (message_params) => {
+                await this.stateService.append_assistant_message(message_params);
             },
             isExecuting: () => this.isExecuting(),
             historyStore: this.historyStore,
@@ -386,7 +266,7 @@ export class Session {
                 await this.ensureReadyForExecution();
             },
             touchMetadata: async () => {
-                await this.touchMetadata();
+                await this.stateService.touch_metadata();
             },
         });
         return this.runtimePort;
@@ -395,149 +275,47 @@ export class Session {
      * 在执行前确保 session 已完成初始化与宿主装配。
      */
     async ensureReadyForExecution() {
-        await this.initialize();
-        if (this.ensureConfiguredPromise) {
-            await this.ensureConfiguredPromise;
-            return;
-        }
-        this.ensureConfiguredPromise = (async () => {
-            if (!this.ensureConfiguredHook)
-                return;
-            await this.ensureConfiguredHook(this);
-        })();
-        try {
-            await this.ensureConfiguredPromise;
-        }
-        catch (error) {
-            this.ensureConfiguredPromise = null;
-            throw error;
-        }
+        await this.stateService.ensure_ready_for_execution();
     }
-    async ensureRunnable() {
-        await this.ensureReadyForExecution();
-        if (!this.sessionConfig.model) {
-            throw new Error(`Session "${this.id}" requires a configured model. Pass model to new Agent({ model }) or call session.set({ model }) first.`);
-        }
-    }
-    async touchMetadata() {
-        await touchSessionMetadata({
-            projectRoot: this.projectRoot,
+    createChildSession(session_id) {
+        return new Session({
             agentId: this.agentId,
-            sessionId: this.id,
-            sessionConfig: this.sessionConfig,
-        });
-    }
-    async ensureTitleFromHistory(input) {
-        const messages = await this.historyStore.list();
-        const beforeMetadata = await readSessionMetadata({
             projectRoot: this.projectRoot,
-            agentId: this.agentId,
-            sessionId: this.id,
-        });
-        const beforeTitle = String(beforeMetadata.title || "").trim();
-        const nextMetadata = await ensureSessionTitle({
-            projectRoot: this.projectRoot,
-            agentId: this.agentId,
-            sessionId: this.id,
-            messages,
-            ...(input?.generate ? { model: this.sessionConfig.model } : {}),
-            generate: input?.generate === true,
-        });
-        const nextTitle = String(nextMetadata.title || "").trim();
-        if (!nextTitle || nextTitle === beforeTitle)
-            return;
-        this.eventHub.publish({
-            type: "session-title",
-            sessionId: this.id,
-            title: nextTitle,
+            sessionId: session_id,
+            tools: this.tools,
+            logger: this.logger,
+            getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+            getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
+            getPluginSystemBlocks: this.getPluginSystemBlocks,
+            composers: this.composers,
         });
     }
-    async persistAssistantResult(assistantMessage) {
-        await persistSdkAssistantResult({
-            projectRoot: this.projectRoot,
+    create_composer_context() {
+        return {
             agentId: this.agentId,
+            projectRoot: this.projectRoot,
             sessionId: this.id,
-            sessionConfig: this.sessionConfig,
-            executor: this.executor,
-            assistantMessage,
-        });
-    }
-    async createAndPersistUserPromptMessage(input) {
-        const message = this.historyStore.userText({
-            text: String(input.query || "").trim(),
-            metadata: {
-                sessionId: this.id,
-            },
-        });
-        await this.executor.appendUserMessage({
-            message,
-        });
-        await this.ensureTitleFromHistory({ generate: true });
-        await this.touchMetadata();
-        return message;
-    }
-    async executePromptTurn(input) {
-        const toolNameByCallId = new Map();
-        const result = await this.executor.run({
-            query: input.promptInput.query,
-            onStepCallback: input.onStepMerge,
-            onAssistantStepCallback: async (step) => {
-                this.eventHub.publish({
-                    type: "assistant-step",
-                    turnId: input.turnId,
-                    text: step.text,
-                    stepIndex: step.stepIndex,
-                    ...(step.visibility ? { visibility: step.visibility } : {}),
-                });
-            },
-            onUiMessageChunkCallback: async (chunk) => {
-                if (chunk.type === "tool-input-start") {
-                    toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
-                    return;
-                }
-                const event = mapUiMessageChunkToAgentEvent(chunk);
-                if (!event)
-                    return;
-                const resolvedEvent = (event.type === "tool-result" ||
-                    event.type === "tool-error") &&
-                    event.toolName === "unknown"
-                    ? {
-                        ...event,
-                        toolName: toolNameByCallId.get(event.toolCallId) || event.toolName,
-                    }
-                    : event;
-                if (resolvedEvent.type === "tool-call" ||
-                    resolvedEvent.type === "tool-error") {
-                    toolNameByCallId.set(resolvedEvent.toolCallId, resolvedEvent.toolName);
-                }
-                const sessionEvent = mapAgentEventToSessionEvent({
-                    event: resolvedEvent,
-                    turnId: input.turnId,
-                });
-                if (sessionEvent) {
-                    this.eventHub.publish(sessionEvent);
-                }
-            },
-        });
-        await this.persistAssistantResult(result.assistantMessage);
-        await this.persistDeferredUserMessages();
-        return {
-            text: extractTextFromUiMessage(result.assistantMessage),
-            success: result.success,
-            assistantMessage: result.assistantMessage,
-            ...(result.error ? { error: result.error } : {}),
+            historyStore: this.historyStore,
+            getTools: () => this.tools,
+            getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+            getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
+            getPluginSystemBlocks: this.getPluginSystemBlocks,
+            getSessionCreatedAt: () => this.localState.createdAt,
+            getSessionTimezone: () => this.localState.timezone,
         };
     }
-    async persistDeferredUserMessages() {
-        const deferredMessages = drainDeferredPersistedUserMessages(this.id);
-        for (const message of deferredMessages) {
-            await this.executor.appendUserMessage({
-                message,
-            });
-        }
-        if (deferredMessages.length > 0) {
-            await this.touchMetadata();
+    resolve_composer(input, context, create_default) {
+        const composer = this.resolve_optional_composer(input, context);
+        return composer || create_default();
+    }
+    resolve_optional_composer(input, context) {
+        if (!input)
+            return undefined;
+        if (typeof input === "function") {
+            const create_composer = input;
+            return create_composer(context);
         }
+        return input;
     }
 }
 //# sourceMappingURL=Session.js.map