@downcity/agent 1.1.408 → 1.1.437

package/src/types/plugin/PluginRuntime.ts

@@ -1,292 +0,0 @@
-/**
- * Plugin runtime 类型。
- *
- * 关键点（中文）
- * - 这里描述 Agent runtime 如何查看、调用、检查 plugin。
- * - setup/usage UI 协议与 action 输入适配不放在这里。
- */
-
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-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/SessionTypes.js";
-import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
-import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
-
-/**
- * Plugin 概览视图。
- */
-export interface PluginView {
-  /** Plugin 稳定名称。 */
-  name: string;
-  /** Plugin 面向用户界面的展示标题。 */
-  title: string;
-  /** Plugin 面向人类的用途说明。 */
-  description: string;
-  /** Plugin Action 名称列表。 */
-  actions: string[];
-  /** Plugin pipeline 点名称列表。 */
-  pipelines: string[];
-  /** Plugin guard 点名称列表。 */
-  guards: string[];
-  /** Plugin effect 点名称列表。 */
-  effects: string[];
-  /** Plugin resolve 点名称列表。 */
-  resolves: string[];
-  /** 是否声明了 system 注入。 */
-  has_system: boolean;
-  /** 是否声明了 availability 检查。 */
-  has_availability: boolean;
-}
-
-/**
- * Plugin Action 读取视图。
- */
-export interface PluginActionReadView {
-  /** Action 名称。 */
-  name: string;
-  /** Action 用途说明。 */
-  description: string;
-  /** 是否声明输入 schema。 */
-  has_input_schema: boolean;
-  /** JSON Schema 形式的输入说明。 */
-  input_schema?: JsonValue;
-  /** Action 调用示例。 */
-  examples?: PluginActionExample[];
-  /** 是否声明 CLI command。 */
-  has_command: boolean;
-  /** 是否声明 HTTP API。 */
-  has_api: boolean;
-}
-
-/**
- * Plugin 读取视图。
- */
-export interface PluginReadView {
-  /** Plugin 稳定名称。 */
-  name: string;
-  /** Plugin 展示标题。 */
-  title: string;
-  /** Plugin 用途说明。 */
-  description: string;
-  /** Action 列表或指定 action。 */
-  actions: PluginActionReadView[];
-}
-
-/**
- * Plugin 可用性结果。
- */
-export interface PluginAvailability {
-  /** Plugin 是否已注册。 */
-  enabled: boolean;
-  /** Plugin 当前环境是否可用。 */
-  available: boolean;
-  /** 不可用原因列表。 */
-  reasons: string[];
-}
-
-/**
- * 当前 Agent 可用的 plugin 调用面。
- */
-export interface AgentPlugins {
-  /** 注册或替换一个 plugin。 */
-  register(plugin: Plugin): Promise<PluginSnapshot>;
-  /**
-   * 从 configured registry 卸载一个 plugin。
-   *
-   * 关键点（中文）
-   * - 返回值表示 configured registry 是否发生删除。
-   * - 活跃 Session step 仍可使用已捕获的 execution lease，lifecycle.stop 在 lease 释放后执行。
-   */
-  unregister(plugin_name: string): Promise<boolean>;
-  /** 启动全部已挂载 plugin lifecycle。 */
-  start_all(): Promise<PluginSnapshot[]>;
-  /** 卸载全部 plugin，并等待所有 execution lease 释放后的 lifecycle.stop 完成。 */
-  unregister_all(): Promise<void>;
-  /** 判断 plugin 是否已注册。 */
-  has(plugin_name: string): boolean;
-  /** 读取单个 plugin 定义。 */
-  get(plugin_name: string): Plugin | null;
-  /** 读取单个 plugin 注册快照。 */
-  status(plugin_name: string): PluginSnapshot | null;
-  /** 列出全部已注册 plugin 快照。 */
-  snapshots(): PluginSnapshot[];
-  /** 列出全部已注册 plugin。 */
-  list(): PluginView[];
-  /** 读取 plugin / action metadata。 */
-  read(params: {
-    /** Plugin 名称。 */
-    plugin?: string;
-    /** Action 名称。 */
-    action?: string;
-  }): PluginReadView | { plugins: PluginView[] };
-  /** 检查指定 plugin 可用性。 */
-  availability(plugin_name: string): Promise<PluginAvailability>;
-  /** 运行指定 plugin action。 */
-  run_action(params: {
-    /** Plugin 名称。 */
-    plugin: string;
-    /** Action 名称。 */
-    action: string;
-    /** Action Payload（可选）。 */
-    payload?: JsonValue;
-    /** 当前 action 所属 Session Turn 的只读 Plugin 执行快照。 */
-    execution_context?: PluginExecutionContext;
-    /** 当前 Session 的 Interaction 端口；非 Session 调用时为空。 */
-    interactions?: SessionInteractionPort;
-  }): Promise<PluginActionResult<JsonValue>>;
-  /** 读取当前生效的 plugin system blocks。 */
-  system_blocks(
-    execution_context?: PluginExecutionContext,
-  ): Promise<AgentSessionSystemBlock[]>;
-  /** 运行 pipeline 点，按顺序链式变换值。 */
-  pipeline<T = JsonValue>(point_name: string, value: T): Promise<T>;
-  /** 运行 guard 点；任一插件抛错即终止。 */
-  guard<T = JsonValue>(point_name: string, value: T): Promise<void>;
-  /** 运行 effect 点；只执行副作用。 */
-  effect<T = JsonValue>(point_name: string, value: T): Promise<void>;
-  /** 运行 resolve 点；要求存在且仅存在一个处理器。 */
-  resolve<TInput = JsonValue, TOutput = JsonValue>(
-    point_name: string,
-    value: TInput,
-  ): Promise<TOutput>;
-
-}
-
-/**
- * Plugin execution view 的只读调用能力。
- */
-export interface AgentPluginExecutionView {
-  /** 读取当前视图中的 plugin/action metadata。 */
-  read(params: {
-    /** Plugin 名称（可选）。 */
-    plugin?: string;
-    /** Action 名称（可选）。 */
-    action?: string;
-  }): PluginReadView | { plugins: PluginView[] };
-
-  /** 运行当前视图中捕获的 plugin action。 */
-  run_action(params: {
-    /** Plugin 名称。 */
-    plugin: string;
-    /** Action 名称。 */
-    action: string;
-    /** Action Payload（可选）。 */
-    payload?: JsonValue;
-    /** 当前 action 所属 Session Turn 的只读 Plugin 执行快照。 */
-    execution_context?: PluginExecutionContext;
-    /** 当前 Session 的 Interaction 端口；非 Session 调用时为空。 */
-    interactions?: SessionInteractionPort;
-  }): Promise<PluginActionResult<JsonValue>>;
-
-  /** 解析当前视图中捕获的 plugin system blocks。 */
-  system_blocks(
-    execution_context?: PluginExecutionContext,
-  ): Promise<AgentSessionSystemBlock[]>;
-}
-
-/**
- * 单次 Session step 持有的 Plugin 执行 lease。
- */
-export interface AgentPluginExecutionLease extends AgentPluginExecutionView {
-  /**
-   * 释放当前 step 对捕获 Plugin lifecycle 的占用。
-   *
-   * 关键点（中文）
-   * - 必须幂等，重复释放不会重复停止 lifecycle。
-   * - 若 Plugin 已从 configured registry 移除，最后一个 lease 释放时完成延迟 stop。
-   */
-  release(): Promise<void>;
-}
-
-/**
- * Session effective 配置持有的 Plugin 执行 runtime。
- */
-export interface AgentPluginExecutionRuntime extends AgentPluginExecutionView {
-  /**
-   * 为当前 Session step 获取独立的 Plugin 执行 lease。
-   *
-   * 关键点（中文）
-   * - lease 只捕获创建 runtime 时存在的 Plugin records。
-   * - 已退休或 lifecycle 未就绪的 Plugin 不会进入新 lease。
-   */
-  acquire(): AgentPluginExecutionLease;
-}
-
-/**
- * Plugin pipeline 处理器。
- */
-export type PluginPipelineHook<
-  TValue extends JsonValue = JsonValue,
-> = (params: {
-  /** 当前执行上下文。 */
-  context: PluginContext;
-  /** 当前值。 */
-  value: TValue;
-  /** 当前插件名称。 */
-  plugin: string;
-}) => Promise<TValue> | TValue;
-
-/**
- * Plugin guard 处理器。
- *
- * 关键点（中文）
- * - 不返回结果；若需阻断流程，直接抛错。
- */
-export type PluginGuardHook<TValue extends JsonValue = JsonValue> = (params: {
-  /** 当前执行上下文。 */
-  context: PluginContext;
-  /** 当前值。 */
-  value: TValue;
-  /** 当前插件名称。 */
-  plugin: string;
-}) => Promise<void> | void;
-
-/**
- * Plugin effect 处理器。
- */
-export type PluginEffectHook<TValue extends JsonValue = JsonValue> = (params: {
-  /** 当前执行上下文。 */
-  context: PluginContext;
-  /** 当前值。 */
-  value: TValue;
-  /** 当前插件名称。 */
-  plugin: string;
-}) => Promise<void> | void;
-
-/**
- * Plugin resolve 处理器。
- */
-export type PluginResolveHook<
-  TInput extends JsonValue = JsonValue,
-  TOutput extends JsonValue = JsonValue,
-> = (params: {
-  /** 当前执行上下文。 */
-  context: PluginContext;
-  /** 当前输入值。 */
-  value: TInput;
-  /** 当前插件名称。 */
-  plugin: string;
-}) => Promise<TOutput> | TOutput;
-
-/**
- * Plugin Hook 定义集合。
- */
-export interface PluginHooks {
-  /** pipeline 点映射。 */
-  pipeline?: Record<string, PluginPipelineHook<JsonValue>[]>;
-  /** guard 点映射。 */
-  guard?: Record<string, PluginGuardHook<JsonValue>[]>;
-  /** effect 点映射。 */
-  effect?: Record<string, PluginEffectHook<JsonValue>[]>;
-}
-
-/**
- * Plugin resolve 点集合。
- */
-export type PluginResolves = {
-  [point_name: string]: PluginResolveHook<JsonValue, JsonValue>;
-};

