@downcity/agent 1.1.12 → 1.1.14

package/src/sdk/Session.ts

@@ -3,16 +3,14 @@
  *
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
- * - 统一收口消息落盘、默认模型配置、run/stream/fork 等高层 API。
- * - 内部继续复用现有 `Session` / `JsonlSessionHistoryComposer` / `LocalSessionExecutor`。
+ * - 统一收口消息落盘、session 级模型配置、run/stream/fork 等高层 API。
+ * - 内部继续复用 `Executor` / `JsonlSessionHistoryComposer` / `Runner`。
  */
 
 import { nanoid } from "nanoid";
 import type { LanguageModel, Tool } from "ai";
-import { Session as CoreSession } from "@session/Session.js";
+import { Executor } from "@session/Executor.js";
 import { JsonlSessionHistoryComposer } from "@session/composer/history/jsonl/JsonlSessionHistoryComposer.js";
-import { JsonlSessionCompactionComposer } from "@session/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
-import { LocalSessionExecutor } from "@session/executors/local/LocalSessionExecutor.js";
 import { extractTextFromUiMessage } from "@/service/builtins/chat/runtime/UIMessageTransformer.js";
 import type {
   AgentSessionConfigSnapshot,
@@ -27,30 +25,30 @@ import type {
 } from "@/sdk/AgentSdkTypes.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import {
-  resolveSdkSessionSystemBlocks,
-  SdkSessionSystemComposer,
-} from "@/sdk/SdkSessionSystemComposer.js";
+  buildSessionSystemBlocks,
+  SessionSystemBuilder,
+} from "@/sdk/SessionSystemBuilder.js";
 import {
   inferModelLabel,
-  patchSdkSessionModelLabel,
-  readSdkSessionMetadata,
+  patchSessionModelLabel,
+  readSessionMetadata,
   resolveSystemTimezone,
-  writeSdkSessionMetadata,
+  writeSessionMetadata,
 } from "@/sdk/SessionMetadata.js";
 import {
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
 } from "@/sdk/Paths.js";
 import { AsyncQueue } from "@/sdk/AsyncQueue.js";
-import type { SessionPort } from "@/runtime/AgentContextTypes.js";
+import type { SessionPort } from "@/core/AgentContextTypes.js";
 import { pushUiMessageChunkAsSdkEvent } from "@/sdk/StreamEvents.js";
 import {
   persistSdkAssistantResult,
-  touchSdkSessionMetadata,
+  touchSessionMetadata,
 } from "@/sdk/SessionPersistence.js";
-import { createSdkSessionServicePort } from "@/sdk/SessionServicePort.js";
+import { createSessionServicePort } from "@/sdk/SessionServicePort.js";
 
