@deepmaid/maid-cron 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenyonxu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: deepmaid-maid-cron
+      name: '@deepmaid/maid-cron'

package/lib/index.d.ts

@@ -0,0 +1,191 @@
+import { DeliveryAddress, MaidDelivery } from "@deepmaid/maid-delivery";
+//#region src/schedule.d.ts
+type JobSchedule = {
+  cron: string;
+  timezone: string;
+} | {
+  everyMinutes: number;
+} | {
+  once: string;
+};
+/** 下一次 due(epoch ms);null = 沉寂(once 已过/表达式非法)。fromMs 语义:从该时刻起算下一次。 */
+declare function nextDueAfter(schedule: JobSchedule, fromMs: number): number | null;
+//#endregion
+//#region src/jobs.d.ts
+declare const BRIEFING_TEMPLATE_DEFAULT: string;
+interface ScriptSpec {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  timeoutMs?: number;
+  env?: Record<string, string>;
+}
+interface JobDeclaration {
+  maidId: string;
+  type?: string;
+  name?: string;
+  enabled?: boolean;
+  schedule: JobSchedule;
+  promptTemplate?: string;
+  target?: DeliveryAddress;
+  genTimeoutMs?: number;
+  script?: ScriptSpec;
+  deliverLocalDir?: string;
+  /**
+   * 固定路径落盘目的地(Task 12):存在即产物写盘、不投递(优先于 deliverLocalDir/target;
+   * script 型与 llm 型共用)。路径支持 `{{date}}` 占位 → job 时区 ISO 日期(YYYY-MM-DD,
+   * isoDateOf)。**job 声明者负责写成 per-maid 路径**(如 `<stateDir>/doris/overnight-{{date}}.txt`
+   * ——maid-voice 读取端按 `<stateDir>/<maidId>/overnight-<date>.txt` 约定读取),防多女仆串档。
+   */
+  persistTo?: string;
+  recentLimit?: number;
+  skipOnEmptyScriptOutput?: boolean;
+}
+interface CompiledJob {
+  jobId: string;
+  type: string;
+  maidId: string;
+  enabled: boolean;
+  kind: 'script' | 'llm';
+  promptTemplate: string;
+  script: ScriptSpec | undefined;
+  deliverLocalDir: string | undefined;
+  persistTo: string | undefined;
+  recentLimit: number | undefined;
+  skipOnEmptyScriptOutput: boolean;
+  target: DeliveryAddress | null;
+  genTimeoutMs: number;
+  schedule: JobSchedule;
+}
+declare function compileJobs(jobs: readonly JobDeclaration[] | undefined, warn: (m: string) => void): CompiledJob[];
+declare function renderRecentMemories(recents: readonly {
+  id?: string;
+  title: string;
+  content: string;
+  createdAt?: string;
+}[], maxChars: number): string;
+declare function renderBriefingPrompt(template: string, vars: {
+  date: string;
+  recentMemories: string;
+  scriptOutput?: string;
+  nightContext?: string;
+  overnightSentence?: string;
+}): string;
+//#endregion
+//#region src/state.d.ts
+type RunStatus = 'ok' | 'ok-silent' | 'script-failed' | 'gen-failed' | 'deliver-failed' | 'misfire-skipped' | 'overlap-skipped';
+interface JobRunState {
+  lastRunAt: string | undefined;
+  lastStatus: RunStatus | undefined;
+  lastError: string | undefined;
+  misfireCount: number;
+  nextDueAt: number | undefined;
+}
+type RunStateMap = Record<string, JobRunState>;
+declare function loadState(file: string): RunStateMap;
+declare function saveState(file: string, map: RunStateMap): void;
+//#endregion
+//#region ../maid-memory/lib/index.d.ts
+interface RecentMemory {
+  readonly id: string;
+  readonly title: string;
+  readonly content: string;
+  readonly createdAt?: string;
+}
+//#endregion
+//#region src/engine.d.ts
+interface EnginePorts {
+  identity: {
+    presetOf(maidId: string): string | undefined;
+    addressOf(maidId: string): {
+      botId: string;
+      targetId: string;
+    } | undefined;
+  };
+  memory: {
+    recent(maidId: string, limit: number): Promise<RecentMemory[]>;
+    markSkip(sessionId: string): void;
+  } | undefined;
+  agents: {
+    create(opts: Record<string, unknown>): Promise<{
+      agent: {
+        followup(message: unknown): void;
+        whenIdle(): Promise<void>;
+      };
+      dispose(): Promise<void>;
+    }>;
+  };
+  delivery: MaidDelivery;
+  events: {
+    onAssistantText(sessionId: string, cb: (text: string) => void): () => void;
+  };
+  now(): number;
+  /**
+   * M3c Task 12:maid-voice 服务面鸭子声明(不引 maid-voice 包依赖;plugin 侧经
+   * reflect 'maidVoice' 接入)。同步两方法;未挂 → {{nightContext}}/{{overnightSentence}}
+   * 渲染为空(fail-open,warn 在 plugin 装配期,照 maidMemory 未挂先例)。
+   */
+  voice?: {
+    buildNightContext(maidId: string): string;
+    getMorningSentence(maidId: string): string;
+  };
+}
+interface ResolvedCronConfig {
+  tickIntervalMs: number;
+  misfireWindowMs: number;
+  recentLimit: number;
+  recentMaxChars: number;
+  timezone: string;
+  deliverRetryDelayMs: number;
+  agent: {
+    provider: string;
+    model: string;
+    cwd?: string;
+  } | undefined;
+  agentSetup: ((agentCtx: unknown) => Promise<void>) | undefined;
+  stateFile: string;
+  /** 终局观测回调:每次终局迁移(finish 各终局 + overlap-skipped/misfire-skipped)在 persist 之后触发,携带同一 status/error。 */
+  onTerminal?: (jobId: string, status: RunStatus, error: string | undefined) => void;
+}
+declare function createCronEngine(config: ResolvedCronConfig, jobs: readonly CompiledJob[], ports: EnginePorts): {
+  tick: (nowMs?: number) => void;
+  whenIdle: () => Promise<void>;
+  dispose: () => Promise<void>;
+  runStates: () => RunStateMap;
+};
+//#endregion
+//#region src/plugin.d.ts
+interface MaidCronConfig {
+  tickIntervalMs?: number;
+  misfireWindowMs?: number;
+  recentLimit?: number;
+  recentMaxChars?: number;
+  timezone?: string;
+  deliverRetryDelayMs?: number;
+  stateFile: string;
+  agent?: {
+    provider: string;
+    model: string;
+    cwd?: string;
+  };
+  agentSetup?: (agentCtx: unknown) => Promise<void>;
+  /** T17:把 maid preset 挂进 cron 会话(persona/工具/技能目录全部继承);缺省 false——现有行为零变化。 */
+  mountPresets?: boolean;
+  /** agent-preset-registry 服务名(0.2.0 通道:ctx[name] 的 resolve/mount);缺省 'agentPresets'。 */
+  presetRegistryService?: string;
+  /** 时钟注入(测试用);缺省 Date.now()。 */
+  now?: () => number;
+  jobs?: JobDeclaration[];
+}
+interface MaidCronService {
+  tick(nowMs?: number): void;
+  whenIdle(): Promise<void>;
+  runStates(): RunStateMap;
+}
+declare const apply: (ctx: any, config: MaidCronConfig) => (() => Promise<void>);
+//#endregion
+//#region src/identity.d.ts
+declare const name = "maid-cron";
+declare const inject: string[];
+//#endregion
+export { BRIEFING_TEMPLATE_DEFAULT, type CompiledJob, type EnginePorts, type JobDeclaration, type JobRunState, type JobSchedule, type MaidCronConfig, type MaidCronService, type ResolvedCronConfig, type RunStateMap, type RunStatus, apply, compileJobs, createCronEngine, inject, loadState, name, nextDueAfter, renderBriefingPrompt, renderRecentMemories, saveState };