runwork 0.2.0

package/bundled-types/core-routes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Core Platform Routes
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module orchestrates core API routes for platform features.
+ * Each feature exposes its own routes in its respective core-* file.
+ * These routes are mounted before user-defined routes in index.ts.
+ */
+import { type Env } from './core-utils';
+import { Hono } from 'hono';
+export interface ClientErrorReport {
+    message: string;
+    url: string;
+    userAgent?: string;
+    timestamp: string;
+    stack?: string;
+    componentStack?: string;
+    errorBoundary?: boolean;
+    errorBoundaryProps?: Record<string, unknown>;
+    source?: string;
+    lineno?: number;
+    colno?: number;
+    error?: unknown;
+    level?: 'error' | 'warning' | 'info';
+    category?: string;
+}
+/**
+ * Mount all core platform routes on the Hono app
+ * Called from index.ts before user-defined routes
+ */
+export declare function setupRoutes(): Hono<{
+    Bindings: Env;
+}, import("hono/types").BlankSchema, "/">;

package/bundled-types/core-scheduler.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Core Scheduled Jobs Framework
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides the infrastructure for scheduled background jobs
+ * using a dedicated Cloudflare Durable Object (SchedulerDO).
+ *
+ * SchedulerDO is a standalone Durable Object that:
+ * - Owns its own storage for job metadata and history
+ * - Handles alarm-based job scheduling
+ * - Provides job management (pause, resume, trigger)
+ *
+ * Job handlers receive JobContext which includes env for entity access.
+ */
+import { DurableObject } from 'cloudflare:workers';
+import { type Env } from './core-utils';
+export interface ScheduledJob {
+    /** Unique name for this job (kebab-case, e.g., "daily-cleanup") */
+    name: string;
+    /** Cron expression (e.g., "0 0 * * *" for daily at midnight UTC) */
+    schedule: string;
+    /** Human-readable description of what this job does */
+    description?: string;
+    /** The handler function to execute */
+    handler: (ctx: JobContext) => Promise<JobResult>;
+    /** Whether the job is enabled (default: true) */
+    enabled?: boolean;
+}
+export interface JobContext {
+    /** Environment bindings */
+    env: Env;
+    /** Name of the job being executed */
+    jobName: string;
+    /** Unique ID for this execution run */
+    runId: string;
+    /** When this job was scheduled to run */
+    scheduledAt: Date;
+    /** Logger for structured job logging */
+    logger: JobLogger;
+}
+export interface JobResult {
+    /** Whether the job completed successfully */
+    success: boolean;
+    /** Additional result data (varies by job) */
+    [key: string]: unknown;
+}
+export interface JobLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+export interface JobRunRecord {
+    id: string;
+    jobName: string;
+    status: 'running' | 'completed' | 'failed';
+    scheduledAt: number;
+    startedAt: number;
+    completedAt?: number;
+    result?: JobResult;
+    error?: string;
+}
+export interface ScheduleState {
+    name: string;
+    schedule: string;
+    description?: string;
+    enabled: boolean;
+    lastRun: number | null;
+    nextRun: number;
+    lastError?: string;
+}
+export interface SchedulerRegistry {
+    schedules: Record<string, ScheduleState>;
+    initialized: boolean;
+}
+export interface ScheduleStatusResponse {
+    schedules: Array<{
+        name: string;
+        schedule: string;
+        description?: string;
+        enabled: boolean;
+        lastRun: number | null;
+        nextRun: number;
+        status: 'active' | 'paused' | 'error';
+        lastError?: string;
+    }>;
+}
+interface CronParts {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+}
+/**
+ * Parse a cron expression into its component parts
+ * Supports standard 5-field cron: minute hour day-of-month month day-of-week
+ */
+export declare function parseCronExpression(expr: string): CronParts;
+/**
+ * Calculate the next run time for a cron expression after the given date
+ */
+export declare function calculateNextRun(cronExpression: string, after?: Date): Date;
+/**
+ * SchedulerDO - Standalone Durable Object for job scheduling
+ *
+ * This is the actual Durable Object class that handles all scheduling.
+ * It owns its own storage for job metadata and execution history.
+ *
+ * Job handlers receive env so they can access entities and other services.
+ */
+export declare class SchedulerDO extends DurableObject<Env> {
+    private jobs;
+    private initialized;
+    constructor(ctx: DurableObjectState, env: Env);
+    /**
+     * Ensure the scheduler is initialized (lazy initialization for DO recovery)
+     * This is needed because DOs can be evicted and recreated, losing in-memory state.
+     * Also handles HMR: if getRegisteredSchedules() has changed since last init, re-sync.
+     */
+    private ensureInitialized;
+    /**
+     * Alarm handler - processes scheduled jobs
+     * Called by Cloudflare when an alarm fires
+     */
+    alarm(): Promise<void>;
+    /**
+     * Initialize the job scheduler with job definitions.
+     * Can be called again after HMR to sync new/changed job definitions.
+     */
+    initializeJobScheduler(jobs: ScheduledJob[]): Promise<void>;
+    /**
+     * Handle alarm - execute due jobs
+     */
+    private handleAlarm;
+    /**
+     * Execute a single job
+     */
+    private executeJob;
+    /**
+     * Store a job execution record in history
+     */
+    private storeHistoryRecord;
+    /**
+     * Schedule the next alarm for the earliest due job
+     */
+    private scheduleNextAlarm;
+    /**
+     * Get status of all schedules
+     */
+    getScheduleStatus(): Promise<ScheduleStatusResponse>;
+    /**
+     * Get job execution history
+     */
+    getJobHistory(jobName?: string, limit?: number): Promise<JobRunRecord[]>;
+    /**
+     * Manually trigger a job (for testing/debugging)
+     */
+    triggerJob(jobName: string): Promise<JobResult>;
+    /**
+     * Pause a scheduled job
+     */
+    pauseJob(jobName: string): Promise<void>;
+    /**
+     * Resume a paused job
+     */
+    resumeJob(jobName: string): Promise<void>;
+}
+/**
+ * Initialize the job scheduler with the given jobs.
+ */
+export declare function initializeScheduler(env: Env, jobs: ScheduledJob[]): Promise<void>;
+import type { Hono } from 'hono';
+/**
+ * Mount scheduler routes on the Hono app
+ * Provides internal API for schedule management
+ */
+export declare function schedulerRoutes(app: Hono<{
+    Bindings: Env;
+}>): void;
+export {};

