@ai-setting/roy-agent-core 1.7.66 → 1.7.68

package/dist/env/task/plugins/laya-completion-plugin.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Task #4760 — task completion hook 的 Laya decision 判定
+ *
+ * 与 create 侧（`laya-decision-plugin.ts`，#4620）的关系：
+ *   - create 侧挂在 `task:before.create`，判「新建 vs 复用」
+ *   - 本插件挂在 `task:after.complete`（AFTER_COMPLETE），判
+ *     「目标 vs 交付物 match / 目标是否达成 / 交付物是否产出」
+ *
+ * 形态：**只提示，不拦截**（与 create 侧契约一致）。
+ *   AFTER_COMPLETE 触发时任务**已经**是 completed —— hint 只能
+ *   ① 追加写进 `task.context.completion_hint`（走 updateTask）
+ *   ② 落一条 operation 记录
+ *   绝不能阻断已完成状态、绝不能抛错。
+ *
+ * ── fail-open 六场景（对齐 create 侧 #4620） ─────────────────────
+ *   1. 未配置 provider（auth.json 缺失 / 无 laya-goal-decision）→ 不调模型
+ *   2. auth 损坏 / port 抛错（网络、超时）→ 静默
+ *   3. 响应畸形（无 answers / 无 answer）→ 静默
+ *   4. 置信度 < 0.92 → 不写 hint
+ *   5. operation chain 空 → 不调模型
+ *   6. choice 无法识别 → 静默
+ *
+ * ── provider 分离（Task #4804） ────────────────────────────────
+ *   completion hook 读 `providers["laya-goal-decision"]`
+ *   （model=task-completion / v13e ckpt，判「目标 vs 交付物」）；
+ *   create hook 继续读 `providers["laya-decision"]`
+ *   （model=task-decision / v3-tags，判「新建 vs 复用」）。
+ *   goal 专用 provider 缺失时保守回退 laya-decision（fail-open 不变）。
+ *
+ * ── 泄漏断言 ─────────────────────────────────────────────────────
+ *   deny-list 含 decision/hint/target/answer 等键名 →
+ *   question key 必须命名 `completion_check`、criteria 用
+ *   `PASS_COMPLETED/FAIL_INCOMPLETE`（已验证不命中）；
+ *   state 用中文文本形态（【】段）则天然无对象键。
+ *
+ * ── 时序关键（勘查结论） ─────────────────────────────────────────
+ *   AFTER_COMPLETE 触发时 `completed` operation 尚未写入
+ *   （completeTask 在 hook 之后才 createOperation）。
+ *   因此 operation chain 里看到的是「完成前的历史记录」——
+ *   这正是判定所需的证据链，无需等 completed 记录。
+ */
+import type { DecisionPort } from "./decision-port";
+import type { TaskCompleteResultContext } from "../hooks/contexts";
+import type { Task, TaskOperation } from "../types";
+/** 完成判定的置信度门禁（对齐 create 侧 LAYA_REUSE_THRESHOLD = 0.92） */
+export declare const LAYA_COMPLETION_THRESHOLD = 0.92;
+/**
+ * 构造完成核验 hint。
+ *
+ * 核实义务 + 二选一：(a) 确认未完成 → 重开继续推进；
+ * (b) 确认已完成 → 落 operation 说明理由。不允许无视。
+ */
+export declare function buildCompletionHint(task: Task, confidence: number): string;
+/**
+ * 渲染 laya 训练格式的中文文本 state。
+ *
+ * ⚠️ 用【】段而非 JSON 对象 —— laya 模型在中文文本形态上训练；
+ *   且文本形态天然没有对象键，不会命中泄漏断言的 deny-list。
+ *
+ * Task #4804 — goals 为编号子项且交付物声明可比对时，插入
+ * 【逐条对照】段（见 renderCriteriaChecklist 注释）。
+ */
+export declare function renderCompletionState(task: Task, ops: TaskOperation[]): string;
+/** 渲染 completion_check 二选一 question（key 不命中泄漏 deny-list） */
+export declare function buildCompletionQuestion(): Record<string, unknown>;
+export interface LayaCompletionPluginOptions {
+    /** auth.json 路径（默认 ~/.roy-agent/auth.json） */
+    authPath?: string;
+    /** 硬超时（默认 2000ms） */
+    timeoutMs?: number;
+    /** 连续超时多少次后自我禁用（默认 3） */
+    maxStrikes?: number;
+    /** 注入 port（测试用；给了就不读 auth.json） */
+    decisionPort?: DecisionPort;
+    /** 完成判定的置信度门禁（默认 0.92） */
+    completionThreshold?: number;
+}
+export declare class LayaCompletionPlugin {
+    readonly name = "laya-completion";
+    readonly version = "1.0.0";
+    readonly description = "Task #4760 \u2014 task:after.complete \u5B8C\u6210\u5224\u5B9A\uFF08\u76EE\u6807/\u4EA4\u4ED8\u7269 match\uFF0C\u53EA\u63D0\u793A\u4E0D\u62E6\u622A\uFF09";
+    private readonly options;
+    private port;
+    private portResolved;
+    constructor(options?: LayaCompletionPluginOptions);
+    /** 当前是否已自我禁用（熔断）—— 供观测 */
+    isDisabled(): boolean;
+    /** 懒加载 + 缓存 port（读 auth.json 只做一次） */
+    private resolvePort;
+    /**
+     * hook 入口 —— **永不抛**。
+     *
+     * @param ctx   TaskCompleteResultContext（或框架 HookContext，载荷在 .data）
+     * @param taskComponent TaskComponent（只读用：listOperations / getTask；
+     *                      写 hint 用 updateTask + createOperation）
+     */
+    execute(ctx: TaskCompleteResultContext | {
+        data: TaskCompleteResultContext;
+    }, taskComponent: any): Promise<void>;
+    private run;
+    /** hint 回写：追加 context.completion_hint + 落 operation 记录（都不阻断） */
+    private writeHint;
+}
+/**
+ * Task #4760 — 把 LayaCompletionPlugin 包成可注册到 task hook 的形态。
+ *
+ * 注册方式仿 `registerLayaDecisionTaskHook`（environment.ts:87）：
+ *   - unregister + register 幂等（globalHookManager.register 是 push）
+ *   - fail-open：注册失败绝不影响 agent 启动
+ *   - hook-manager `safeExecute` 自带异常隔离（hook 抛错只记日志）
+ */
+export declare function createLayaCompletionPlugin(options?: LayaCompletionPluginOptions): {
+    /** Hook 唯一名称（用于幂等去重 / unregister） */
+    name: string;
+    /** 执行优先级 */
+    priority: number;
+    /** hook 执行体 —— 永不抛 */
+    execute: (ctx: unknown) => Promise<void>;
+    /** 内层插件实例（供观测 / 测试） */
+    plugin: LayaCompletionPlugin;
+};
+/**
+ * 把 LayaCompletionPlugin 注册到 `task:after.complete`（AFTER_COMPLETE）。
+ *
+ * ⚠️ 幂等：先 unregister 再 register，保证全局恰好 1 份。
+ * ⚠️ fail-open：注册失败返回 false，不影响调用方。
+ *
+ * @param taskComponent TaskComponent（由 this.getComponent("task") 取得）
+ * @param options LayaCompletionPluginOptions（生产不传 → 读 auth.json；
+ *                测试可注入 decisionPort）
+ * @returns 是否成功注册
+ */
+export declare function registerLayaCompletionTaskHook(taskComponent: any | undefined | null, options?: LayaCompletionPluginOptions): boolean;

