@downcity/agent 1.1.7 → 1.1.10

package/src/shared/types/Sandbox.ts

@@ -1,144 +0,0 @@
-/**
- * Sandbox 共享类型定义。
- *
- * 关键点（中文）
- * - 这里放的是 console 模块与 agent 执行层都会使用的最小 sandbox 协议。
- * - 当前版本不引入复杂 profile / binding / permission 模型，只表达“命令执行边界”。
- * - 运行时句柄与状态化 session 类型放在 `src/types/sandbox/`。
- */
-
-/**
- * Sandbox 网络模式。
- *
- * 说明（中文）
- * - `off`：完全禁止网络访问。
- * - `restricted`：允许受限网络访问（后续实现白名单时再细化）。
- * - `full`：允许完整网络访问。
- */
-export type SandboxNetworkMode = "off" | "restricted" | "full";
-
-/**
- * Sandbox 路径访问模式。
- *
- * 说明（中文）
- * - `ro`：只读。
- * - `rw`：可读写。
- */
-export type SandboxPathAccessMode = "ro" | "rw";
-
-/**
- * 单条路径边界规则。
- */
-export interface SandboxPathRule {
-  /**
-   * 宿主机上的绝对路径。
-   */
-  path: string;
-
-  /**
-   * 当前路径在 sandbox 中的访问模式。
-   */
-  access: SandboxPathAccessMode;
-
-  /**
-   * 当前规则的说明文本。
-   */
-  reason?: string;
-}
-
-/**
- * sandbox 最小配置。
- *
- * 说明（中文）
- * - 当前只表达命令执行边界，不表达 chat 用户授权与审批流。
- * - `rootPath` 是默认工作根目录。
- * - `writablePaths` 决定哪些路径允许写入。
- * - `envAllowlist` 决定哪些环境变量允许导出到 sandbox。
- */
-export interface SandboxConfig {
-  /**
-   * 当前 sandbox 的默认根目录。
-   */
-  rootPath: string;
-
-  /**
-   * 允许导出的环境变量名集合。
-   *
-   * 说明（中文）
-   * - 这里仅声明允许导出的 key，不在共享配置层直接保存明文值。
-   */
-  envAllowlist: string[];
-
-  /**
-   * 允许写入的路径集合。
-   *
-   * 说明（中文）
-   * - 路径可以是绝对路径，也可以是相对 `rootPath` 的相对路径。
-   * - 运行时会统一解析为绝对路径，并限制在 `rootPath` 范围内。
-   */
-  writablePaths: string[];
-
-  /**
-   * 当前 sandbox 的网络模式。
-   */
-  networkMode: SandboxNetworkMode;
-}
-
-/**
- * 项目级 sandbox 配置。
- *
- * 说明（中文）
- * - 这是 `downcity.json` 中面向用户暴露的最小配置。
- * - 当前版本只服务 CLI / shell 执行边界，不扩展到审批或用户权限系统。
- */
-export interface SandboxProjectConfig {
-  /**
-   * 允许导出的环境变量名集合。
-   *
-   * 说明（中文）
-   * - 这里只声明允许导出的 key，不直接保存变量值。
-   * - 运行时仍会注入少量必需变量，例如隔离后的 `HOME`、`TMPDIR`。
-   */
-  envAllowlist?: string[];
-
-  /**
-   * 允许写入的路径集合。
-   *
-   * 说明（中文）
-   * - 路径可以是绝对路径，也可以是相对 `rootPath` 的相对路径。
-   * - 当前版本会把越出 `rootPath` 的路径裁掉，避免把宿主文件系统重新暴露回去。
-   */
-  writablePaths?: string[];
-
-  /**
-   * 当前 sandbox 的网络模式。
-   *
-   * 说明（中文）
-   * - 默认建议使用 `off`。
-   * - `restricted` 先保留为受限网络语义占位，当前实现会按保守策略处理。
-   */
-  networkMode?: SandboxNetworkMode;
-}
-
-/**
- * console 模块中保存的 agent sandbox 配置记录。
- */
-export interface AgentSandboxConfigRecord {
-  /**
-   * 当前 agent 的稳定标识。
-   *
-   * 说明（中文）
-   * - 当前建议直接使用 agent 项目根目录绝对路径。
-   */
-  agentId: string;
-
-  /**
-   * 当前 agent 使用的 sandbox 配置。
-   */
-  config: SandboxConfig;
-
-  /**
-   * 最近更新时间（ISO8601）。
-   */
-  updatedAt: string;
-}