package/bundled-types/core-utils.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Core Utilities
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides:
+ * - Env type: Environment bindings for Cloudflare Workers
+ * - API helpers: Response utilities for Hono routes
+ *
+ * Entity System: See core-entities.ts
+ * Workspace Context: See core-workspace.ts
+ * Scheduler: See core-scheduler.ts
+ */
+import type { Context } from 'hono';
+import type { EntityDO } from './core-entity-do';
+import type { SchedulerDO } from './core-scheduler';
+import type { BaseAgent } from './core-base-agent';
+/**
+ * Environment bindings for Cloudflare Workers
+ */
+export interface Env {
+    EntityDO: DurableObjectNamespace<EntityDO>;
+    SchedulerDO: DurableObjectNamespace<SchedulerDO>;
+    BaseAgent?: DurableObjectNamespace<BaseAgent>;
+    WorkspaceObject?: DurableObjectNamespace;
+    WorkflowInstance: DurableObjectNamespace;
+    WorkflowCoordinator: DurableObjectNamespace;
+    BUCKET?: R2Bucket;
+    WORKSPACE_ID?: string;
+    APP_ID?: string;
+    APP_NAME?: string;
+    WORKSPACE_API_URL?: string;
+    WORKSPACE_API_BASE_URL?: string;
+    WORKSPACE_API_KEY?: string;
+    DEPLOYMENT_MODE?: 'preview' | 'production';
+    VITE_DEPLOYMENT_MODE?: 'preview' | 'production';
+    RUNWORK_AI_PROXY_URL?: string;
+    RUNWORK_PROXY_TOKEN?: string;
+    INTEGRATIONS_PROXY_URL?: string;
+    ALLOWED_ORIGINS?: string;
+}
+/**
+ * Return a successful JSON response.
+ * Returns the data directly as the response body with 200 status.
+ */
+export declare const ok: <T>(c: Context, data: T) => Response & import("hono").TypedResponse<{
+    [x: string]: import("hono/utils/types").JSONValue;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">;
+/**
+ * Return a 400 Bad Request response
+ * Automatically logs the error for debugging in production logs
+ */
+export declare const bad: (c: Context, error: string) => Response & import("hono").TypedResponse<{
+    error: string;
+}, 400, "json">;
+/**
+ * Return a 404 Not Found response
+ * Automatically logs the error for debugging in production logs
+ */
+export declare const notFound: (c: Context, error?: string) => Response & import("hono").TypedResponse<{
+    error: string;
+}, 404, "json">;
+/**
+ * Type guard for non-empty strings
+ */
+export declare const isStr: (s: unknown) => s is string;
+/**
+ * Safely clone a value for Durable Object storage.
+ * Strips non-serializable references (R2Bucket, D1Database, DO stubs, etc.)
+ * that would cause structured clone to fail in ctx.storage.put().
+ */
+export declare function safeClone<T>(value: T, fallback?: T): T;
+export declare function platformFetch(env: Env, url: string | URL, init?: RequestInit): Promise<Response>;
+/**
+ * Workspace API fetch - routes workspace service requests through WorkspaceObject DO
+ * for production WfP workers, avoiding 522 recursive invocation errors.
+ *
+ * Workers for Platforms workers cannot HTTP-fetch back to their dispatcher domain.
+ * This routes through the WorkspaceObject DO binding in production, and falls back
+ * to standard HTTP with x-workspace-key auth header in preview/sandbox.
+ *
+ * @param env - Environment with workspace bindings
+ * @param path - Workspace API sub-path (e.g., '/ingest-event')
+ * @param init - Standard fetch options
+ */
+export declare function workspaceApiFetch(env: Pick<Env, 'WORKSPACE_API_URL' | 'WORKSPACE_API_KEY' | 'WORKSPACE_ID' | 'DEPLOYMENT_MODE' | 'WorkspaceObject'>, path: string, init?: RequestInit): Promise<Response>;

package/bundled-types/core-workflow-cloudflare.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Cloudflare Workflows Implementation
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * @deprecated This module is DEPRECATED and kept for reference only.
+ * Cloudflare Workflows do not support Workers for Platforms, so this code path
+ * is no longer used. The native DO-based workflow engine is used instead.
+ *
+ * For active workflow implementation, see:
+ * - core-workflow-instance.ts (WorkflowInstance DO)
+ * - core-workflow-coordinator.ts (WorkflowCoordinator DO)
+ * - core-workflows.ts (public API)
+ */
+import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
+import type { Env } from './core-utils';
+import type { WorkflowResult, WorkflowStatus, WorkflowInstanceInfo, WorkflowDefinition, WorkflowLogger, WorkflowStatusResponse } from './core-workflow-types';
+type WorkflowParams = {
+    workflowName: string;
+    params: Record<string, unknown>;
+};
+/**
+ * WorkflowRunner - Single entrypoint for all user-defined workflows
+ *
+ * This class extends Cloudflare's WorkflowEntrypoint and dispatches to
+ * the appropriate workflow handler based on the workflowName parameter.
+ */
+export declare class WorkflowRunner extends WorkflowEntrypoint<Env, WorkflowParams> {
+    run(event: WorkflowEvent<WorkflowParams>, step: WorkflowStep): Promise<WorkflowResult>;
+}
+/**
+ * WorkflowManager - Manages workflow state within a Durable Object
+ *
+ * Note: Actual workflow execution is handled by Cloudflare Workflows.
+ * This manager tracks metadata and provides status APIs.
+ */
+export declare class WorkflowManager {
+    private ctx;
+    private env;
+    private initialized;
+    constructor(ctx: DurableObjectState, env: Env);
+    /**
+     * Initialize the workflow manager with workflow definitions
+     */
+    initialize(workflows: WorkflowDefinition[]): Promise<void>;
+    /**
+     * Record a workflow instance creation
+     */
+    recordInstanceCreated(instanceId: string, workflowName: string, params: Record<string, unknown>): Promise<void>;
+    /**
+     * Update instance status
+     */
+    updateInstanceStatus(instanceId: string, status: WorkflowStatus, result?: WorkflowResult, error?: string): Promise<void>;
+    /**
+     * Get instance info
+     */
+    getInstance(instanceId: string): Promise<WorkflowInstanceInfo | null>;
+    /**
+     * List instances with optional filters
+     */
+    listInstances(options?: {
+        workflowName?: string;
+        status?: WorkflowStatus;
+        limit?: number;
+    }): Promise<WorkflowInstanceInfo[]>;
+    /**
+     * Get status of all workflows
+     */
+    getStatus(): Promise<WorkflowStatusResponse>;
+    /**
+     * Send an event to a workflow instance.
+     * Note: This stores the event for the workflow to pick up. The actual
+     * event delivery depends on how the workflow binding is configured.
+     */
+    sendEvent(instanceId: string, eventType: string, payload: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Get the workflow manager instance for a DO
+ * Used internally by workflow Durable Objects
+ */
+export declare function getWorkflowManager(ctx: DurableObjectState, env: Env): WorkflowManager;
+/**
+ * Create a workflow logger instance
+ */
+export declare function createWorkflowLogger(workflowName: string, instanceId: string): WorkflowLogger;
+export {};

package/bundled-types/core-workflow-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Workflow Configuration
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This platform uses native DO-based workflows exclusively.
+ * Cloudflare Workflows mode was removed because CF Workflows
+ * do not support Workers for Platforms.
+ *
+ * For workflow implementation, see:
+ * - core-workflow-instance.ts (WorkflowInstance DO)
+ * - core-workflow-coordinator.ts (WorkflowCoordinator DO)
+ * - core-workflows.ts (public API)
+ */
+/**
+ * Workflow infrastructure mode - always 'native'.
+ * Kept for backward compatibility.
+ */
+export declare const WORKFLOW_INFRA_MODE: "native";

package/bundled-types/core-workflow-coordinator.d.ts

@@ -0,0 +1,78 @@
+/**
+ * WorkflowCoordinator Durable Object - Native Workflow Engine
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * Singleton coordinator that manages workflow instances.
+ * - Creates WorkflowInstance DOs
+ * - Maintains an index for querying workflows
+ * - Routes signals to correct instances
+ */
+import { DurableObject } from 'cloudflare:workers';
+import type { NativeWorkflowStatus, NativeWorkflowConfig, ListWorkflowsOptions, WorkflowInstanceInfo, WorkflowInstanceStub } from './core-workflow-types';
+import { type Env } from './core-utils';
+/**
+ * WorkflowCoordinator Durable Object
+ *
+ * Acts as the central point for workflow management in native mode.
+ * Similar to WorkflowManager but creates actual DO instances instead
+ * of relying on Cloudflare Workflows.
+ */
+export declare class WorkflowCoordinator extends DurableObject<Env> {
+    private index;
+    /**
+     * Create a new workflow instance
+     */
+    create(workflowName: string, params: Record<string, unknown>, config?: Partial<NativeWorkflowConfig>, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Get a workflow instance stub
+     */
+    getInstance(instanceId: string): WorkflowInstanceStub;
+    /**
+     * Get workflow instance info (combines index with instance state)
+     */
+    getInstanceInfo(instanceId: string): Promise<WorkflowInstanceInfo | null>;
+    /**
+     * List workflow instances with optional filters
+     */
+    listInstances(options?: ListWorkflowsOptions): Promise<WorkflowInstanceInfo[]>;
+    /**
+     * Send a signal/event to a workflow instance
+     */
+    signal(instanceId: string, eventType: string, payload: unknown): Promise<void>;
+    /**
+     * Pause a workflow instance
+     */
+    pause(instanceId: string): Promise<void>;
+    /**
+     * Resume a paused workflow instance
+     */
+    resume(instanceId: string): Promise<void>;
+    /**
+     * Cancel a workflow instance
+     */
+    cancel(instanceId: string): Promise<void>;
+    /**
+     * Update the index when a workflow instance changes status
+     * Called by WorkflowInstance DOs
+     */
+    updateIndex(instanceId: string, workflowName: string, status: NativeWorkflowStatus): Promise<void>;
+    /**
+     * Get workflow statistics
+     */
+    getStats(): Promise<{
+        total: number;
+        byStatus: Record<string, number>;
+        byWorkflow: Record<string, number>;
+    }>;
+    /**
+     * Clean up completed/old workflow entries
+     * Should be called periodically to prevent index bloat
+     */
+    cleanup(options?: {
+        olderThanMs?: number;
+        keepCompleted?: boolean;
+        maxEntries?: number;
+    }): Promise<number>;
+    private ensureIndexLoaded;
+    private persistIndex;
+}

package/bundled-types/core-workflow-instance.d.ts

@@ -0,0 +1,82 @@
+/**
+ * WorkflowInstance Durable Object - Native Workflow Engine
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * One instance per workflow execution. Uses alarm-based execution
+ * to bypass the 30-second CPU limit and provide durability.
+ */
+import { DurableObject } from 'cloudflare:workers';
+import type { NativeWorkflowInstance, NativeWorkflowConfig } from './core-workflow-types';
+import type { StepOptions, WaitEventOptions } from './core-workflows';
+import { type Env } from './core-utils';
+/**
+ * WorkflowInstance Durable Object
+ *
+ * Manages the execution of a single workflow instance.
+ * Uses alarm chaining for step execution to bypass CPU limits.
+ */
+export declare class WorkflowInstanceDO extends DurableObject<Env> {
+    private instance;
+    private definition;
+    private stepCounter;
+    /**
+     * Create and start a new workflow instance
+     */
+    create(workflowName: string, input: unknown, instanceId: string, config?: Partial<NativeWorkflowConfig>, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Get current workflow status
+     */
+    getStatus(): Promise<NativeWorkflowInstance | null>;
+    /**
+     * Signal the workflow with an event (for waitForEvent steps)
+     */
+    signal(eventType: string, payload: unknown): Promise<void>;
+    /**
+     * Pause the workflow
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume a paused workflow
+     */
+    resume(): Promise<void>;
+    /**
+     * Cancel the workflow
+     */
+    cancel(): Promise<void>;
+    /**
+     * Alarm handler - main execution loop
+     */
+    alarm(): Promise<void>;
+    /**
+     * Execute the workflow handler
+     */
+    private executeWorkflow;
+    /**
+     * Execute or retrieve cached result for a step
+     */
+    executeStep<T>(name: string, options: StepOptions | undefined, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Sleep for a duration
+     */
+    executeSleep(name: string, duration: string): Promise<void>;
+    /**
+     * Sleep until a specific timestamp
+     */
+    executeSleepUntil(name: string, timestamp: Date): Promise<void>;
+    /**
+     * Wait for an external event
+     */
+    executeWaitForEvent<T>(name: string, options?: WaitEventOptions): Promise<T>;
+    private ensureLoaded;
+    private persist;
+    private isTerminal;
+    private isTimedOut;
+    private getCurrentStep;
+    private transitionTo;
+    private notifyCoordinator;
+    private generateStepId;
+    private parseDuration;
+    private calculateBackoff;
+    private executeWithTimeout;
+    private normalizeError;
+}