@portel/photon-core 1.3.0 → 1.4.0

package/dist/stateful.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Stateful Workflow Execution with JSONL Persistence
+ *
+ * Enables photon workflows to be paused, resumed, and recovered across daemon restarts.
+ *
+ * ══════════════════════════════════════════════════════════════════════════════
+ * DESIGN PHILOSOPHY
+ * ══════════════════════════════════════════════════════════════════════════════
+ *
+ * Stateful workflows use an append-only JSONL log for persistence:
+ * - Each line is a self-contained JSON entry (start, emit, checkpoint, ask, answer, return, error)
+ * - Checkpoints mark safe resume points with accumulated state
+ * - Developer places checkpoint AFTER side effects to ensure idempotency
+ * - Resume loads log, reconstructs state from last checkpoint, continues
+ *
+ * ══════════════════════════════════════════════════════════════════════════════
+ * CHECKPOINT PATTERN (Idempotent Resume)
+ * ══════════════════════════════════════════════════════════════════════════════
+ *
+ * ```typescript
+ * async *workflow() {
+ *   // Step 1: Side effect (e.g., posting to Slack)
+ *   const posted = await this.slack.post_message({ channel: '#eng', text: 'Hello' });
+ *   yield { checkpoint: true, state: { step: 1, messageTs: posted.ts } };
+ *
+ *   // Step 2: Another side effect (e.g., creating GitHub issue)
+ *   const issue = await this.github.create_issue({ ... });
+ *   yield { checkpoint: true, state: { step: 2, messageTs: posted.ts, issueNumber: issue.number } };
+ *
+ *   return { posted, issue };
+ * }
+ * ```
+ *
+ * On resume: Load state from last checkpoint, skip to that step, continue execution.
+ *
+ * ══════════════════════════════════════════════════════════════════════════════
+ * JSONL LOG FORMAT
+ * ══════════════════════════════════════════════════════════════════════════════
+ *
+ * ~/.photon/runs/{runId}.jsonl
+ *
+ * ```jsonl
+ * {"t":"start","tool":"generate","params":{"week":"52"},"ts":1704067200}
+ * {"t":"emit","emit":"status","message":"Collecting data...","ts":1704067201}
+ * {"t":"checkpoint","id":"cp_1","state":{"commits":["a1b2c3"],"step":1},"ts":1704067205}
+ * {"t":"ask","id":"approve","ask":"confirm","message":"Continue?","ts":1704067211}
+ * {"t":"answer","id":"approve","value":true,"ts":1704067215}
+ * {"t":"return","value":{"status":"done"},"ts":1704067220}
+ * ```
+ *
+ * @module stateful
+ */
+import type { StateLogEntry, WorkflowRun, WorkflowStatus } from './types.js';
+import { type PhotonYield, type InputProvider, type OutputHandler } from './generator.js';
+/**
+ * Default runs directory (~/.photon/runs)
+ */
+export declare const RUNS_DIR: string;
+/**
+ * Checkpoint yield - marks a safe resume point
+ *
+ * @example
+ * // After a side effect, checkpoint to preserve state
+ * const posted = await this.slack.post_message({ ... });
+ * yield { checkpoint: true, state: { step: 1, messageTs: posted.ts } };
+ */
+export interface CheckpointYield {
+    /** Marker for checkpoint yield */
+    checkpoint: true;
+    /** State snapshot to preserve */
+    state: Record<string, any>;
+    /** Optional checkpoint ID (auto-generated if not provided) */
+    id?: string;
+}
+/**
+ * Extended yield type including checkpoint
+ */
+export type StatefulYield = PhotonYield | CheckpointYield;
+/**
+ * Type guard for checkpoint yields
+ */
+export declare function isCheckpointYield(y: StatefulYield): y is CheckpointYield;
+/**
+ * State log writer for a single workflow run
+ */
+export declare class StateLog {
+    private runId;
+    private logPath;
+    constructor(runId: string, runsDir?: string);
+    /**
+     * Ensure runs directory exists
+     */
+    init(): Promise<void>;
+    /**
+     * Append an entry to the log
+     */
+    append(entry: Omit<StateLogEntry, 'ts'>): Promise<void>;
+    /**
+     * Write start entry
+     */
+    writeStart(tool: string, params: Record<string, any>): Promise<void>;
+    /**
+     * Write emit entry
+     */
+    writeEmit(emit: string, message?: string, data?: any): Promise<void>;
+    /**
+     * Write checkpoint entry
+     */
+    writeCheckpoint(id: string, state: Record<string, any>): Promise<void>;
+    /**
+     * Write ask entry
+     */
+    writeAsk(id: string, ask: string, message: string): Promise<void>;
+    /**
+     * Write answer entry
+     */
+    writeAnswer(id: string, value: any): Promise<void>;
+    /**
+     * Write return entry
+     */
+    writeReturn(value: any): Promise<void>;
+    /**
+     * Write error entry
+     */
+    writeError(message: string, stack?: string): Promise<void>;
+    /**
+     * Read all entries from the log
+     */
+    readAll(): Promise<StateLogEntry[]>;
+    /**
+     * Stream entries from the log (memory efficient for large logs)
+     */
+    stream(): AsyncGenerator<StateLogEntry>;
+    /**
+     * Get the log file path
+     */
+    getPath(): string;
+}
+/**
+ * Reconstructed state from a workflow log
+ */
+export interface ResumeState {
+    /** Tool/method being executed */
+    tool: string;
+    /** Input parameters */
+    params: Record<string, any>;
+    /** Is workflow complete? */
+    isComplete: boolean;
+    /** Final result (if complete) */
+    result?: any;
+    /** Error (if failed) */
+    error?: string;
+    /** Last checkpoint state */
+    lastCheckpoint?: {
+        id: string;
+        state: Record<string, any>;
+        ts: number;
+    };
+    /** Answered asks (id -> value) */
+    answers: Record<string, any>;
+    /** All entries in order */
+    entries: StateLogEntry[];
+}
+/**
+ * Parse a workflow log and reconstruct resume state
+ */
+export declare function parseResumeState(runId: string, runsDir?: string): Promise<ResumeState | null>;
+/**
+ * Configuration for stateful generator execution
+ */
+export interface StatefulExecutorConfig {
+    /** Run ID (generated if not provided) */
+    runId?: string;
+    /** Runs directory (defaults to ~/.photon/runs) */
+    runsDir?: string;
+    /** Photon name (for metadata) */
+    photon: string;
+    /** Tool name being executed */
+    tool: string;
+    /** Input parameters */
+    params: Record<string, any>;
+    /** Input provider for ask yields */
+    inputProvider: InputProvider;
+    /** Output handler for emit yields */
+    outputHandler?: OutputHandler;
+    /** Resume from existing run (skips to last checkpoint) */
+    resume?: boolean;
+}
+/**
+ * Result of stateful execution
+ */
+export interface StatefulExecutionResult<T> {
+    /** Run ID */
+    runId: string;
+    /** Final result (if completed) */
+    result?: T;
+    /** Error message (if failed) */
+    error?: string;
+    /** Was this resumed from a previous run? */
+    resumed: boolean;
+    /** Final status */
+    status: WorkflowStatus;
+}
+/**
+ * Generate a unique run ID
+ */
+export declare function generateRunId(): string;
+/**
+ * Execute a stateful generator with checkpoint support
+ *
+ * @example
+ * const result = await executeStatefulGenerator(workflow(), {
+ *   photon: 'weekly-report',
+ *   tool: 'generate',
+ *   params: { week: 52 },
+ *   inputProvider: cliInputProvider,
+ *   outputHandler: (emit) => console.log(emit.message)
+ * });
+ */
+export declare function executeStatefulGenerator<T>(generatorFn: () => AsyncGenerator<StatefulYield, T, any>, config: StatefulExecutorConfig): Promise<StatefulExecutionResult<T>>;
+/**
+ * List all workflow runs
+ */
+export declare function listRuns(runsDir?: string): Promise<WorkflowRun[]>;
+/**
+ * Get info about a specific run
+ */
+export declare function getRunInfo(runId: string, runsDir?: string): Promise<WorkflowRun | null>;
+/**
+ * Delete a workflow run
+ */
+export declare function deleteRun(runId: string, runsDir?: string): Promise<void>;
+/**
+ * Clean up completed/failed runs older than specified age
+ */
+export declare function cleanupRuns(maxAgeMs: number, runsDir?: string): Promise<number>;
+export { type StateLogEntry, type StateLogStart, type StateLogEmit, type StateLogCheckpoint, type StateLogAsk, type StateLogAnswer, type StateLogReturn, type StateLogError, type WorkflowRun, type WorkflowStatus, } from './types.js';
+//# sourceMappingURL=stateful.d.ts.map

package/dist/stateful.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful.d.ts","sourceRoot":"","sources":["../src/stateful.ts"],"names":[],"mappings":"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"}