package/src/shared/types/Service.ts

@@ -1,223 +0,0 @@
-/**
- * Service 类型定义。
- *
- * 关键点（中文）
- * - 这里集中声明 service 体系的共享契约。
- * - 这些类型会被 `main/service/*`、`services/*`、tests 等多层复用，因此提升到 `shared/types/`。
- * - `main/service/ServiceManager.ts` 之后只保留门面 re-export，不再承担类型源文件职责。
- */
-
-import type { Command } from "commander";
-import type { Context as HonoContext } from "hono";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonValue } from "@/shared/types/Json.js";
-
-/**
- * 服务运行状态。
- *
- * 说明（中文）
- * - `starting` / `stopping` 仅用于生命周期控制中的过渡态。
- * - `error` 表示最近一次控制或命令执行失败后留下的状态标记。
- */
-export type ServiceState =
-  | "running"
-  | "stopped"
-  | "starting"
-  | "stopping"
-  | "error";
-
-/**
- * 服务命令执行结果。
- */
-export type ServiceCommandResult = {
-  /**
-   * 本次命令是否执行成功。
-   */
-  success: boolean;
-  /**
-   * 对人类可读的补充说明文本。
-   */
-  message?: string;
-  /**
-   * 命令附带返回的数据载荷。
-   */
-  data?: JsonValue;
-};
-
-/**
- * 单个 action 执行结果。
- */
-export type ServiceActionResult<R extends JsonValue = JsonValue> = {
-  /**
-   * action 是否执行成功。
-   */
-  success: boolean;
-  /**
-   * action 成功时返回的数据载荷。
-   */
-  data?: R;
-  /**
-   * action 失败时返回的错误文本。
-   */
-  error?: string;
-};
-
-/**
- * Action CLI 输入。
- */
-export type ServiceActionCommandInput = {
-  /**
-   * 位置参数列表。
-   */
-  args: string[];
-  /**
-   * 解析后的 option 键值对。
-   */
-  opts: Record<string, JsonValue>;
-};
-
-/**
- * Action CLI 定义。
- */
-export type ServiceActionCommand<P extends JsonValue = JsonValue> = {
-  /**
-   * CLI 子命令描述。
-   */
-  description: string;
-  /**
-   * 对 commander command 的额外配置。
-   */
-  configure?: (command: Command) => void;
-  /**
-   * 把 CLI 输入映射为结构化 payload。
-   */
-  mapInput: (input: ServiceActionCommandInput) => P | Promise<P>;
-};
-
-/**
- * Action HTTP 定义。
- */
-export type ServiceActionApi<P extends JsonValue = JsonValue> = {
-  /**
-   * HTTP 方法。
-   */
-  method?: "GET" | "POST" | "PUT" | "DELETE";
-  /**
-   * 自定义路由路径；省略时走默认 `/service/<service>/<action>`。
-   */
-  path?: string;
-  /**
-   * 把 HTTP 请求映射为结构化 payload。
-   */
-  mapInput?: (ctx: HonoContext) => P | Promise<P>;
-};
-
-/**
- * 单个 service action 定义。
- */
-export type ServiceAction<
-  P extends JsonValue = JsonValue,
-  R extends JsonValue = JsonValue,
-> = {
-  /**
-   * CLI 定义；省略则该 action 不暴露为 CLI 子命令。
-   */
-  command?: ServiceActionCommand<P>;
-  /**
-   * HTTP API 定义；省略则该 action 不注册 HTTP 路由。
-   */
-  api?: ServiceActionApi<P>;
-  /**
-   * action 的实际执行函数。
-   */
-  execute: (params: {
-    /**
-     * 当前统一执行上下文。
-     */
-    context: AgentContext;
-    /**
-     * 当前 action 的结构化输入。
-     */
-    payload: P;
-    /**
-     * 当前 service 名称。
-     */
-    serviceName: string;
-    /**
-     * 当前 action 名称。
-     */
-    actionName: string;
-  }) => Promise<ServiceActionResult<R>> | ServiceActionResult<R>;
-};
-
-/**
- * Service action 映射。
- *
- * 关键点（中文）
- * - key 就是 action 名称。
- * - 使用对象结构，便于直接按名称索引和动态装配。
- */
-export type ServiceActions = {
-  [actionName: string]: ServiceAction<JsonValue, JsonValue>;
-};
-
-/**
- * Service 生命周期扩展能力。
- */
-export interface ServiceLifecycle {
-  /**
-   * service 启动钩子。
-   */
-  start?(context: AgentContext): Promise<void> | void;
-  /**
-   * service 停止钩子。
-   */
-  stop?(context: AgentContext): Promise<void> | void;
-  /**
-   * 非 action 命令分发钩子。
-   */
-  command?(params: {
-    /**
-     * 当前统一执行上下文。
-     */
-    context: AgentContext;
-    /**
-     * 当前命令名称。
-     */
-    command: string;
-    /**
-     * 可选 payload。
-     */
-    payload?: JsonValue;
-  }): Promise<ServiceCommandResult> | ServiceCommandResult;
-}
-
-/**
- * Service：服务统一契约。
- *
- * 关键点（中文）
- * - 一个 service 至少要提供稳定名称与 action 集合。
- * - 生命周期钩子与 system 构建器都是可选能力，不强制所有 service 实现。
- */
-export interface Service {
-  /**
-   * service 名称。
-   */
-  name: string;
-  /**
-   * action 集合。
-   *
-   * 关键点（中文）
-   * - 一个 service 对应多个 action。
-   * - main 会基于这里自动注册 CLI 与 HTTP 路由。
-   */
-  actions: ServiceActions;
-  /**
-   * service 级 system 文本构建器。
-   */
-  system?: (context: AgentContext) => string | Promise<string>;
-  /**
-   * service 生命周期钩子集合。
-   */
-  lifecycle?: ServiceLifecycle;
-}

