@downcity/agent 1.1.74 → 1.1.81

package/bin/types/session/SessionComposerOptions.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Session Composer 配置类型。
+ *
+ * 关键点（中文）
+ * - Composer 是 session 执行阶段的可替换策略对象。
+ * - 调用方可以传入现成实例，也可以传入 factory 为每个 session 创建独立实例。
+ * - factory 适合 history/system 等可能绑定 sessionId、historyStore 或 session 元信息的 composer。
+ */
+import type { Tool } from "ai";
+import type { SessionCompactionComposer } from "../../executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionContextComposer } from "../../executor/composer/context/SessionContextComposer.js";
+import type { SessionHistoryComposer } from "../../executor/composer/history/SessionHistoryComposer.js";
+import type { SessionSystemComposer } from "../../executor/composer/system/SessionSystemComposer.js";
+import type { SessionHistoryStore } from "../../executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionSystemBlock } from "../../types/agent/SessionTypes.js";
+/**
+ * 单个 session 创建 Composer 时可读取的稳定上下文。
+ */
+export interface SessionComposerFactoryContext {
+    /**
+     * 当前 agent 的稳定标识。
+     */
+    agentId: string;
+    /**
+     * 当前 agent 绑定的项目根目录。
+     */
+    projectRoot: string;
+    /**
+     * 当前 session 唯一标识。
+     */
+    sessionId: string;
+    /**
+     * 当前 session 对应的 history 事实源。
+     *
+     * 关键点（中文）
+     * - history composer 和 compaction composer 通常需要基于它读取或压缩历史。
+     * - factory 每次收到的都是当前 session 自己的 store。
+     */
+    historyStore: SessionHistoryStore;
+    /**
+     * 当前 agent 默认工具集合读取器。
+     */
+    getTools: () => Record<string, Tool>;
+    /**
+     * 读取当前 SDK 调用方传入的 instruction system blocks。
+     */
+    getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+    /**
+     * 读取当前 agent 显式注入的受托管 plugin system blocks。
+     */
+    getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+    /**
+     * 读取当前 agent 显式注册 plugin 的 system blocks。
+     */
+    getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+    /**
+     * 读取当前 session 首次创建时间（ms）。
+     */
+    getSessionCreatedAt: () => number;
+    /**
+     * 读取当前 session 初始化时解析到的系统时区。
+     */
+    getSessionTimezone: () => string;
+}
+/**
+ * 可直接传入 composer 实例，也可传入按 session 创建 composer 的 factory。
+ */
+export type SessionComposerInput<TComposer> = TComposer | ((context: SessionComposerFactoryContext) => TComposer);
+/**
+ * Session Composer 覆盖项。
+ */
+export interface SessionComposerOptions {
+    /**
+     * 覆盖本轮 system messages 的 composer。
+     */
+    systemComposer?: SessionComposerInput<SessionSystemComposer>;
+    /**
+     * 覆盖本轮 history messages 的 composer。
+     */
+    historyComposer?: SessionComposerInput<SessionHistoryComposer>;
+    /**
+     * 覆盖本轮 tools、step hooks、fallback assistant message 等运行上下文 composer。
+     */
+    contextComposer?: SessionComposerInput<SessionContextComposer>;
+    /**
+     * 覆盖本轮上下文压缩 composer。
+     */
+    compactionComposer?: SessionComposerInput<SessionCompactionComposer>;
+}
+//# sourceMappingURL=SessionComposerOptions.d.ts.map

package/bin/types/session/SessionComposerOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionComposerOptions.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionComposerOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,6DAA6D,CAAC;AAC7G,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uDAAuD,CAAC;AACpG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uDAAuD,CAAC;AACpG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qDAAqD,CAAC;AACjG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iDAAiD,CAAC;AAC3F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,YAAY,EAAE,mBAAmB,CAAC;IAElC;;OAEG;IACH,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAErC;;OAEG;IACH,0BAA0B,EAAE,MAAM,uBAAuB,EAAE,CAAC;IAE5D;;OAEG;IACH,4BAA4B,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEvE;;OAEG;IACH,qBAAqB,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEhE;;OAEG;IACH,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAElC;;OAEG;IACH,kBAAkB,EAAE,MAAM,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,SAAS,IACtC,SAAS,GACT,CAAC,CAAC,OAAO,EAAE,6BAA6B,KAAK,SAAS,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC,qBAAqB,CAAC,CAAC;IAE7D;;OAEG;IACH,eAAe,CAAC,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;IAE/D;;OAEG;IACH,eAAe,CAAC,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;IAE/D;;OAEG;IACH,kBAAkB,CAAC,EAAE,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;CACtE"}

