@downcity/agent 1.1.408 → 1.1.437

package/src/types/plugin/PluginAction.ts

@@ -1,178 +0,0 @@
-/**
- * Plugin action 类型。
- *
- * 关键点（中文）
- * - action 是 plugin 对外暴露的显式能力。
- * - CLI / HTTP 只是 action 的输入适配层，真正执行器统一走 `execute`。
- */
-
-import type { Command } from "commander";
-import type { Context as HonoContext } from "hono";
-import type { z } from "zod";
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { PluginActionExecutionContext } from "@/types/plugin/PluginActionExecution.js";
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { ActionResultMessage } from "@/types/action/ActionResult.js";
-
-/**
- * Plugin action 调用参数。
- */
-export interface PluginActionInvokeParams {
-  /** 目标 plugin 名称。 */
-  plugin: string;
-  /** 目标 action 名称。 */
-  action: string;
-  /** 调用 payload（可选）。 */
-  payload?: JsonValue;
-}
-
-/**
- * Plugin action 调用结果。
- */
-export interface PluginActionInvokeResult {
-  /** 调用是否成功。 */
-  success: boolean;
-  /** 结构化返回数据（可选）。 */
-  data?: JsonValue;
-  /** 错误信息（可选）。 */
-  error?: string;
-}
-
-/**
- * Plugin action 调用端口。
- */
-export interface PluginActionInvokePort {
-  /** 调用指定 plugin action。 */
-  invoke(
-    params: PluginActionInvokeParams,
-  ): Promise<PluginActionInvokeResult>;
-}
-
-/**
- * Plugin Action 执行结果。
- */
-export interface PluginActionResult<R extends JsonValue = JsonValue> {
-  /** Action 是否成功。 */
-  success: boolean;
-  /** 返回数据（可选）。 */
-  data?: R;
-  /** 错误信息（可选）。 */
-  error?: string;
-  /** 人类可读消息（可选）。 */
-  message?: string;
-  /** Action 执行后应写入 Session 的真实 User / Assistant Messages。 */
-  messages?: ActionResultMessage[];
-}
-
-/**
- * Plugin Action 命令输入。
- */
-export interface PluginActionCommandInput {
-  /** 位置参数列表。 */
-  args: string[];
-  /** 选项参数对象。 */
-  opts: Record<string, JsonValue>;
-}
-
-/**
- * Plugin Action CLI 定义。
- */
-export interface PluginActionCommand<P extends JsonValue = JsonValue> {
-  /** 命令说明。 */
-  description: string;
-  /** 额外 commander 配置（可选）。 */
-  configure?: (command: Command) => void;
-  /** 将 CLI 输入映射为 payload。 */
-  map_input: (input: PluginActionCommandInput) => P | Promise<P>;
-}
-
-/**
- * Plugin Action HTTP 定义。
- */
-export interface PluginActionApi<P extends JsonValue = JsonValue> {
-  /** HTTP 方法。 */
-  method?: "GET" | "POST" | "PUT" | "DELETE";
-  /** HTTP 路径。 */
-  path?: string;
-  /** 将 HTTP 输入映射为 payload（可选）。 */
-  map_input?: (ctx: HonoContext) => P | Promise<P>;
-}
-
-/**
- * Plugin Action 示例。
- */
-export interface PluginActionExample<P extends JsonValue = JsonValue> {
-  /** 示例标题。 */
-  title: string;
-  /** 示例说明。 */
-  description?: string;
-  /** 示例 payload。 */
-  payload: P;
-}
-
-/**
- * Plugin Action 输入 schema。
- *
- * 关键点（中文）
- * - 优先支持 Zod，运行时用 safeParse 做校验。
- * - `json_schema` 用于给模型或 UI 读取；没有时仍可依赖 description/examples。
- */
-export interface PluginActionInputSchema<P extends JsonValue = JsonValue> {
-  /** Zod schema，负责运行时校验与 TypeScript 推导。 */
-  zod?: z.ZodTypeAny;
-  /** 面向模型和 UI 的 JSON Schema 描述。 */
-  json_schema?: JsonObject;
-}
-
-/**
- * Plugin Action 元数据。
- */
-export interface PluginActionMetadata<P extends JsonValue = JsonValue> {
-  /** Action 用途说明。 */
-  description?: string;
-  /** Action 输入 schema。 */
-  input_schema?: PluginActionInputSchema<P>;
-  /** Action 调用示例。 */
-  examples?: PluginActionExample<P>[];
-  /** Action 的协作式超时上限（毫秒）；Action 必须监听 execution.abort_signal。 */
-  timeout_ms?: number;
-}
-
-/**
- * Plugin Action 定义。
- */
-export interface PluginAction<
-  P extends JsonValue = JsonValue,
-  R extends JsonValue = JsonValue,
-> extends PluginActionMetadata<P> {
-  /** CLI 定义（可选）。 */
-  command?: PluginActionCommand<P>;
-  /** HTTP 定义（可选）。 */
-  api?: PluginActionApi<P>;
-  /** Action 执行器。 */
-  execute: (params: {
-    /** WorkspaceEntry 创建的稳定 Plugin 能力视图。 */
-    context: PluginContext;
-    /**
-     * 当前 action 所属 Session Turn 的只读 Plugin 执行快照。
-     *
-     * 关键点（中文）
-     * - 模型 tool 调用复用对应 tool call ID 和 Turn 取消信号。
-     * - CLI、HTTP 与定时任务等非 Session 入口由 Registry 补齐调用身份和取消信号。
-     */
-    execution: PluginActionExecutionContext;
-    /** 已通过 schema 校验后的输入。 */
-    input: P;
-    /** 当前插件名称。 */
-    plugin_name: string;
-    /** 当前 Action 名称。 */
-    action_name: string;
-  }) => Promise<PluginActionResult<R>> | PluginActionResult<R>;
-}
-
-/**
- * Plugin Action 集合。
- */
-export type PluginActions = {
-  [action_name: string]: PluginAction<JsonValue, JsonValue>;
-};

