@downcity/agent 1.1.11 → 1.1.13

package/src/sdk/Session.ts

@@ -4,15 +4,13 @@
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
  * - 统一收口消息落盘、默认模型配置、run/stream/fork 等高层 API。
- * - 内部继续复用现有 `Session` / `JsonlSessionHistoryComposer` / `LocalSessionExecutor`。
+ * - 内部继续复用 `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,
@@ -22,15 +20,20 @@ import type {
   AgentSessionRunResult,
   AgentSessionSetInput,
   AgentSessionStreamEvent,
+  AgentSessionSystemBlock,
+  AgentSessionSystemSnapshot,
 } from "@/sdk/AgentSdkTypes.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import { SdkSessionSystemComposer } from "@/sdk/SdkSessionSystemComposer.js";
-import { resolveSdkSessionSystemMessages } from "@/sdk/SdkSessionSystemComposer.js";
+import {
+  buildSessionSystemBlocks,
+  SessionSystemBuilder,
+} from "@/sdk/SessionSystemBuilder.js";
 import {
   inferModelLabel,
-  patchSdkSessionModelLabel,
-  readSdkSessionMetadata,
-  writeSdkSessionMetadata,
+  patchSessionModelLabel,
+  readSessionMetadata,
+  resolveSystemTimezone,
+  writeSessionMetadata,
 } from "@/sdk/SessionMetadata.js";
 import {
   getSdkAgentSessionArchiveDirPath,
@@ -41,11 +44,11 @@ import type { SessionPort } from "@/runtime/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 稳定标识。
    */
@@ -75,57 +78,59 @@ type SdkSessionOptions = {
   };
 
   /**
-   * 读取静态 system 文本集合。
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
    */
-  getStaticSystemPrompts: () => string[];
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
 
   /**
-   * 读取当前 agent 显式注入 service 的 system 文本集合。
+   * 读取当前 agent 显式注入 service 的 system blocks。
    */
-  getServiceSystemPrompts: () => Promise<string[]>;
+  getServiceSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
-   * 读取当前 agent 显式注册 plugin 的 system 文本集合。
+   * 读取当前 agent 显式注册 plugin 的 system blocks。
    */
-  getPluginSystemPrompts: () => Promise<string[]>;
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 };
 
 /**
  * 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 getStaticSystemPrompts: SdkSessionOptions["getStaticSystemPrompts"];
-  private readonly getServiceSystemPrompts: SdkSessionOptions["getServiceSystemPrompts"];
-  private readonly getPluginSystemPrompts: SdkSessionOptions["getPluginSystemPrompts"];
+  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();
     this.tools = options.tools;
     this.logger = options.logger;
-    this.getStaticSystemPrompts = options.getStaticSystemPrompts;
-    this.getServiceSystemPrompts = options.getServiceSystemPrompts;
-    this.getPluginSystemPrompts = options.getPluginSystemPrompts;
+    this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
+    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(
@@ -150,30 +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({
-            projectRoot: this.projectRoot,
-            getStaticSystemPrompts: this.getStaticSystemPrompts,
-            getServiceSystemPrompts: this.getServiceSystemPrompts,
-            getPluginSystemPrompts: this.getPluginSystemPrompts,
-          }),
-          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,
     });
   }
 
@@ -185,22 +181,30 @@ 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,
       });
-      await writeSdkSessionMetadata({
+      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:
-            typeof metadata.createdAt === "number" ? metadata.createdAt : Date.now(),
+          createdAt,
+          timezone,
         },
       });
+      this.createdAt = createdAt;
+      this.timezone = timezone;
       this.sessionConfig = {
         ...(metadata.sdkConfig?.modelLabel
           ? { modelLabel: metadata.sdkConfig.modelLabel }
@@ -227,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,
@@ -246,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();
@@ -261,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();
@@ -279,34 +283,45 @@ export class SdkSession {
    *
    * 关键点（中文）
    * - 返回内容与实际 run 时使用的 SDK system composer 同源。
-   * - 包含静态 system、显式注入 service system、显式注册 plugin system 与 runtime clock。
-   * - 这里只返回文本数组，不把 system prompt 写入会话历史。
+   * - 包含 instruction/core、显式注入 service system、显式注册 plugin system 与 session 上下文。
+   * - 返回结构化快照，不把 system prompt 写入会话历史。
    */
-  async system(): Promise<string[]> {
-    const messages = await resolveSdkSessionSystemMessages({
+  async system(): Promise<AgentSessionSystemSnapshot> {
+    const blocks = await buildSessionSystemBlocks({
+      agentId: this.agentId,
       projectRoot: this.projectRoot,
       sessionId: this.id,
-      getStaticSystemPrompts: this.getStaticSystemPrompts,
-      getServiceSystemPrompts: this.getServiceSystemPrompts,
-      getPluginSystemPrompts: this.getPluginSystemPrompts,
+      createdAt: this.createdAt,
+      timezone: this.timezone,
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
-    return messages
-      .map((message) => String(message.content || ""))
-      .filter((content) => content.trim().length > 0);
+    return {
+      sessionId: this.id,
+      session: {
+        agentId: this.agentId,
+        sessionId: this.id,
+        projectRoot: this.projectRoot,
+        createdAt: new Date(this.createdAt).toISOString(),
+        timezone: this.timezone,
+      },
+      blocks,
+    };
   }
 
   /**
    * 返回当前 session 是否正在执行。
    */
   isExecuting(): boolean {
-    return this.coreSession.isExecuting();
+    return this.executor.isExecuting();
   }
 
   /**
    * 清理当前 session 的执行器缓存。
    */
   clearExecutor(): void {
-    this.coreSession.clearExecutor();
+    this.executor.clearExecutor();
   }
 
   /**
@@ -318,7 +333,7 @@ export class SdkSession {
       throw new Error("session.run requires a non-empty query");
     }
     await this.appendUserMessage({ text: query });
-    const result = await this.coreSession.run({
+    const result = await this.executor.run({
       query,
     });
     await this.persistAssistantResult(result.assistantMessage);
@@ -346,7 +361,7 @@ export class SdkSession {
 
     const runPromise = (async () => {
       try {
-        const result = await this.coreSession.run({
+        const result = await this.executor.run({
           query,
           onUiMessageChunkCallback: async (chunk) => {
             pushUiMessageChunkAsSdkEvent({
@@ -377,7 +392,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 =
@@ -395,15 +410,15 @@ 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)}`,
       tools: this.tools,
       logger: this.logger,