package/dist/env/task/plugins/laya-port.d.ts

@@ -131,6 +131,17 @@ export interface LayaAuthConfig {
     apiKey: string;
     model: string;
 }
+/**
+ * Task #4804 — provider 名常量（provider 分离）：
+ *   - create hook（task:before.create，判新建 vs 复用）→ laya-decision
+ *   - completion hook（task:after.complete，判目标 vs 交付物）→ laya-goal-decision
+ *     （缺失时保守回退 laya-decision —— fail-open 语义不变）
+ */
+export declare const LAYA_DECISION_PROVIDER = "laya-decision";
+export declare const LAYA_GOAL_DECISION_PROVIDER = "laya-goal-decision";
+/** hook 用途 → provider 名（Task #4804 provider 分离的唯一映射点） */
+export type LayaHookPurpose = "create" | "goal";
+export declare function providerNameForPurpose(purpose: LayaHookPurpose): string;
 /**
  * 从 `~/.roy-agent/auth.json` 的 `providers["laya-decision"]` 读取端点配置。
  *
@@ -139,5 +150,17 @@ export interface LayaAuthConfig {
  *                                  → providers["laya-decision"].model（可选）
  *
  * ⚠️ 读不到就返回 null —— 调用方必须 fail-open（不提示、不报错）。
+ *
+ * Task #4804 — 向后兼容：默认仍读 laya-decision（create hook 语义）。
+ *   completion hook 侧请用 `loadLayaAuthForPurpose(path, "goal")`。
  */
 export declare function loadLayaAuth(authPath?: string): Promise<LayaAuthConfig | null>;
