@downcity/agent 1.1.79 → 1.1.81

package/src/executor/services/ExecutorRecoveryPolicy.ts

@@ -0,0 +1,213 @@
+/**
+ * ExecutorRecoveryPolicy：执行恢复与重试策略。
+ *
+ * 关键点（中文）
+ * - 统一封装“压缩后重试”和“普通失败兜底”逻辑。
+ * - Executor 只负责准备输入与调用策略，不再直接承载重试状态机。
+ * - 不改变外部行为，只把异常分流规则集中到一个地方。
+ */
+
+import type { LanguageModel } from "ai";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { SessionCompactionComposer } from "@executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionContextComposer } from "@executor/composer/context/SessionContextComposer.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type {
+  SessionExecuteInput,
+  SessionRunResult,
+} from "@/executor/types/SessionRun.js";
+
+/**
+ * 可压缩错误的最大重试次数。
+ */
+const MAX_COMPACTION_RETRY_ATTEMPTS = 3;
+
+interface ExecutorRecoveryPolicyOptions {
+  /**
+   * 当前 session 对应的 compaction Composer。
+   */
+  compaction_composer: SessionCompactionComposer;
+
+  /**
+   * 当前 session 对应的 context Composer。
+   */
+  context_composer: SessionContextComposer;
+
+  /**
+   * 当前 session 统一日志器。
+   */
+  logger: Logger;
+}
+
+interface ExecutorPrepareRunInput {
+  /**
+   * 当前轮用户 query。
+   */
+  query: string;
+
+  /**
+   * 当前轮模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前显式运行上下文。
+   */
+  run_context: SessionRunContext;
+
+  /**
+   * 当前压缩重试次数。
+   */
+  retry_count: number;
+}
+
+interface ExecutorExecutePreparedRunInput {
+  /**
+   * 已装配好的执行输入。
+   */
+  execute_input: SessionExecuteInput;
+
+  /**
+   * 当前轮模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前显式运行上下文。
+   */
+  run_context: SessionRunContext;
+}
+
+interface ExecutorRecoveryRunInput {
+  /**
+   * 当前轮用户 query。
+   */
+  query: string;
+
+  /**
+   * 当前轮模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前显式运行上下文。
+   */
+  run_context: SessionRunContext;
+
+  /**
+   * 运行前装配执行输入。
+   */
+  prepare_execute_input: (
+    input: ExecutorPrepareRunInput,
+  ) => Promise<SessionExecuteInput>;
+
+  /**
+   * 执行已装配好的运行输入。
+   */
+  execute_prepared_run: (
+    input: ExecutorExecutePreparedRunInput,
+  ) => Promise<SessionRunResult>;
+}
+
+/**
+ * 执行恢复与重试策略服务。
+ */
+export class ExecutorRecoveryPolicy {
+  private readonly compaction_composer: SessionCompactionComposer;
+  private readonly context_composer: SessionContextComposer;
+  private readonly logger: Logger;
+  private retry_count = 0;
+
+  constructor(options: ExecutorRecoveryPolicyOptions) {
+    this.compaction_composer = options.compaction_composer;
+    this.context_composer = options.context_composer;
+    this.logger = options.logger;
+  }
+
+  /**
+   * 重置当前 run 级状态。
+   */
+  reset_run_state(): void {
+    this.retry_count = 0;
+  }
+
+  /**
+   * 执行一次带恢复策略的 session run。
+   */
+  async run_with_retry(
+    input: ExecutorRecoveryRunInput,
+  ): Promise<SessionRunResult> {
+    try {
+      const execute_input = await input.prepare_execute_input({
+        query: input.query,
+        model: input.model,
+        run_context: input.run_context,
+        retry_count: this.retry_count,
+      });
+      return await input.execute_prepared_run({
+        execute_input,
+        model: input.model,
+        run_context: input.run_context,
+      });
+    } catch (error) {
+      if (this.compaction_composer.shouldCompactOnError(error)) {
+        await this.logger.log("info", "[agent] compacting", {
+          retryCount: this.retry_count,
+          error: String(error),
+        });
+
+        if (this.retry_count < MAX_COMPACTION_RETRY_ATTEMPTS) {
+          this.retry_count += 1;
+          return await this.run_with_retry(input);
+        }
+
+        return this.build_failure_result({
+          error_text:
+            "Context length exceeded and retries failed. Please resend your question.",
+          fallback_text:
+            "Context length exceeded and retries failed. Please resend your question.",
+          run_context: input.run_context,
+        });
+      }
+
+      const error_text = String(error);
+      await this.logger.log("error", "Executor execution failed", {
+        error: error_text,
+      });
+      return this.build_failure_result({
+        error_text,
+        fallback_text: `Execution failed: ${error_text}`,
+        run_context: input.run_context,
+      });
+    }
+  }
+
+  private build_failure_result(input: {
+    /**
+     * 对外暴露的错误文本。
+     */
+    error_text: string;
+
+    /**
+     * fallback assistant 消息文本。
+     */
+    fallback_text: string;
+
+    /**
+     * 当前显式运行上下文。
+     */
+    run_context: SessionRunContext;
+  }): SessionRunResult {
+    return {
+      success: false,
+      error: input.error_text,
+      assistantMessage: this.context_composer.buildFallbackAssistantMessage(
+        input.fallback_text,
+        input.run_context,
+      ),
+      deferredPersistedUserMessages: [
+        ...input.run_context.deferredPersistedUserMessages,
+      ],
+    };
+  }
+}

