ralphwiggums 0.0.0 → 0.0.1

package/dist/src/checkpoint-do.js

@@ -0,0 +1,232 @@
+/**
+ * ralphwiggums - Durable Object Checkpoint Storage
+ * Production-ready checkpoint persistence using Cloudflare Durable Objects.
+ */
+import { Effect, Data, Layer } from "effect";
+// ============================================================================
+// Errors
+// ============================================================================
+export class CheckpointError extends Data.TaggedError("CheckpointError") {
+}
+// ============================================================================
+// In-Memory Store (fallback for single-instance or testing)
+// ============================================================================
+const IN_MEMORY_TTL = 3600000; // 1 hour
+/**
+ * Creates an in-memory checkpoint store (for development/testing).
+ */
+export function createInMemoryCheckpointStore() {
+    const store = new Map();
+    const taskIndex = new Map();
+    return {
+        async save(data) {
+            store.set(data.checkpointId, data);
+            const checkpoints = taskIndex.get(data.taskId) || [];
+            if (!checkpoints.includes(data.checkpointId)) {
+                checkpoints.push(data.checkpointId);
+                taskIndex.set(data.taskId, checkpoints);
+            }
+        },
+        async load(checkpointId) {
+            return store.get(checkpointId) || null;
+        },
+        async delete(checkpointId) {
+            const data = store.get(checkpointId);
+            if (data) {
+                store.delete(checkpointId);
+                const checkpoints = taskIndex.get(data.taskId);
+                if (checkpoints) {
+                    const idx = checkpoints.indexOf(checkpointId);
+                    if (idx >= 0)
+                        checkpoints.splice(idx, 1);
+                }
+            }
+        },
+        async list(taskId) {
+            const checkpointIds = taskIndex.get(taskId) || [];
+            return checkpointIds
+                .map((id) => store.get(id))
+                .filter((c) => c !== undefined);
+        },
+        async gc() {
+            const now = Date.now();
+            for (const [id, data] of store.entries()) {
+                if (now > data.expiresAt) {
+                    store.delete(id);
+                    const checkpoints = taskIndex.get(data.taskId);
+                    if (checkpoints) {
+                        const idx = checkpoints.indexOf(id);
+                        if (idx >= 0)
+                            checkpoints.splice(idx, 1);
+                    }
+                }
+            }
+        },
+    };
+}
+/**
+ * Checkpoint Durable Object utility class for Cloudflare Workers.
+ *
+ * Usage in worker:
+ * ```typescript
+ * import { CheckpointDO } from "ralphwiggums/checkpoint-do";
+ *
+ * export class RalphAgent extends DurableObject {
+ *   async fetch(request) {
+ *     return CheckpointDO.fetch(this.state, this.env, request);
+ *   }
+ * }
+ * ```
+ */
+export class CheckpointDO {
+    static async fetch(state, env, request) {
+        const url = new URL(request.url);
+        const path = url.pathname.slice(1);
+        try {
+            switch (request.method) {
+                case "GET": {
+                    if (path.startsWith("list/")) {
+                        const taskId = path.slice(5);
+                        const checkpoints = await CheckpointDO.list(state, taskId);
+                        return new Response(JSON.stringify(checkpoints), {
+                            headers: { "Content-Type": "application/json" },
+                        });
+                    }
+                    const checkpoint = await CheckpointDO.load(state, path);
+                    if (!checkpoint) {
+                        return new Response(JSON.stringify({ error: "not found" }), {
+                            status: 404,
+                            headers: { "Content-Type": "application/json" },
+                        });
+                    }
+                    return new Response(JSON.stringify(checkpoint), {
+                        headers: { "Content-Type": "application/json" },
+                    });
+                }
+                case "POST": {
+                    if (path === "save") {
+                        const data = await request.json();
+                        await CheckpointDO.save(state, data);
+                        return new Response(JSON.stringify({ success: true }), {
+                            headers: { "Content-Type": "application/json" },
+                        });
+                    }
+                    if (path === "gc") {
+                        await CheckpointDO.gc(state);
+                        return new Response(JSON.stringify({ success: true }), {
+                            headers: { "Content-Type": "application/json" },
+                        });
+                    }
+                    return new Response(JSON.stringify({ error: "unknown endpoint" }), {
+                        status: 404,
+                        headers: { "Content-Type": "application/json" },
+                    });
+                }
+                case "DELETE": {
+                    await CheckpointDO.delete(state, path);
+                    return new Response(JSON.stringify({ success: true }), {
+                        headers: { "Content-Type": "application/json" },
+                    });
+                }
+                default:
+                    return new Response(JSON.stringify({ error: "method not allowed" }), {
+                        status: 405,
+                        headers: { "Content-Type": "application/json" },
+                    });
+            }
+        }
+        catch (error) {
+            return new Response(JSON.stringify({
+                error: error instanceof Error ? error.message : "unknown error",
+            }), {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+    }
+    // ========================================================================
+    // DO Storage Operations
+    // ========================================================================
+    static async save(state, data) {
+        await state.storage.put(`checkpoint:${data.checkpointId}`, data);
+        const taskIndexRaw = await state.storage.get(`task_index:${data.taskId}`);
+        const taskIndex = taskIndexRaw || [];
+        if (!taskIndex.includes(data.checkpointId)) {
+            taskIndex.push(data.checkpointId);
+            await state.storage.put(`task_index:${data.taskId}`, taskIndex);
+        }
+    }
+    static async load(state, checkpointId) {
+        const data = await state.storage.get(`checkpoint:${checkpointId}`);
+        if (!data)
+            return null;
+        if (Date.now() > data.expiresAt) {
+            await CheckpointDO.delete(state, checkpointId);
+            return null;
+        }
+        return data;
+    }
+    static async delete(state, checkpointId) {
+        const data = await state.storage.get(`checkpoint:${checkpointId}`);
+        if (!data)
+            return;
+        await state.storage.delete(`checkpoint:${checkpointId}`);
+        const taskIndexRaw = await state.storage.get(`task_index:${data.taskId}`);
+        if (taskIndexRaw) {
+            const idx = taskIndexRaw.indexOf(checkpointId);
+            if (idx >= 0) {
+                taskIndexRaw.splice(idx, 1);
+                if (taskIndexRaw.length === 0) {
+                    await state.storage.delete(`task_index:${data.taskId}`);
+                }
+                else {
+                    await state.storage.put(`task_index:${data.taskId}`, taskIndexRaw);
+                }
+            }
+        }
+    }
+    static async list(state, taskId) {
+        const taskIndexRaw = await state.storage.get(`task_index:${taskId}`);
+        if (!taskIndexRaw)
+            return [];
+        const checkpoints = [];
+        const now = Date.now();
+        for (const checkpointId of taskIndexRaw) {
+            const data = await state.storage.get(`checkpoint:${checkpointId}`);
+            if (data && now <= data.expiresAt) {
+                checkpoints.push(data);
+            }
+        }
+        return checkpoints;
+    }
+    static async gc(state) {
+        const now = Date.now();
+        const taskIndexEntries = await state.storage.list({
+            start: "task_index:",
+            end: "task_index:\xff",
+        });
+        for (const [key, value] of taskIndexEntries) {
+            const taskIndex = value;
+            const validCheckpoints = [];
+            for (const checkpointId of taskIndex) {
+                const data = await state.storage.get(`checkpoint:${checkpointId}`);
+                if (data && now <= data.expiresAt) {
+                    validCheckpoints.push(checkpointId);
+                }
+                else {
+                    await state.storage.delete(`checkpoint:${checkpointId}`);
+                }
+            }
+            if (validCheckpoints.length === 0) {
+                await state.storage.delete(key);
+            }
+            else {
+                await state.storage.put(key, validCheckpoints);
+            }
+        }
+    }
+}
+// ============================================================================
+// Effect-friendly API
+// ============================================================================
+//# sourceMappingURL=checkpoint-do.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * ralphwiggums - Core
+ * Effect-first browser automation with OpenCode Zen.
+ * Production-ready with secure-by-default configuration.
+ */
+import { Effect } from "effect";
+export interface RalphOptions {
+    maxIterations?: number;
+    timeout?: number;
+    resumeFrom?: string;
+}
+export interface RalphResult {
+    success: boolean;
+    message: string;
+    data?: unknown;
+    iterations: number;
+    checkpointId?: string;
+    requestId?: string;
+}
+export interface RalphConfig {
+    apiKey: string;
+    maxPromptLength: number;
+    maxConcurrent: number;
+    requestTimeout: number;
+    debug: boolean;
+}
+declare const ValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ValidationError";
+} & Readonly<A>;
+export declare class ValidationError extends ValidationError_base<{
+    field: string;
+    reason: string;
+}> {
+}
+declare const MaxIterationsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MaxIterationsError";
+} & Readonly<A>;
+export declare class MaxIterationsError extends MaxIterationsError_base<{
+    maxIterations: number;
+    requestId: string;
+}> {
+}
+declare const TimeoutError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "TimeoutError";
+} & Readonly<A>;
+export declare class TimeoutError extends TimeoutError_base<{
+    duration: number;
+    requestId: string;
+}> {
+}
+declare const BrowserError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BrowserError";
+} & Readonly<A>;
+export declare class BrowserError extends BrowserError_base<{
+    reason: string;
+    requestId: string;
+}> {
+}
+declare const RateLimitError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RateLimitError";
+} & Readonly<A>;
+export declare class RateLimitError extends RateLimitError_base<{
+    retryAfter: number;
+}> {
+}
+declare const UnauthorizedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "UnauthorizedError";
+} & Readonly<A>;
+export declare class UnauthorizedError extends UnauthorizedError_base {
+}
+declare const InternalError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InternalError";
+} & Readonly<A>;
+declare class InternalError extends InternalError_base {
+    readonly requestId: string;
+    readonly message: string;
+    constructor(requestId: string, message: string);
+}
+export declare function getConfig(): RalphConfig;
+export declare function generateRequestId(): string;
+export declare function log(requestId: string, level: string, message: string, meta?: Record<string, unknown>): void;
+interface CircuitState {
+    state: "closed" | "open" | "half-open";
+    lastFailure: number;
+    failureCount: number;
+}
+export declare function getCircuitState(): CircuitState;
+export interface CheckpointData {
+    checkpointId: string;
+    taskId: string;
+    iteration: number;
+    url?: string;
+    pageState?: string;
+    timestamp: number;
+    expiresAt: number;
+}
+export interface CheckpointStore {
+    save(data: CheckpointData): Promise<void>;
+    load(checkpointId: string): Promise<CheckpointData | null>;
+    delete(checkpointId: string): Promise<void>;
+    list(taskId: string): Promise<CheckpointData[]>;
+    gc(): Promise<void>;
+}
+export { CheckpointDO, createInMemoryCheckpointStore, type CheckpointDOState, } from "./checkpoint-do.js";
+interface LocalDurableObjectStorage {
+    get<T>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    list<T>(options?: {
+        start?: string;
+        end?: string;
+        limit?: number;
+    }): Promise<Map<string, T>>;
+}
+export declare function getCheckpointStore(): CheckpointStore;
+/**
+ * Create a checkpoint store backed by Durable Objects.
+ * Use this for production deployments with multiple workers.
+ *
+ * @param state - DO state with storage
+ * @returns CheckpointStore implementation using DO storage
+ */
+export declare function createDOCheckpointStore(state: {
+    storage: LocalDurableObjectStorage;
+}): CheckpointStore;
+export declare function saveCheckpoint(requestId: string, taskId: string, iteration: number, url?: string, pageState?: string): Promise<string>;
+export declare function loadCheckpoint(checkpointId: string): Promise<CheckpointData | null>;
+export declare function acquireSemaphore(): Promise<void>;
+export declare function releaseSemaphore(): void;
+export declare function getActiveRequestCount(): number;
+export declare function setContainerBinding(binding: any): void;
+export declare function setContainerFetch(fetchFn: ((path: string, body?: object) => Promise<any>) | null): void;
+export declare function setContainerUrl(url: string): void;
+export declare function doThis(prompt: string, opts?: RalphOptions, requestId?: string): Effect.Effect<RalphResult, ValidationError | MaxIterationsError | TimeoutError | BrowserError | RateLimitError | InternalError, never>;
+export declare function run(prompt: string, opts?: RalphOptions, requestId?: string): Promise<RalphResult>;
+import { Hono } from "hono";
+export declare function createHandlers(): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;