@tencent-ai/agent-harness 0.2.0-beta.6 → 0.2.0-beta.8

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/truncation-recovery.d.ts

@@ -98,3 +98,11 @@ export declare function readTruncatedResponseUsage(lastTurnResponse: unknown): {
  * 截断不该因为落在不同入口而收到不同指导。
  */
 export declare function buildRecoveryPrompt(truncatedToolNames?: readonly string[]): string;
+/**
+ * 包成 error-recovery system-reminder 后再注入。
+ *
+ * 裸文本会被 `UserQueryWrapperAgentRunInterceptor` 当成用户输入包进 `<user_query>`，
+ * 模型会把内部续写提示读成用户提问；包成带 data-role 的 reminder 后，它与
+ * `buildErrorRecoveryReminder` 等其他恢复提示同形，也不会被当成规则型 reminder。
+ */
+export declare function buildTruncationRecoveryReminder(truncatedToolNames?: readonly string[]): string;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session-title/session-title-utils.d.ts

@@ -28,6 +28,41 @@ export declare function getEffectiveSessionTitle(messages: AgentInputItem[]): st
  * not disappear merely because old conversation turns are trimmed.
  */
 export declare function getEffectiveSessionTitleItem(messages: AgentInputItem[]): AgentInputItem | undefined;
+/** 标题 item 类型 → 标题文本字段。 */
+declare const SESSION_TITLE_TEXT_FIELDS: {
+    readonly 'custom-title': 'customTitle';
+    readonly 'ai-title': 'aiTitle';
+    readonly topic: 'topic';
+};
+export type SessionTitleItemType = keyof typeof SESSION_TITLE_TEXT_FIELDS;
+/**
+ * 一条可持久化的标题事实（#138181）：原 item 的类型、id、标题文本与落盘时间戳，
+ * 不带 parent 链接 / sessionId。形状与标题 item 兼容，可以和 item 混排后用
+ * {@link resolveSessionTitleFacts} 折叠。
+ */
+export interface SessionTitleFact {
+    type: SessionTitleItemType;
+    id?: string;
+    timestamp?: number;
+    customTitle?: string;
+    aiTitle?: string;
+    topic?: string;
+}
+export declare function isSessionTitleItemType(type: unknown): type is SessionTitleItemType;
+/**
+ * 从标题 item / 标题事实里取出标题服务依赖的事实：最新的真实生成标题（`ai-title`，
+ * 没有时是 `topic`）与最新的非空 `custom-title`，与 {@link hasGeneratedTitle} /
+ * {@link hasCustomTitle} / {@link getEffectiveSessionTitleItem} 同一判定（占位标题不算）。
+ *
+ * 「最新」先比 `timestamp`，缺失或相同再按 `items` 的顺序（调用方按文件序传入）。
+ * 只按位置排序不够：另一个进程补写的快照可能带着旧事实落在更新的重命名之后。
+ * 顺序固定为 [生成, 自定义]。
+ */
+export declare function resolveSessionTitleFacts(items: ReadonlyArray<unknown>): SessionTitleFact[];
+/** 读回持久化的标题事实；形状不对（手改 / 未来格式）按「没有」处理。 */
+export declare function parseSessionTitleFacts(value: unknown): SessionTitleFact[] | undefined;
+/** `items` 里已有这条标题：同 id，或同类型同文本（fork 克隆的标题 id 会被重铸）。 */
+export declare function hasMatchingTitleItem(items: ReadonlyArray<AgentInputItem>, fact: SessionTitleFact): boolean;
 /**
  * Extract the first real user message's full text, used as the LLM input for
  * title generation. Unlike `getEffectiveSessionTitle`'s fallback (which
@@ -49,3 +84,4 @@ export declare function getFirstRealUserMessageText(messages: AgentInputItem[]):
  * both breaks that deadlock and yields a more representative title.
  */
 export declare function getFirstUsableUserMessageText(messages: AgentInputItem[], minLength: number): string | undefined;
+export {};

package/cli/dist-server/types/workspace/cbc-core/lib/node/utils/history-utils.d.ts

@@ -12,6 +12,7 @@ export { CompactSummaryNotFoundError };
  */
 export declare const PROMPT_CONTEXT_ROLES: readonly ["user-context", "additional-data"];
 export declare abstract class HistoryUtils {
+    static readonly PRESERVE_GENERAL_PURPOSE_TASK_HISTORY = "preserveGeneralPurposeTaskHistory";
     /**
      * 获取可供 Agent 使用的活跃历史记录
      * 获取活跃对话链（过滤废弃分支），并且滤自定义类型消息
@@ -265,7 +266,9 @@ export declare abstract class HistoryUtils {
      * @param transcriptPath session jsonl 文件路径，用于包装后缀中的 transcript 链接
      */
     static replaceCompactWithSummary(history: AgentInputItem[], transcriptPath: string): AgentInputItem[];
-    static filterTaskHistory(agent: Agent<any, any>, history: AgentInputItem[]): AgentInputItem[];
+    static filterTaskHistory(agent: Agent<any, any>, history: AgentInputItem[], session?: {
+        meta?: Record<string, unknown>;
+    }): AgentInputItem[];
     /**
      * 找到最后一条明确的 compact boundary 消息（压缩结果），
      * 丢弃它之前的所有历史项，只保留该消息及其后的内容。
@@ -319,18 +322,43 @@ export declare abstract class HistoryUtils {
     static containsUserContext(input: AgentInputItem[], userContext: string): boolean;
     static filterTruncatedHistory(history: AgentInputItem[]): AgentInputItem[];
     /**
-     * 用户取消的普通轮次只保留在 transcript 中，不再进入下一轮模型输入。
+     * 把用户取消的轮次投影成模型可见的"被打断"语义，对齐 Codex
+     * （`core/src/tasks/mod.rs` 在 TurnAbortReason::Interrupted 时记入一条
+     * user 角色的 `<turn_aborted>`）：原 prompt、已发生的工具记录都留在模型
+     * 输入里，取消边界本身换成一条 user 角色的中断说明。
+     *
+     * 于是下一轮模型看到的是「原问题 → 中断说明 → 新问题」三段，既知道上一个
+     * 请求没做完，也不会把它当成仍待执行的指令。
      *
-     * 仅处理已落历史的标准取消形态：本轮 user 之后追加了一条 skipRun 的
-     * assistant "Interrupted by user"。为避免影响 /insights 等特殊顺序，只有当
-     * user→取消边界之间没有已完成 assistant 回复时才剔除该段。
+     * 只处理已落历史的标准取消形态：skipRun 的 assistant "Interrupted by user"
+     * （由 `interruption-service` 写入），且该边界确实终结了一个**尚未得到回复**的
+     * 用户轮次 —— 沿 parentId 能找到真实 user、user 在边界之前、两者之间没有已完成的
+     * assistant 回复。这三个条件沿用原过滤器，是 marker 能成立的因果前提：文案断言
+     * 的是"用户打断了上一轮"，若边界挂在一个已经正常回复完的轮次后面（`/insights`
+     * 等特殊顺序、恢复流程留下的错位记录），投影出去就是在对模型说假话。
      *
-     * 该段内的 function_call / function_call_result 会被保留：取消作废的是用户
-     * 的"待执行意图"，而工具调用已经产生过副作用，属于既成事实。
+     * 守卫不通过时原样返回该条，交回 `filterApiErrorMessages` 按基线行为剔除，
+     * 模型侧语义与改动前完全一致。
+     *
+     * 不落盘、不改 transcript：UI 继续显示原来那条 assistant 占位。
      */
-    static filterCancelledPromptHistory(history: AgentInputItem[]): AgentInputItem[];
+    static projectCancelledTurnMarker(history: AgentInputItem[]): AgentInputItem[];
     private static findCancelledTurnUserId;
-    private static hasCompletedAssistantBetween;
+    /**
+     * 这一段里是否已经出现过**结束该轮的** assistant 答复。
+     *
+     * 不能只看"有没有 completed 的 assistant message"：模型调用工具前常先写一句叙述
+     * （tool-call carrier，真实 jsonl 里就是 `status: 'completed'` 的独立 message，
+     * 见 `history-utils.parallel-tool-calls.spec.ts`）。那句话不是对用户的答复，
+     * 这一轮还在继续 —— 所以每遇到一个 `function_call` 就把"已答复"重置掉。
+     *
+     * 依据的是一轮的结构：assistant message 与 function_call 交替，只有**后面再没有
+     * 工具调用**的那条 assistant message 才是对用户的答复。于是三种形态各自判对：
+     *   - `user → 答复(completed) → 边界`                 → 已答复，边界错位，不投影
+     *   - `user → carrier → call → result → 边界`         → 未答复（工具跑完但还没回答），投影
+     *   - `user → carrier → call → result → 答复 → 边界`  → 已答复，边界错位，不投影
+     */
+    private static hasCompletedAssistantReplyBetween;
     /**
      * 在每次模型请求前应用 content-filter 清理:
      * 上一轮模型响应若以 finish_reason=content_filter 结束,

package/cli/dist-server/types/workspace/cbc-core/lib/node/utils/input-item-utils.d.ts

@@ -254,6 +254,33 @@ export declare abstract class InputItemUtils {
     static isAssistantMessage(item: AgentInputItem): boolean;
     static isSessionSeparatorItem(item: AgentInputItem): boolean;
     static isUserInterrupted(item: AgentInputItem): boolean;
+    static readonly TURN_ABORTED_TAG_OPEN = "<turn_aborted>";
+    static readonly TURN_ABORTED_TAG_CLOSE = "</turn_aborted>";
+    /**
+     * 取消轮在模型输入里的说明文案。
+     *
+     * 逐字沿用 Codex `core/src/context/turn_aborted.rs` 的 INTERRUPTED_GUIDANCE，
+     * 只把它自家的 "unified exec processes" 换成本 CLI 真实存在的 "background tasks"
+     * （Bash 的 run_in_background、后台 Agent）——照抄不存在的概念会误导模型。
+     */
+    static readonly TURN_ABORTED_GUIDANCE: string;
+    /**
+     * 把一条已落史的取消边界（assistant "Interrupted by user"）投影成模型可见的
+     * user 角色中断标记，对齐 Codex：原 prompt 留在历史里，后面紧跟一条
+     * `<turn_aborted>` 说明，下一轮用户输入再接在后面。
+     *
+     * 只用于构造当轮模型输入，不落盘：transcript 与 UI 继续显示原来那条 assistant
+     * 占位（见 `interruption-service`），所以 id / parentId 沿用边界项——既让
+     * 父链遍历仍然成立，也保证同一段历史每轮投影出的 id 稳定（换成随机 id 会让
+     * 模型输入每轮都变，破坏 prompt 缓存）。
+     *
+     * providerData 整体继承而不是重建：投影只改"角色 + 文本"这两件事，边界上的
+     * 结构化标记（`agent` / `truncated` 等）仍被后续管线用来做过滤决策
+     * （`replaceCompactWithSummary` 认 `agent`、`filterTruncatedHistory` 认
+     * `truncated`），重建一个干净 providerData 会让这些决策静默改变。
+     */
+    static createTurnAbortedMarker(boundaryItem: AgentInputItem): UserMessageItem;
+    static isTurnAbortedMarker(item: AgentInputItem): item is UserMessageItem;
     static isSuccessfulFunctionCallResultItem(item: AgentInputItem): item is FunctionCallResultItem;
     static isCompactBoundaryMessage(item: AgentInputItem): boolean;
     /**
@@ -266,6 +293,7 @@ export declare abstract class InputItemUtils {
     static isStructuredCompactBoundaryMessage(item: AgentInputItem): boolean;
     static isReplayRecoverableCompactMessage(item: AgentInputItem): item is UserMessageItem;
     static isCompactUserMessage(item: AgentInputItem): item is UserMessageItem;
+    static isCompactEnvelopeMessage(item: AgentInputItem): item is UserMessageItem;
     private static hasCompactBoundaryContent;
     static isCompactContinuePromptMessage(item: AgentInputItem): item is UserMessageItem;
     private static hasTeammateMessageContent;

package/cli/dist-server/types/workspace/cbc-core/lib/node/utils/message-utils.d.ts

@@ -12,6 +12,7 @@ export declare abstract class MessageUtils {
      * @returns 合并后的消息列表
      */
     static mergeConsecutiveUserMessages(messages: AgentInputItem[]): AgentInputItem[];
+    private static shouldKeepUserMessageSeparate;
     /**
      * 合并用户消息组
      *

package/cli/dist-server/types/workspace/cbc-core/lib/node/utils/model-utils.d.ts

@@ -69,14 +69,18 @@ export declare abstract class ModelUtils {
      * 各写一份 `||` 顺序漂移。
      */
     private static readRuntimeModelId;
-    static isHunyuanModel(session: Session): Promise<boolean>;
     /**
-     * ImageGen 实际使用的图片模型是否为混元。
+     * 从模型配置的 credits 字段解析计费倍率；未配置或无法解析时返回 undefined。
+     * 兼容 `x0.00` / `0.00x` / `x2.20 credits` 等格式，取首个数字。
+     */
+    private static parseCreditsValue;
+    /**
+     * 当前会话模型是否为免费模型。
      *
-     * 取「产品配置里第一个带 text-to-image tag 的模型」，与 image-service 的解析顺序一致；
-     * 配置里没有图片模型时会走客户端的混元兜底模型，同样按混元处理。
+     * 判据是模型计费（credits）：明确收费（> 0）不算免费；计费为 0、未配置或
+     * 无法解析时按免费处理。免费模型会话下生图会额外消耗积分，需要前置提醒。
      */
-    static isHunyuanImageModel(): Promise<boolean>;
+    static isFreeModel(session: Session): Promise<boolean>;
     static isMandatoryApprovalTarget(session: Session, targetToolName: string): Promise<boolean>;
 }
 export {};

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-parser.d.ts

@@ -0,0 +1,34 @@
+import { CronTask, JitterConfig, ParsedCron } from './cron-protocol.js';
+/**
+ * Parse a single cron field.
+ * Supports: *, *\/N, 5-20, 5-20/2, 5,10,15, single value.
+ * dayOfWeek: 7 maps to 0 (Sunday).
+ */
+export declare function parseField(field: string, range: {
+    min: number;
+    max: number;
+}): number[] | null;
+export declare function parseCron(expr: string): ParsedCron | null;
+/**
+ * Calculate the next fire time from a parsed cron and a start date.
+ * Iterates minute-by-minute, matching month -> day -> hour -> minute.
+ * dayOfMonth and dayOfWeek follow standard cron semantics:
+ * when both are non-wildcard, they are OR'd (union).
+ * Max ~527040 iterations (~1 year of minutes).
+ */
+export declare function getNextFireTime(parsed: ParsedCron, fromDate: Date): Date | null;
+/** Wrapper: cron expression + timestamp -> next fire timestamp */
+export declare function getNextFireTimestamp(cron: string, fromTimestamp: number): number | null;
+/** Compute a deterministic [0,1] fraction from the first 8 hex chars of task ID */
+export declare function deterministicFraction(taskId: string): number;
+/**
+ * Recurring task: next fire = match time + jitter(10% of period, capped at 15min)
+ */
+export declare function getRecurringFireTime(cron: string, fromTimestamp: number, taskId: string, config?: JitterConfig): number | null;
+/**
+ * One-shot task: on :00/:30 marks, fire up to 90s early
+ */
+export declare function getOneShotFireTime(cron: string, fromTimestamp: number, taskId: string, config?: JitterConfig): number | null;
+export declare function humanSchedule(cron: string): string;
+export declare function isExpired(task: CronTask, now?: number): boolean;
+export declare function detectMissedTasks(tasks: CronTask[], now: number): CronTask[];

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-protocol.d.ts

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+/** 3 days expiry (ms) */
+export declare const CRON_EXPIRY_MS = 259200000;
+/** Scheduler main loop interval (ms) */
+export declare const SCHEDULER_TICK_MS = 500;
+/** Distributed lock retry interval (ms) */
+export declare const LOCK_RETRY_MS = 5000;
+/** Max scheduled jobs per session */
+export declare const MAX_SCHEDULED_JOBS = 50;
+/** Default /loop interval */
+export declare const DEFAULT_LOOP_INTERVAL = "10m";
+/** Persisted tasks file name */
+export declare const SCHEDULED_TASKS_FILE = "scheduled_tasks.json";
+/** Lock file name */
+export declare const SCHEDULED_TASKS_LOCK = "scheduled_tasks.scheduler.lock";
+/** Persisted execution history file name */
+export declare const SCHEDULED_TASK_EXECUTIONS_FILE = "scheduled_task_executions.json";
+/** Maximum retained executions per task */
+export declare const MAX_EXECUTIONS_PER_TASK = 50;
+/** Active execution ownership lease duration (ms) */
+export declare const EXECUTION_LEASE_TTL_MS = 30000;
+/** Active execution ownership lease renewal interval (ms) */
+export declare const EXECUTION_LEASE_RENEW_MS = 10000;
+export interface JitterConfig {
+    recurringFrac: number;
+    recurringCapMs: number;
+    oneShotMaxMs: number;
+    oneShotFloorMs: number;
+    oneShotMinuteMod: number;
+}
+export declare const DEFAULT_JITTER_CONFIG: JitterConfig;
+export interface CronTask {
+    id: string;
+    cron: string;
+    prompt: string;
+    createdAt: number;
+    recurring?: boolean;
+    durable?: boolean;
+    permanent?: boolean;
+    lastFiredAt?: number;
+    enabled?: boolean;
+}
+export interface CronTaskUpdate {
+    cron?: string;
+    prompt?: string;
+    recurring?: boolean;
+    durable?: boolean;
+    enabled?: boolean;
+}
+export type CronTaskExecutionStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+export type CronTaskExecutionOwnerKind = 'daemon' | 'webui' | 'cli';
+export interface CronTaskExecutionOwner {
+    ownerKind: CronTaskExecutionOwnerKind;
+    ownerId: string;
+    ownerPid: number;
+    sessionId: string;
+}
+export interface CronTaskExecution {
+    id: string;
+    taskId: string;
+    schedule: string;
+    prompt: string;
+    durable?: boolean;
+    recurring?: boolean;
+    status: CronTaskExecutionStatus;
+    ownerKind?: CronTaskExecutionOwnerKind;
+    ownerId?: string;
+    ownerPid?: number;
+    sessionId?: string;
+    leaseExpiresAt?: number;
+    runId?: string;
+    startedAt: number;
+    completedAt?: number;
+    durationMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    error?: string;
+}
+export interface ScheduledTaskExecutionsFile {
+    executions: CronTaskExecution[];
+}
+export interface CronCreateOutput {
+    id: string;
+    humanSchedule: string;
+    recurring: boolean;
+    durable?: boolean;
+}
+export interface CronListOutput {
+    jobs: Array<{
+        id: string;
+        cron: string;
+        humanSchedule: string;
+        prompt: string;
+        recurring?: boolean;
+        durable?: boolean;
+        enabled?: boolean;
+    }>;
+}
+export interface ParsedCron {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+}
+export interface LockContent {
+    sessionId: string;
+    pid: number;
+    acquiredAt: number;
+}
+export interface ScheduledTasksFile {
+    tasks: CronTask[];
+}
+/** CronCreate schema. `durable` is model-visible but gated by tool approval. */
+export declare const CronCreateFullSchema: z.ZodObject<{
+    cron: z.ZodString;
+    prompt: z.ZodString;
+    recurring: z.ZodOptional<z.ZodBoolean>;
+    durable: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    cron: string;
+    prompt: string;
+    recurring?: boolean | undefined;
+    durable?: boolean | undefined;
+}, {
+    cron: string;
+    prompt: string;
+    recurring?: boolean | undefined;
+    durable?: boolean | undefined;
+}>;
+export declare const CronDeleteSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export declare const CronListSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export type CronSchedulerOwnerKind = 'daemon' | 'session';
+export interface CronSchedulerStartOptions {
+    ownerKind?: CronSchedulerOwnerKind;
+    shouldDeferToPreferredOwner?: (storageDir: string) => Promise<boolean>;
+}
+export type CronTaskFireResult = 'enqueued' | 'active' | 'already-completed' | 'rejected';
+export interface CronExecutionClaimResult {
+    status: 'inserted' | 'active' | 'already-completed';
+    execution?: CronTaskExecution;
+}
+export type CronExecutionDeleteResult = {
+    status: 'deleted';
+    deletedIds: string[];
+    missingIds: string[];
+} | {
+    status: 'active';
+    activeIds: string[];
+};
+export interface CronSchedulerOptions extends CronSchedulerStartOptions {
+    sessionId: string;
+    onFire: (prompt: string) => void;
+    isLoading: () => boolean;
+    onFireTask?: (task: CronTask, isLeadershipValid: () => boolean) => CronTaskFireResult | void | Promise<CronTaskFireResult | void>;
+    onMissed?: (tasks: CronTask[]) => void;
+    dir: string;
+    lockIdentity: {
+        sessionId: string;
+        pid: number;
+    };
+    getJitterConfig?: () => JitterConfig;
+    assistantMode?: boolean;
+    isKilled?: () => boolean;
+}
+export declare const CronSchedulerService: unique symbol;
+export declare const CronStateManagerService: unique symbol;
+export declare const CronStorageService: unique symbol;
+/**
+ * Per-session lifecycle manager for cron scheduler instances.
+ * Injected into SessionManager for start/stop on session transitions.
+ */
+export interface CronSchedulerServiceInterface {
+    /** Start the scheduler for a session (fire-and-forget) */
+    start(session: {
+        id: string;
+        agentState?: string;
+        abortSignal: AbortSignal;
+    }, options?: CronSchedulerStartOptions): boolean;
+    /** Stop the scheduler for a session */
+    stop(sessionId: string): void;
+    /** Get the next fire time for a session's scheduler */
+    getNextFireTime(sessionId: string): number | null;
+}

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-scheduler-service.d.ts

@@ -0,0 +1,131 @@
+import { TelemetryService } from '../../../../../node/telemetry/telemetry-protocol.js';
+import { Session, SessionRunStateMachine } from '../../../../cbc-core/lib/node/index.js';
+import { Logger } from '../../../../telemetry/lib/common/index.js';
+import { type CronSchedulerStartOptions } from './cron-protocol.js';
+import { CronStateManager } from './cron-state-manager.js';
+interface ExecutionCompletion {
+    status: 'succeeded' | 'failed';
+    error?: string;
+}
+/**
+ * Correlates a scheduled-task execution with the physical run that actually
+ * admitted its input. PREPARING alone is deliberately insufficient: queue
+ * arbitration happens later, and the cron item may remain queued for another
+ * run. The inputSubject notification is emitted by History after arbitration,
+ * so it is the first authoritative admission signal visible to this package.
+ */
+export declare class CronExecutionRunTracker {
+    private readonly session;
+    private readonly stateMachine;
+    private readonly markExecutionRunning;
+    private readonly completeExecution;
+    private readonly pendingExecutions;
+    private readonly runStateSubscription;
+    private readonly historySubscription;
+    constructor(session: Session, stateMachine: SessionRunStateMachine, markExecutionRunning: (executionId: string, runId: string) => void, completeExecution: (executionId: string, result: ExecutionCompletion) => void);
+    track(executionId: string): void;
+    untrack(executionId: string): void;
+    fail(executionId: string, error: string): void;
+    finalizeAll(error: string): void;
+    dispose(): void;
+    private onHistoryItem;
+    private onRunStateChanged;
+    private continueRun;
+    private completeRun;
+    private complete;
+}
+/**
+ * Per-session lifecycle manager for the cron scheduler.
+ *
+ * Responsibilities:
+ * 1. Create/start a CronSchedulerInstance when a session starts
+ * 2. Stop/destroy it when the session is cleaned up or removed
+ * 3. Wire the `onFire` callback to inject isMeta messages via MessageQueueManager
+ * 4. Wire `isLoading` to check the session's agentState
+ */
+export declare class CronSchedulerServiceImpl {
+    protected readonly logger: Logger;
+    protected readonly stateManager: CronStateManager;
+    protected readonly telemetryService?: TelemetryService;
+    protected readonly stateMachine: SessionRunStateMachine;
+    /** Active scheduler instances keyed by session ID */
+    private schedulers;
+    private executionTrackers;
+    private schedulerLifecycles;
+    private executionOwnerIds;
+    private executionLeaseTimers;
+    private modeBIdleSubscriptions;
+    /**
+     * 任务会话注册表，按任务会话 id 索引。
+     *
+     * 生命周期是「进程级」而不是「调度器级」：任务会话不属于任何宿主会话，宿主
+     * 切换（/clear、setCurrent）会 stop 旧调度器再 start 新的，若跟着释放就会把
+     * 在途的定时任务执行误判为失败。规模由持久化任务数封顶，不随执行次数增长。
+     */
+    private taskSessions;
+    /** 同一 tick 内并发触发同一任务时复用的创建 promise，避免重复建会话。 */
+    private taskSessionResolutions;
+    private taskSessionTrackers;
+    /**
+     * Start the cron scheduler for a session.
+     * Called in SessionManager.setCurrent() when a new session is activated.
+     *
+     * This method is fire-and-forget (non-blocking).
+     */
+    start(session: Session, options?: CronSchedulerStartOptions): boolean;
+    /**
+     * Stop the cron scheduler for a session.
+     * Called during session cleanup in SessionManager.setCurrent() and remove().
+     */
+    stop(sessionId: string): void;
+    /**
+     * 解析持久化任务的执行会话。
+     *
+     * 会话 id 由 taskId 纯函数派生（uuid v5，见 cronTaskSessionId），因此任何进程
+     * （daemon / WebUI / CLI / TUI）对同一任务都落在同一条会话上：不需要把
+     * 「任务 → 会话」映射落盘，也不需要在各入口之间对齐归属。首次触发时懒创建，
+     * 之后按 id 从会话存储复原，所以会话数等于持久化任务数，不随执行次数增长。
+     */
+    private resolveTaskSession;
+    private loadOrCreateTaskSession;
+    /**
+     * 任务会话由 SessionManager 直建，不经过 SessionMiddleware，因此进程级 CLI 参数
+     * （-y / --permission-mode / --model / --tools）必须在此显式注入，否则权限模式会
+     * 兜底成 Default，而任务会话没有宿主可以应答审批，无人值守执行会直接挂死。
+     * 配方与 webhook 直建会话（GatewayAcpBridge.createSessionForConversation）一致。
+     *
+     * MCP 与技能是进程档能力（AgentScopedMcpManager 无 scoped state 时回落全局
+     * servers、mergeSessionSkills 无会话档绑定时 no-op），不随会话创建路径变化，
+     * 无需在此注入；已由 task-session-mcp-skill.spec.ts 覆盖。
+     */
+    private taskSessionOptions;
+    private taskSessionTracker;
+    private createExecutionTracker;
+    /**
+     * 把触发消息投递到任务会话。
+     *
+     * 任务会话没有 ACP 宿主来驱动队列排空，所以空闲时直接以本轮输入起 run；忙时
+     * 入队，由 AgentService 的空闲排空接管，避免两条排空路径抢跑同一轮。
+     */
+    private dispatchToTaskSession;
+    private runTaskSession;
+    /**
+     * Get the next fire time across all active schedulers.
+     */
+    getNextFireTime(sessionId: string): number | null;
+    /**
+     * Report telemetry when a scheduled task fires.
+     *
+     * NOTE: Full telemetry event types (scheduled_task_fire, scheduled_task_missed, scheduled_task_expired)
+     * are not yet defined in @genie/telemetry package. This is a placeholder for future integration.
+     *
+     * To fully implement telemetry:
+     * 1. Add ScheduledTaskFireTelemetry, ScheduledTaskMissedTelemetry, ScheduledTaskExpiredTelemetry
+     *    to packages/telemetry/src/common/event/types/
+     * 2. Add corresponding Events enum values
+     * 3. Update EventPayloadMapping in packages/telemetry/src/common/event/types/events.ts
+     * 4. Uncomment the report() calls below
+     */
+    private reportScheduledTaskFire;
+}
+export {};

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-scheduler.d.ts

@@ -0,0 +1,20 @@
+import { CronSchedulerOptions } from './cron-protocol.js';
+import { CronStateManager } from './cron-state-manager.js';
+export interface CronSchedulerInstance {
+    start(): void;
+    stop(): void;
+    getNextFireTime(): number | null;
+}
+/**
+ * Create a cron scheduler with a 4-layer timer architecture:
+ * 1. Enablement check: polls scheduledTasksEnabled every 500ms
+ * 2. Main loop: checks expired tasks every 500ms
+ * 3. Lock retry: retries lock acquisition every 5s
+ * 4. File watcher: chokidar monitors scheduled_tasks.json
+ *
+ * State machine:
+ * STOPPED → ENABLEMENT_CHECK → LOCK_ACQUIRING → RUNNING → STOPPING → STOPPED
+ *
+ * All setInterval calls use .unref() to not block process exit.
+ */
+export declare function createCronScheduler(options: CronSchedulerOptions, stateManager: CronStateManager): CronSchedulerInstance;

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-state-manager.d.ts

@@ -0,0 +1,50 @@
+import { CronExecutionClaimResult, CronExecutionDeleteResult, CronTask, CronTaskExecution, CronTaskExecutionOwner, CronTaskUpdate } from './cron-protocol.js';
+export declare class CronStateManager {
+    private scheduledTasksEnabled;
+    private sessionCronTasksMap;
+    private durableCronTasks;
+    private taskExecutions;
+    private executionWriteQueue;
+    private failedExecutionWrites;
+    private deletingExecutionIds;
+    private executionRetryTimer;
+    private executionPersistenceError;
+    private storageDir;
+    setEnabled(enabled: boolean): void;
+    isScheduledTasksEnabled(): boolean;
+    setStorageDir(dir: string): void;
+    getStorageDir(): string | undefined;
+    getSessionTasks(sessionId: string): CronTask[];
+    getDurableTasks(): CronTask[];
+    readDurableTasks(): Promise<CronTask[]>;
+    replaceDurableTasks(tasks: CronTask[]): void;
+    refreshDurableTasks(): Promise<CronTask[]>;
+    addSessionTask(sessionId: string, task: CronTask): void;
+    removeSessionTasks(sessionId: string, ids: string[]): number;
+    clearSessionTasks(sessionId: string): void;
+    createTask(sessionId: string, cron: string, prompt: string, recurring: boolean, durable: boolean): Promise<string>;
+    getAllTasks(sessionId: string): Promise<CronTask[]>;
+    updateTask(sessionId: string, id: string, updates: CronTaskUpdate): Promise<CronTask | undefined>;
+    private applyTaskUpdates;
+    tryQueueExecution(task: CronTask, owner: CronTaskExecutionOwner): Promise<CronTaskExecution | undefined>;
+    tryQueueExecutionDetailed(task: CronTask, owner: CronTaskExecutionOwner): Promise<CronExecutionClaimResult>;
+    markExecutionRunning(id: string, runId: string): void;
+    hasActiveExecution(taskId: string): boolean;
+    renewExecutionLeases(ownerId: string): Promise<number>;
+    completeExecution(id: string, result: {
+        status: 'succeeded' | 'failed';
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        error?: string;
+    }): Promise<void>;
+    getTaskExecutions(taskId: string): Promise<CronTaskExecution[]>;
+    deleteTaskExecutions(taskId: string, executionIds: readonly string[]): Promise<CronExecutionDeleteResult>;
+    private findActiveExecutionIds;
+    private pruneTaskExecutions;
+    recoverInterruptedExecutions(error?: string): Promise<number>;
+    flushExecutionPersistence(): Promise<void>;
+    private persistExecution;
+    private scheduleExecutionPersistenceRetry;
+    removeTasks(sessionId: string, ids: string[]): Promise<number>;
+}