package/src/types/plugin/PluginServices.ts

@@ -1,11 +0,0 @@
-/** Agent 向 Plugin 提供的可选外部服务能力。 */
-
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-
-/** Plugin 可使用的 Web 服务最小协议。 */
-export interface PluginWebServices {
-  /** 搜索公开 Web 内容。 */
-  search(input: JsonObject): Promise<JsonValue>;
-  /** 读取指定 Web 文档。 */
-  open(input: JsonObject): Promise<JsonValue>;
-}

package/src/types/plugin/PluginState.ts

@@ -1,65 +0,0 @@
-/**
- * Plugin 注册状态类型。
- *
- * 关键点（中文）
- * - Plugin 只属于 Agent：完成 lifecycle.start 后生效，卸载后立即不可见。
- * - 不再暴露 start / stop / restart 这类生命周期状态。
- * - `error` 只表示最近一次注册后运行发生错误，方便开发者诊断。
- */
-
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-
-/**
- * Plugin 当前可观察状态。
- */
-export type PluginState = "initializing" | "ready" | "error";
-
-/**
- * 单个已注册 plugin 的运行时记录。
- */
-export interface PluginRuntimeRecord {
-  /** 当前 plugin 实例。 */
-  plugin: Plugin;
-  /** 当前可观察状态。 */
-  state: PluginState;
-  /** plugin 注册时间（毫秒时间戳）。 */
-  registered_at: number;
-  /** 最近一次状态更新时间（毫秒时间戳）。 */
-  updated_at: number;
-  /** 最近一次错误信息。 */
-  last_error?: string;
-  /** 当前串行变更链。 */
-  chain: Promise<void>;
-  /** lifecycle.start 是否已经执行成功。 */
-  lifecycle_started: boolean;
-  /** 当前正在使用该 Plugin 的 Session step lease 数量。 */
-  active_execution_leases: number;
-  /** 当前 Plugin 是否已从 configured registry 移除并等待释放。 */
-  retired: boolean;
-  /** 当前 Plugin 的延迟 lifecycle.stop 是否已经开始。 */
-  retirement_started: boolean;
-  /** 当前 Plugin 完成延迟 lifecycle.stop 后兑现的 Promise。 */
-  retirement_promise?: Promise<void>;
-  /** 兑现当前 Plugin retirement Promise 的内部回调。 */
-  resolve_retirement?: () => void;
-}
-
-/**
- * 单个 plugin 注册快照。
- */
-export interface PluginSnapshot {
-  /** plugin 名称。 */
-  name: string;
-  /** plugin 标题。 */
-  title: string;
-  /** plugin 描述。 */
-  description: string;
-  /** 当前注册后的可用状态。 */
-  status: PluginState;
-  /** 注册时间（毫秒时间戳）。 */
-  registered_at: number;
-  /** 最近更新时间（毫秒时间戳）。 */
-  updated_at: number;
-  /** 最近错误。 */
-  last_error?: string;
-}

