@downcity/agent 1.1.408 → 1.1.437

package/src/plugin/core/PluginStateController.ts

@@ -1,19 +0,0 @@
-/**
- * Plugin 注册状态读取模块。
- *
- * 关键点（中文）
- * - 新模型中 plugin 只有注册 / 卸载，不再暴露 start / stop / restart。
- * - 控制动作与类型协议保持一致，只支持状态查询和卸载。
- */
-
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
-
-/**
- * 列出当前 Agent 已注册 plugin 快照。
- */
-export function list_plugin_states(input?: {
-  context?: PluginContext;
-}): PluginSnapshot[] {
-  return input?.context?.plugins.snapshots() || [];
-}

package/src/plugin/tool/PluginToolRuntime.ts

@@ -1,124 +0,0 @@
-/**
- * Plugin Tool 运行时。
- *
- * 关键点（中文）
- * - Plugin Action 自己完成业务输出和本地文件保存。
- * - 本模块不猜测 `data` 是否为 UIMessage，也不下载、复制或挂载文件。
- * - Action 的普通字段成为 `plugin_call` output，messages 交给统一 Session Tool 边界。
- */
-
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { ActionResult } from "@/types/action/ActionResult.js";
-import type {
-  PluginCallInput,
-  PluginCallToolResult,
-  InvokePluginCallToolOptions,
-  InvokePluginReadToolOptions,
-  PluginReadInput,
-  PluginReadToolResult,
-} from "@/types/plugin/PluginTool.js";
-
-/** 判断值是否为普通 JSON 对象。 */
-function to_json_object(value: unknown): JsonObject | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value as JsonObject;
-}
-
-/** 调用 Plugin Action，并把 Action messages 原样交给统一 Tool Result。 */
-export async function invoke_plugin_call_tool(
-  params: InvokePluginCallToolOptions,
-): Promise<ActionResult<PluginCallToolResult>> {
-  const input: PluginCallInput = params.input;
-  const plugin = String(input.plugin || "").trim();
-  const action = String(input.action || "").trim();
-  const payload = to_json_object(input.payload ?? {}) ?? {};
-  if (!plugin || !action) {
-    const error = !plugin ? "plugin is required" : "action is required";
-    return {
-      output: {
-        success: false,
-        plugin,
-        action,
-        message: error,
-        error,
-      },
-      messages: [],
-    };
-  }
-
-  try {
-    const turn_context = params.turn_context;
-    const plugins = turn_context.step.plugins || params.plugins;
-    const result = await plugins.run_action({
-      plugin,
-      action,
-      payload,
-      execution_context: turn_context.step.plugin_execution_context(params.call_id),
-      ...(turn_context.interactions
-        ? { interactions: turn_context.interactions }
-        : {}),
-    });
-    return {
-      output: {
-        success: result.success,
-        plugin,
-        action,
-        message:
-          String(result.message || result.error || "").trim() ||
-          (result.success ? "plugin action completed" : "plugin action failed"),
-        ...(result.error ? { error: result.error } : {}),
-        ...(result.data === undefined
-          ? {}
-          : {
-              data: to_json_object(result.data) || {
-                kind: "json",
-                value: result.data as JsonValue,
-              },
-            }),
-      },
-      messages: result.messages || [],
-    };
-  } catch (error) {
-    return {
-      output: {
-        success: false,
-        plugin,
-        action,
-        message: String(error),
-        error: String(error),
-      },
-      messages: [],
-    };
-  }
-}
-
-/** 读取 Plugin metadata，并作为普通 JSON Tool Result 返回。 */
-export async function invoke_plugin_read_tool(
-  params: InvokePluginReadToolOptions,
-): Promise<ActionResult<PluginReadToolResult>> {
-  const input: PluginReadInput = params.input;
-  try {
-    const plugins = params.turn_context.step.plugins || params.plugins;
-    const data = plugins.read({
-      plugin: typeof input.plugin === "string" ? input.plugin : undefined,
-      action: typeof input.action === "string" ? input.action : undefined,
-    });
-    return {
-      output: {
-        success: true,
-        message: "plugin metadata read",
-        data: data as unknown as JsonObject,
-      },
-      messages: [],
-    };
-  } catch (error) {
-    return {
-      output: {
-        success: false,
-        message: String(error),
-        data: { error: String(error) },
-      },
-      messages: [],
-    };
-  }
-}

package/src/plugin/tool/PluginToolSchemas.ts

