@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/automation/runner.js

@@ -0,0 +1,92 @@
+/**
+ * cron-runtime — wire the CronScheduler's executor to a real run backend.
+ *
+ * B1 fix: `CronScheduler.setExecutor` was never called in production, so cron
+ * jobs were created and ticked but did nothing on fire. `bindCronToEngine`
+ * installs an executor that, for each fired job, hands a one-shot headless run
+ * request to the caller-supplied `runner`.
+ *
+ * Security contract: cron runs unattended, so each job's permission tier
+ * (`job.permissionLevel`) is resolved through `resolveWritePolicy`, which maps
+ * the tier to a permissionMode + approval backend (see write-policy.ts). The
+ * mode stays "default" so the classifier doesn't add its own acceptEdits
+ * auto-allow rules ahead of the backend — the backend is the single source of
+ * truth for what a tier permits. An undefined/unknown tier falls back to the
+ * read-only backend.
+ */
+import { AUTOMATION_RUN_SOURCE } from "../run/EngineRunner.js";
+import { resolveWritePolicy } from "./write-policy.js";
+import { logger } from "../logging/logger.js";
+/**
+ * Log a cron executor failure, then re-throw so the scheduler's own try/catch
+ * still records run stats and keeps ticking. Without this the failure was
+ * silently swallowed (the scheduler catch is empty) — a job could fail every
+ * fire with zero trace, which is the exact opposite of what the executor
+ * docstrings claimed ("we still log here so failures are visible").
+ */
+function logCronFailure(job, err) {
+    logger.warn("cron.executor_failed", {
+        cat: "automation",
+        jobId: job.id,
+        jobName: job.name,
+        error: err instanceof Error ? err.message : String(err),
+    });
+}
+/**
+ * Install the cron executor. After this call, a fired job invokes `runner`
+ * with a run request whose permission tier comes from the job. A thrown error
+ * is logged (`logCronFailure`) and re-thrown so the scheduler's catch records
+ * stats and keeps ticking — one transient bad run never stops future ticks. A
+ * PERMANENT failure the runner flags via `result.stop` (e.g. a resume target
+ * whose session was deleted) auto-disables the job with that reason, so it
+ * stops silently retrying forever.
+ */
+export function bindCronToEngine(scheduler, runner) {
+    scheduler.setExecutor(async (job, signal) => {
+        const policy = resolveWritePolicy(job.permissionLevel);
+        const req = {
+            job,
+            prompt: job.prompt,
+            permissionMode: policy.permissionMode,
+            approvalBackend: policy.approvalBackend,
+            sandboxMode: policy.sandboxMode,
+            signal,
+        };
+        try {
+            const result = await runner(req);
+            // A PERMANENT failure the runner flags (e.g. a resume target whose session
+            // was deleted) auto-disables the job so it stops silently retrying.
+            if (result?.stop) {
+                scheduler.disableWithReason(job.id, result.stop.reason);
+            }
+        }
+        catch (err) {
+            logCronFailure(job, err);
+            throw err; // let the scheduler's catch record stats + keep ticking
+        }
+    });
+}
+/**
+ * Wire the scheduler to submit each fired job into a RunManager. Records the
+ * resulting runId back onto the job (`lastRunId`) so the UI can link a job to
+ * its latest run in the RunStore. Read-only is enforced at the RunManager level
+ * by the host injecting `approvalBackend: HeadlessApprovalBackend("approve-read-only")`
+ * into createRunManager (Phase 2) until sandbox+write tiers land (Phase 4/5).
+ */
+export function bindCronToRunManager(scheduler, runManager) {
+    scheduler.setExecutor(async (job, _signal) => {
+        try {
+            const snapshot = await runManager.submit({
+                objective: job.prompt,
+                cwd: job.cwd,
+                metadata: { source: AUTOMATION_RUN_SOURCE, cronJobId: job.id, cronJobName: job.name },
+            });
+            // Record the run id on the job so the UI can link to run history.
+            job.lastRunId = snapshot.runId;
+        }
+        catch (err) {
+            logCronFailure(job, err);
+            throw err; // let the scheduler's catch record stats + keep ticking
+        }
+    });
+}

