@downcity/agent 1.1.208 → 1.1.212

package/src/session/runtime/SessionPromptRuntime.ts

@@ -98,6 +98,21 @@ export interface SessionPromptRuntimeOptions {
     input: AgentSessionPromptInput,
   ) => Promise<SessionUserMessageV1>;
 
+  /**
+   * 在 steer message 成功持久化后发送对应 action。
+   */
+  emit_steer_action: (input: {
+    /**
+     * steer message 所属的当前 turn 标识。
+     */
+    turn_id: string;
+
+    /**
+     * 已成功持久化的 steer message。
+     */
+    message: SessionUserMessageV1;
+  }) => Promise<void>;
+
   /**
    * 执行单轮 turn。
    */
@@ -126,6 +141,7 @@ export class SessionPromptRuntime {
   private readonly sessionId: string;
   private readonly publish: SessionPromptRuntimeOptions["publish"];
   private readonly createAndPersistUserMessage: SessionPromptRuntimeOptions["createAndPersistUserMessage"];
+  private readonly emit_steer_action: SessionPromptRuntimeOptions["emit_steer_action"];
   private readonly executeTurn: SessionPromptRuntimeOptions["executeTurn"];
   private readonly stopTurn: SessionPromptRuntimeOptions["stopTurn"];
   private readonly queue: QueuedPrompt[] = [];
@@ -136,6 +152,7 @@ export class SessionPromptRuntime {
     this.sessionId = String(options.sessionId || "").trim();
     this.publish = options.publish;
     this.createAndPersistUserMessage = options.createAndPersistUserMessage;
+    this.emit_steer_action = options.emit_steer_action;
     this.executeTurn = options.executeTurn;
     this.stopTurn = options.stopTurn;
     if (!this.sessionId) {
@@ -329,12 +346,20 @@ export class SessionPromptRuntime {
     const merged: SessionUserMessageV1[] = [];
 
     for (let index = 0; index < drained.length; index += 1) {
-        const item = drained[index];
+      const item = drained[index];
+      try {
+        const message = await this.createAndPersistUserMessage(item.input);
+        item.deferredHandle.resolve(createTurnHandle(activeTurn));
+        merged.push(message);
         try {
-          const message = await this.createAndPersistUserMessage(item.input);
-          item.deferredHandle.resolve(createTurnHandle(activeTurn));
-          merged.push(message);
+          await this.emit_steer_action({
+            turn_id: activeTurn.turnId,
+            message,
+          });
         } catch {
+          // action 发送失败不应阻断已经持久化的 steer message。
+        }
+      } catch {
         // 关键点（中文）：若某条消息持久化失败，把未处理部分重新放回队列头部，避免静默丢失。
         const remaining = drained.slice(index);
         this.queue.unshift(...remaining);

package/src/session/services/SessionStateService.ts

@@ -15,9 +15,9 @@ import {
   patchSessionModelLabel,
   readSessionMetadata,
   resolveSystemTimezone,
-  touchSessionMetadata,
   writeSessionMetadata,
-} from "@/session/index.js";
+} from "@/session/storage/Metadata.js";
+import { touchSessionMetadata } from "@/session/storage/Persistence.js";
 import { ensureSessionTitle } from "@/session/SessionTitle.js";
 import { persistSdkAssistantResult } from "@/session/storage/Persistence.js";
 import { hydrateUserPromptFileParts } from "@executor/messages/SessionAttachmentMapper.js";
@@ -26,7 +26,7 @@ import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/Js
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionSetInput,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
 import type {
   AgentSessionEvent,
 } from "@/types/sdk/AgentSessionEvent.js";
@@ -259,7 +259,6 @@ export class SessionStateService {
       if (input.model) {
         this.state.sessionConfig.model = normalizeAgentModel(input.model);
         this.state.sessionConfig.modelLabel = next_model_label;
-        this.executor.clearExecutor();
       }
       await patchSessionModelLabel({
         projectRoot: this.project_root,

package/src/session/services/SessionTurnService.ts

@@ -83,6 +83,15 @@ export class SessionTurnService {
           input,
         );
       },
+      emit_steer_action: async ({ turn_id, message }) => {
+        await this.state_service.emit_action_event({
+          id: `steer-message:${message.id}`,
+          title: "Session steer message sent",
+          description: "Merged a new user message into the active turn.",
+          state: "completed",
+          turnId: turn_id,
+        });
+      },
       executeTurn: async ({ turnId, promptInput, onStepMerge, abortSignal }) => {
         return await this.execute_prompt_turn({
           turnId,

package/src/session/services/SessionViewService.ts

@@ -11,11 +11,11 @@ import { nanoid } from "nanoid";
 import {
   buildSessionRecordsPage,
   buildSessionInfo,
-  getSdkAgentSessionArchiveFilePath,
-  ensureSessionTitle,
   loadSessionArchiveMessagesFromPath,
-  readSessionMetadata,
-} from "@/session/index.js";
+} from "@/session/browse/Browse.js";
+import { getSdkAgentSessionArchiveFilePath } from "@/session/storage/Paths.js";
+import { ensureSessionTitle } from "@/session/SessionTitle.js";
+import { readSessionMetadata } from "@/session/storage/Metadata.js";
 import { buildSessionSystemBlocks } from "@/session/SessionSystemBuilder.js";
 import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
 import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
@@ -24,10 +24,10 @@ import type {
   AgentSessionRecordsInput,
   AgentSessionRecordsPage,
   AgentSessionInfo,
-  AgentSession,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
+import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 import { SessionStateService } from "@/session/services/SessionStateService.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";

package/src/session/storage/Metadata.ts

@@ -56,6 +56,23 @@ function normalizeTimezone(input: unknown): string | undefined {
   return timezone || undefined;
 }
 
+function normalize_message_count(input: unknown): number | undefined {
+  return typeof input === "number" && Number.isInteger(input) && input >= 0
+    ? input
+    : undefined;
+}
+
+function normalize_preview_text(input: unknown): string | undefined {
+  const preview_text = typeof input === "string" ? input.trim() : "";
+  return preview_text || undefined;
+}
+
+function normalize_history_bytes(input: unknown): number | undefined {
+  return typeof input === "number" && Number.isInteger(input) && input >= 0
+    ? input
+    : undefined;
+}
+
 /**
  * 从模型实例推导轻量可读标签。
  */
@@ -136,6 +153,15 @@ export async function readSessionMetadataFromPath(input: {
       ...(normalizeModelLabel(raw.modelLabel)
         ? { modelLabel: normalizeModelLabel(raw.modelLabel) }
         : {}),
+      ...(normalize_message_count(raw.messageCount) !== undefined
+        ? { messageCount: normalize_message_count(raw.messageCount) }
+        : {}),
+      ...(normalize_preview_text(raw.previewText)
+        ? { previewText: normalize_preview_text(raw.previewText) }
+        : {}),
+      ...(normalize_history_bytes(raw.historyBytes) !== undefined
+        ? { historyBytes: normalize_history_bytes(raw.historyBytes) }
+        : {}),
     };
   } catch {
     return {

package/src/session/storage/Persistence.ts

@@ -13,7 +13,7 @@ import type {
   SessionMessageRecordV1,
 } from "@/executor/types/SessionRecords.js";
 import { persistAssistantResult } from "@/executor/messages/AssistantResultPersistence.js";
-import type { AgentSessionConfigSnapshot } from "@/types/agent/AgentTypes.js";
+import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
 import {
   readSessionMetadata,
   writeSessionMetadata,

package/src/session/storage/RuntimeSessionPort.ts

@@ -47,14 +47,6 @@ export interface CreateRuntimeSessionPortParams {
    * 发布一条 session runtime 事件。
    */
   publishEvent: (event: AgentSessionEvent) => void;
-  /**
-   * 清理当前 session executor 状态。
-   */
-  clearExecutor: () => void;
-  /**
-   * session 更新后的异步通知回调。
-   */
-  afterSessionUpdatedAsync: () => Promise<void>;
   /**
    * 追加 user 消息到底层历史。
    */
@@ -75,10 +67,6 @@ export interface CreateRuntimeSessionPortParams {
    * 在执行前确保当前 session 已完成初始化与宿主级配置。
    */
   ensureReadyForExecution: () => Promise<void>;
-  /**
-   * session 更新后需要同步执行的持久化回调。
-   */
-  touchMetadata: () => Promise<void>;
 }
 
 /**
@@ -105,19 +93,11 @@ export function createRuntimeSessionPort(
     publishEvent: (event) => {
       params.publishEvent(event);
     },
-    clearExecutor: () => {
-      params.clearExecutor();
-    },
-    afterSessionUpdatedAsync: async () => {
-      await params.afterSessionUpdatedAsync();
-    },
     append_user_message: async (messageParams) => {
       await params.append_user_message(messageParams);
-      await params.touchMetadata();
     },
     append_assistant_message: async (messageParams) => {
       await params.append_assistant_message(messageParams);
-      await params.touchMetadata();
     },
     isExecuting: () => params.isExecuting(),
   };

package/src/types/plugin/PluginAction.ts

@@ -139,14 +139,6 @@ export interface PluginAction<
   P extends JsonValue = JsonValue,
   R extends JsonValue = JsonValue,
 > extends PluginActionMetadata<P> {
-  /**
-   * disabled 状态下是否仍允许执行。
-   *
-   * 说明（中文）
-   * - 用于 `on` / `status` / `models` / `configure` / `install` 这类 setup 相关 action。
-   * - 默认 false，避免 disabled plugin 绕过 registry 保护执行普通业务 action。
-   */
-  allowWhenDisabled?: boolean;
   /** CLI 定义（可选）。 */
   command?: PluginActionCommand<P>;
   /** HTTP 定义（可选）。 */
@@ -155,8 +147,6 @@ export interface PluginAction<
   execute: (params: {
     /** 当前执行上下文。 */
     context: AgentContext;
-    /** 输入 payload。 */
-    payload: P;
     /** 已通过 schema 校验后的输入。 */
     input: P;
     /** 当前插件名称。 */

package/src/types/plugin/PluginCommand.ts

@@ -71,11 +71,10 @@ export interface PluginCommandResult {
 }
 
 /**
- * Plugin 生命周期兼容定义。
+ * Plugin 生命周期定义。
  *
  * 关键点（中文）
- * - 这是从旧运行生命周期过渡过来的兼容层。
- * - 新代码优先直接实现 `start/stop/command`。
+ * - 生命周期只描述 plugin 启动、停止和非 action 命令处理。
  */
 export interface PluginLifecycle {
   /** plugin 启动钩子。 */

package/src/types/plugin/PluginControl.ts

@@ -0,0 +1,80 @@
+/**
+ * Plugin 控制面协议类型。
+ *
+ * 关键点（中文）
+ * - CLI、HTTP 与 RPC 共用同一套 plugin 控制请求和响应结构。
+ * - 状态数据统一复用 `PluginSnapshot`，不再复制字段或保留旧别名。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+import type { PluginControlAction, PluginSnapshot } from "@/types/plugin/PluginState.js";
+
+export type { PluginControlAction } from "@/types/plugin/PluginState.js";
+
+/**
+ * plugin 状态列表响应。
+ */
+export type PluginStateListResponse = {
+  /** 请求是否成功。 */
+  success: boolean;
+  /** 当前已注册 plugin 快照。 */
+  plugins?: PluginSnapshot[];
+  /** 失败原因。 */
+  error?: string;
+};
+
+/**
+ * 单个 plugin 控制响应。
+ */
+export type PluginControlResponse = {
+  /** 请求是否成功。 */
+  success: boolean;
+  /** 当前 plugin 快照。 */
+  plugin?: PluginSnapshot;
+  /** 失败原因。 */
+  error?: string;
+};
+
+/**
+ * plugin command/action 执行响应。
+ */
+export type PluginCommandResponse = {
+  /** 调用是否成功。 */
+  success: boolean;
+  /** 当前 plugin 快照。 */
+  plugin?: PluginSnapshot;
+  /** 人类可读结果。 */
+  message?: string;
+  /** 结构化结果。 */
+  data?: JsonValue;
+  /** 失败原因。 */
+  error?: string;
+};
+
+/**
+ * plugin CLI 通用选项。
+ */
+export type PluginCliBaseOptions = {
+  /** agent 项目路径。 */
+  path?: string;
+  /** 目标 agent 标识。 */
+  agent?: string;
+  /** HTTP 主机。 */
+  host?: string;
+  /** HTTP 端口。 */
+  port?: number;
+  /** 控制面认证令牌。 */
+  token?: string;
+  /** 是否输出 JSON。 */
+  json?: boolean;
+};
+
+/**
+ * plugin 控制请求。
+ */
+export type PluginControlRequest = {
+  /** 目标 plugin 名称。 */
+  plugin_name: string;
+  /** 控制动作。 */
+  action: PluginControlAction;
+};

package/src/types/plugin/PluginDefinition.ts

@@ -63,7 +63,7 @@ export interface Plugin {
   resolves?: PluginResolves;
   /** Plugin system 文本构建器（可选）。 */
   system?: (context: AgentContext) => string | Promise<string>;
-  /** 旧生命周期兼容定义（可选）。 */
+  /** Plugin 生命周期定义（可选）。 */
   lifecycle?: PluginLifecycle;
   /** Plugin 可用性检查器（可选）。 */
   availability?: (

package/src/types/plugin/PluginRuntime.ts

@@ -14,7 +14,7 @@ import type { JsonValue } from "@/types/common/Json.js";
 import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
 import type { PluginActionExample } from "@/types/plugin/PluginAction.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type { AgentSessionSystemBlock } from "@/types/agent/AgentTypes.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
 
 /**
@@ -57,8 +57,6 @@ export interface PluginActionReadView {
   input_schema?: JsonValue;
   /** Action 调用示例。 */
   examples?: PluginActionExample[];
-  /** disabled 状态下是否仍允许执行。 */
-  allow_when_disabled: boolean;
   /** 是否声明 CLI command。 */
   has_command: boolean;
   /** 是否声明 HTTP API。 */

package/src/types/plugin/PluginState.ts

@@ -46,40 +46,23 @@ export interface PluginSnapshot {
   description: string;
   /** 当前注册后的可用状态。 */
   status: PluginState;
-  /** 兼容旧字段的状态别名。 */
-  state: PluginState;
   /** 注册时间（毫秒时间戳）。 */
   registered_at: number;
   /** 最近更新时间（毫秒时间戳）。 */
   updated_at: number;
-  /** 兼容旧字段的最近更新时间。 */
-  updatedAt: number;
   /** 最近错误。 */
   last_error?: string;
-  /** 兼容旧字段的最近错误。 */
-  lastError?: string;
 }
 
 /**
- * 兼容旧名称的 plugin 快照类型。
- */
-export type PluginStateSnapshot = PluginSnapshot;
-
-/**
- * 兼容旧控制动作类型。
- *
- * 说明（中文）
- * - 控制面只保留状态查询与卸载。
+ * Plugin 控制动作。
  */
-export type PluginStateControlAction =
-  | "register"
-  | "unregister"
-  | "status";
+export type PluginControlAction = "unregister" | "status";
 
 /**
  * plugin 控制结果。
  */
-export interface PluginStateControlResult {
+export interface PluginControlResult {
   /** 控制动作是否成功。 */
   success: boolean;
   /** 成功或失败后返回的最新 plugin 快照。 */

package/src/types/rpc/RpcProtocol.ts

@@ -16,13 +16,13 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionRecordsInput,
-  AgentSessionStopResult,
   AgentSessionSystemSnapshot,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { PluginStateControlAction } from "@/plugin/types/Plugin.js";
+import type { PluginControlAction } from "@/types/plugin/PluginState.js";
 import type { ShellApprovalMode } from "@downcity/shell";
 
 /**
@@ -229,7 +229,7 @@ export type RpcRequest =
         /** plugin 名称。 */
         pluginName: string;
         /** 控制动作。 */
-        action: PluginStateControlAction;
+        action: PluginControlAction;
       };
     }
   | {

package/src/types/runtime/agent/AgentContext.ts

@@ -15,7 +15,7 @@ import type {
 } from "@/types/agent/AgentRuntimeAssembly.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonValue } from "@/types/common/Json.js";
-import type { AgentPlugins } from "@/plugin/types/Plugin.js";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type {
   SessionMetadataV1,
@@ -144,14 +144,6 @@ export interface SessionPort {
    * - 历史消息持久化仍由 append_user_message / append_assistant_message 负责。
    */
   publishEvent(event: AgentSessionEvent): void;
-  /**
-   * 清理当前 session 的 executor 缓存。
-   */
-  clearExecutor(): void;
-  /**
-   * 当前 session 更新后的异步通知钩子。
-   */
-  afterSessionUpdatedAsync(): Promise<void>;
   /**
    * 追加一条 user 消息。
    */

package/src/types/session/SessionLocalState.ts

@@ -7,7 +7,7 @@
  * - 这里只保存运行态，不承载行为逻辑。
  */
 
-import type { AgentSessionConfigSnapshot } from "@/types/agent/AgentTypes.js";
+import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
 
 /**
  * 本地 Session 内存状态。