+/**
+ * Task #4804 — 按用途读 provider：
+ *   - "create" → providers["laya-decision"]
+ *   - "goal"   → providers["laya-goal-decision"]，缺失时保守回退
+ *                providers["laya-decision"]（共享共享配置，fail-open 不变）
+ *
+ * ⚠️ 读不到就返回 null —— 调用方必须 fail-open（不提示、不报错）。
+ */
+export declare function loadLayaAuthForPurpose(authPath?: string, purpose?: LayaHookPurpose): Promise<LayaAuthConfig | null>;

package/dist/env/task/task-component.d.ts

@@ -41,6 +41,21 @@ export interface TaskComponentOptions {
     envPrefix?: string;
     /** 直接传入的配置对象（可选，优先级最高） */
     config?: Partial<TaskConfig>;
+    /**
+     * Task #4794 — 组件 stop() 时 BackgroundTaskManager.dispose() 的收尾行为。
+     *
+     * CLI `act` 一次性命令收尾时传 true（主 run 已结束，后台子 agent
+     * 是有意留下继续跑的）；REPL / ESC cascade 等用户主动退出场景
+     * 保持默认 false（abort 全部，语义不变）。
+     */
+    skipAbortRunningTasksOnDispose?: boolean;
+    /**
+     * Task #4794 — 与 skipAbortRunningTasksOnDispose 配套：
+     * stop() 时等待运行中的后台任务完成后再返回。
+     * 子 agent 是同进程异步 run，进程 exit 会直接杀死它们，
+     * 所以 act 收尾必须等待。默认 false。
+     */
+    waitForRunningTasksOnDispose?: boolean;
 }
 export declare class TaskComponent extends BaseComponent {
     name: string;
@@ -49,6 +64,17 @@ export declare class TaskComponent extends BaseComponent {
     private config?;
     private toolComponent?;
     private backgroundTaskManager?;
+    /**
+     * Task #4794 — stop() 时是否跳过 abort 仍在运行的后台任务
+     * （act 一次性命令收尾 = true；用户主动退出 = false 默认）。
+     */
+    private skipAbortRunningTasksOnDispose;
+    /**
+     * Task #4794 — stop() 时是否等待运行中任务完成
+     * （act 收尾配套：跳过 abort 后必须等子 agent 跑完，
+     * 否则 process.exit 仍会杀死同进程子 agent）。
+     */
+    private waitForRunningTasksOnDispose;
     private configComponent?;
     private tagService;
     private plugins;
@@ -235,6 +261,23 @@ export declare class TaskComponent extends BaseComponent {
      * @returns 更新后的 Task 或 undefined
      */
     completeTask(id: number, sessionId: string, deliverableStoragePath?: string): Promise<Task | undefined>;
+    /**
+     * 直接更新任务 context（不触发 BEFORE/AFTER_UPDATE hook、不发事件）
+     *
+     * ★ Task #4776 review MINOR-1：AFTER_COMPLETE hook 内的嵌套
+     *   updateTask({context}) 会二次 fire AFTER_UPDATE，把订阅者
+     *   （LarkCliTaskNotifyHook 等）无谓拉起 —— 终态任务被再次走
+     *   cardStatusOf 终态路径。hint 回写这类「内部簿记」不应有通知副作用，
+     *   因此提供本方法绕过 hook 链，直接走 store 层。
+     *
+     * 语义与 updateTask({context}) 完全一致：整份覆盖 context 字段。
+     * 调用方负责自己 merge 既有字段（不要拿快照整份覆盖别人写的内容）。
+     *
+     * @param id 任务 ID
+     * @param context 新的 context JSON 字符串（整份覆盖）
+     * @returns 更新后的 Task，任务不存在时返回 undefined
+     */
+    updateTaskContext(id: number, context: string): Promise<Task | undefined>;
     /**
      * Create operation record
      */

package/dist/env/task/tools/completion-copy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Task #4834 — F3: task_complete 验收文案同源锚点
+ *
+ * 背景（reports/goals-criteria-rules-e2e-rebase.md §遗留 F3）：
+ *   prompts-index.ts 的 COMPLETE 生命周期步骤与工具描述
+ *   （TASK_COMPLETE_DESCRIPTION）**不同源** —— 文案漂移会
+ *   稀释工具描述的遵循度。
+ *
+ * 方案：三个关键短语定义于此，complete-tool 与
+ * prompts-index（default prompt）都引用同一常量，
+ * 文案一致性由 completion-copy-consistency.test.ts 守住。
+ *
+ * ⚠️ 本模块必须保持**零依赖**（不 import 任何其他模块），
+ *   以便 prompts-index（超大模板串）与 tools 层都能安全引用。
+ */
+/** 逐条验收短语（工具描述 / default prompt 共用） */
+export declare const TASK_COMPLETE_ITEM_BY_ITEM = "\u6309\u5B50\u9879\u9010\u6761\u9A8C\u6536";
+/** hint 锚点 token（completion hook 写入 task context 的标记） */
+export declare const TASK_COMPLETION_HINT_ANCHOR = "TASK_COMPLETION_HINT";
+/** 核实义务短语（收到 hint 后必须核实，二选一） */
+export declare const TASK_COMPLETE_VERIFY_DUTY = "\u6838\u5B9E\u4E49\u52A1";
+/** F3 同源文案集合（聚合导出，便于测试解构） */
+export declare const TASK_COMPLETE_ACCEPTANCE: {
+    readonly itemByItem: "按子项逐条验收";
+    readonly hintAnchor: "TASK_COMPLETION_HINT";
+    readonly verifyDuty: "核实义务";
+};

package/dist/env/task/tools/index.js

@@ -9,8 +9,9 @@ import {
   searchTasksTool,
   treeTasksTool,
   updateTaskTool
-} from "../../../shared/@ai-setting/roy-agent-core-t0ktaevq.js";
+} from "../../../shared/@ai-setting/roy-agent-core-h5vmff8w.js";
 import"../../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
+import"../../../shared/@ai-setting/roy-agent-core-6m4bw8jy.js";
 import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
 import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
 import"../../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";

package/dist/env/workflow/plugins/index.js

@@ -1,8 +1,8 @@
 import {
   LarkCliWorkflowNotifyHook,
   createLarkCliWorkflowNotifyHook
-} from "../../../shared/@ai-setting/roy-agent-core-0ys85x46.js";
-import"../../../shared/@ai-setting/roy-agent-core-zk2jg0v7.js";
+} from "../../../shared/@ai-setting/roy-agent-core-8bjj3d1b.js";
+import"../../../shared/@ai-setting/roy-agent-core-tadj19vp.js";
 import"../../../shared/@ai-setting/roy-agent-core-c2gbt68e.js";
 import"../../../shared/@ai-setting/roy-agent-core-ax9e9szb.js";
 import"../../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";

package/dist/index.js

@@ -31,7 +31,7 @@ import"./shared/@ai-setting/roy-agent-core-adg9ghbt.js";
 import {
   PromptComponent,
   PromptStore
-} from "./shared/@ai-setting/roy-agent-core-cvm1xgmg.js";
+} from "./shared/@ai-setting/roy-agent-core-wksgtqf9.js";
 import {
   MemoryComponent
 } from "./shared/@ai-setting/roy-agent-core-nwbfepba.js";
