@theokit/sdk 1.5.0

package/dist/cron-BYVdYzob.d.ts

@@ -0,0 +1,221 @@
+import { aG as SDKUserMessage, A as AgentOptions, j as ListResult, m as Run } from './run-DkCD5DeO.js';
+
+/**
+ * Runtime hosting a cron job. Mirrors the agent runtime split.
+ *
+ * - `local` — the in-process scheduler activated via `Cron.start()` fires the
+ *   job while the host process is alive.
+ * - `cloud` — Theo PaaS schedules the job server-side; fires independent of
+ *   any SDK process.
+ *
+ * @public
+ */
+type CronRuntime = "local" | "cloud";
+/**
+ * Lifecycle state reported by `Cron.list()` / `Cron.get()`.
+ *
+ * @public
+ */
+type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
+/**
+ * Persistent cron-scheduled invocation of the Theo agent.
+ *
+ * Exactly one of {@link CronJob.agent} (ephemeral agent created on each fire)
+ * or {@link CronJob.agentId} (bound to an existing agent for context
+ * continuity) is set.
+ *
+ * @public
+ */
+interface CronJob {
+    id: string;
+    name?: string;
+    /** Standard 5-field POSIX cron expression or shorthand (`@hourly`, `@daily`, ...). */
+    cron: string;
+    /** IANA timezone identifier. Defaults to `"UTC"`. */
+    timezone?: string;
+    /** Message sent to the agent on each fire. */
+    message: string | SDKUserMessage;
+    /** Ephemeral agent options. Mutually exclusive with `agentId`. */
+    agent?: AgentOptions;
+    /** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`. */
+    agentId?: string;
+    /** Whether the scheduler will fire this job on schedule. */
+    enabled: boolean;
+    /** Current status. */
+    status: CronJobStatus;
+    /** Runtime that hosts this job. Inferred from `agent`/`agentId` at create time. */
+    runtime: CronRuntime;
+    /** Unix ms of the last successful fire, if any. */
+    lastRunAt?: number;
+    /** Unix ms of the next scheduled fire, computed by the scheduler. */
+    nextRunAt?: number;
+    /** Unix ms when the job was created. */
+    createdAt: number;
+}
+/**
+ * Options for `Cron.create()`.
+ *
+ * Pass `agent` for an ephemeral agent created fresh on each fire, OR
+ * `agentId` to reuse an existing agent (preserves conversation context across
+ * fires). Setting both is a `ConfigurationError`.
+ *
+ * @public
+ */
+interface CronCreateOptions {
+    cron: string;
+    message: string | SDKUserMessage;
+    agent?: AgentOptions;
+    agentId?: string;
+    name?: string;
+    timezone?: string;
+    /** Defaults to `true`. */
+    enabled?: boolean;
+    /** Falls back to `THEOKIT_API_KEY`. */
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.list()`.
+ *
+ * @public
+ */
+type CronListOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    apiKey?: string;
+});
+/**
+ * Options for `Cron.get()`.
+ *
+ * @public
+ */
+interface CronGetOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
+ *
+ * @public
+ */
+interface CronOperationOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.run()` — manually trigger a job off-schedule.
+ *
+ * @public
+ */
+interface CronRunOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.start()` — activates the in-process scheduler for local
+ * jobs.
+ *
+ * @public
+ */
+interface CronStartOptions {
+    /** Local workspace whose `.theokit/cron/jobs.json` to load. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Override the env API key. */
+    apiKey?: string;
+}
+/**
+ * Snapshot of the local scheduler returned by `Cron.status()`.
+ *
+ * @public
+ */
+interface CronSchedulerStatus {
+    /** Whether the in-process scheduler is currently running. */
+    running: boolean;
+    /** Number of jobs loaded into the scheduler. */
+    jobCount: number;
+    /** Unix ms of the next scheduled fire across all jobs, if any. */
+    nextFireAt?: number;
+    /** Last error observed in the scheduler, if any. */
+    lastError?: {
+        jobId: string;
+        message: string;
+        at: number;
+    };
+}
+
+/**
+ * Static façade for scheduling Theo agent runs on a cron expression.
+ *
+ * @public
+ */
+declare class Cron {
+    private constructor();
+    /**
+     * Create and persist a cron job.
+     *
+     * @public
+     */
+    static create(options: CronCreateOptions): Promise<CronJob>;
+    /**
+     * List cron jobs (local, cloud, or both).
+     *
+     * @public
+     */
+    static list(options?: CronListOptions): Promise<ListResult<CronJob>>;
+    /**
+     * Get a single cron job by ID.
+     *
+     * @public
+     */
+    static get(jobId: string, _options?: CronGetOptions): Promise<CronJob>;
+    /**
+     * Delete a cron job permanently.
+     *
+     * @public
+     */
+    static delete(jobId: string, _options?: CronOperationOptions): Promise<void>;
+    /**
+     * Re-enable a paused cron job.
+     *
+     * @public
+     */
+    static enable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Pause a cron job without deleting it.
+     *
+     * @public
+     */
+    static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Manually trigger a cron job off-schedule. Returns the resulting `Run`.
+     *
+     * @public
+     */
+    static run(jobId: string, _options?: CronRunOptions): Promise<Run>;
+    /**
+     * Activate the in-process scheduler for local cron jobs.
+     *
+     * @public
+     */
+    static start(options?: CronStartOptions): Promise<void>;
+    /**
+     * Stop the in-process scheduler. Jobs are preserved.
+     *
+     * @public
+     */
+    static stop(): Promise<void>;
+    /**
+     * Snapshot of the local scheduler.
+     *
+     * @public
+     */
+    static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
+}
+
+export { Cron as C, type CronCreateOptions as a, type CronGetOptions as b, type CronJob as c, type CronJobStatus as d, type CronListOptions as e, type CronOperationOptions as f, type CronRunOptions as g, type CronRuntime as h, type CronSchedulerStatus as i, type CronStartOptions as j };