package/src/types/plugin/PluginActionExecution.ts

@@ -1,36 +0,0 @@
-/**
- * Plugin Action 单次执行上下文。
- *
- * 关键点（中文）
- * - 每次 Action 调用都获得独立、只读的身份与取消快照。
- * - Agent 与 Workspace 的稳定身份只保留在 PluginContext，不复制到单次执行对象。
- * - Session 字段来自可选的 PluginExecutionContext；HTTP、CLI 与 Schedule 调用可以没有 Session。
- */
-
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
-import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
-
-/** 当前 Action 所属 Session 的执行范围。 */
-export interface PluginSessionExecutionScope {
-  /** 当前 Session 标识。 */
-  readonly session_id: string;
-  /** 当前 Turn 标识。 */
-  readonly turn_id: string;
-  /** 当前 Session 的用户交互端口；当前入口未开放交互能力时为空。 */
-  readonly interactions?: SessionInteractionPort;
-}
-
-/** Plugin Action 执行器传给业务 Action 的完整只读上下文。 */
-export interface PluginActionExecutionContext {
-  /** 当前 Action 调用的稳定标识；模型 Tool 调用时等于对应 tool call ID。 */
-  readonly call_id: string;
-
-  /** 当前 Action 必须监听的取消信号；可同时承载 Turn 取消和 Action 超时。 */
-  readonly abort_signal: AbortSignal;
-
-  /** 当前调用所属的 Session；非 Session 入口时为空。 */
-  readonly session?: PluginSessionExecutionScope;
-
-  /** 当前调用开始时捕获的只读 Step 快照。 */
-  readonly snapshot: PluginExecutionContext;
-}

package/src/types/plugin/PluginCommand.ts

@@ -1,15 +0,0 @@
-/**
- * Plugin 生命周期类型。
- *
- * 关键点（中文）：生命周期只负责启动和停止；所有显式能力调用统一使用 Action。
- */
-
-import type { AgentPluginContext } from "@/types/plugin/AgentPluginContext.js";
-
-/** Plugin 生命周期定义。 */
-export interface PluginLifecycle {
-  /** Plugin 随 Agent 启动的钩子；不得假设存在 Workspace。 */
-  start?(context: AgentPluginContext): Promise<void> | void;
-  /** Plugin 随 Agent 停止的钩子。 */
-  stop?(context: AgentPluginContext): Promise<void> | void;
-}

package/src/types/plugin/PluginContext.ts