@@ -1,44 +0,0 @@
-/**
- * Plugin tool 输入 schema。
- *
- * 关键点（中文）
- * - plugin_call 是 agent 内置的最低层 plugin action 入口。
- * - plugin_call.payload 是透传给具体 plugin action 的 JSON object。
- * - 这里不用 Zod 表达 payload 的开放对象语义，避免 JSON Schema
- *   转换后把 additionalProperties 收窄为 false。
- */
-
-import { z } from "zod";
-
-export const plugin_call_input_schema = {
-  type: "object",
-  required: ["plugin", "action"],
-  additionalProperties: false,
-  properties: {
-    plugin: {
-      type: "string",
-      description: "Registered plugin name to call, for example image.",
-    },
-    action: {
-      type: "string",
-      description: "Plugin action name to execute, for example image_create.",
-    },
-    payload: {
-      type: "object",
-      additionalProperties: true,
-      default: {},
-      description: "JSON payload passed to the plugin action.",
-    },
-  },
-};
-
-export const plugin_read_input_schema = z.object({
-  plugin: z
-    .string()
-    .optional()
-    .describe("Registered plugin name to inspect. Omit to list plugins."),
-  action: z
-    .string()
-    .optional()
-    .describe("Plugin action name to inspect. Requires plugin."),
-});

package/src/plugin/tool/PluginTools.ts

@@ -1,92 +0,0 @@
-/**
- * Plugin 运行时工具。
- *
- * 设计目标（中文）
- * - plugin_call 是 agent 内置 plugin action 的底层能力入口。
- * - tool 只负责 Downcity Runtime Tool 协议适配，不理解具体 plugin 的业务语义。
- * - Plugin Action 返回的 messages 由 Executor 的统一 ActionResult 边界分流。
- */
-
-import {
-  define_runtime_tool,
-  type RuntimeToolExecutionOptions as ToolExecutionOptions,
-} from "@downcity/type";
-import type {
-  AgentPluginTools,
-  CreatePluginToolsOptions,
-  PluginCallInput,
-  PluginReadInput,
-} from "@/types/plugin/PluginTool.js";
-import {
-  invoke_plugin_call_tool,
-  invoke_plugin_read_tool,
-} from "./PluginToolRuntime.js";
-import {
-  plugin_call_input_schema,
-  plugin_read_input_schema,
-} from "./PluginToolSchemas.js";
-import type { SessionToolExecutionContext } from "@/types/executor/SessionToolExecutionContext.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
-
-/**
- * 要求当前 plugin tool 具有 Executor 显式绑定的 Session 上下文。
- */
-function require_turn_context(
-  options: ToolExecutionOptions,
-): SessionTurnContext {
-  const execution_context = options.context as
-    | Partial<SessionToolExecutionContext>
-    | undefined;
-  const turn_context = execution_context?.session_turn_context;
-  if (!turn_context) {
-    throw new Error("plugin tool requires an explicit Session Turn context");
-  }
-  return turn_context;
-}
-
-/**
- * 创建 `plugin_call`：调用当前 Agent 已注册 plugin action。
- */
-export function create_plugin_call_tool(options: CreatePluginToolsOptions) {
-  return define_runtime_tool<PluginCallInput>({
-    description:
-      "Call a registered agent plugin action. Use plugin_read first when you need the action list, input schema, or examples. Generated files may be attached to the final assistant message automatically.",
-    input_schema: plugin_call_input_schema,
-    execute: async (input, execution_options) =>
-      await invoke_plugin_call_tool({
-        plugins: options.plugins,
-        turn_context: require_turn_context(execution_options),
-        call_id: String(execution_options.tool_call_id || "").trim(),
-        input: input as PluginCallInput,
-      }),
-  });
-}
-
-/**
- * 创建 `plugin_read`：读取当前 Agent 已注册 plugin / action metadata。
- */
-export function create_plugin_read_tool(options: CreatePluginToolsOptions) {
-  return define_runtime_tool<PluginReadInput>({
-    description:
-      "Read registered agent plugin metadata, including action names, descriptions, input schemas, and examples. Use this before plugin_call when the payload shape is unclear.",
-    input_schema: plugin_read_input_schema,
-    execute: async (input, execution_options) =>
-      await invoke_plugin_read_tool({
-        plugins: options.plugins,
-        turn_context: require_turn_context(execution_options),
-        input: input as PluginReadInput,
-      }),
-  });
-}
-
-/**
- * 创建当前 Agent 专属 Plugin 工具集合。
- */
-export function create_plugin_tools(
-  options: CreatePluginToolsOptions,
-): AgentPluginTools {
-  return {
-    plugin_call: create_plugin_call_tool(options),
-    plugin_read: create_plugin_read_tool(options),
-  };
-}

package/src/plugin/types/ActionSchedule.ts