package/src/shared/types/ServiceSchedule.ts

@@ -1,134 +0,0 @@
-/**
- * Service Schedule 类型定义。
- *
- * 关键点（中文）
- * - 统一描述“延迟/定时执行 service action”的持久化记录结构。
- * - 该模块只承载调度层状态，不耦合具体 service 的业务语义。
- */
-
-import type { JsonValue } from "@/shared/types/Json.js";
-
-/**
- * 调度任务状态。
- *
- * 说明（中文）
- * - `pending`：等待到点执行。
- * - `running`：已被调度器领取，当前正在执行。
- * - `succeeded`：执行成功。
- * - `failed`：执行失败。
- * - `cancelled`：已取消，不再执行。
- */
-export type ScheduledJobStatus =
-  | "pending"
-  | "running"
-  | "succeeded"
-  | "failed"
-  | "cancelled";
-
-/**
- * 调度任务完整记录。
- */
-export interface ScheduledJobRecord {
-  /**
-   * 调度任务唯一 ID。
-   *
-   * 说明（中文）
-   * - 由 runtime 创建并稳定持久化。
-   * - 用于取消、查询、状态更新与恢复。
-   */
-  id: string;
-
-  /**
-   * 目标 service 名称。
-   *
-   * 说明（中文）
-   * - 对应 `city <service> <action>` 中的 `<service>`。
-   */
-  serviceName: string;
-
-  /**
-   * 目标 action 名称。
-   *
-   * 说明（中文）
-   * - 对应 `city <service> <action>` 中的 `<action>`。
-   */
-  actionName: string;
-
-  /**
-   * 原始 action payload。
-   *
-   * 说明（中文）
-   * - 直接保存 service action 的 JSON payload。
-   * - 调度器到点后会原样回放给 `runServiceCommand(...)`。
-   */
-  payload: JsonValue;
-
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   *
-   * 说明（中文）
-   * - 统一归一化为 Unix epoch ms。
-   */
-  runAtMs: number;
-
-  /**
-   * 当前调度状态。
-   */
-  status: ScheduledJobStatus;
-
-  /**
-   * 最近一次错误文本。
-   *
-   * 说明（中文）
-   * - 仅在失败场景下写入。
-   */
-  error?: string;
-
-  /**
-   * 创建时间（毫秒时间戳）。
-   */
-  createdAt: number;
-
-  /**
-   * 最近更新时间（毫秒时间戳）。
-   */
-  updatedAt: number;
-}
-
-/**
- * 创建调度任务所需输入。
- */
-export interface CreateScheduledJobInput {
-  /**
-   * 目标 service 名称。
-   */
-  serviceName: string;
-
-  /**
-   * 目标 action 名称。
-   */
-  actionName: string;
-
-  /**
-   * 目标 action payload。
-   */
-  payload: JsonValue;
-
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   */
-  runAtMs: number;
-}
-
-/**
- * 统一 service command 调度输入。
- */
-export interface ServiceCommandScheduleInput {
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   *
-   * 说明（中文）
-   * - command 层统一只接收归一化后的绝对时间。
-   */
-  runAtMs: number;
-}