@@ -1,59 +0,0 @@
-/**
- * PluginContext：Agent 向 Plugin 投影的稳定能力视图。
- *
- * 边界说明（中文）
- * - Plugin 只依赖本接口，不持有 Agent、City 实例，也不参与 Session 内核编排。
- * - 动态状态通过只读 getter 暴露，保证 Workspace env 与 instruction 始终来自唯一状态源。
- */
-
-import type { AgentSessionCollection } from "@/types/agent/AgentSessionCollection.js";
-import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
-import type { FileSystem, WorkspaceShell } from "@downcity/workspace";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { PluginWebServices } from "@/types/plugin/PluginServices.js";
-import type { Embassy } from "@downcity/federation";
-
-/** Agent 向 Plugin 开放的最小、稳定运行时能力。 */
-export interface PluginContext {
-  /** 当前 Agent 的稳定标识。 */
-  readonly agent_id: string;
-
-  /** 当前 Workspace 的稳定标识。 */
-  readonly workspace_id: string;
-
-  /** 当前 Workspace 的绝对根目录。 */
-  readonly workspace_path: string;
-
-  /** 当前 Plugin 在 Agent 内的运行时私有数据根路径。 */
-  readonly data_path: string;
-
-  /** 当前 Workspace 的统一文件能力。 */
-  readonly files: FileSystem;
-
-  /** 当前 Plugin 运行时私有数据目录的统一文件能力。 */
-  readonly data_files: FileSystem;
-
-  /** 当前 Workspace 显式挂载的 Shell；未启用时为空。 */
-  readonly shell?: WorkspaceShell;
-
-  /** 当前 Agent 在当前 Workspace 执行上下文中使用的统一日志器。 */
-  readonly logger: Logger;
-
-  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
-  readonly web?: PluginWebServices;
-
-  /** City 注入的 Embassy 能力；Agent 未加入 City 时为空。 */
-  readonly embassy?: Embassy;
-
-  /** 当前 Agent 的 Session 集合入口。 */
-  readonly sessions: AgentSessionCollection;
-
-  /** 当前 Agent 唯一的 Plugin 调用与注册入口。 */
-  readonly plugins: AgentPlugins;
-
-  /** 当前 Workspace 已配置环境变量的只读快照。 */
-  readonly workspace_env: Readonly<Record<string, string>>;
-
-  /** 当前 Agent 已配置静态指令的只读快照。 */
-  readonly instructions: readonly string[];
-}

package/src/types/plugin/PluginDefinition.ts

@@ -1,54 +0,0 @@
-/**
- * Plugin 顶层定义类型。
- *
- * 关键点（中文）
- * - 这里只组合 plugin 的各类能力，不展开每个能力的细节。
- * - 细节类型分散在 State / Action / Runtime / Lifecycle / HTTP 模块。
- */
-
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { PluginActions } from "@/types/plugin/PluginAction.js";
-import type {
-  PluginAvailability,
-  PluginHooks,
-  PluginResolves,
-} from "@/types/plugin/PluginRuntime.js";
-import type { PluginLifecycle } from "@/types/plugin/PluginCommand.js";
-import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
-
-/**
- * Plugin 定义。
- */
-export interface Plugin {
-  /** Plugin 稳定名称。 */
-  name: string;
-  /** Plugin 面向用户界面的展示标题。 */
-  title: string;
-  /** Plugin 面向人类的用途说明。 */
-  description: string;
-  /** Plugin 显式 Action 集合（可选）。 */
-  actions?: PluginActions;
-  /** Plugin Hook 集合（可选）。 */
-  hooks?: PluginHooks;
-  /** Plugin resolve 点集合（可选）。 */
-  resolves?: PluginResolves;
-  /**
-   * Plugin system 文本构建器（可选）。
-   *
-   * @param context Agent 稳定能力上下文。
-   * @param execution_context 当前 Session Turn 的只读 Plugin 执行快照；非 Session 调用时可缺省。
-   */
-  system?: (
-    context: PluginContext,
-    execution_context?: PluginExecutionContext,
-  ) => string | Promise<string>;
-  /** Plugin 生命周期定义（可选）。 */
-  lifecycle?: PluginLifecycle;
-  /** Plugin 可用性检查器（可选）。 */
-  availability?: (
-    context: PluginContext,
-  ) => Promise<PluginAvailability> | PluginAvailability;
-  /** Plugin HTTP 注入定义（可选）。 */
-  http?: PluginHttpDefinition;
-}

package/src/types/plugin/PluginExecutionContext.ts