package/bin/types/session/SessionComposerOptions.js

@@ -0,0 +1,10 @@
+/**
+ * Session Composer 配置类型。
+ *
+ * 关键点（中文）
+ * - Composer 是 session 执行阶段的可替换策略对象。
+ * - 调用方可以传入现成实例，也可以传入 factory 为每个 session 创建独立实例。
+ * - factory 适合 history/system 等可能绑定 sessionId、historyStore 或 session 元信息的 composer。
+ */
+export {};
+//# sourceMappingURL=SessionComposerOptions.js.map

package/bin/types/session/SessionComposerOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionComposerOptions.js","sourceRoot":"","sources":["../../../src/types/session/SessionComposerOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/bin/types/session/SessionLocalState.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SessionLocalState：本地 Session 运行态快照。
+ *
+ * 关键点（中文）
+ * - 这里承载本地 Session 在内存中的可变运行态。
+ * - state / turn / view 三类 service 通过共享该对象协作，避免彼此复制状态。
+ * - 这里只保存运行态，不承载行为逻辑。
+ */
+import type { AgentSessionConfigSnapshot } from "../../types/agent/AgentTypes.js";
+/**
+ * 本地 Session 内存状态。
+ */
+export interface SessionLocalState {
+    /**
+     * 当前 session 配置快照。
+     */
+    sessionConfig: AgentSessionConfigSnapshot;
+    /**
+     * 当前 session 创建时间（毫秒时间戳）。
+     */
+    createdAt: number;
+    /**
+     * 当前 session 参考时区。
+     */
+    timezone: string;
+    /**
+     * initialize() 过程中的并发复用 Promise。
+     */
+    initializePromise: Promise<void> | null;
+    /**
+     * ensureReadyForExecution() 过程中的并发复用 Promise。
+     */
+    ensureConfiguredPromise: Promise<void> | null;
+}
+//# sourceMappingURL=SessionLocalState.d.ts.map

package/bin/types/session/SessionLocalState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionLocalState.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionLocalState.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,aAAa,EAAE,0BAA0B,CAAC;IAE1C;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,iBAAiB,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExC;;OAEG;IACH,uBAAuB,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/C"}

package/bin/types/session/SessionLocalState.js

@@ -0,0 +1,10 @@
+/**
+ * SessionLocalState：本地 Session 运行态快照。
+ *
+ * 关键点（中文）
+ * - 这里承载本地 Session 在内存中的可变运行态。
+ * - state / turn / view 三类 service 通过共享该对象协作，避免彼此复制状态。
+ * - 这里只保存运行态，不承载行为逻辑。
+ */
+export {};
+//# sourceMappingURL=SessionLocalState.js.map