-type SdkSessionOptions = {
+type SessionOptions = {
   /**
    * 当前 agent 稳定标识。
    */
@@ -98,25 +96,25 @@ type SdkSessionOptions = {
 /**
  * SDK 本地 Session。
  */
-export class SdkSession {
+export class Session {
   readonly id: string;
   readonly agentId: string;
 
   private readonly projectRoot: string;
   private readonly tools: Record<string, Tool>;
-  private readonly logger: SdkSessionOptions["logger"];
-  private readonly getInstructionSystemBlocks: SdkSessionOptions["getInstructionSystemBlocks"];
-  private readonly getServiceSystemBlocks: SdkSessionOptions["getServiceSystemBlocks"];
-  private readonly getPluginSystemBlocks: SdkSessionOptions["getPluginSystemBlocks"];
+  private readonly logger: SessionOptions["logger"];
+  private readonly getInstructionSystemBlocks: SessionOptions["getInstructionSystemBlocks"];
+  private readonly getServiceSystemBlocks: SessionOptions["getServiceSystemBlocks"];
+  private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
   private readonly historyComposer: JsonlSessionHistoryComposer;
-  private readonly coreSession: CoreSession;
+  private readonly executor: Executor;
   private sessionConfig: AgentSessionConfigSnapshot = {};
   private createdAt = Date.now();
   private timezone = resolveSystemTimezone();
   private initializePromise: Promise<this> | null = null;
   private servicePort: SessionPort | null = null;
 
-  constructor(options: SdkSessionOptions) {
+  constructor(options: SessionOptions) {
     this.id = String(options.sessionId || "").trim();
     this.agentId = String(options.agentId || "").trim();
     this.projectRoot = String(options.projectRoot || "").trim();
@@ -126,13 +124,13 @@ export class SdkSession {
     this.getServiceSystemBlocks = options.getServiceSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     if (!this.id) {
-      throw new Error("SdkSession requires a non-empty sessionId");
+      throw new Error("Session requires a non-empty sessionId");
     }
     if (!this.agentId) {
-      throw new Error("SdkSession requires a non-empty agentId");
+      throw new Error("Session requires a non-empty agentId");
     }
     if (!this.projectRoot) {
-      throw new Error("SdkSession requires a non-empty projectRoot");
+      throw new Error("Session requires a non-empty projectRoot");
     }
 
     const sessionDirPath = getSdkAgentSessionDirPath(
@@ -157,33 +155,21 @@ export class SdkSession {
       },
     });
 
-    this.coreSession = new CoreSession({
+    this.executor = new Executor({
       sessionId: this.id,
       historyComposer: this.historyComposer,
-      createExecutor: (historyComposer) => {
-        const model = this.sessionConfig.model;
-        if (!model) {
-          throw new Error(
-            `Session "${this.id}" has no model configured. Call session.set({ model }) first.`,
-          );
-        }
-        return new LocalSessionExecutor({
-          model,
-          logger: this.logger as never,
-          historyComposer,
-          compactionComposer: new JsonlSessionCompactionComposer(),
-          systemComposer: new SdkSessionSystemComposer({
-            agentId: this.agentId,
-            projectRoot: this.projectRoot,
-            getSessionCreatedAt: () => this.createdAt,
-            getSessionTimezone: () => this.timezone,
-            getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-            getServiceSystemBlocks: this.getServiceSystemBlocks,
-            getPluginSystemBlocks: this.getPluginSystemBlocks,
-          }),
-          getTools: () => this.tools,
-        });
-      },
+      getModel: () => this.sessionConfig.model,
+      logger: this.logger as never,
+      systemComposer: new SessionSystemBuilder({
+        agentId: this.agentId,
+        projectRoot: this.projectRoot,
+        getSessionCreatedAt: () => this.createdAt,
+        getSessionTimezone: () => this.timezone,
+        getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+        getServiceSystemBlocks: this.getServiceSystemBlocks,
+        getPluginSystemBlocks: this.getPluginSystemBlocks,
+      }),
+      getTools: () => this.tools,
     });
   }
 
@@ -195,7 +181,7 @@ export class SdkSession {
       return await this.initializePromise;
     }
     this.initializePromise = (async () => {
-      const metadata = await readSdkSessionMetadata({
+      const metadata = await readSessionMetadata({
         projectRoot: this.projectRoot,
         agentId: this.agentId,
         sessionId: this.id,
@@ -206,7 +192,7 @@ export class SdkSession {
         typeof metadata.timezone === "string" && metadata.timezone.trim()
           ? metadata.timezone.trim()
           : resolveSystemTimezone();
-      await writeSdkSessionMetadata({
+      await writeSessionMetadata({
         projectRoot: this.projectRoot,
         agentId: this.agentId,
         sessionId: this.id,
@@ -245,9 +231,9 @@ export class SdkSession {
     if (input.model) {
       this.sessionConfig.model = input.model;
       this.sessionConfig.modelLabel = inferModelLabel(input.model);
-      this.coreSession.clearExecutor();
+      this.executor.clearExecutor();
     }
-    await patchSdkSessionModelLabel({
+    await patchSessionModelLabel({
       projectRoot: this.projectRoot,
       agentId: this.agentId,
       sessionId: this.id,
@@ -264,7 +250,7 @@ export class SdkSession {
      */
     text: string;
   }): Promise<void> {
-    await this.coreSession.appendUserMessage({
+    await this.executor.appendUserMessage({
       text: String(input.text || "").trim(),
     });
     await this.touchMetadata();
@@ -279,7 +265,7 @@ export class SdkSession {
      */
     text: string;
   }): Promise<void> {
-    await this.coreSession.appendAssistantMessage({
+    await this.executor.appendAssistantMessage({
       fallbackText: String(input.text || "").trim(),
     });
     await this.touchMetadata();
@@ -301,7 +287,7 @@ export class SdkSession {
    * - 返回结构化快照，不把 system prompt 写入会话历史。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
-    const blocks = await resolveSdkSessionSystemBlocks({
+    const blocks = await buildSessionSystemBlocks({
       agentId: this.agentId,
       projectRoot: this.projectRoot,
       sessionId: this.id,
@@ -328,14 +314,14 @@ export class SdkSession {
    * 返回当前 session 是否正在执行。
    */
   isExecuting(): boolean {
-    return this.coreSession.isExecuting();
+    return this.executor.isExecuting();
   }
 
   /**
    * 清理当前 session 的执行器缓存。
    */
   clearExecutor(): void {
-    this.coreSession.clearExecutor();
+    this.executor.clearExecutor();
   }
 
   /**
@@ -346,8 +332,13 @@ export class SdkSession {
     if (!query) {
       throw new Error("session.run requires a non-empty query");
     }
+    if (!this.sessionConfig.model) {
+      throw new Error(
+        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+      );
+    }
     await this.appendUserMessage({ text: query });
-    const result = await this.coreSession.run({
+    const result = await this.executor.run({
       query,
     });
     await this.persistAssistantResult(result.assistantMessage);
@@ -369,13 +360,18 @@ export class SdkSession {
     if (!query) {
       throw new Error("session.stream requires a non-empty query");
     }
+    if (!this.sessionConfig.model) {
+      throw new Error(
+        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+      );
+    }
     const queue = new AsyncQueue<AgentSessionStreamEvent>();
     const toolNameByCallId = new Map<string, string>();
     await this.appendUserMessage({ text: query });
 
     const runPromise = (async () => {
       try {
-        const result = await this.coreSession.run({
+        const result = await this.executor.run({
           query,
           onUiMessageChunkCallback: async (chunk) => {
             pushUiMessageChunkAsSdkEvent({
@@ -406,7 +402,7 @@ export class SdkSession {
   /**
    * 从当前 session 创建一个分叉会话。
    */
-  async fork(input?: AgentSessionForkInput["messageId"]): Promise<SdkSession> {
+  async fork(input?: AgentSessionForkInput["messageId"]): Promise<Session> {
     const messageId = String(input || "").trim() || undefined;
     const messages = await this.historyComposer.list();
     const forkMessages =
@@ -424,7 +420,7 @@ export class SdkSession {
             return messages.slice(0, targetIndex + 1);
           })();
 
-    const forked = new SdkSession({
+    const forked = new Session({
       agentId: this.agentId,
       projectRoot: this.projectRoot,
       sessionId: `fork-${Date.now()}-${nanoid(8)}`,
@@ -451,7 +447,7 @@ export class SdkSession {
    * 生成当前 session 的元数据快照。
    */
   async toMetadata(): Promise<AgentSessionMetadata> {
-    const meta = await readSdkSessionMetadata({
+    const meta = await readSessionMetadata({
       projectRoot: this.projectRoot,
       agentId: this.agentId,
       sessionId: this.id,
@@ -472,9 +468,9 @@ export class SdkSession {
    */
   getServicePort(): SessionPort {
     if (this.servicePort) return this.servicePort;
-    this.servicePort = createSdkSessionServicePort({
+    this.servicePort = createSessionServicePort({
       sessionId: this.id,
-      coreSession: this.coreSession,
+      executor: this.executor,
       historyComposer: this.historyComposer,
       touchMetadata: async () => {
         await this.touchMetadata();
@@ -484,7 +480,7 @@ export class SdkSession {
   }
 
   private async touchMetadata(): Promise<void> {
-    await touchSdkSessionMetadata({
+    await touchSessionMetadata({
       projectRoot: this.projectRoot,
       agentId: this.agentId,
       sessionId: this.id,
@@ -500,7 +496,7 @@ export class SdkSession {
       agentId: this.agentId,
       sessionId: this.id,
       sessionConfig: this.sessionConfig,
-      coreSession: this.coreSession,
+      executor: this.executor,
       assistantMessage,
     });
   }

package/src/sdk/SessionMetadata.ts

@@ -80,7 +80,7 @@ export function inferModelLabel(
 /**
  * 读取当前 session 的 meta.json。
  */
-export async function readSdkSessionMetadata(
+export async function readSessionMetadata(
   input: ReadSessionMetadataInput,
 ): Promise<SessionHistoryMetaV1> {
   const filePath = getSdkAgentSessionMetaPath(
@@ -142,7 +142,7 @@ export async function readSdkSessionMetadata(
 /**
  * 写回当前 session 的 meta.json。
  */
-export async function writeSdkSessionMetadata(
+export async function writeSessionMetadata(
   input: ReadSessionMetadataInput & {
     /**
      * 下一份 meta 数据。
@@ -162,7 +162,7 @@ export async function writeSdkSessionMetadata(
 /**
  * 更新当前 session 的 SDK 配置摘要。
  */
-export async function patchSdkSessionModelLabel(
+export async function patchSessionModelLabel(
   input: ReadSessionMetadataInput & {
     /**
      * 当前模型实例。
@@ -170,7 +170,7 @@ export async function patchSdkSessionModelLabel(
     model?: LanguageModel;
   },
 ): Promise<SessionHistoryMetaV1> {
-  const current = await readSdkSessionMetadata(input);
+  const current = await readSessionMetadata(input);
   const modelLabel = inferModelLabel(input.model);
   const next: SessionHistoryMetaV1 = {
     ...current,
@@ -188,7 +188,7 @@ export async function patchSdkSessionModelLabel(
         }
       : {}),
   };
-  await writeSdkSessionMetadata({
+  await writeSessionMetadata({
     ...input,
     meta: next,
   });

package/src/sdk/SessionPersistence.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 集中处理 session meta 更新时间、模型展示标签与 assistant 消息落盘。
- * - `SdkSession` 只负责调用这些能力，不直接拼装 meta 结构。
+ * - `Session` 只负责调用这些能力，不直接拼装 meta 结构。
  */
 
 import { resolveAssistantMessageForPersistence } from "@/service/builtins/chat/runtime/UserVisibleText.js";
@@ -12,14 +12,14 @@ import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { AgentSessionConfigSnapshot } from "@/sdk/AgentSdkTypes.js";
 import {
-  readSdkSessionMetadata,
-  writeSdkSessionMetadata,
+  readSessionMetadata,
+  writeSessionMetadata,
 } from "@/sdk/SessionMetadata.js";
 
 /**
  * SDK Session 元数据写入参数。
  */
-export interface TouchSdkSessionMetadataParams {
+export interface TouchSessionMetadataParams {
   /**
    * 当前项目根目录。
    */
@@ -42,11 +42,11 @@ export interface TouchSdkSessionMetadataParams {
  * Assistant 结果落盘参数。
  */
 export interface PersistSdkAssistantResultParams
-  extends TouchSdkSessionMetadataParams {
+  extends TouchSessionMetadataParams {
   /**
-   * 追加 assistant 消息的底层 session 端口。
+   * 追加 assistant 消息的底层执行编排器。
    */
-  coreSession: {
+  executor: {
     appendAssistantMessage(params: {
       /**
        * 已构造好的完整消息。
@@ -67,10 +67,10 @@ export interface PersistSdkAssistantResultParams
 /**
  * 刷新 SDK session 元数据。
  */
-export async function touchSdkSessionMetadata(
-  params: TouchSdkSessionMetadataParams,
+export async function touchSessionMetadata(
+  params: TouchSessionMetadataParams,
 ): Promise<void> {
-  const current = await readSdkSessionMetadata({
+  const current = await readSessionMetadata({
     projectRoot: params.projectRoot,
     agentId: params.agentId,
     sessionId: params.sessionId,
@@ -90,7 +90,7 @@ export async function touchSdkSessionMetadata(
         }
       : {}),
   };
-  await writeSdkSessionMetadata({
+  await writeSessionMetadata({
     projectRoot: params.projectRoot,
     agentId: params.agentId,
     sessionId: params.sessionId,
@@ -105,9 +105,9 @@ export async function persistSdkAssistantResult(
   params: PersistSdkAssistantResultParams,
 ): Promise<void> {
   const persisted = resolveAssistantMessageForPersistence(params.assistantMessage);
-  await params.coreSession.appendAssistantMessage({
+  await params.executor.appendAssistantMessage({
     ...(persisted ? { message: persisted } : {}),
     fallbackText: extractTextFromUiMessage(params.assistantMessage),
   });
-  await touchSdkSessionMetadata(params);
+  await touchSessionMetadata(params);
 }

package/src/sdk/SessionServicePort.ts

@@ -3,23 +3,23 @@
  *
  * 关键点（中文）
  * - 把 SDK 本地 session 适配成 chat service 依赖的 `SessionPort`。
- * - service 侧直接复用底层 `CoreSession` 协议，避免 SDK `run()` 包装层重复补写消息。
+ * - service 侧直接复用底层 `Executor` 协议，避免 SDK `run()` 包装层重复补写消息。
  */
 
-import type { SessionPort } from "@/runtime/AgentContextTypes.js";
+import type { SessionPort } from "@/core/AgentContextTypes.js";
 
 /**
  * 构造 SDK SessionPort 的参数。
  */
-export interface CreateSdkSessionServicePortParams {
+export interface CreateSessionServicePortParams {
   /**
    * 当前 sessionId。
    */
   sessionId: string;
   /**
-   * 底层 session 实例。
+   * 底层执行编排器。
    */
-  coreSession: Omit<SessionPort, "sessionId" | "getHistoryComposer">;
+  executor: Omit<SessionPort, "sessionId" | "getHistoryComposer">;
   /**
    * 当前 session 历史持久化端口。
    */
@@ -33,30 +33,30 @@ export interface CreateSdkSessionServicePortParams {
 /**
  * 创建供 service 使用的 session 端口。
  */
-export function createSdkSessionServicePort(
-  params: CreateSdkSessionServicePortParams,
+export function createSessionServicePort(
+  params: CreateSessionServicePortParams,
 ): SessionPort {
   return {
     sessionId: params.sessionId,
-    getExecutor: () => params.coreSession.getExecutor(),
+    getExecutor: () => params.executor.getExecutor(),
     getHistoryComposer: () => params.historyComposer,
     run: async (runParams) => {
-      return await params.coreSession.run(runParams);
+      return await params.executor.run(runParams);
     },
     clearExecutor: () => {
-      params.coreSession.clearExecutor();
+      params.executor.clearExecutor();
     },
     afterSessionUpdatedAsync: async () => {
-      await params.coreSession.afterSessionUpdatedAsync();
+      await params.executor.afterSessionUpdatedAsync();
     },
     appendUserMessage: async (messageParams) => {
-      await params.coreSession.appendUserMessage(messageParams);
+      await params.executor.appendUserMessage(messageParams);
       await params.touchMetadata();
     },
     appendAssistantMessage: async (messageParams) => {
-      await params.coreSession.appendAssistantMessage(messageParams);
+      await params.executor.appendAssistantMessage(messageParams);
       await params.touchMetadata();
     },
-    isExecuting: () => params.coreSession.isExecuting(),
+    isExecuting: () => params.executor.isExecuting(),
   };
 }

package/src/sdk/{SdkSessionSystemComposer.ts → SessionSystemBuilder.ts}

@@ -18,7 +18,7 @@ import type {
 /**
  * 解析 SDK session system blocks 的输入。
  */
-export interface ResolveSdkSessionSystemBlocksParams {
+export interface BuildSessionSystemBlocksParams {
   /**
    * 当前 agent 的稳定标识。
    */
@@ -60,7 +60,7 @@ export interface ResolveSdkSessionSystemBlocksParams {
   getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 }
 
-type SdkSessionSystemComposerOptions = {
+type SessionSystemBuilderOptions = {
   /**
    * 当前 agent 的稳定标识。
    */
@@ -126,7 +126,7 @@ function normalizeSystemBlocks(
 
 function createSessionInfo(
   params: Pick<
-    ResolveSdkSessionSystemBlocksParams,
+    BuildSessionSystemBlocksParams,
     "agentId" | "sessionId" | "projectRoot" | "createdAt" | "timezone"
   >,
 ): AgentSessionSystemSessionInfo {
@@ -161,8 +161,8 @@ function createSessionSystemBlock(
 /**
  * 解析 SDK session 当前生效的 system blocks。
  */
-export async function resolveSdkSessionSystemBlocks(
-  params: ResolveSdkSessionSystemBlocksParams,
+export async function buildSessionSystemBlocks(
+  params: BuildSessionSystemBlocksParams,
 ): Promise<AgentSessionSystemBlock[]> {
   const agentId = String(params.agentId || "").trim();
   const projectRoot = String(params.projectRoot || "").trim();
@@ -170,19 +170,19 @@ export async function resolveSdkSessionSystemBlocks(
   const createdAt = Number(params.createdAt || 0);
   const timezone = String(params.timezone || "").trim();
   if (!agentId) {
-    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty agentId");
+    throw new Error("buildSessionSystemBlocks requires a non-empty agentId");
   }
   if (!projectRoot) {
-    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty projectRoot");
+    throw new Error("buildSessionSystemBlocks requires a non-empty projectRoot");
   }
   if (!sessionId) {
-    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty sessionId");
+    throw new Error("buildSessionSystemBlocks requires a non-empty sessionId");
   }
   if (!Number.isFinite(createdAt) || createdAt <= 0) {
-    throw new Error("resolveSdkSessionSystemBlocks requires a valid createdAt");
+    throw new Error("buildSessionSystemBlocks requires a valid createdAt");
   }
   if (!timezone) {
-    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty timezone");
+    throw new Error("buildSessionSystemBlocks requires a non-empty timezone");
   }
   return [
     ...normalizeSystemBlocks(params.getInstructionSystemBlocks()),
@@ -198,10 +198,10 @@ export async function resolveSdkSessionSystemBlocks(
 /**
  * 解析 SDK session 当前生效的 system messages。
  */
-export async function resolveSdkSessionSystemMessages(
-  params: ResolveSdkSessionSystemBlocksParams,
+export async function buildSessionSystemMessages(
+  params: BuildSessionSystemBlocksParams,
 ): Promise<SessionSystemMessage[]> {
-  const blocks = await resolveSdkSessionSystemBlocks(params);
+  const blocks = await buildSessionSystemBlocks(params);
   return blocks.map((block) => ({
     role: "system" as const,
     content: block.content,
@@ -211,18 +211,18 @@ export async function resolveSdkSessionSystemMessages(
 /**
  * SDK Session system composer 实现。
  */
-export class SdkSessionSystemComposer extends SessionSystemComposer {
+export class SessionSystemBuilder extends SessionSystemComposer {
   readonly name = "sdk_prompt_system";
 
   private readonly agentId: string;
   private readonly projectRoot: string;
-  private readonly getSessionCreatedAt: SdkSessionSystemComposerOptions["getSessionCreatedAt"];
-  private readonly getSessionTimezone: SdkSessionSystemComposerOptions["getSessionTimezone"];
-  private readonly getInstructionSystemBlocks: SdkSessionSystemComposerOptions["getInstructionSystemBlocks"];
-  private readonly getServiceSystemBlocks: SdkSessionSystemComposerOptions["getServiceSystemBlocks"];
-  private readonly getPluginSystemBlocks: SdkSessionSystemComposerOptions["getPluginSystemBlocks"];
+  private readonly getSessionCreatedAt: SessionSystemBuilderOptions["getSessionCreatedAt"];
+  private readonly getSessionTimezone: SessionSystemBuilderOptions["getSessionTimezone"];
+  private readonly getInstructionSystemBlocks: SessionSystemBuilderOptions["getInstructionSystemBlocks"];
+  private readonly getServiceSystemBlocks: SessionSystemBuilderOptions["getServiceSystemBlocks"];
+  private readonly getPluginSystemBlocks: SessionSystemBuilderOptions["getPluginSystemBlocks"];
 
-  constructor(options: SdkSessionSystemComposerOptions) {
+  constructor(options: SessionSystemBuilderOptions) {
     super();
     this.agentId = String(options.agentId || "").trim();
     this.projectRoot = String(options.projectRoot || "").trim();
@@ -232,10 +232,10 @@ export class SdkSessionSystemComposer extends SessionSystemComposer {
     this.getServiceSystemBlocks = options.getServiceSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     if (!this.agentId) {
-      throw new Error("SdkSessionSystemComposer requires a non-empty agentId");
+      throw new Error("SessionSystemBuilder requires a non-empty agentId");
     }
     if (!this.projectRoot) {
-      throw new Error("SdkSessionSystemComposer requires a non-empty projectRoot");
+      throw new Error("SessionSystemBuilder requires a non-empty projectRoot");
     }
   }
 
@@ -245,9 +245,9 @@ export class SdkSessionSystemComposer extends SessionSystemComposer {
   async resolve() {
     const sessionId = String(getSessionRunScope()?.sessionId || "").trim();
     if (!sessionId) {
-      throw new Error("SdkSessionSystemComposer.resolve requires a non-empty sessionId");
+      throw new Error("SessionSystemBuilder.resolve requires a non-empty sessionId");
     }
-    return await resolveSdkSessionSystemMessages({
+    return await buildSessionSystemMessages({
       agentId: this.agentId,
       projectRoot: this.projectRoot,
       sessionId,