package/src/shared/types/ServiceState.ts

@@ -1,112 +0,0 @@
-/**
- * ServiceState：service 状态相关共享类型。
- *
- * 关键点（中文）
- * - 这里只放状态快照与控制结果，不放 service 契约本身。
- * - 目的是让 main/service 内部拆分后，仍能共享统一的状态结构。
- */
-
-import type { ServiceState } from "@/shared/types/Service.js";
-
-/**
- * 单个 service 实例内部持有的状态记录。
- *
- * 关键点（中文）
- * - 这是 service 实例级的内部状态，不直接暴露给外部 API。
- * - `ServiceStateController` 负责更新它，service 实例负责持有它。
- */
-export type ServiceStateRecord = {
-  /**
-   * 当前运行状态。
-   */
-  state: ServiceState;
-  /**
-   * 最近一次状态更新时间（毫秒时间戳）。
-   */
-  updatedAt: number;
-  /**
-   * 最近一次错误信息。
-   */
-  lastError?: string;
-  /**
-   * 最近一次执行的命令名。
-   */
-  lastCommand?: string;
-  /**
-   * 最近一次执行命令的时间（毫秒时间戳）。
-   */
-  lastCommandAt?: number;
-  /**
-   * 当前串行控制链。
-   *
-   * 关键点（中文）
-   * - 用于把同一 service 的 start/stop/restart 串行化。
-   * - 避免并发控制命令把状态机打乱。
-   */
-  chain: Promise<void>;
-};
-
-/**
- * 单个 service 状态的对外快照。
- */
-export type ServiceStateSnapshot = {
-  /**
-   * service 名称。
-   */
-  name: string;
-  /**
-   * 当前运行状态。
-   */
-  state: ServiceState;
-  /**
-   * 最近一次状态更新时间（毫秒时间戳）。
-   */
-  updatedAt: number;
-  /**
-   * 最近一次错误信息。
-   */
-  lastError?: string;
-  /**
-   * 最近一次执行的命令名。
-   */
-  lastCommand?: string;
-  /**
-   * 最近一次执行命令的时间（毫秒时间戳）。
-   */
-  lastCommandAt?: number;
-  /**
-   * 是否支持 start/stop 生命周期控制。
-   */
-  supportsLifecycle: boolean;
-  /**
-   * 是否支持 command/action 命令调用。
-   */
-  supportsCommand: boolean;
-};
-
-/**
- * service 状态控制动作。
- */
-export type ServiceStateControlAction =
-  | "start"
-  | "stop"
-  | "restart"
-  | "status";
-
-/**
- * service 状态控制结果。
- */
-export type ServiceStateControlResult = {
-  /**
-   * 控制动作是否成功。
-   */
-  success: boolean;
-  /**
-   * 成功或失败后返回的最新 service 快照。
-   */
-  service?: ServiceStateSnapshot;
-  /**
-   * 失败时的错误信息。
-   */
-  error?: string;
-};