@@ -1,100 +0,0 @@
-/**
- * ActionSchedule：plugin action 延迟执行能力的共享类型。
- *
- * 关键点（中文）
- * - 这里描述的是“某个 plugin action 在未来某个时间执行”的通用记录。
- * - 它不是独立 Plugin，也不表达业务语义，只服务于 Plugin Action 调度。
- * - 外部请求字段仍可叫 `schedule`，但内部类型统一归入 ActionSchedule 模块。
- */
-
-import type { JsonValue } from "@/types/common/Json.js";
-
-/**
- * ActionSchedule 任务状态。
- */
-export type ActionScheduleJobStatus =
-  | "pending"
-  | "running"
-  | "succeeded"
-  | "failed"
-  | "cancelled";
-
-/**
- * ActionSchedule 任务完整记录。
- */
-export interface ActionScheduleJobRecord {
-  /**
-   * ActionSchedule 任务唯一 ID。
-   */
-  id: string;
-  /** 执行该任务的 Agent 稳定标识。 */
-  agent_id: string;
-  /** 任务所属 Workspace 的稳定标识。 */
-  workspace_id?: string;
-  /**
-   * 目标 plugin 名称。
-   */
-  plugin_name: string;
-  /**
-   * 目标 action 名称。
-   */
-  action_name: string;
-  /**
-   * 原始 action payload。
-   */
-  payload: JsonValue;
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   */
-  run_at_ms: number;
-  /**
-   * 当前任务状态。
-   */
-  status: ActionScheduleJobStatus;
-  /**
-   * 最近一次错误文本。
-   */
-  error?: string;
-  /**
-   * 创建时间（毫秒时间戳）。
-   */
-  created_at: number;
-  /**
-   * 最近更新时间（毫秒时间戳）。
-   */
-  updated_at: number;
-}
-
-/**
- * 创建 ActionSchedule 任务所需输入。
- */
-export interface CreateActionScheduleJobInput {
-  /** 任务执行时解析 PluginContext 所需的 Workspace 稳定标识；省略时使用当前活动 Workspace。 */
-  workspace_id: string;
-  /**
-   * 目标 plugin 名称。
-   */
-  plugin_name: string;
-  /**
-   * 目标 action 名称。
-   */
-  action_name: string;
-  /**
-   * 目标 action payload。
-   */
-  payload: JsonValue;
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   */
-  run_at_ms: number;
-}
-
-/**
- * 统一 plugin action 延迟执行输入。
- */
-export interface PluginActionScheduleInput {
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   */
-  run_at_ms: number;
-}

package/src/plugin/types/PluginApi.ts

@@ -1,86 +0,0 @@
-/**
- * plugin catalog / availability / action API 类型。
- *
- * 关键点（中文）
- * - 统一描述 downcity CLI -> Agent runtime 的 plugin 管理协议。
- * - 当前阶段支持 list / availability / action 三类调用。
- */
-
-import type { JsonValue } from "@/types/common/Json.js";
-import type {
-  PluginAvailability,
-  PluginView,
-} from "@/types/plugin/PluginRuntime.js";
-
-export type { PluginView } from "@/types/plugin/PluginRuntime.js";
-export type PluginAvailabilityView = PluginAvailability;
-
-/**
- * plugin catalog 响应。
- */
-export interface PluginCatalogResponse {
-  /**
-   * 请求是否成功。
-   */
-  success: boolean;
-  /**
-   * Plugin 列表（可选）。
-   */
-  plugins?: PluginView[];
-  /**
-   * 错误信息（可选）。
-   */
-  error?: string;
-}
-
-/**
- * plugin availability 响应。
- */
-export interface PluginAvailabilityResponse {
-  /**
-   * 请求是否成功。
-   */
-  success: boolean;
-  /**
-   * Plugin 名称（可选）。
-   */
-  plugin_name?: string;
-  /**
-   * Plugin 可用性视图（可选）。
-   */
-  availability?: PluginAvailabilityView;
-  /**
-   * 错误信息（可选）。
-   */
-  error?: string;
-}
-
-/**
- * plugin action 响应。
- */
-export interface PluginActionResponse {
-  /**
-   * Action 是否成功。
-   */
-  success: boolean;
-  /**
-   * Plugin 名称（可选）。
-   */
-  plugin_name?: string;
-  /**
-   * Action 名称（可选）。
-   */
-  action_name?: string;
-  /**
-   * 返回数据（可选）。
-   */
-  data?: JsonValue;
-  /**
-   * 人类可读消息（可选）。
-   */
-  message?: string;
-  /**
-   * 错误信息（可选）。
-   */
-  error?: string;
-}

package/src/remote/RemoteAgent.ts