package/bin/types/session/SessionLocalState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionLocalState.js","sourceRoot":"","sources":["../../../src/types/session/SessionLocalState.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/bin/types/session/SessionOptions.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Session 构造参数类型。
+ *
+ * 关键点（中文）
+ * - 这里描述 Agent 创建本地 Session 时传入的稳定上下文。
+ * - 默认 Session 和自定义 Session 类都应使用这组参数。
+ * - Composer 仍然是 Session 级能力，不向 Agent 的执行策略层泄漏。
+ */
+import type { Tool } from "ai";
+import type { AgentSession } from "../../types/agent/SessionActor.js";
+import type { SessionPort } from "../../types/runtime/agent/AgentContext.js";
+import type { AgentSessionSystemBlock } from "../../types/agent/SessionTypes.js";
+import type { SessionComposerOptions } from "../../types/session/SessionComposerOptions.js";
+/**
+ * Agent 可管理的本地 Session 实例。
+ */
+export interface AgentManagedSession extends AgentSession {
+    /**
+     * 初始化当前 session。
+     */
+    initialize(): Promise<this>;
+    /**
+     * 返回供 plugin/runtime 使用的 session 端口。
+     */
+    getRuntimePort(): SessionPort;
+    /**
+     * 返回当前 session 是否正在执行。
+     */
+    isExecuting(): boolean;
+}
+/**
+ * 本地 Session 构造参数。
+ */
+export interface SessionOptions {
+    /**
+     * 当前 agent 稳定标识。
+     */
+    agentId: string;
+    /**
+     * 当前项目根目录。
+     */
+    projectRoot: string;
+    /**
+     * 当前 sessionId。
+     */
+    sessionId: string;
+    /**
+     * 当前 agent 默认工具集合。
+     */
+    tools: Record<string, Tool>;
+    /**
+     * 统一日志器。
+     */
+    logger: {
+        /**
+         * 记录普通信息。
+         */
+        info(message: string, details?: Record<string, unknown>): void;
+        /**
+         * 记录警告信息。
+         */
+        warn(message: string, details?: Record<string, unknown>): void;
+    };
+    /**
+     * 读取当前 SDK 调用方传入的 instruction system blocks。
+     */
+    getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+    /**
+     * 读取当前 agent 显式注入的受托管 plugin system blocks。
+     */
+    getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+    /**
+     * 读取当前 agent 显式注册 plugin 的 system blocks。
+     */
+    getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+    /**
+     * 在执行前确保当前 session 已完成宿主侧默认配置。
+     */
+    ensureConfigured?: (session: AgentManagedSession) => Promise<void>;
+    /**
+     * 当前 session 的 Composer 覆盖项。
+     */
+    composers?: SessionComposerOptions;
+}
+//# sourceMappingURL=SessionOptions.d.ts.map

package/bin/types/session/SessionOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionOptions.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AACzE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAExF;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,cAAc,IAAI,WAAW,CAAC;IAE9B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,MAAM,EAAE;QACN;;WAEG;QACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QAE/D;;WAEG;QACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAChE,CAAC;IAEF;;OAEG;IACH,0BAA0B,EAAE,MAAM,uBAAuB,EAAE,CAAC;IAE5D;;OAEG;IACH,4BAA4B,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEvE;;OAEG;IACH,qBAAqB,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEhE;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;OAEG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC"}

package/bin/types/session/SessionOptions.js

@@ -0,0 +1,10 @@
+/**
+ * Session 构造参数类型。
+ *
+ * 关键点（中文）
+ * - 这里描述 Agent 创建本地 Session 时传入的稳定上下文。
+ * - 默认 Session 和自定义 Session 类都应使用这组参数。
+ * - Composer 仍然是 Session 级能力，不向 Agent 的执行策略层泄漏。
+ */
+export {};
+//# sourceMappingURL=SessionOptions.js.map

package/bin/types/session/SessionOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionOptions.js","sourceRoot":"","sources":["../../../src/types/session/SessionOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.74",
+  "version": "1.1.81",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -29,7 +29,7 @@
     "node-cron": "^4.2.1",
     "ws": "^8.21.0",
     "zod": "^4.4.3",
-    "@downcity/type": "0.1.16"
+    "@downcity/type": "0.1.20"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/scripts/session-history-inflight.test.mjs

