@downcity/agent 1.1.408 → 1.1.437

package/src/plugin/core/ActionScheduleStore.ts

@@ -1,414 +0,0 @@
-/**
- * ActionSchedule 持久化存储。
- *
- * 关键点（中文）
- * - ActionSchedule 是 plugin action 的延迟执行能力，不是一个独立 plugin。
- * - 任务使用项目内 `jsonl` 事件流持久化，不再依赖 SQLite。
- * - 这里采用“全量重放 + 内存归并”的最简实现，保持职责清晰且易于迁移。
- * - 文件只记录状态事件；对外仍暴露稳定的调度任务查询与状态更新接口。
- */
-
-import type {
-  ActionScheduleJobRecord,
-  ActionScheduleJobStatus,
-  CreateActionScheduleJobInput,
-} from "@/plugin/types/ActionSchedule.js";
-import { generate_id } from "@/utils/Id.js";
-import { get_downcity_schedule_db_path } from "@/workspace/WorkspacePaths.js";
-import type { FileSystem } from "@downcity/workspace";
-
-type ActionScheduleJobEvent =
-  | {
-      /**
-       * 事件版本号。
-       */
-      v: 1;
-      /**
-       * 事件类型：创建任务。
-       */
-      type: "created";
-      /**
-       * ActionSchedule 任务快照。
-       */
-      job: ActionScheduleJobRecord;
-    }
-  | {
-      /**
-       * 事件版本号。
-       */
-      v: 1;
-      /**
-       * 事件类型：状态更新。
-       */
-      type: "status";
-      /**
-       * 目标任务 ID。
-       */
-      job_id: string;
-      /**
-       * 新状态。
-       */
-      status: ActionScheduleJobStatus;
-      /**
-       * 最新更新时间。
-       */
-      updated_at: number;
-      /**
-       * 可选错误信息。
-       */
-      error?: string;
-    };
-
-async function read_jsonl_lines(
-  files: FileSystem,
-  file_path: string,
-): Promise<string[]> {
-  if (!(await files.path_exists(file_path))) return [];
-  const raw = (await files.read_file(file_path)).toString("utf8");
-  return raw
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-}
-
-function normalizeJobRecord(
-  input: ActionScheduleJobRecord,
-): ActionScheduleJobRecord {
-  return {
-    id: String(input.id || "").trim(),
-    agent_id: String(input.agent_id || "").trim(),
-    workspace_id: String(input.workspace_id || "").trim(),
-    plugin_name: String(input.plugin_name || "").trim(),
-    action_name: String(input.action_name || "").trim(),
-    payload: input.payload ?? null,
-    run_at_ms: Math.trunc(input.run_at_ms),
-    status: input.status,
-    ...(typeof input.error === "string" && input.error
-      ? { error: input.error }
-      : {}),
-    created_at: Math.trunc(input.created_at),
-    updated_at: Math.trunc(input.updated_at),
-  };
-}
-
-function parseEvent(line: string): ActionScheduleJobEvent | null {
-  try {
-    const raw = JSON.parse(line) as Partial<ActionScheduleJobEvent> | null;
-    if (!raw || typeof raw !== "object") return null;
-    if (raw.type === "created" && raw.job) {
-      return {
-        v: 1,
-        type: "created",
-        job: normalizeJobRecord(raw.job as ActionScheduleJobRecord),
-      };
-    }
-    if (
-      raw.type === "status" &&
-      typeof raw.job_id === "string" &&
-      typeof raw.status === "string" &&
-      typeof raw.updated_at === "number"
-    ) {
-      return {
-        v: 1,
-        type: "status",
-        job_id: raw.job_id,
-        status: raw.status as ActionScheduleJobStatus,
-        updated_at: Math.trunc(raw.updated_at),
-        ...(typeof raw.error === "string" ? { error: raw.error } : {}),
-      };
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-function compareJobs(
-  a: ActionScheduleJobRecord,
-  b: ActionScheduleJobRecord,
-): number {
-  if (a.run_at_ms !== b.run_at_ms) return a.run_at_ms - b.run_at_ms;
-  return b.created_at - a.created_at;
-}
-
-/**
- * ActionSchedule Store。
- */
-export class ActionScheduleStore {
-  private readonly file_path: string;
-  private readonly lock_path: string;
-  private readonly files: FileSystem;
-  private readonly agent_id: string;
-  private readonly default_workspace_id?: string;
-
-  constructor(
-    files: FileSystem,
-    storage_root_path: string,
-    agent_id: string,
-    default_workspace_id?: string,
-  ) {
-    this.files = files;
-    this.agent_id = String(agent_id || "").trim();
-    if (!this.agent_id) {
-      throw new Error("ActionScheduleStore requires agent_id");
-    }
-    this.default_workspace_id = String(default_workspace_id || "").trim() || undefined;
-    this.file_path = get_downcity_schedule_db_path(storage_root_path);
-    this.lock_path = `${this.file_path}.lock`;
-  }
-
-  /**
-   * 关闭存储。
-   *
-   * 说明（中文）
-   * - jsonl 版本无需保持长连接，因此 close 为 no-op。
-   */
-  close(): void {}
-
-  /**
-   * 创建调度任务。
-   */
-  async create_job(input: CreateActionScheduleJobInput): Promise<ActionScheduleJobRecord> {
-    const now = Date.now();
-    const job: ActionScheduleJobRecord = {
-      id: `sched_${generate_id()}`,
-      agent_id: this.agent_id,
-      workspace_id: String(input.workspace_id || this.default_workspace_id || "").trim(),
-      plugin_name: String(input.plugin_name || "").trim(),
-      action_name: String(input.action_name || "").trim(),
-      payload: input.payload ?? null,
-      run_at_ms: Math.trunc(input.run_at_ms),
-      status: "pending",
-      created_at: now,
-      updated_at: now,
-    };
-    await this.with_store_lock(async () => {
-      await this.append_event_unlocked({
-        v: 1,
-        type: "created",
-        job,
-      });
-    });
-    return job;
-  }
-
-  /**
-   * 获取单个任务。
-   */
-  async get_job_by_id(job_id: string): Promise<ActionScheduleJobRecord | null> {
-    const key = String(job_id || "").trim();
-    if (!key) return null;
-    return await this.with_store_lock(async () => {
-      const job = (await this.read_job_map_unlocked()).get(key);
-      return job && this.owns_job(job) ? job : null;
-    });
-  }
-
-  /**
-   * 列出指定状态的任务。
-   */
-  async list_jobs_by_status(
-    statuses: ActionScheduleJobStatus[],
-  ): Promise<ActionScheduleJobRecord[]> {
-    if (statuses.length === 0) return [];
-    const allowed = new Set(statuses);
-    return await this.with_store_lock(async () =>
-      (await this.read_jobs_unlocked())
-        .filter((job) => this.owns_job(job) && allowed.has(job.status))
-        .sort(compareJobs)
-    );
-  }
-
-  /**
-   * 列出任务。
-   */
-  async list_jobs(params?: {
-    status?: ActionScheduleJobStatus;
-    limit?: number;
-  }): Promise<ActionScheduleJobRecord[]> {
-    const limit =
-      typeof params?.limit === "number" && Number.isFinite(params.limit)
-        ? Math.max(1, Math.trunc(params.limit))
-        : 100;
-    return await this.with_store_lock(async () => {
-      const jobs = (await this.read_jobs_unlocked())
-        .filter((job) =>
-          this.owns_job(job) &&
-          (!params?.status || job.status === params.status)
-        )
-        .sort(compareJobs);
-      return jobs.slice(0, limit);
-    });
-  }
-
-  /**
-   * 列出已到点且待执行的任务。
-   */
-  async list_due_pending_jobs(nowMs: number): Promise<ActionScheduleJobRecord[]> {
-    return await this.with_store_lock(async () =>
-      (await this.read_jobs_unlocked())
-        .filter(
-          (job) =>
-            this.owns_job(job) &&
-            job.status === "pending" &&
-            job.run_at_ms <= Math.trunc(nowMs),
-        )
-        .sort(compareJobs)
-    );
-  }
-
-  /**
-   * 启动恢复时，把历史 `running` 回退到 `pending`。
-   */
-  async reset_running_jobs_to_pending(): Promise<number> {
-    return await this.with_store_lock(async () => {
-      const running_jobs = (await this.read_jobs_unlocked())
-        .filter((job) => this.owns_job(job) && job.status === "running");
-      const now = Date.now();
-      for (const job of running_jobs) {
-        await this.append_event_unlocked({
-          v: 1,
-          type: "status",
-          job_id: job.id,
-          status: "pending",
-          updated_at: now,
-        });
-      }
-      return running_jobs.length;
-    });
-  }
-
-  /**
-   * 将任务标记为执行中。
-   */
-  async mark_job_running(job_id: string): Promise<boolean> {
-    return await this.transition_pending_job(job_id, "running");
-  }
-
-  /**
-   * 将任务标记为成功。
-   */
-  async mark_job_succeeded(job_id: string): Promise<boolean> {
-    return await this.update_terminal_status({
-      job_id,
-      status: "succeeded",
-    });
-  }
-
-  /**
-   * 将任务标记为失败。
-   */
-  async mark_job_failed(job_id: string, error: string): Promise<boolean> {
-    return await this.update_terminal_status({
-      job_id,
-      status: "failed",
-      error,
-    });
-  }
-
-  /**
-   * 取消待执行任务。
-   */
-  async cancel_pending_job(job_id: string): Promise<boolean> {
-    return await this.transition_pending_job(job_id, "cancelled");
-  }
-
-  /**
-   * 仅读取当前任务快照。
-   */
-  private async read_jobs_unlocked(): Promise<ActionScheduleJobRecord[]> {
-    return [...(await this.read_job_map_unlocked()).values()];
-  }
-
-  /**
-   * 重放事件流，构造当前任务快照。
-   */
-  private async read_job_map_unlocked(): Promise<Map<string, ActionScheduleJobRecord>> {
-    const jobs = new Map<string, ActionScheduleJobRecord>();
-    for (const line of await read_jsonl_lines(this.files, this.file_path)) {
-      const event = parseEvent(line);
-      if (!event) continue;
-      if (event.type === "created") {
-        jobs.set(event.job.id, normalizeJobRecord(event.job));
-        continue;
-      }
-      const current = jobs.get(event.job_id);
-      if (!current) continue;
-      jobs.set(event.job_id, {
-        ...current,
-        status: event.status,
-        updated_at: event.updated_at,
-        ...(event.error ? { error: event.error } : {}),
-        ...(event.status === "succeeded" || event.status === "cancelled"
-          ? { error: undefined }
-          : {}),
-      });
-    }
-    return jobs;
-  }
-
-  /**
-   * 追加单条事件。
-   */
-  private async append_event_unlocked(event: ActionScheduleJobEvent): Promise<void> {
-    await this.files.append_file(this.file_path, `${JSON.stringify(event)}\n`);
-  }
-
-  /** 使用 Workspace 跨进程锁串行执行一次调度存储事务。 */
-  private async with_store_lock<T>(action: () => Promise<T>): Promise<T> {
-    return await this.files.with_file_lock(this.lock_path, action);
-  }
-
-  /**
-   * 执行 pending -> target 的状态迁移。
-   */
-  private async transition_pending_job(
-    job_id: string,
-    status: "running" | "cancelled",
-  ): Promise<boolean> {
-    return await this.with_store_lock(async () => {
-      const current = (await this.read_job_map_unlocked()).get(job_id);
-      if (!current || !this.owns_job(current) || current.status !== "pending") {
-        return false;
-      }
-      await this.append_event_unlocked({
-        v: 1,
-        type: "status",
-        job_id: current.id,
-        status,
-        updated_at: Date.now(),
-      });
-      return true;
-    });
-  }
-
-  /**
-   * 统一写入终态。
-   */
-  private async update_terminal_status(params: {
-    job_id: string;
-    status: Exclude<ActionScheduleJobStatus, "pending" | "running">;
-    error?: string;
-  }): Promise<boolean> {
-    return await this.with_store_lock(async () => {
-      const current = (await this.read_job_map_unlocked()).get(params.job_id);
-      if (!current || !this.owns_job(current) || current.status !== "running") {
-        return false;
-      }
-      await this.append_event_unlocked({
-        v: 1,
-        type: "status",
-        job_id: current.id,
-        status: params.status,
-        updated_at: Date.now(),
-        ...(params.error ? { error: String(params.error) } : {}),
-      });
-      return true;
-    });
-  }
-
-  /** 判断任务是否属于当前 Agent 的调度视图。 */
-  private owns_job(job: ActionScheduleJobRecord): boolean {
-    return job.agent_id === this.agent_id;
-  }
-}

package/src/plugin/core/ActionScheduleTime.ts

@@ -1,132 +0,0 @@
-/**
- * ActionSchedule 时间解析工具。
- *
- * 关键点（中文）
- * - 统一解析 plugin action 通用 `--delay` / `--time` 参数。
- * - 输出统一毫秒时间戳，供 command 请求解析与持久化层复用。
- * - 该模块只处理“action 延迟执行时间”，不表达独立 schedule plugin。
- */
-
-/**
- * 判断是否为“缺少时区”的 ISO 时间字符串。
- */
-function looksLikeIsoDatetimeWithoutTimezone(value: string): boolean {
-  const text = String(value || "").trim();
-  if (!text) return false;
-  const isoLike = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(text);
-  if (!isoLike) return false;
-  return !/(?:Z|[+-]\d{2}:\d{2})$/i.test(text);
-}
-
-/**
- * 解析非负整数。
- */
-function parseNonNegativeIntOptionOrThrow(value: string, fieldName: string): number {
-  const text = String(value || "").trim();
-  if (!text) {
-    throw new Error(`${fieldName} is required`);
-  }
-  if (!/^\d+$/.test(text)) {
-    throw new Error(`Invalid ${fieldName}: ${value}`);
-  }
-  const parsed = Number.parseInt(text, 10);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
-    throw new Error(`Invalid ${fieldName}: ${value}`);
-  }
-  return parsed;
-}
-
-/**
- * 解析绝对执行时间。
- *
- * 支持格式（中文）
- * - Unix 时间戳秒/毫秒
- * - ISO 时间字符串（必须显式带时区）
- */
-export function parse_schedule_time_option_or_throw(
-  value: string,
-  fieldName: string,
-): number {
-  const text = String(value || "").trim();
-  if (!text) {
-    throw new Error(`${fieldName} is required`);
-  }
-
-  if (/^\d+$/.test(text)) {
-    const parsed = Number.parseInt(text, 10);
-    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-      throw new Error(`Invalid ${fieldName}: ${value}`);
-    }
-    return parsed < 1_000_000_000_000 ? parsed * 1000 : parsed;
-  }
-
-  if (looksLikeIsoDatetimeWithoutTimezone(text)) {
-    throw new Error(
-      `Invalid ${fieldName}: ${value}. ISO datetime must include timezone offset (e.g. +08:00 or Z).`,
-    );
-  }
-
-  const parsed = Date.parse(text);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-    throw new Error(
-      `Invalid ${fieldName}: ${value}. Use Unix timestamp (seconds/ms) or ISO datetime.`,
-    );
-  }
-  return parsed;
-}
-
-/**
- * 解析 command 层调度输入并归一化为绝对毫秒时间戳。
- *
- * 说明（中文）
- * - `delay_ms` 与 `time` 只能二选一。
- * - 未传时返回 `undefined`，表示立即执行。
- */
-export function parse_action_schedule_run_at_ms_or_throw(params: {
-  delay?: string | number | undefined;
-  time?: string | number | undefined;
-}): number | undefined {
-  const delayText =
-    params.delay === undefined || params.delay === null
-      ? ""
-      : String(params.delay).trim();
-  const timeText =
-    params.time === undefined || params.time === null
-      ? ""
-      : String(params.time).trim();
-
-  if (delayText && timeText) {
-    throw new Error("`--delay` and `--time` cannot be used together.");
-  }
-
-  if (delayText) {
-    return Date.now() + parseNonNegativeIntOptionOrThrow(delayText, "delay");
-  }
-
-  if (timeText) {
-    return parse_schedule_time_option_or_throw(timeText, "time");
-  }
-
-  return undefined;
-}
-
-/**
- * 规范化 API/存储层传入的 run_at_ms。
- */
-export function normalize_run_at_ms_or_throw(
-  value: string | number | undefined,
-  fieldName: string,
-): number {
-  const text = String(value ?? "").trim();
-  if (!text) {
-    throw new Error(`${fieldName} is required`);
-  }
-  if (!/^\d+$/.test(text)) {
-    throw new Error(`Invalid ${fieldName}: ${String(value)}`);
-  }
-  const parsed = Number.parseInt(text, 10);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-    throw new Error(`Invalid ${fieldName}: ${String(value)}`);
-  }
-  return parsed;
-}