package/src/executor/tools/plugin/PluginToolBridge.ts

@@ -0,0 +1,161 @@
+/**
+ * Plugin tool 运行时桥接。
+ *
+ * 关键点（中文）
+ * - tool 层不直接持有 agent 或 plugin registry，只通过装配期注入的 PluginPort 调用 action。
+ * - 如果 action 返回 AI SDK UIMessage，则抽取 file parts 并入最终 assistant 消息。
+ * - 返回给模型的 tool result 只保留短摘要，避免 data URL 等大内容污染上下文。
+ */
+
+import type { FileUIPart } from "ai";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { PluginPort } from "@/plugin/types/Plugin.js";
+import type {
+  PluginCallInput,
+  PluginCallToolResult,
+} from "@/executor/tools/plugin/types/PluginTool.js";
+import { enqueueAssistantFileParts } from "@executor/SessionRunScope.js";
+
+let plugin_tool_runtime: PluginPort | null = null;
+
+/**
+ * 注入 plugin tool 运行时。
+ */
+export function setPluginToolRuntime(next: PluginPort): void {
+  plugin_tool_runtime = next;
+}
+
+/**
+ * 读取已注入的 plugin tool 运行时。
+ */
+function require_plugin_tool_runtime(): PluginPort {
+  if (plugin_tool_runtime) return plugin_tool_runtime;
+  throw new Error(
+    "Plugin tool runtime is not initialized. Ensure agent assembly completed before using plugin_call.",
+  );
+}
+
+/**
+ * 判断值是否为普通对象。
+ */
+function to_json_object(value: unknown): JsonObject | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as JsonObject;
+}
+
+/**
+ * 判断 UI part 是否为 file part。
+ */
+function is_file_part(value: unknown): value is FileUIPart {
+  const record = to_json_object(value);
+  if (!record) return false;
+  return (
+    record.type === "file" &&
+    typeof record.mediaType === "string" &&
+    typeof record.url === "string"
+  );
+}
+
+/**
+ * 从 action data 中抽取可落盘的 assistant file parts。
+ */
+function extract_assistant_file_parts(data: JsonValue | undefined): FileUIPart[] {
+  const message = to_json_object(data);
+  const parts: unknown[] = Array.isArray(message?.parts) ? message.parts : [];
+  return parts.filter(is_file_part);
+}
+
+/**
+ * 生成给模型读取的短摘要。
+ */
+function summarize_action_data(data: JsonValue | undefined): JsonObject {
+  const message = to_json_object(data);
+  const parts: unknown[] = Array.isArray(message?.parts) ? message.parts : [];
+  const file_parts = parts.filter(is_file_part);
+  if (parts.length > 0) {
+    return {
+      kind: "ui_message",
+      role: typeof message?.role === "string" ? message.role : "assistant",
+      part_count: parts.length,
+      file_count: file_parts.length,
+      files: file_parts.map((part, index) => ({
+        index,
+        mediaType: part.mediaType,
+        filename: typeof part.filename === "string" ? part.filename : "",
+        // 关键点（中文）：不把 data URL 或长 URL 原样返回给模型，完整内容只进入 assistant file part。
+        has_url: Boolean(part.url),
+      })),
+    };
+  }
+  if (data === undefined) return {};
+  return {
+    kind: "json",
+    value: data,
+  };
+}
+
+/**
+ * 调用 plugin action 并桥接最终 assistant file parts。
+ */
+export async function invokePluginCallTool(
+  input: PluginCallInput,
+): Promise<PluginCallToolResult> {
+  const plugin = String(input.plugin || "").trim();
+  const action = String(input.action || "").trim();
+  const payload = to_json_object(input.payload ?? {}) ?? {};
+  if (!plugin) {
+    return {
+      success: false,
+      plugin,
+      action,
+      assistant_file_count: 0,
+      message: "plugin is required",
+      error: "plugin is required",
+    };
+  }
+  if (!action) {
+    return {
+      success: false,
+      plugin,
+      action,
+      assistant_file_count: 0,
+      message: "action is required",
+      error: "action is required",
+    };
+  }
+
+  try {
+    const runtime = require_plugin_tool_runtime();
+    const result = await runtime.runAction({
+      plugin,
+      action,
+      payload,
+    });
+    const file_parts = result.success
+      ? extract_assistant_file_parts(result.data)
+      : [];
+    if (file_parts.length > 0) {
+      enqueueAssistantFileParts(file_parts);
+    }
+    return {
+      success: result.success,
+      plugin,
+      action,
+      assistant_file_count: file_parts.length,
+      message:
+        String(result.message || result.error || "").trim() ||
+        (result.success ? "plugin action completed" : "plugin action failed"),
+      ...(result.error ? { error: result.error } : {}),
+      data: summarize_action_data(result.data),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      plugin,
+      action,
+      assistant_file_count: 0,
+      message: String(error),
+      error: String(error),
+    };
+  }
+}