package/src/shared/types/Services.ts

@@ -1,100 +0,0 @@
-/**
- * service 管理命令类型。
- *
- * 关键点（中文）
- * - 统一描述 CLI -> daemon 的 service 管理协议
- * - 支持 lifecycle 控制与通用 command 转发
- */
-
-import type { JsonValue } from "@/shared/types/Json.js";
-
-export type ServiceControlAction = "start" | "stop" | "restart" | "status";
-
-/**
- * 单个 service 的对外状态视图。
- */
-export type ServiceStateView = {
-  /** service 稳定名称。 */
-  name: string;
-  /** 当前运行状态。 */
-  state: "running" | "stopped" | "starting" | "stopping" | "error";
-  /** 最近一次状态更新时间（毫秒时间戳）。 */
-  updatedAt: number;
-  /** 最近一次错误信息。 */
-  lastError?: string;
-  /** 最近一次执行的命令名称。 */
-  lastCommand?: string;
-  /** 最近一次执行命令的时间（毫秒时间戳）。 */
-  lastCommandAt?: number;
-  /** 当前 service 是否支持显式 start/stop 生命周期控制。 */
-  supportsLifecycle: boolean;
-  /** 当前 service 是否支持 command/action 调用。 */
-  supportsCommand: boolean;
-};
-
-/**
- * service 列表响应。
- */
-export type ServiceListResponse = {
-  /** 本次读取是否成功。 */
-  success: boolean;
-  /** 成功时返回的 service 状态列表。 */
-  services?: ServiceStateView[];
-  /** 失败时返回的错误信息。 */
-  error?: string;
-};
-
-/**
- * service 生命周期控制响应。
- */
-export type ServiceControlResponse = {
-  /** 本次控制动作是否成功。 */
-  success: boolean;
-  /** 成功时返回最新的 service 状态视图。 */
-  service?: ServiceStateView;
-  /** 失败时的错误信息。 */
-  error?: string;
-};
-
-/**
- * service command/action 执行响应。
- */
-export type ServiceCommandResponse = {
-  /** 本次 command/action 是否执行成功。 */
-  success: boolean;
-  /** 当前 service 的最新状态视图。 */
-  service?: ServiceStateView;
-  /** 面向人类可读的补充文本。 */
-  message?: string;
-  /** command/action 的数据输出。 */
-  data?: JsonValue;
-  /** 失败时的错误信息。 */
-  error?: string;
-};
-
-export type ServiceCliBaseOptions = {
-  /**
-   * agent 项目路径（默认当前目录）。
-   */
-  path?: string;
-  /**
-   * agent 名称（从 managed agent registry 解析到项目路径）。
-   */
-  agent?: string;
-  /**
-   * 覆盖服务主机地址。
-   */
-  host?: string;
-  /**
-   * 覆盖服务端口。
-   */
-  port?: number;
-  /**
-   * 显式覆盖 Bearer Token。
-   */
-  token?: string;
-  /**
-   * 是否输出 JSON。
-   */
-  json?: boolean;
-};