@@ -61,21 +61,21 @@ import {
   BaseEnvironment,
   generateDescendingId,
   generateId
-} from "./shared/@ai-setting/roy-agent-core-8mjnb7xc.js";
+} from "./shared/@ai-setting/roy-agent-core-43r4bxey.js";
 import {
   TaskComponent
-} from "./shared/@ai-setting/roy-agent-core-nr2m4xw1.js";
+} from "./shared/@ai-setting/roy-agent-core-1k83dq3a.js";
 import"./shared/@ai-setting/roy-agent-core-58804s3j.js";
 import"./shared/@ai-setting/roy-agent-core-jm136jzh.js";
-import"./shared/@ai-setting/roy-agent-core-2wxbx36p.js";
+import"./shared/@ai-setting/roy-agent-core-dnjm17sa.js";
 import"./shared/@ai-setting/roy-agent-core-fttgm52a.js";
 import"./shared/@ai-setting/roy-agent-core-ntq0gz7q.js";
 import"./shared/@ai-setting/roy-agent-core-8gxth0eh.js";
-import"./shared/@ai-setting/roy-agent-core-t0ktaevq.js";
+import"./shared/@ai-setting/roy-agent-core-h5vmff8w.js";
 import"./shared/@ai-setting/roy-agent-core-p5cz9m8v.js";
 import {
   EventSourceComponent
-} from "./shared/@ai-setting/roy-agent-core-4882qsjx.js";
+} from "./shared/@ai-setting/roy-agent-core-x0ddc2cr.js";
 import {
   BountyIMInstance,
   COMMAND_PREFIX,
@@ -107,7 +107,7 @@ import {
   timerHandler,
   translateCardActionToCommand,
   writeFallbackModelList
-} from "./shared/@ai-setting/roy-agent-core-8nksrtnf.js";
+} from "./shared/@ai-setting/roy-agent-core-19na22cc.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -132,7 +132,7 @@ import {
 import {
   TaskTagPlugin,
   createAutoTaskPlugin
-} from "./shared/@ai-setting/roy-agent-core-v8bz7d8x.js";
+} from "./shared/@ai-setting/roy-agent-core-keyb45z3.js";
 import {
   EventStoreImpl,
   getSharedEventStore,
@@ -149,10 +149,11 @@ import {
 import {
   getBuiltInPrompt,
   getBuiltInPromptNames
-} from "./shared/@ai-setting/roy-agent-core-vs5gxgwh.js";
+} from "./shared/@ai-setting/roy-agent-core-ma35jyd9.js";
 import"./shared/@ai-setting/roy-agent-core-tr3ep81v.js";
-import"./shared/@ai-setting/roy-agent-core-0ys85x46.js";
-import"./shared/@ai-setting/roy-agent-core-zk2jg0v7.js";
+import"./shared/@ai-setting/roy-agent-core-6m4bw8jy.js";
+import"./shared/@ai-setting/roy-agent-core-8bjj3d1b.js";
+import"./shared/@ai-setting/roy-agent-core-tadj19vp.js";
 import {
   WorkflowComponent
 } from "./shared/@ai-setting/roy-agent-core-37tj4y6a.js";
@@ -199,7 +200,7 @@ import"./shared/@ai-setting/roy-agent-core-jagkferh.js";
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "./shared/@ai-setting/roy-agent-core-j1kksatb.js";
+} from "./shared/@ai-setting/roy-agent-core-hfr6bzts.js";
 import {
   ToolComponent,
   ToolRegistry,

package/dist/shared/@ai-setting/{roy-agent-core-8nksrtnf.js → roy-agent-core-19na22cc.js}

@@ -13,17 +13,17 @@ import {
   createPerTaskGroupChatPlugin,
   extractPerTaskChatId,
   extractPerTaskChatName
-} from "./roy-agent-core-v8bz7d8x.js";
+} from "./roy-agent-core-keyb45z3.js";
 import {
   getSharedEventStore
 } from "./roy-agent-core-na18zwj0.js";
 import {
   createLarkCliWorkflowNotifyHook
-} from "./roy-agent-core-0ys85x46.js";
+} from "./roy-agent-core-8bjj3d1b.js";
 import {
   LarkCardPatchNotifier,
   buildTaskCard
-} from "./roy-agent-core-zk2jg0v7.js";
+} from "./roy-agent-core-tadj19vp.js";
 import {
   normalizeLarkAtMentions
 } from "./roy-agent-core-m880qz3y.js";