-      getStaticSystemPrompts: this.getStaticSystemPrompts,
-      getServiceSystemPrompts: this.getServiceSystemPrompts,
-      getPluginSystemPrompts: this.getPluginSystemPrompts,
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
     await forked.initialize();
     if (this.sessionConfig.model) {
@@ -422,7 +437,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,
@@ -443,9 +458,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();
@@ -455,7 +470,7 @@ export class SdkSession {
   }
 
   private async touchMetadata(): Promise<void> {
-    await touchSdkSessionMetadata({
+    await touchSessionMetadata({
       projectRoot: this.projectRoot,
       agentId: this.agentId,
       sessionId: this.id,
@@ -471,7 +486,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

@@ -36,6 +36,21 @@ function normalizeModelLabel(input: unknown): string | undefined {
   return label || undefined;
 }
 
+/**
+ * 读取当前系统时区。
+ */
+export function resolveSystemTimezone(): string {
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return typeof timezone === "string" && timezone.trim()
+    ? timezone.trim()
+    : "UTC";
+}
+
+function normalizeTimezone(input: unknown): string | undefined {
+  const timezone = typeof input === "string" ? input.trim() : "";
+  return timezone || undefined;
+}
+
 /**
  * 从模型实例推导轻量可读标签。
  */
@@ -65,7 +80,7 @@ export function inferModelLabel(
 /**
  * 读取当前 session 的 meta.json。
  */
-export async function readSdkSessionMetadata(
+export async function readSessionMetadata(
   input: ReadSessionMetadataInput,
 ): Promise<SessionHistoryMetaV1> {
   const filePath = getSdkAgentSessionMetaPath(
@@ -83,6 +98,7 @@ export async function readSdkSessionMetadata(
         typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
           ? raw.createdAt
           : Date.now(),
+      timezone: normalizeTimezone(raw.timezone) || resolveSystemTimezone(),
       updatedAt:
         typeof raw.updatedAt === "number" && Number.isFinite(raw.updatedAt)
           ? raw.updatedAt
@@ -116,6 +132,7 @@ export async function readSdkSessionMetadata(
       sessionId: input.sessionId,
       agentId: input.agentId,
       createdAt: Date.now(),
+      timezone: resolveSystemTimezone(),
       updatedAt: 0,
       pinnedSkillIds: [],
     };
@@ -125,7 +142,7 @@ export async function readSdkSessionMetadata(
 /**
  * 写回当前 session 的 meta.json。
  */
-export async function writeSdkSessionMetadata(
+export async function writeSessionMetadata(
   input: ReadSessionMetadataInput & {
     /**
      * 下一份 meta 数据。
@@ -145,7 +162,7 @@ export async function writeSdkSessionMetadata(
 /**
  * 更新当前 session 的 SDK 配置摘要。
  */
-export async function patchSdkSessionModelLabel(
+export async function patchSessionModelLabel(
   input: ReadSessionMetadataInput & {
     /**
      * 当前模型实例。
@@ -153,13 +170,14 @@ 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,
     agentId: input.agentId,
     createdAt:
       typeof current.createdAt === "number" ? current.createdAt : Date.now(),
+    timezone: normalizeTimezone(current.timezone) || resolveSystemTimezone(),
     updatedAt: Date.now(),
     ...(modelLabel
       ? {
@@ -170,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,7 +3,7 @@
  *
  * 关键点（中文）
  * - 把 SDK 本地 session 适配成 chat service 依赖的 `SessionPort`。
- * - service 侧直接复用底层 `CoreSession` 协议，避免 SDK `run()` 包装层重复补写消息。
+ * - service 侧直接复用底层 `Executor` 协议，避免 SDK `run()` 包装层重复补写消息。
  */
 
 import type { SessionPort } from "@/runtime/AgentContextTypes.js";
@@ -11,15 +11,15 @@ import type { SessionPort } from "@/runtime/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(),
   };
 }