package/src/types/plugin/PluginTool.ts

@@ -1,106 +0,0 @@
-/**
- * Plugin tool 类型定义。
- *
- * 关键点（中文）
- * - 这里描述模型通过 plugin_call 提交的最低层调用协议。
- * - payload 保持 JSON 对象，避免 tool 层理解具体 plugin 的业务字段。
- */
-
-import type { RuntimeTool as Tool } from "@downcity/type";
-import type { JsonObject } from "@/types/common/Json.js";
-import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
-
-/**
- * plugin_call 输入。
- */
-export interface PluginCallInput {
-  /** 目标 plugin 名称。 */
-  plugin: string;
-  /** 目标 action 名称。 */
-  action: string;
-  /** 传给 plugin action 的 JSON payload。 */
-  payload?: JsonObject;
-}
-
-/**
- * plugin_read 输入。
- */
-export interface PluginReadInput {
-  /** 要读取的 plugin 名称；不传则列出 plugin 概览。 */
-  plugin?: string;
-  /** 要读取的 action 名称；仅在 plugin 存在时生效。 */
-  action?: string;
-}
-
-/**
- * plugin_call 返回给模型的摘要结果。
- */
-export interface PluginCallToolResult {
-  /** 调用是否成功。 */
-  success: boolean;
-  /** 目标 plugin 名称。 */
-  plugin: string;
-  /** 目标 action 名称。 */
-  action: string;
-  /** 人类可读消息。 */
-  message: string;
-  /** 错误信息。 */
-  error?: string;
-  /** 返回给模型读取的短摘要数据。 */
-  data?: JsonObject;
-}
-
-/**
- * plugin_read 返回给模型的 metadata。
- */
-export interface PluginReadToolResult {
-  /** 调用是否成功。 */
-  success: boolean;
-  /** 人类可读消息。 */
-  message: string;
-  /** 读取到的 metadata。 */
-  data: JsonObject;
-}
-
-/** 创建当前 Agent 专属 Plugin Tools 的参数。 */
-export interface CreatePluginToolsOptions {
-  /** 当前 Agent 自己的 Plugin 调用面；Tool 只能访问该 Registry。 */
-  plugins: AgentPlugins;
-}
-
-/** 当前 Agent 专属的 Plugin Tools。 */
-export interface AgentPluginTools {
-  /** 通过闭包绑定当前 Registry 的 Plugin metadata 读取 Tool。 */
-  plugin_read: Tool;
-
-  /** 通过闭包绑定当前 Registry 的 Plugin Action 执行 Tool。 */
-  plugin_call: Tool;
-}
-
-/** 调用 plugin_call 运行时的显式依赖。 */
-export interface InvokePluginCallToolOptions {
-  /** 当前 Agent 自己的 Plugin 调用面。 */
-  plugins: AgentPlugins;
-
-  /** Executor 为当前 Tool Call 绑定的 Session Turn Context。 */
-  turn_context: SessionTurnContext;
-
-  /** Downcity Model Protocol 为当前 plugin_call 分配的稳定 Tool Call 标识。 */
-  call_id: string;
-
-  /** 模型提交给 plugin_call 的结构化输入。 */
-  input: PluginCallInput;
-}
-
-/** 调用 plugin_read 运行时的显式依赖。 */
-export interface InvokePluginReadToolOptions {
-  /** 当前 Agent 自己的 Plugin 调用面。 */
-  plugins: AgentPlugins;
-
-  /** Executor 为当前 Tool Call 绑定的 Session Turn Context。 */
-  turn_context: SessionTurnContext;
-
-  /** 模型提交给 plugin_read 的结构化输入。 */
-  input: PluginReadInput;
-}