@@ -1,130 +0,0 @@
-/**
- * RemoteAgent：统一远程 SDK 客户端。
- *
- * 关键点（中文）
- * - 对外只暴露一个 `url` 入口，不向用户暴露 transport 细节。
- * - 当前内部支持 `http/https` 与 `rpc` 两种访问方式。
- * - `RemoteAgent` 只负责远程访问，不重复实现第二套会话编排器。
- */
-
-import type {
-  AgentArchiveSessionInput,
-  AgentArchiveSessionsInput,
-  AgentArchiveSessionResult,
-  AgentArchiveSessionsResult,
-  AgentCleanArchiveResult,
-  AgentCreateSessionInput,
-  AgentListSessionsInput,
-  AgentSessionSummaryPage,
-} from "@/types/agent/SessionTypes.js";
-import type { AgentSessions, RemoteAgentSession } from "@/types/agent/SessionActor.js";
-import type { RemoteAgentOptions } from "@/types/agent/RemoteAgentOptions.js";
-import type {
-  RemoteAgentPluginActionInput,
-  RemoteAgentPluginActionResult,
-} from "@/types/agent/RemoteAgentPluginAction.js";
-import type { RemoteAgentTransport } from "@/remote/RemoteTransport.js";
-import { RemoteSession } from "@/remote/RemoteSession.js";
-import { create_remote_agent_transport } from "@/remote/TransportFactory.js";
-
-/**
- * RemoteAgent：远程 Agent 客户端。
- */
-export class RemoteAgent {
-  readonly sessions: AgentSessions<RemoteAgentSession>;
-
-  private readonly transport: RemoteAgentTransport;
-
-  constructor(options: RemoteAgentOptions) {
-    const url = String(options.url || "").trim();
-    if (!url) {
-      throw new Error("RemoteAgent requires a non-empty url");
-    }
-    this.transport = create_remote_agent_transport(url, options.token);
-    this.sessions = new RemoteAgentSessions(this.transport);
-  }
-
-  /**
-   * 执行远程 Agent runtime 内的 plugin action。
-   *
-   * 关键点（中文）
-   * - 这是 RemoteAgent 顶层能力，不绑定某个 session。
-   * - Shell approval 通过具体 RemoteSession 处理。
-   */
-  async run_plugin_action(
-    input: RemoteAgentPluginActionInput,
-  ): Promise<RemoteAgentPluginActionResult> {
-    const plugin = String(input.plugin || "").trim();
-    const action = String(input.action || "").trim();
-    if (!plugin) {
-      throw new Error("run_plugin_action requires a non-empty plugin");
-    }
-    if (!action) {
-      throw new Error("run_plugin_action requires a non-empty action");
-    }
-    return await this.transport.run_plugin_action({
-      plugin,
-      action,
-      ...(input.payload !== undefined ? { payload: input.payload } : {}),
-    });
-  }
-
-  /**
-   * 关闭远程 transport。
-   *
-   * 关键点（中文）
-   * - `rpc://` 会关闭底层长连接。
-   * - `http://` / `https://` 没有常驻连接，调用时是安全 no-op。
-   */
-  async close(): Promise<void> {
-    await this.transport.close?.();
-  }
-
-}
-
-/**
- * 远程 Agent session 集合入口。
- *
- * 关键点（中文）
- * - `RemoteAgentTransport` 只负责协议传输，不直接暴露为用户 SDK API。
- * - 这里把远程传输包装成和本地 `agent.sessions` 一致的方法命名。
- */
-class RemoteAgentSessions implements AgentSessions<RemoteAgentSession> {
-  private readonly transport: RemoteAgentTransport;
-
-  constructor(transport: RemoteAgentTransport) {
-    this.transport = transport;
-  }
-
-  /** 新建一个远程 session。 */
-  async create(input?: AgentCreateSessionInput): Promise<RemoteAgentSession> {
-    const info = await this.transport.create_session(input);
-    return new RemoteSession(this.transport, info);
-  }
-
-  /** 获取一个远程 session。 */
-  async get(session_id: string): Promise<RemoteAgentSession> {
-    const info = await this.transport.get_info(session_id);
-    return new RemoteSession(this.transport, info);
-  }
-
-  /** 列出远程 session 摘要页。 */
-  async list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
-    return await this.transport.list_sessions(input);
-  }
-
-  /** 归档一个远程 session。 */
-  async archive(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult> {
-    return await this.transport.archive_session(input);
-  }
-
-  /** 列出远程已归档 session。 */
-  async archived(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult> {
-    return await this.transport.archive_sessions(input);
-  }
-
-  /** 永久清空远程已归档 session。 */
-  async clean_archive(): Promise<AgentCleanArchiveResult> {
-    return await this.transport.clean_archive();
-  }
-}