@@ -0,0 +1,146 @@
+/**
+ * @file 验证 session history 会把运行中的 assistant 收敛到 inflight 快照，并在完成后写回正式历史。
+ *
+ * 关键点（中文）
+ * - 直接覆盖 JSONL history store 的落盘语义，确保运行中不中断丢失过程。
+ * - `messages.jsonl` 仍保持一轮一条 assistant 的正式历史语义。
+ * - 运行中快照放在 `inflight.json`，浏览层读取时也应可见。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import { JsonlSessionHistoryStore } from "../bin/index.js";
+
+function create_assistant_message(parts) {
+  return {
+    id: "a:test:final",
+    role: "assistant",
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: "session_test",
+      source: "egress",
+      kind: "normal",
+    },
+    parts,
+  };
+}
+
+test("JsonlSessionHistoryStore exposes inflight assistant during execution and finalizes it into history", async () => {
+  const root_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-history-inflight-"),
+  );
+
+  const store = new JsonlSessionHistoryStore({
+    rootPath: root_path,
+    agentId: "official",
+    sessionId: "session_test",
+  });
+
+  await store.append(
+    store.userText({
+      text: "write to document",
+      metadata: {
+        sessionId: "session_test",
+      },
+    }),
+  );
+
+  await store.writeInflight(
+    create_assistant_message([
+      { type: "step-start" },
+      { type: "text", text: "Let me inspect the document.", state: "done" },
+      {
+        type: "tool-exec_command",
+        toolCallId: "call_1",
+        input: { cmd: "cat demo.mdx" },
+        state: "output-available",
+        output: { success: true, output: "# demo" },
+      },
+    ]),
+  );
+
+  const during_run = await store.list();
+  assert.equal(during_run.length, 2);
+  assert.equal(during_run[1]?.role, "assistant");
+  assert.deepEqual(
+    during_run[1]?.parts.map((part) => part.type),
+    ["step-start", "text", "tool-exec_command"],
+  );
+
+  await store.finalizeInflight(
+    create_assistant_message([
+      { type: "text", text: "Done writing.", state: "done" },
+    ]),
+  );
+
+  const after_finish = await store.list();
+  assert.equal(after_finish.length, 2);
+  assert.deepEqual(
+    after_finish[1]?.parts.map((part) => part.type),
+    ["step-start", "text", "tool-exec_command", "text"],
+  );
+
+  const inflight_path = path.join(
+    root_path,
+    ".downcity",
+    "agents",
+    "official",
+    "sessions",
+    "session_test",
+    "messages",
+    "inflight.json",
+  );
+  const inflight_exists = await fs
+    .access(inflight_path)
+    .then(() => true)
+    .catch(() => false);
+  assert.equal(inflight_exists, false);
+});
+
+test("Appending a new user message flushes stale inflight assistant before the new turn", async () => {
+  const root_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-history-flush-"),
+  );
+
+  const store = new JsonlSessionHistoryStore({
+    rootPath: root_path,
+    agentId: "official",
+    sessionId: "session_flush_test",
+  });
+
+  await store.append(
+    store.userText({
+      text: "first",
+      metadata: {
+        sessionId: "session_flush_test",
+      },
+    }),
+  );
+
+  await store.writeInflight(
+    create_assistant_message([
+      { type: "step-start" },
+      { type: "text", text: "partial assistant", state: "done" },
+    ]),
+  );
+
+  await store.append(
+    store.userText({
+      text: "second",
+      metadata: {
+        sessionId: "session_flush_test",
+      },
+    }),
+  );
+
+  const messages = await store.list();
+  assert.equal(messages.length, 3);
+  assert.equal(messages[0]?.role, "user");
+  assert.equal(messages[1]?.role, "assistant");
+  assert.equal(messages[2]?.role, "user");
+});

package/src/agent/local/Agent.ts

@@ -0,0 +1,197 @@
+/**
+ * Agent local：本地入口与 facade。
+ *
+ * 职责说明（中文）
+ * - 对外暴露 `Agent` 这一唯一的本地实例类。
+ * - facade 只保留公开 API 与 service 组合，不再直接承载装配、session 管理与生命周期细节。
+ * - 单个 agent 的长期对象装配、session 管理、后台能力生命周期分别下沉到独立 service。
+ */
+
+import type { Tool } from "ai";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { PluginPort } from "@/plugin/types/Plugin.js";
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentModel,
+  AgentOptions,
+  AgentSession,
+  AgentSessionCollection,
+  AgentSessionSummaryPage,
+  AgentStartOptions,
+  AgentStartResult,
+  AgentStopResult,
+} from "@/types/agent/AgentTypes.js";
+import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
+import { Logger } from "@/utils/logger/Logger.js";
+import { normalizeInstructionInput } from "@/agent/local/AgentInstructions.js";
+import {
+  AgentAssemblyService,
+  type AgentAssemblyResult,
+} from "@/agent/local/services/AgentAssemblyService.js";
+import { AgentSessionManager } from "@/agent/local/services/AgentSessionManager.js";
+import { AgentLifecycleService } from "@/agent/local/services/AgentLifecycleService.js";
+
+/**
+ * SDK 本地 Agent。
+ */
+export class Agent {
+  readonly id: string;
+  readonly path: string;
+  readonly tools: Record<string, Tool>;
+  readonly plugins: PluginPort;
+
+  private readonly logger: Logger;
+  private readonly runtime: AgentRuntime;
+  private readonly agentContext: AgentContext;
+  private readonly pluginRegistry: PluginRegistry;
+  private readonly config: DowncityConfig;
+  private readonly env: Record<string, string>;
+  private readonly defaultModel?: AgentModel;
+  private readonly SessionClass: AgentOptions["Session"];
+  private readonly sessionManager: AgentSessionManager;
+  private readonly lifecycleService: AgentLifecycleService;
+
+  private instruction: string[];
+
+  constructor(options: AgentOptions) {
+    this.defaultModel = options.model;
+    this.SessionClass = options.Session;
+    let session_manager_ref: AgentSessionManager | null = null;
+    const assembly_service = new AgentAssemblyService({
+      options,
+      list_cached_sessions: () => session_manager_ref?.list_cached_sessions() || [],
+      get_session_port: (session_id) => {
+        if (!session_manager_ref) {
+          throw new Error("Agent session manager is not initialized");
+        }
+        return session_manager_ref.get_session_port(session_id);
+      },
+      resolve_session_model: async (session_id) => {
+        if (!session_manager_ref) return undefined;
+        const session = await session_manager_ref.get_session(session_id);
+        return session.config.model;
+      },
+    });
+    const assembly = assembly_service.assemble();
+
+    this.id = assembly.id;
+    this.path = assembly.path;
+    this.tools = assembly.tools;
+    this.plugins = assembly.plugins;
+    this.logger = assembly.logger;
+    this.runtime = assembly.runtime;
+    this.agentContext = assembly.agent_context;
+    this.pluginRegistry = assembly.plugin_registry;
+    this.config = assembly.config;
+    this.env = assembly.env;
+    this.instruction = assembly.instruction;
+
+    this.sessionManager = this.create_session_manager(assembly);
+    session_manager_ref = this.sessionManager;
+    this.lifecycleService = new AgentLifecycleService({
+      logger: this.logger,
+      agent_context: this.agentContext,
+      session_collection: this.sessionManager.get_session_collection(),
+      get_runtime: () => this.runtime,
+    });
+  }
+
+  /**
+   * 新建一个 session。
+   */
+  async createSession(input?: AgentCreateSessionInput): Promise<AgentSession> {
+    return await this.sessionManager.create_session(input);
+  }
+
+  /**
+   * 获取一个已存在的 session。
+   */
+  async getSession(sessionId: string): Promise<AgentSession> {
+    return await this.sessionManager.get_session(sessionId);
+  }
+
+  /**
+   * 列出当前 agent 的 session 摘要页。
+   */
+  async listSessions(
+    input?: AgentListSessionsInput,
+  ): Promise<AgentSessionSummaryPage> {
+    return await this.sessionManager.list_sessions(input);
+  }
+
+  /**
+   * 启动当前 agent 实例的长期运行能力。
+   */
+  async start(options?: AgentStartOptions): Promise<AgentStartResult> {
+    return await this.lifecycleService.start(options);
+  }
+
+  /**
+   * 停止当前 agent 实例的长期运行能力。
+   */
+  async stop(): Promise<AgentStopResult> {
+    return await this.lifecycleService.stop();
+  }
+
+  /**
+   * 更新当前 SDK Agent 的静态基础指令。
+   */
+  setInstruction(input: string | string[]): void {
+    this.instruction = normalizeInstructionInput(input);
+  }
+
+  /**
+   * 返回当前项目根目录解析后的配置快照。
+   */
+  getConfig(): DowncityConfig {
+    return this.config;
+  }
+
+  /**
+   * 返回当前 agent 绑定的统一日志器。
+   */
+  getLogger(): Logger {
+    return this.logger;
+  }
+
+  /**
+   * 返回当前 agent runtime。
+   */
+  getRuntime(): AgentRuntime {
+    return this.runtime;
+  }
+
+  /**
+   * 返回当前 agent context。
+   */
+  getContext(): AgentContext {
+    return this.agentContext;
+  }
+
+  /**
+   * 返回当前 session collection。
+   */
+  getSessionCollection(): AgentSessionCollection {
+    return this.sessionManager.get_session_collection();
+  }
+
+  private create_session_manager(
+    assembly: AgentAssemblyResult,
+  ): AgentSessionManager {
+    return new AgentSessionManager({
+      agent_id: this.id || assembly.id,
+      project_root: this.path || assembly.path,
+      tools: this.tools || assembly.tools,
+      logger: this.logger || assembly.logger,
+      runtime: this.runtime || assembly.runtime,
+      get_agent_context: () => this.agentContext || assembly.agent_context,
+      get_instruction: () => this.instruction,
+      plugin_instances: assembly.plugin_instances,
+      default_model: this.defaultModel,
+      SessionClass: this.SessionClass,
+    });
+  }
+}