package/src/executor/tools/plugin/PluginToolDefinition.ts

@@ -0,0 +1,32 @@
+/**
+ * Plugin tools。
+ *
+ * 设计目标（中文）
+ * - plugin_call 是 agent 内置 plugin action 桥，类似 shell tool 的底层能力入口。
+ * - tool 只负责 AI SDK 工具协议适配，不理解具体 plugin 的业务语义。
+ * - 插件业务输出若包含 UIMessage file parts，会由 bridge 并入最终 assistant 消息。
+ */
+
+import { tool } from "ai";
+import type { PluginCallInput } from "@/executor/tools/plugin/types/PluginTool.js";
+import { invokePluginCallTool, setPluginToolRuntime } from "./PluginToolBridge.js";
+import { plugin_call_input_schema } from "./PluginToolSchemas.js";
+
+export { setPluginToolRuntime } from "./PluginToolBridge.js";
+
+/**
+ * `plugin_call`：调用已注册 plugin action。
+ */
+export const plugin_call = tool({
+  description:
+    "Call a registered agent plugin action. Use this for plugin capabilities such as image generation. Generated files may be attached to the final assistant message automatically.",
+  inputSchema: plugin_call_input_schema,
+  execute: async (input) => await invokePluginCallTool(input as PluginCallInput),
+});
+
+/**
+ * Plugin 工具导出集合。
+ */
+export const plugin_tools = {
+  plugin_call,
+};

package/src/executor/tools/plugin/PluginToolSchemas.ts

@@ -0,0 +1,20 @@
+/**
+ * Plugin tool 输入 schema。
+ *
+ * 关键点（中文）
+ * - plugin_call 是 agent 内置的最低层 plugin action 桥。
+ * - schema 只描述模型需要提交的目标 plugin、action 与 JSON payload。
+ */
+
+import { z } from "zod";
+
+export const plugin_call_input_schema = z.object({
+  plugin: z.string().describe("Registered plugin name to call, for example image."),
+  action: z.string().describe("Plugin action name to execute, for example generate."),
+  payload: z
+    .object({})
+    .passthrough()
+    .optional()
+    .default({})
+    .describe("JSON payload passed to the plugin action."),
+});

package/src/executor/tools/plugin/types/PluginTool.ts

@@ -0,0 +1,41 @@
+/**
+ * Plugin tool 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里描述模型通过 plugin_call 提交的最低层调用协议。
+ * - payload 保持 JSON 对象，避免 tool 层理解具体 plugin 的业务字段。
+ */
+
+import type { JsonObject } from "@/types/common/Json.js";
+
+/**
+ * plugin_call 输入。
+ */
+export interface PluginCallInput {
+  /** 目标 plugin 名称。 */
+  plugin: string;
+  /** 目标 action 名称。 */
+  action: string;
+  /** 传给 plugin action 的 JSON payload。 */
+  payload?: JsonObject;
+}
+
+/**
+ * plugin_call 返回给模型的摘要结果。
+ */
+export interface PluginCallToolResult {
+  /** 调用是否成功。 */
+  success: boolean;
+  /** 目标 plugin 名称。 */
+  plugin: string;
+  /** 目标 action 名称。 */
+  action: string;
+  /** 本次 action 产生并写入 assistant 消息的 file part 数量。 */
+  assistant_file_count: number;
+  /** 人类可读消息。 */
+  message: string;
+  /** 错误信息。 */
+  error?: string;
+  /** 返回给模型读取的短摘要数据。 */
+  data?: JsonObject;
+}

package/src/executor/tools/shell/ShellToolBridge.ts