package/dist/automation/scheduler.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Cron scheduler — schedule and manage recurring agent tasks.
+ *
+ * Supports simple cron-like intervals. Each job runs the Engine
+ * with a predefined prompt on schedule.
+ */
+import type { CronStore } from "./store.js";
+/**
+ * True when a cron timer fired too far past its scheduled instant to be a
+ * legitimate on-time run — i.e. the host slept through the scheduled time and
+ * the timer fired on wake. Exported for unit testing the sleep/wake guard.
+ */
+export declare function isCronMisfire(scheduledFor: number, now: number): boolean;
+/** Permission tier a scheduled job runs under (Phase 5 enforces write tiers). */
+export type CronPermissionLevel = "read-only" | "workspace-write" | "full";
+export interface CronJob {
+    id: string;
+    name: string;
+    schedule: string;
+    prompt: string;
+    enabled: boolean;
+    lastRun?: number;
+    nextRun?: number;
+    runCount: number;
+    createdAt: number;
+    /** Working directory the job runs in (the project it monitors/edits). */
+    cwd?: string;
+    /** IANA timezone for cron-expression schedules (e.g. "Asia/Shanghai"). Default "UTC". */
+    timezone?: string;
+    /** Permission tier; defaults to read-only when unset. */
+    permissionLevel?: CronPermissionLevel;
+    /** RunStore run id of the most recent execution (Phase 2 RunManager path). */
+    lastRunId?: string;
+    /** True = one-shot: delete the job after its first real execution so it never
+     *  fires again (e.g. "in 10 minutes, do X once"). */
+    once?: boolean;
+    /** When set, the fired job RESUMES this codeshell chat session instead of
+     *  starting a fresh one: the prompt is appended as a new user turn to that
+     *  session (restored from disk if not in memory), carrying its transcript /
+     *  goal / context. Unset = the default standalone behaviour (new session per
+     *  fire). The host's executor honours this. */
+    resumeSessionId?: string;
+    /** Why the job was auto-disabled (set by `disableWithReason`), e.g. a resume
+     *  target whose session no longer exists. Surfaced in the UI so a silently
+     *  stopped job is explainable; cleared when the job is re-enabled. */
+    disabledReason?: string;
+}
+/** Optional metadata accepted by create(). */
+export interface CreateJobOptions {
+    cwd?: string;
+    timezone?: string;
+    permissionLevel?: CronPermissionLevel;
+    once?: boolean;
+    resumeSessionId?: string;
+}
+/** Fields editable via update(). Any omitted field is left unchanged. */
+export interface UpdateJobPatch {
+    name?: string;
+    prompt?: string;
+    schedule?: string;
+    timezone?: string;
+    cwd?: string;
+    permissionLevel?: CronPermissionLevel;
+}
+export declare class CronScheduler {
+    private jobs;
+    private timers;
+    /** Job ids with an execution currently in flight — prevents a tick from
+     *  starting a second run of a job whose previous run hasn't finished. */
+    private running;
+    /** In-flight runs keyed by job id: the AbortController that cancels the run,
+     *  plus `done` — a promise that resolves when the run has FULLY settled
+     *  (executor returned, including any post-abort bookkeeping like Engine's
+     *  final saveState). The re-entrancy guard (`running`) ensures at most one
+     *  run per job, so one entry per job id is sufficient. `abort(jobId)` trips
+     *  the controller and returns `done` so callers can wait for the run to
+     *  actually stop before acting (e.g. deleting its session dir without racing
+     *  a final write that would recreate it). */
+    private runningControllers;
+    private nextId;
+    private onExecute?;
+    /** Optional persistence backend. When set, every create/delete/pause/resume
+     *  writes the full job set to disk so jobs survive a restart. */
+    private store?;
+    /** When false, the scheduler persists + tracks jobs but NEVER arms timers
+     *  (so it can't execute). Used by the desktop agent worker, a separate
+     *  process from the main process that owns execution. Default true. */
+    private executionEnabled;
+    constructor(store?: CronStore);
+    /**
+     * Disable (or re-enable) timer arming / execution. A host that only needs to
+     * persist + read jobs — never run them — calls setExecutionEnabled(false).
+     * Stops any timers already armed when turning off.
+     */
+    setExecutionEnabled(enabled: boolean): void;
+    /** Attach (or replace) the persistence backend. Used to give the shared
+     *  singleton a store at runtime startup without changing its identity. */
+    setStore(store: CronStore): void;
+    setExecutor(fn: (job: CronJob, signal: AbortSignal) => Promise<void>): void;
+    /**
+     * Abort the in-flight run of `jobId`, if any. Aborts the AbortSignal handed
+     * to the executor (which Engine.run cooperates with — it resolves with
+     * reason "aborted_streaming" rather than throwing). Returns false when the
+     * job has no run currently in flight (already settled, never started, or
+     * unknown id). The run's own finally block clears the controller, so a
+     * settled run is a no-op here.
+     */
+    abort(jobId: string): Promise<boolean>;
+    /**
+     * Restore persisted jobs and rebuild their timers. Call once at startup
+     * after `setStore`. nextRun is recomputed forward from now — we do NOT
+     * catch up on runs missed while the process was down (avoids a restart
+     * thundering-herd; aligns with Codex's stateless philosophy). Disabled
+     * jobs are restored without a timer.
+     */
+    /**
+     * Reconcile in-memory jobs against the on-disk store (the store is the source
+     * of truth). Safe to call repeatedly — used both at startup and as a periodic
+     * re-sync when another process (e.g. the desktop agent worker) may have
+     * created/deleted/changed jobs through the same store. Reconciliation:
+     *   - jobs on disk but not in memory  → added (and armed if enabled)
+     *   - jobs in memory but not on disk  → removed + timer cleared
+     *   - jobs whose schedule/enabled differ → re-armed to match disk
+     *
+     * Pass `{ arm: false }` in a host that must NOT execute jobs (the worker —
+     * separate process from the one that owns execution); it still tracks +
+     * persists but starts no timers, so jobs never run twice across processes.
+     */
+    loadJobs(opts?: {
+        arm?: boolean;
+    }): void;
+    private reconcileJobs;
+    private nextPersistedId;
+    /** Recompute nextRun without arming a timer (for display in disabled/no-arm hosts). */
+    private refreshNextRunForDisplay;
+    private persist;
+    private persistRunStats;
+    create(name: string, schedule: string, prompt: string, opts?: CreateJobOptions): CronJob;
+    delete(id: string): boolean;
+    list(): CronJob[];
+    get(id: string): CronJob | undefined;
+    pause(id: string): boolean;
+    /**
+     * Auto-disable a job and record WHY (e.g. its resume target session was
+     * deleted). Unlike `delete`, the job is retained (enabled=false) so the user
+     * can see it stopped and its reason in the UI, then delete or re-point it.
+     * Mirrors `pause` but also stamps `disabledReason`. Idempotent-safe: a
+     * subsequent `resume()` clears the reason.
+     */
+    disableWithReason(id: string, reason: string): boolean;
+    resume(id: string): boolean;
+    /**
+     * Edit an existing job's fields (name/prompt/schedule/timezone/cwd/
+     * permissionLevel) without recreating it. A changed schedule is validated up
+     * front (throws on invalid, leaving the job untouched), then the timer is
+     * re-armed so the new schedule takes effect immediately. Enabled state is
+     * preserved — a paused job stays paused (no timer). Returns the updated job,
+     * or null if the id is unknown.
+     */
+    update(id: string, patch: UpdateJobPatch): CronJob | null;
+    stopAll(): void;
+    /**
+     * Fire a job immediately, out of band of its schedule (the "Run now" button).
+     * Respects the re-entrancy guard (no-op if a run is already in flight) and
+     * does not disturb the existing timer. Returns false if the id is unknown.
+     */
+    runNow(id: string): boolean;
+    /**
+     * Arm a job's timer. Interval schedules ("5m") use setInterval; cron-
+     * expression schedules ("0 9 * * 1-5") compute the next trigger in the
+     * job's timezone and use setTimeout, re-arming after each fire. nextRun is
+     * updated to reflect the scheduled instant.
+     */
+    private arm;
+    private refreshIntervalNextRun;
+    private armCron;
+    private clearTimer;
+    /**
+     * Shared fire path for both schedule kinds. Re-entrancy guard, run-stat
+     * bookkeeping, persistence, then the executor. `afterStats` updates nextRun
+     * for the next occurrence (interval: now+interval; cron: re-armed inside).
+     */
+    private fire;
+}
+/**
+ * Parse a schedule string into milliseconds.
+ * Supports: "30s", "5m", "1h", "1d", or raw (all-digit) milliseconds.
+ *
+ * Throws on anything else rather than silently falling back to a default —
+ * a typo like "5mn" should surface as an error, not quietly schedule every
+ * 10 minutes (review-2026-05-30).
+ */
+export declare function parseSchedule(schedule: string): number;
+export declare const cronScheduler: CronScheduler;