package/src/plugin/core/BasePlugin.ts

@@ -1,79 +0,0 @@
-/**
- * BasePlugin：统一 plugin 类基座。
- *
- * 关键点（中文）
- * - 主动运行型能力与被动扩展型能力统一收敛到 plugin 概念。
- * - plugin 的长期状态归属于实例本身，而不是模块级单例。
- * - Agent 注册 plugin 时自动启动 lifecycle；卸载时自动停止 lifecycle。
- */
-
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type { PluginActions } from "@/types/plugin/PluginAction.js";
-import type { PluginLifecycle } from "@/types/plugin/PluginCommand.js";
-import type {
-  PluginAvailability,
-  PluginHooks,
-  PluginResolves,
-} from "@/types/plugin/PluginRuntime.js";
-import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
-
-/**
- * BasePlugin 抽象基类。
- */
-export abstract class BasePlugin implements Plugin {
-  /**
-   * 当前 plugin 名称。
-   */
-  abstract readonly name: string;
-
-  /**
-   * 插件标题。
-   */
-  readonly title: string = "";
-
-  /**
-   * 插件说明。
-   */
-  readonly description: string = "";
-
-  /**
-   * 显式 action 集合。
-   */
-  readonly actions: PluginActions = {};
-
-  /**
-   * pipeline / guard / effect 扩展点。
-   */
-  readonly hooks?: PluginHooks;
-
-  /**
-   * resolve 扩展点。
-   */
-  readonly resolves?: PluginResolves;
-
-  /**
-   * HTTP 路由扩展。
-   */
-  readonly http?: PluginHttpDefinition;
-
-  /** Plugin 生命周期钩子。 */
-  lifecycle?: PluginLifecycle;
-
-  /**
-   * Plugin 可用性检查。
-   */
-  availability?(
-    context: PluginContext,
-  ): Promise<PluginAvailability> | PluginAvailability;
-
-  /**
-   * Plugin system 文本提供器。
-   */
-  system?(
-    context: PluginContext,
-    execution_context?: PluginExecutionContext,
-  ): Promise<string> | string;
-
-}