@@ -16,7 +16,7 @@ import type { ShellActionResponse } from "@/executor/tools/shell/types/ShellPlug
 import {
   enqueueDeferredPersistedUserMessage,
   enqueueInjectedUserMessage,
-  getSessionRunScope,
+  getSessionRunContext,
 } from "@executor/SessionRunScope.js";
 
 /**
@@ -88,8 +88,8 @@ async function injectUserTextMessage(params: {
    */
   note?: string;
 }): Promise<boolean> {
-  const store = getSessionRunScope();
-  const sessionId = String(store?.sessionId || "").trim();
+  const run_context = getSessionRunContext();
+  const sessionId = String(run_context?.sessionId || "").trim();
   const text = String(params.text || "").trim();
   if (!sessionId || !text) return false;
   const note = String(params.note || "runtime_injected_user_message");

package/src/executor/types/SessionRun.ts

@@ -9,7 +9,9 @@
 
 import type { Tool, UIMessageChunk } from "ai";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**
  * Assistant step 可见性。
@@ -94,6 +96,15 @@ export interface SessionRunResult {
    * 最终 assistant 消息。
    */
   assistantMessage: SessionMessageV1;
+
+  /**
+   * 本轮执行结束后待写入长期历史的 user 消息。
+   *
+   * 关键点（中文）
+   * - 这些消息通常由 tool 运行时在执行过程中动态注入。
+   * - 为保证消息顺序稳定，统一在 assistant 结果落盘后再由外层 Session 持久化。
+   */
+  deferredPersistedUserMessages?: SessionUserMessageV1[];
 }
 
 /**
@@ -104,6 +115,15 @@ export interface SessionRunInput {
    * 本轮用户输入查询文本。
    */
   query: string;
+
+  /**
+   * 本轮显式运行上下文。
+   *
+   * 关键点（中文）
+   * - 这里承载 step 合并、UI chunk 回调等跨组件运行期数据。
+   * - 若未传入，则由执行器按最小默认值兜底创建。
+   */
+  runContext?: SessionRunContext;
 }
 
 /**

package/src/index.ts

@@ -10,6 +10,8 @@
 // Agent 入口
 export { Agent } from "./agent/local/Agent.js";
 export { RemoteAgent } from "./agent/remote/RemoteAgent.js";
+export { Session } from "./session/Session.js";
+export type { SessionOptions } from "./types/session/SessionOptions.js";
 export {
   inferAgentModelLabel,
   normalizeAgentModel,
@@ -17,8 +19,10 @@ export {
 export type {
   AgentSessionCollection,
   AgentModel,
+  AgentManagedSession,
   AgentSessionActor,
   AgentSession,
+  AgentSessionConstructor,
   AgentCreateSessionInput,
   AgentListSessionsInput,
   AgentOptions,
@@ -65,6 +69,7 @@ export type {
 
 // Plugin 作者 API
 export { BasePlugin } from "./plugin/core/BasePlugin.js";
+export { ImagePlugin } from "./plugin/core/ImagePlugin.js";
 
 // Session 与即时执行集成
 export { Executor } from "./executor/Executor.js";
@@ -73,9 +78,27 @@ export {
   getSessionRunScope,
 } from "./executor/SessionRunScope.js";
 export { JsonlSessionHistoryComposer } from "./executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+export { LocalSessionContextComposer } from "./executor/composer/context/LocalSessionContextComposer.js";
 export { JsonlSessionHistoryStore } from "./executor/store/history/jsonl/JsonlSessionHistoryStore.js";
 export { JsonlSessionCompactionComposer } from "./executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
+export type {
+  SessionCompactionComposer,
+  SessionCompactionInput,
+} from "./executor/composer/compaction/SessionCompactionComposer.js";
+export type {
+  SessionContextComposer,
+  SessionContextComposeResult,
+} from "./executor/composer/context/SessionContextComposer.js";
+export type {
+  SessionHistoryComposer,
+  SessionHistoryPrepareInput,
+} from "./executor/composer/history/SessionHistoryComposer.js";
 export type { SessionSystemComposer } from "./executor/composer/system/SessionSystemComposer.js";
+export type {
+  SessionComposerFactoryContext,
+  SessionComposerInput,
+  SessionComposerOptions,
+} from "./types/session/SessionComposerOptions.js";
 export { transformPromptsIntoSystemMessages } from "./executor/composer/system/default/PromptRenderer.js";
 export {
   loadStaticSystemPrompts,
@@ -202,6 +225,16 @@ export type {
 } from "./types/runtime/http/InlineInstant.js";
 
 // Plugin 作者与控制面类型
+export type {
+  ImagePluginContent,
+  ImagePluginFileContent,
+  ImagePluginInput,
+  ImagePluginMessage,
+  ImagePluginOptions,
+  ImagePluginResult,
+  ImagePluginTextContent,
+} from "./types/plugin/ImagePlugin.js";
+
 export type {
   Plugin,
   PluginAction,

package/src/plugin/core/BasePlugin.ts

@@ -55,12 +55,12 @@ export abstract class BasePlugin implements Plugin {
   /**
    * 插件标题。
    */
-  readonly title = "";
+  readonly title: string = "";
 
   /**
    * 插件说明。
    */
-  readonly description = "";
+  readonly description: string = "";
 
   /**
    * 插件配置定义。