@@ -1,29 +0,0 @@
-/**
- * Plugin action 与 system provider 可读取的执行快照。
- *
- * Session 调用时，该对象是当前 Turn 的只读 Plugin 投影；CLI、HTTP 与
- * scheduler 等非 Session 调用也可以提供自己的调用快照或完全缺省。
- */
-
-export interface PluginExecutionContext {
-  /** 当前调用所属的 Session 标识；非 Session 调用可以缺省。 */
-  readonly session_id?: string;
-
-  /** 当前调用所属的 Turn 标识。 */
-  readonly turn_id?: string;
-
-  /** 当前 Agent 绑定的项目根目录。 */
-  readonly project_root?: string;
-
-  /** 当前 Session Step 已提交生效的 Workspace env 快照。 */
-  readonly workspace_env?: Readonly<Record<string, string>>;
-
-  /** 当前 Session Step 已提交生效的 instruction 快照。 */
-  readonly agent_systems?: readonly string[];
-
-  /** 当前 Turn 的取消信号。 */
-  readonly abort_signal?: AbortSignal;
-
-  /** 当前 Action 调用标识；仅 Action 执行时存在。 */
-  readonly call_id?: string;
-}

package/src/types/plugin/PluginHttp.ts

@@ -1,36 +0,0 @@
-/**
- * Plugin HTTP 注入类型。
- *
- * 关键点（中文）
- * - plugin 只声明自己的路由与鉴权策略。
- * - server 装配、代理和鉴权执行仍由宿主负责。
- */
-
-import type { Hono } from "hono";
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { AuthRoutePolicy } from "@downcity/type";
-
-/**
- * Plugin HTTP 注入参数。
- */
-export interface PluginHttpRegistration {
-  /** 该组路由对应的鉴权策略列表。 */
-  auth_policies?: AuthRoutePolicy[];
-  /** 向 runtime Hono 应用注册路由。 */
-  register(params: {
-    /** 当前 Hono 应用实例。 */
-    app: Hono;
-    /** 获取当前统一执行上下文。 */
-    get_context: () => PluginContext;
-    /** 当前 plugin 稳定名称。 */
-    plugin_name: string;
-  }): void;
-}
-
-/**
- * Plugin HTTP 注入定义。
- */
-export interface PluginHttpDefinition {
-  /** server HTTP 路由注入（可选）。 */
-  server?: PluginHttpRegistration;
-}

package/src/types/plugin/PluginNotification.ts

@@ -1,38 +0,0 @@
-/**
- * Agent Plugin 向宿主发布用户注意事项的通知协议。
- *
- * Plugin 只描述通知内容与自身工作区路由，不感知 Desktop、Dock、持久化或已读策略。
- * 宿主负责绑定 Plugin 身份、聚合通知并决定具体呈现方式。
- */
-
-import type { JsonObject } from "@/types/common/Json.js";
-
-/** Agent Plugin 发布的一条宿主通知。 */
-export interface PluginNotificationInput {
-  /** Plugin 内稳定的聚合键；同一键的新通知替换旧的未读通知。 */
-  readonly topic_key: string;
-
-  /** 简短的用户可见标题。 */
-  readonly title: string;
-
-  /** 可选的用户可见补充说明。 */
-  readonly body?: string;
-
-  /** 打开通知时使用的当前 Plugin 工作区 JSON 路由。 */
-  readonly route?: JsonObject;
-}
-
-/** Plugin 要清除的一项本地通知主题。 */
-export interface PluginNotificationTopicInput {
-  /** Plugin 内稳定的聚合键。 */
-  readonly topic_key: string;
-}
-
-/** 宿主注入给 Agent Plugin factory 的通知发布能力。 */
-export interface PluginNotificationPublisher {
-  /** 发布一条由当前 Plugin 拥有的通知。 */
-  publish(input: PluginNotificationInput): Promise<void>;
-
-  /** 清除当前 Plugin 命名空间内一个主题的未读通知。 */
-  dismiss(input: PluginNotificationTopicInput): Promise<void>;
-}

package/src/types/plugin/PluginRegistry.ts

@@ -1,25 +0,0 @@
-/**
- * PluginRegistry 变化订阅类型。
- *
- * 关键点（中文）
- * - Agent 订阅 Registry 变化后同步 Plugin Tools 与 Session execution view。
- * - PluginRegistry 不直接修改 Agent 持有的工具集合。
- */
-
-/** PluginRegistry 的单次配置变化。 */
-export interface PluginRegistryChange {
-  /** 当前修改是注册还是卸载。 */
-  type: "register" | "unregister";
-
-  /** 当前发生修改的 Plugin 稳定名称。 */
-  plugin_name: string;
-}
-
-/** PluginRegistry 变化监听器。 */
-export type PluginRegistrySubscriber = (
-  /** 当前 Plugin 配置变化。 */
-  change: PluginRegistryChange,
-) => void;
-
-/** 取消 PluginRegistry 变化订阅的函数。 */
-export type PluginRegistryUnsubscribe = () => void;