@@ -311,6 +311,88 @@ var SELF_REMINDER_MESSAGE = `[Timer Self-Reminder]
 
 请根据分析结果，创建 1-3 个有价值的任务并执行。`;
 var TIMER_OPTIONS_KEY_GET_MANAGER = "getBackgroundTaskManager";
+var SCHEDULE_TICK_INTERVAL_MS = 30 * 1000;
+var TIMER_OPTIONS_KEY_SCHEDULE = "schedule";
+var TIMER_OPTIONS_KEY_SESSION_ID = "sessionId";
+var TIMER_OPTIONS_KEY_SKIP_WHEN_RUNNING = "skipWhenRunning";
+var TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/;
+function isValidScheduleTime(time) {
+  return typeof time === "string" && TIME_PATTERN.test(time);
+}
+function parseSchedule(raw) {
+  if (!Array.isArray(raw))
+    return [];
+  const result = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object")
+      continue;
+    const obj = item;
+    if (!isValidScheduleTime(obj.time))
+      continue;
+    if (typeof obj.prompt !== "string" || obj.prompt.trim().length === 0)
+      continue;
+    const entry = {
+      time: obj.time,
+      prompt: obj.prompt
+    };
+    if (typeof obj.label === "string" && obj.label.length > 0) {
+      entry.label = obj.label;
+    }
+    if (typeof obj.sessionId === "string" && obj.sessionId.length > 0) {
+      entry.sessionId = obj.sessionId;
+    }
+    result.push(entry);
+  }
+  return result;
+}
+function validateScheduleConfig(config) {
+  const errors = [];
+  const options = config.options ?? {};
+  const raw = options[TIMER_OPTIONS_KEY_SCHEDULE];
+  if (raw === undefined || raw === null)
+    return errors;
+  if (!Array.isArray(raw)) {
+    errors.push("Timer schedule must be an array of { time, prompt } entries");
+    return errors;
+  }
+  if (raw.length === 0) {
+    errors.push("Timer schedule must not be empty");
+    return errors;
+  }
+  raw.forEach((item, index) => {
+    if (!item || typeof item !== "object") {
+      errors.push(`Timer schedule[${index}] must be an object`);
+      return;
+    }
+    const obj = item;
+    if (!isValidScheduleTime(obj.time)) {
+      errors.push(`Timer schedule[${index}].time must be in HH:MM format (24-hour), got: ${String(obj.time)}`);
+    }
+    if (typeof obj.prompt !== "string" || obj.prompt.trim().length === 0) {
+      errors.push(`Timer schedule[${index}].prompt is required and must be a non-empty string`);
+    }
+  });
+  const seenTimes = new Set;
+  const duplicatedTimes = new Set;
+  for (const item of raw) {
+    if (!item || typeof item !== "object")
+      continue;
+    const time = item.time;
+    if (!isValidScheduleTime(time))
+      continue;
+    if (seenTimes.has(time)) {
+      duplicatedTimes.add(time);
+    }
+    seenTimes.add(time);
+  }
+  if (duplicatedTimes.size > 0) {
+    errors.push(`Timer schedule contains duplicate time entries: ${Array.from(duplicatedTimes).join(", ")}`);
+  }
+  if (config.interval !== undefined && config.interval !== null) {
+    errors.push("Timer schedule and interval are mutually exclusive: use schedule for fixed daily times, or interval for periodic triggering");
+  }
+  return errors;
+}
 
 class TimerInstance {
   config;
@@ -318,21 +400,38 @@ class TimerInstance {
   sessionId;
   getRunningTasks;
   customPrompt;
+  schedule;
+  scheduleMode;
+  invalidScheduleWarned = false;
+  scheduleSessionId;
+  skipWhenRunning;
+  firedKeys = new Set;
+  now;
   status = "created";
   timerId;
   eventHandler;
-  constructor(config, getRunningTasks) {
+  constructor(config, getRunningTasks, now) {
     this.config = config;
-    this.interval = typeof config.interval === "number" && config.interval > 0 ? config.interval : DEFAULT_TIMER_INTERVAL_MS;
+    this.now = now ?? (() => Date.now());
+    const options = config.options ?? {};
+    const rawSchedule = options[TIMER_OPTIONS_KEY_SCHEDULE];
+    const scheduleConfigured = rawSchedule !== undefined && rawSchedule !== null;
+    this.schedule = parseSchedule(rawSchedule);
+    this.scheduleMode = scheduleConfigured;
+    const isScheduleMode = this.scheduleMode;
+    this.interval = isScheduleMode ? SCHEDULE_TICK_INTERVAL_MS : typeof config.interval === "number" && config.interval > 0 ? config.interval : DEFAULT_TIMER_INTERVAL_MS;
     this.sessionId = `timer-${config.id}-${process.pid}`;
-    const optionsPrompt = config.options?.prompt;
+    const explicitSessionId = options[TIMER_OPTIONS_KEY_SESSION_ID];
+    this.scheduleSessionId = typeof explicitSessionId === "string" && explicitSessionId.length > 0 ? explicitSessionId : `timer-${config.id}`;
+    this.skipWhenRunning = options[TIMER_OPTIONS_KEY_SKIP_WHEN_RUNNING] === true;
+    const optionsPrompt = options.prompt;
     if (typeof optionsPrompt === "string" && optionsPrompt.trim().length > 0) {
       this.customPrompt = optionsPrompt;
     }
     if (getRunningTasks) {
       this.getRunningTasks = getRunningTasks;
     } else {
-      const factory = config.options?.[TIMER_OPTIONS_KEY_GET_MANAGER];
+      const factory = options[TIMER_OPTIONS_KEY_GET_MANAGER];
       if (typeof factory === "function") {
         const manager = factory();
         this.getRunningTasks = () => manager.listTasks();
@@ -341,6 +440,9 @@ class TimerInstance {
       }
     }
   }
+  get isScheduleMode() {
+    return this.scheduleMode;
+  }
   async start() {
     if (this.status === "running")
       return;
@@ -366,6 +468,10 @@ class TimerInstance {
     this.eventHandler = undefined;
   }
   tick() {
+    if (this.isScheduleMode) {
+      this.tickSchedule();
+      return;
+    }
     let allTasks;
     try {
       allTasks = this.getRunningTasks();
@@ -380,19 +486,81 @@ class TimerInstance {
     const event = this.buildSelfReminderEvent();
     this.eventHandler?.(event);
   }
-  buildSelfReminderEvent() {
-    const timestamp = Date.now();
-    const message = this.customPrompt ?? SELF_REMINDER_MESSAGE;
+  tickSchedule() {
+    if (this.schedule.length === 0) {
+      if (!this.invalidScheduleWarned) {
+        this.invalidScheduleWarned = true;
+        console.warn(`[TimerInstance] Timer ${this.config.id} has an invalid or empty schedule configuration; ` + `no events will be fired. Check options.schedule (expected [{ time: "HH:MM", prompt: "..." }]).`);
+      }
+      return;
+    }
+    const now = new Date(this.now());
+    const hh = String(now.getHours()).padStart(2, "0");
+    const mm = String(now.getMinutes()).padStart(2, "0");
+    const currentTime = `${hh}:${mm}`;
+    const dateKey = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+    for (const entry of this.schedule) {
+      if (entry.time !== currentTime)
+        continue;
+      const firedKey = `${dateKey}#${entry.time}`;
+      if (this.firedKeys.has(firedKey)) {
+        continue;
+      }
+      if (this.skipWhenRunning) {
+        let hasRunning = false;
+        try {
+          const allTasks = this.getRunningTasks();
+          hasRunning = Array.isArray(allTasks) && allTasks.some((t) => t.status === "running");
+        } catch (error) {
+          console.warn(`[TimerInstance] Failed to get running tasks, skipping tick: ${error}`);
+          return;
+        }
+        if (hasRunning) {
+          continue;
+        }
+      }
+      this.firedKeys.add(firedKey);
+      this.pruneFiredKeys(dateKey);
+      const event = this.buildSelfReminderEvent(entry);
+      this.eventHandler?.(event);
+      return;
+    }
+  }
+  pruneFiredKeys(currentDateKey) {
+    if (this.firedKeys.size <= 32)
+      return;
+    for (const key of this.firedKeys) {
+      const datePart = key.split("#")[0];
+      if (datePart !== currentDateKey) {
+        this.firedKeys.delete(key);
+      }
+    }
+  }
+  buildSelfReminderEvent(entry) {
+    const timestamp = this.now();
+    const message = entry?.prompt ?? this.customPrompt ?? SELF_REMINDER_MESSAGE;
+    const triggerSessionId = entry !== undefined ? entry.sessionId ?? this.scheduleSessionId : undefined;
+    const metadata = {
+      source: "event-source",
+      sourceId: this.config.id,
+      sourceMessageType: "timer.selfReminder",
+      sessionId: this.sessionId
+    };
+    if (triggerSessionId !== undefined) {
+      metadata.trigger_session_id = triggerSessionId;
+      metadata.createSessionIfMissing = true;
+    }
+    if (entry?.label !== undefined) {
+      metadata.scheduleLabel = entry.label;
+    }
+    if (entry !== undefined) {
+      metadata.scheduleTime = entry.time;
+    }
     return {
       id: `es-${this.config.id}-${timestamp}-${Math.random().toString(36).slice(2, 8)}`,
       type: "event-source.event.timer",
       timestamp,
-      metadata: {
-        source: "event-source",
-        sourceId: this.config.id,
-        sourceMessageType: "timer.selfReminder",
-        sessionId: this.sessionId
-      },
+      metadata,
       payload: {
         sourceId: this.config.id,
         sourceType: "timer",
@@ -415,6 +583,9 @@ class TimerInstance {
 __legacyDecorateClassTS([
   TracedAs("timer.tick", { recordParams: false, log: false })
 ], TimerInstance.prototype, "tick", null);
+__legacyDecorateClassTS([
+  TracedAs("timer.tickSchedule", { recordParams: false, log: false })
+], TimerInstance.prototype, "tickSchedule", null);
 __legacyDecorateClassTS([
   TracedAs("timer.buildSelfReminderEvent", { recordParams: false, log: false })
 ], TimerInstance.prototype, "buildSelfReminderEvent", null);
@@ -423,7 +594,9 @@ var timerHandler = {
   validateConfig(config) {
     const errors = [];
     const { interval } = config;
-    if (interval !== undefined && interval !== null) {
+    errors.push(...validateScheduleConfig(config));
+    const hasSchedule = config.options?.[TIMER_OPTIONS_KEY_SCHEDULE] !== undefined;
+    if (!hasSchedule && interval !== undefined && interval !== null) {
       if (typeof interval !== "number" || !Number.isFinite(interval)) {
         errors.push("Timer interval must be a finite number");
       } else if (interval <= 0) {
@@ -439,7 +612,7 @@ var timerHandler = {
     return [
       {
         name: "interval",
-        description: `Timer interval in milliseconds (default: ${DEFAULT_TIMER_INTERVAL_MS} = 10 minutes)`,
+        description: `Timer interval in milliseconds (default: ${DEFAULT_TIMER_INTERVAL_MS} = 10 minutes). Mutually exclusive with schedule.`,
         required: false,
         type: "number"
       },
@@ -448,6 +621,18 @@ var timerHandler = {
         description: "Custom prompt message for SelfReminder events (replaces default message)",
         required: false,
         type: "string"
+      },
+      {
+        name: TIMER_OPTIONS_KEY_SCHEDULE,
+        description: "JSON array of { time: 'HH:MM', prompt: string, label?: string, sessionId?: string } " + "for fixed daily trigger times (e.g. 10:00 / 17:00 / 20:00). Mutually exclusive with interval.",
+        required: false,
+        type: "string"
+      },
+      {
+        name: TIMER_OPTIONS_KEY_SESSION_ID,
+        description: "Explicit session ID for timer events (schedule mode). Events are routed to this " + "session instead of the main REPL session.",
+        required: false,
+        type: "string"
       }
     ];
   }