agent.libx.js 0.93.45 → 0.94.1

package/dist/index.d.ts

@@ -293,6 +293,99 @@ declare class FakeAIClient implements ChatLike {
 /** Build a tool_call block (arguments JSON-stringified, matching the wire format). */
 declare const toolCall: (id: string, name: string, args: object) => ToolCall;
 
+/**
+ * In-process scheduler — timers that fire prompts into the agent loop while the session is alive.
+ * Three trigger modes: one-off ({at}), interval ({everyMs}), cron ({cron}).
+ * The scheduler never calls `turn()` itself — it invokes an IoC `fire` callback with due jobs,
+ * keeping it testable and host-agnostic. Persistence is the host's responsibility (serialize jobs
+ * into the session and re-arm on resume).
+ *
+ * Survives --resume (host reloads); does NOT survive process exit (no daemon, no launchd).
+ */
+type TriggerOneOff = {
+    at: number;
+};
+type TriggerInterval = {
+    everyMs: number;
+};
+type TriggerCron = {
+    cron: string;
+};
+type Trigger = TriggerOneOff | TriggerInterval | TriggerCron;
+type ScheduledJobStatus = 'active' | 'done';
+interface ScheduledJob {
+    id: string;
+    prompt: string;
+    trigger: Trigger;
+    status: ScheduledJobStatus;
+    created: number;
+    lastRun?: number;
+    runs: number;
+    /** Optional label for display (e.g. footer, /schedule list). */
+    label?: string;
+}
+/** Serializable snapshot for session persistence (same shape — kept as an alias for clarity at call sites). */
+type ScheduledJobSnapshot = ScheduledJob;
+interface SchedulerOptions {
+    /** Called when a job is due. Must not throw — the scheduler logs errors and continues. */
+    fire: (job: ScheduledJob) => Promise<void> | void;
+    /** Monotonic clock override for testing (default: Date.now). */
+    now?: () => number;
+    /** Tick interval in ms (default: 15_000 — 15s). */
+    tickMs?: number;
+    /** If true, suppress the setInterval (for unit tests that call tick() manually). */
+    manual?: boolean;
+}
+interface CronFields {
+    minute: number[];
+    hour: number[];
+    dom: number[];
+    month: number[];
+    dow: number[];
+}
+declare function parseCron(expr: string): CronFields;
+declare function cronMatches(fields: CronFields, date: Date): boolean;
+/** Next occurrence of `cron` after `after` (epoch ms). Returns epoch ms, or null if >366 days out (guard). */
+declare function nextCronAfter(cron: string, after: number): number | null;
+declare class Scheduler {
+    private jobs;
+    private seq;
+    private timer;
+    private firing;
+    private readonly fire;
+    private readonly now;
+    private readonly tickMs;
+    constructor(opts: SchedulerOptions);
+    /** Start the tick timer. Idempotent. */
+    start(): void;
+    /** Stop the tick timer. Does not clear jobs. */
+    stop(): void;
+    /** Add a scheduled job. Returns the job id. */
+    add(opts: {
+        prompt: string;
+        trigger: Trigger;
+        label?: string;
+    }): string;
+    /** Cancel a job. Returns false if not found. */
+    cancel(id: string): boolean;
+    get(id: string): ScheduledJob | undefined;
+    list(): ScheduledJob[];
+    active(): ScheduledJob[];
+    /** Compute when a job next fires (epoch ms), or null if done/unknown. */
+    nextFire(job: ScheduledJob): number | null;
+    /** Check all active jobs and fire any that are due. Reentrant-safe. */
+    tick(): Promise<void>;
+    /** Export all jobs for session persistence. */
+    snapshot(): ScheduledJobSnapshot[];
+    /** Restore jobs from a snapshot (e.g. on --resume). Clears existing jobs first. */
+    restore(snapshots: ScheduledJobSnapshot[]): void;
+    /** Number of active jobs. */
+    get size(): number;
+    destroy(): void;
+}
+
+declare function makeScheduleTools(scheduler: Scheduler): AgentTool[];
+
 /** Sandbox mode: an in-memory VFS — the real disk is never read or written. Edge/browser/test/dry-run. */
 declare function sandboxAgentOptions(opts?: Partial<AgentOptions>): Partial<AgentOptions>;
 /** Disk mode (the default): operate on the real filesystem, jailed to cwd (secrets hidden by DEFAULT_DENY).
@@ -1162,4 +1255,4 @@ declare class CartesiaTTS {
     close(): void;
 }
 
-export { Agent, type AgentDef, AgentOptions, AgentTool, type AskOptions, type Attempt, type AudioSink, type AudioSource, type AuthProvider, BodDbFilesystem, CartesiaTTS, CartesiaTTSOptions, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_DENY, DuplexAgent, DuplexAgentOptions, type DuplexTaskStatus, FakeAIClient, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, type LoadMemoryOpts, MEMORY_PROMPT, MessageContent, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, type ReflectOptions, RunResult, SCRATCH_DIR, STT_SAMPLE_RATE, Scratch, type ScratchOptions, ScriptedHostBridge, type SkillInfo, SonioxSTT, SonioxSTTOptions, type SttLike, TTS_SAMPLE_RATE, type TaskRecord, type TaskToolOptions, ToolCall, type ToolSpec, type TtsLike, UserQuestion, VOICE_MEMORY_PROMPT, VOICE_SYSTEM_PROMPT, VoiceEngine, VoiceEngineOptions, type VoiceState, type WebFetchOptions, type WebSearchOptions, type WorkerTier, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, compileSynthesizedTool, decodeDdgUrl, diskAgentOptions, expandCommand, expandTemplate, forComponent, fullAgentOptions, globTool, grepTool, htmlToText, idfWeights, lessonCapture, loadAgents, loadCommands, loadInstructions, loadMemory, loadSkills, makeAskTool, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchTool, mkdirp, multiEditTool, parseDdgHtml, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, resolveAuth, rollbackTool, sandboxAgentOptions, slugify, tokenize, toolCall, topByRelevance, validateToolCode, webFetchTool, webSearchTool, writeFact, writeTool };
+export { Agent, type AgentDef, AgentOptions, AgentTool, type AskOptions, type Attempt, type AudioSink, type AudioSource, type AuthProvider, BodDbFilesystem, CartesiaTTS, CartesiaTTSOptions, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_DENY, DuplexAgent, DuplexAgentOptions, type DuplexTaskStatus, FakeAIClient, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, type LoadMemoryOpts, MEMORY_PROMPT, MessageContent, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, type ReflectOptions, RunResult, SCRATCH_DIR, STT_SAMPLE_RATE, type ScheduledJob, type ScheduledJobSnapshot, Scheduler, type SchedulerOptions, Scratch, type ScratchOptions, ScriptedHostBridge, type SkillInfo, SonioxSTT, SonioxSTTOptions, type SttLike, TTS_SAMPLE_RATE, type TaskRecord, type TaskToolOptions, ToolCall, type ToolSpec, type Trigger, type TriggerCron, type TriggerInterval, type TriggerOneOff, type TtsLike, UserQuestion, VOICE_MEMORY_PROMPT, VOICE_SYSTEM_PROMPT, VoiceEngine, VoiceEngineOptions, type VoiceState, type WebFetchOptions, type WebSearchOptions, type WorkerTier, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, compileSynthesizedTool, cronMatches, decodeDdgUrl, diskAgentOptions, expandCommand, expandTemplate, forComponent, fullAgentOptions, globTool, grepTool, htmlToText, idfWeights, lessonCapture, loadAgents, loadCommands, loadInstructions, loadMemory, loadSkills, makeAskTool, makeScheduleTools, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchTool, mkdirp, multiEditTool, nextCronAfter, parseCron, parseDdgHtml, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, resolveAuth, rollbackTool, sandboxAgentOptions, slugify, tokenize, toolCall, topByRelevance, validateToolCode, webFetchTool, webSearchTool, writeFact, writeTool };

package/dist/index.js

@@ -3583,6 +3583,253 @@ var toolCall = (id, name, args) => ({
 // src/index.ts
 init_tools();
 
+// src/scheduler.ts
+function parseCronField(field, min, max) {
+  const vals = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    const [rangeStr, stepStr] = part.split("/");
+    const step = stepStr ? parseInt(stepStr, 10) : 1;
+    if (isNaN(step) || step < 1) throw new Error(`invalid cron step: ${part}`);
+    let lo, hi;
+    if (rangeStr === "*") {
+      lo = min;
+      hi = max;
+    } else if (rangeStr.includes("-")) {
+      const [a, b] = rangeStr.split("-").map(Number);
+      if (isNaN(a) || isNaN(b)) throw new Error(`invalid cron range: ${part}`);
+      lo = a;
+      hi = b;
+    } else {
+      const n = parseInt(rangeStr, 10);
+      if (isNaN(n)) throw new Error(`invalid cron value: ${part}`);
+      lo = n;
+      hi = stepStr ? max : n;
+    }
+    for (let i = lo; i <= hi; i += step) vals.add(i);
+  }
+  return [...vals].sort((a, b) => a - b);
+}
+function parseCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error(`cron expression must have 5 fields (minute hour dom month dow), got ${parts.length}: "${expr}"`);
+  return {
+    minute: parseCronField(parts[0], 0, 59),
+    hour: parseCronField(parts[1], 0, 23),
+    dom: parseCronField(parts[2], 1, 31),
+    month: parseCronField(parts[3], 1, 12),
+    dow: parseCronField(parts[4], 0, 6)
+  };
+}
+function cronMatches(fields, date) {
+  return fields.minute.includes(date.getMinutes()) && fields.hour.includes(date.getHours()) && fields.dom.includes(date.getDate()) && fields.month.includes(date.getMonth() + 1) && fields.dow.includes(date.getDay());
+}
+function nextCronAfter(cron, after) {
+  const fields = parseCron(cron);
+  const d = new Date(after);
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1);
+  const limit = after + 366 * 864e5;
+  while (d.getTime() <= limit) {
+    if (cronMatches(fields, d)) return d.getTime();
+    d.setMinutes(d.getMinutes() + 1);
+  }
+  return null;
+}
+var Scheduler = class {
+  jobs = /* @__PURE__ */ new Map();
+  seq = 0;
+  timer = null;
+  firing = false;
+  fire;
+  now;
+  tickMs;
+  constructor(opts) {
+    this.fire = opts.fire;
+    this.now = opts.now ?? Date.now;
+    this.tickMs = opts.tickMs ?? 15e3;
+    if (!opts.manual) this.start();
+  }
+  /** Start the tick timer. Idempotent. */
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.tick(), this.tickMs);
+    if (typeof this.timer === "object" && "unref" in this.timer) this.timer.unref();
+  }
+  /** Stop the tick timer. Does not clear jobs. */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /** Add a scheduled job. Returns the job id. */
+  add(opts) {
+    if ("cron" in opts.trigger) parseCron(opts.trigger.cron);
+    if ("at" in opts.trigger && opts.trigger.at < this.now()) {
+    }
+    if ("everyMs" in opts.trigger && opts.trigger.everyMs < 1e3) {
+      throw new Error("interval must be >= 1000ms");
+    }
+    const id = `sched-${++this.seq}`;
+    this.jobs.set(id, {
+      id,
+      prompt: opts.prompt,
+      trigger: opts.trigger,
+      status: "active",
+      created: this.now(),
+      runs: 0,
+      label: opts.label
+    });
+    return id;
+  }
+  /** Cancel a job. Returns false if not found. */
+  cancel(id) {
+    const j = this.jobs.get(id);
+    if (!j) return false;
+    j.status = "done";
+    return true;
+  }
+  get(id) {
+    return this.jobs.get(id);
+  }
+  list() {
+    return [...this.jobs.values()];
+  }
+  active() {
+    return this.list().filter((j) => j.status === "active");
+  }
+  /** Compute when a job next fires (epoch ms), or null if done/unknown. */
+  nextFire(job) {
+    if (job.status !== "active") return null;
+    const t = job.trigger;
+    if ("at" in t) return t.at;
+    if ("everyMs" in t) return (job.lastRun ?? job.created) + t.everyMs;
+    if ("cron" in t) return nextCronAfter(t.cron, job.lastRun ?? job.created);
+    return null;
+  }
+  /** Check all active jobs and fire any that are due. Reentrant-safe. */
+  async tick() {
+    if (this.firing) return;
+    this.firing = true;
+    try {
+      const now4 = this.now();
+      for (const job of this.jobs.values()) {
+        if (job.status !== "active") continue;
+        const due = this.nextFire(job);
+        if (due == null || due > now4) continue;
+        job.lastRun = now4;
+        job.runs++;
+        if ("at" in job.trigger) job.status = "done";
+        try {
+          await this.fire(job);
+        } catch {
+        }
+      }
+    } finally {
+      this.firing = false;
+    }
+  }
+  /** Export all jobs for session persistence. */
+  snapshot() {
+    return this.list().filter((j) => j.status === "active").map((j) => ({ ...j }));
+  }
+  /** Restore jobs from a snapshot (e.g. on --resume). Clears existing jobs first. */
+  restore(snapshots) {
+    this.jobs.clear();
+    for (const s of snapshots) {
+      this.seq = Math.max(this.seq, parseInt(s.id.replace("sched-", ""), 10) || 0);
+      this.jobs.set(s.id, { ...s });
+    }
+  }
+  /** Number of active jobs. */
+  get size() {
+    return this.active().length;
+  }
+  destroy() {
+    this.stop();
+    this.jobs.clear();
+  }
+};
+function makeScheduleTools(scheduler) {
+  return [
+    {
+      name: "ScheduleTask",
+      description: 'Schedule a prompt to fire automatically while this session is alive.\nModes:\n  \u2022 One-off:   {at: <epoch_ms>}        \u2014 fires once at that time, then done.\n  \u2022 Interval:  {everyMs: <ms>}          \u2014 fires repeatedly (\u22651s).\n  \u2022 Cron:      {cron: "min hr dom mon dow"} \u2014 standard 5-field cron.\nReturns the job id. Jobs only fire while the CLI session is running \u2014 they do NOT survive quitting.',
+      parameters: {
+        type: "object",
+        required: ["prompt", "trigger"],
+        properties: {
+          prompt: { type: "string", description: "The prompt to inject when the job fires." },
+          trigger: {
+            type: "object",
+            description: 'One of: {at: epoch_ms}, {everyMs: ms}, {cron: "5-field expr"}.',
+            properties: {
+              at: { type: "number" },
+              everyMs: { type: "number" },
+              cron: { type: "string" }
+            }
+          },
+          label: { type: "string", description: "Short label for display (optional)." }
+        }
+      },
+      async run({ prompt, trigger, label }) {
+        try {
+          const id = scheduler.add({ prompt, trigger, label });
+          const job = scheduler.get(id);
+          const next = scheduler.nextFire(job);
+          return `Scheduled ${id}${label ? ` (${label})` : ""}. Next fire: ${next ? new Date(next).toLocaleString() : "now"}.`;
+        } catch (e) {
+          return `Error: ${e?.message ?? e}`;
+        }
+      }
+    },
+    {
+      name: "ScheduleList",
+      description: "List all scheduled jobs and their next fire time.",
+      parameters: { type: "object", properties: {} },
+      async run() {
+        const jobs = scheduler.list();
+        if (!jobs.length) return "(no scheduled jobs)";
+        return jobs.map((j) => {
+          const next = scheduler.nextFire(j);
+          const trig = "at" in j.trigger ? `once @ ${new Date(j.trigger.at).toLocaleString()}` : "everyMs" in j.trigger ? `every ${(j.trigger.everyMs / 1e3).toFixed(0)}s` : `cron: ${j.trigger.cron}`;
+          return `${j.id}  ${j.status}  ${trig}  runs:${j.runs}  next:${next ? new Date(next).toLocaleTimeString() : "\u2014"}${j.label ? "  " + j.label : ""}`;
+        }).join("\n");
+      }
+    },
+    {
+      name: "ScheduleCancel",
+      description: "Cancel a scheduled job by id.",
+      parameters: { type: "object", required: ["id"], properties: { id: { type: "string" } } },
+      async run({ id }) {
+        return scheduler.cancel(String(id)) ? `Cancelled ${id}.` : `Error: no scheduled job '${id}'. Use ScheduleList to see jobs.`;
+      }
+    },
+    {
+      name: "Wakeup",
+      description: 'Self-pacing: schedule a one-off re-invocation of the agent after a delay.\nUse this to resume work later in the session (e.g. "check back in 5 minutes").\nThe prompt fires once, while the session is alive. Equivalent to ScheduleTask with {at: now + delayMs}.',
+      parameters: {
+        type: "object",
+        required: ["delayMs", "prompt"],
+        properties: {
+          delayMs: { type: "number", description: "Delay in milliseconds (minimum 5000)." },
+          prompt: { type: "string", description: "The prompt to inject when waking up." },
+          label: { type: "string" }
+        }
+      },
+      async run({ delayMs, prompt, label }) {
+        const delay = Math.max(5e3, Number(delayMs) || 5e3);
+        try {
+          const id = scheduler.add({ prompt, trigger: { at: Date.now() + delay }, label: label ?? "wakeup" });
+          return `Wakeup ${id} in ${(delay / 1e3).toFixed(0)}s.`;
+        } catch (e) {
+          return `Error: ${e?.message ?? e}`;
+        }
+      }
+    }
+  ];
+}
+
 // src/presets.ts
 init_tools();
 import { MemFilesystem } from "@livx.cc/wcli/core";
@@ -5380,6 +5627,7 @@ export {
   SCRATCH_DIR,
   STT_SAMPLE_RATE,
   SandboxJobRegistry,
+  Scheduler,
   Scratch,
   ScriptedHostBridge,
   SonioxSTT,
@@ -5398,6 +5646,7 @@ export {
   compileSynthesizedTool,
   composeHooks,
   contentText,
+  cronMatches,
   decodeDdgUrl,
   defaultTools,
   diskAgentOptions,
@@ -5425,6 +5674,7 @@ export {
   makeLazyMcpToolSearch,
   makeMcpToolSearch,
   makeMcpToolSearchFromMounted,
+  makeScheduleTools,
   makeTaskBatchTool,
   makeTaskTool,
   makeWebFetchTool,
@@ -5433,6 +5683,8 @@ export {
   mcpToolsToAgentTools,
   mkdirp,
   multiEditTool,
+  nextCronAfter,
+  parseCron,
   parseDdgHtml,
   planMode,
   raceAttempts,