digital-workers 2.1.1 → 2.3.0

package/dist/worker.d.ts

@@ -0,0 +1,343 @@
+/**
+ * Worker Export - WorkerEntrypoint for RPC access to Digital Workers
+ *
+ * Exposes worker lifecycle management, messaging, and coordination via Cloudflare RPC.
+ *
+ * @example
+ * ```typescript
+ * // wrangler.jsonc
+ * {
+ *   "services": [
+ *     { "binding": "DIGITAL_WORKERS", "service": "digital-workers" }
+ *   ]
+ * }
+ *
+ * // worker.ts - consuming service
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const service = env.DIGITAL_WORKERS.connect()
+ *     const worker = await service.spawn({ name: 'my-worker' })
+ *     return Response.json(worker)
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { WorkerEntrypoint, RpcTarget } from 'cloudflare:workers';
+/**
+ * Worker instance status
+ */
+type WorkerInstanceStatus = 'spawning' | 'running' | 'paused' | 'terminated' | 'error';
+/**
+ * Worker instance state
+ */
+interface WorkerInstance {
+    id: string;
+    name: string;
+    status: WorkerInstanceStatus;
+    type: 'agent' | 'human';
+    tier?: string | undefined;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown> | undefined;
+}
+/**
+ * Message sent between workers
+ */
+interface WorkerMessage<T = unknown> {
+    id: string;
+    from: string;
+    to: string;
+    type: string;
+    payload: T;
+    timestamp: Date;
+    acknowledged?: boolean;
+}
+/**
+ * Worker spawn options
+ */
+interface SpawnOptions {
+    name?: string;
+    type?: 'agent' | 'human';
+    tier?: string;
+    metadata?: Record<string, unknown>;
+    timeout?: number;
+}
+/**
+ * Receive options
+ */
+interface ReceiveOptions {
+    type?: string;
+    limit?: number;
+    acknowledged?: boolean;
+}
+/**
+ * List options
+ */
+interface ListOptions {
+    status?: WorkerInstanceStatus;
+    type?: 'agent' | 'human';
+    tier?: string;
+    limit?: number;
+    includeTerminated?: boolean;
+}
+/**
+ * Set state options
+ */
+interface SetStateOptions {
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Broadcast result
+ */
+interface BroadcastResult {
+    workerId: string;
+    success: boolean;
+    messageId?: string | undefined;
+    error?: string | undefined;
+}
+/**
+ * Coordination task
+ */
+interface CoordinationTask<T = unknown> {
+    id: string;
+    type: 'fanout' | 'pipeline' | 'race' | 'consensus';
+    workers: string[];
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    result?: T | undefined;
+    errors?: Error[] | undefined;
+}
+/**
+ * Consensus options
+ */
+interface ConsensusOptions {
+    quorum?: number;
+}
+/**
+ * Notification target
+ */
+type NotificationTarget = string | string[] | {
+    id: string;
+    contacts: Record<string, unknown>;
+};
+/**
+ * Notification options
+ */
+interface NotifyOptions {
+    target: NotificationTarget;
+    message: string;
+    via?: string;
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Notification result
+ */
+interface NotifyResult {
+    sent: boolean;
+    messageId: string;
+    via: string[];
+    recipients?: string[];
+    sentAt: Date;
+    jobId: string;
+}
+/**
+ * Decide options
+ */
+interface DecideOptions {
+    options: (string | {
+        id?: string;
+        label?: string;
+        [key: string]: unknown;
+    })[];
+    context?: string;
+    criteria?: string[];
+}
+/**
+ * Decision result
+ */
+interface DecisionResult {
+    choice: string | {
+        id?: string;
+        label?: string;
+        [key: string]: unknown;
+    };
+    reasoning: string;
+    confidence: number;
+    alternatives?: {
+        option: string | {
+            id?: string;
+            label?: string;
+            [key: string]: unknown;
+        };
+        score: number;
+    }[];
+    jobId: string;
+}
+/**
+ * Ask AI options
+ */
+interface AskAIOptions {
+    context?: Record<string, unknown>;
+    schema?: Record<string, unknown>;
+    track?: boolean;
+}
+/**
+ * Cloudflare Workers AI interface
+ */
+interface AIBinding {
+    run(model: string, input: {
+        prompt?: string;
+        messages?: {
+            role: string;
+            content: string;
+        }[];
+    }): Promise<{
+        response?: string;
+    }>;
+}
+/**
+ * Environment bindings
+ */
+export interface Env {
+    AI?: AIBinding | undefined;
+    WORKER_STATE?: DurableObjectNamespace | undefined;
+}
+/**
+ * Core digital workers service - extends RpcTarget for RPC communication
+ *
+ * Provides worker lifecycle management, messaging, and coordination.
+ */
+export declare class DigitalWorkersServiceCore extends RpcTarget {
+    private env;
+    constructor(env?: Env);
+    /**
+     * Spawn a new worker instance
+     */
+    spawn(options?: SpawnOptions): Promise<WorkerInstance>;
+    /**
+     * Terminate a worker
+     */
+    terminate(workerId: string): Promise<boolean>;
+    /**
+     * Pause a worker
+     */
+    pause(workerId: string): Promise<boolean>;
+    /**
+     * Resume a paused worker
+     */
+    resume(workerId: string): Promise<boolean>;
+    /**
+     * Send a message from one worker to another
+     */
+    send<T = unknown>(fromId: string, toId: string, type: string, payload: T): Promise<WorkerMessage<T>>;
+    /**
+     * Receive messages for a worker
+     */
+    receive<T = unknown>(workerId: string, options?: ReceiveOptions): Promise<WorkerMessage<T>[]>;
+    /**
+     * Acknowledge a message
+     */
+    acknowledge(workerId: string, messageId: string): Promise<boolean>;
+    /**
+     * Broadcast a message to multiple workers
+     */
+    broadcast<T = unknown>(fromId: string, toIds: string[], type: string, payload: T): Promise<BroadcastResult[]>;
+    /**
+     * Get worker state
+     */
+    getState(workerId: string): Promise<WorkerInstance | null>;
+    /**
+     * Set worker state (update metadata)
+     */
+    setState(workerId: string, options: SetStateOptions): Promise<void>;
+    /**
+     * List workers with optional filtering
+     */
+    list(options?: ListOptions): Promise<WorkerInstance[]>;
+    /**
+     * Fan out work to multiple workers (parallel execution)
+     */
+    fanOut<T = unknown>(coordinatorId: string, workerIds: string[], type: string, payload: T): Promise<CoordinationTask<T>>;
+    /**
+     * Create a sequential processing pipeline
+     */
+    pipeline<T = unknown>(workerIds: string[], type: string, payload: T): Promise<CoordinationTask<T>>;
+    /**
+     * Create a race (first to complete wins)
+     */
+    race<T = unknown>(workerIds: string[], type: string, payload: T): Promise<CoordinationTask<T>>;
+    /**
+     * Create a consensus task (all must agree)
+     */
+    consensus<T = unknown>(workerIds: string[], type: string, payload: T, options?: ConsensusOptions): Promise<CoordinationTask<T>>;
+    /**
+     * Get coordination task status
+     */
+    getTaskStatus<T = unknown>(taskId: string): Promise<CoordinationTask<T> | null>;
+    /**
+     * Generate a job ID for tracking
+     */
+    private generateJobId;
+    /**
+     * Send a notification (stateless action)
+     *
+     * Sends notifications to one or more targets. Does not require a spawned worker.
+     *
+     * @param options - Notification options
+     * @returns Notification result with sent status, message ID, and job ID
+     */
+    notify(options: NotifyOptions): Promise<NotifyResult>;
+    /**
+     * Make a decision between options using AI (stateless action)
+     *
+     * Uses the AI binding to evaluate options and make a decision.
+     * Does not require a spawned worker.
+     *
+     * @param options - Decision options including choices and context
+     * @returns Decision result with choice, reasoning, confidence, and job ID
+     */
+    decide(options: DecideOptions): Promise<DecisionResult>;
+    /**
+     * Ask AI a question (stateless action)
+     *
+     * Uses the AI binding to answer questions with optional context and schema.
+     * Does not require a spawned worker.
+     *
+     * @param question - The question to ask
+     * @param options - Optional context, schema, or tracking options
+     * @returns Answer string, structured response (if schema provided), or tracked response object
+     */
+    askAI(question: string, options?: AskAIOptions): Promise<string | Record<string, unknown> | {
+        answer: string;
+        jobId: string;
+    }>;
+}
+/**
+ * Digital Workers Service - WorkerEntrypoint for RPC access
+ *
+ * Provides `connect()` method that returns an RpcTarget service
+ * with all worker management methods.
+ *
+ * @example
+ * ```typescript
+ * // In consuming worker
+ * const workers = env.DIGITAL_WORKERS.connect()
+ * const worker = await workers.spawn({ name: 'my-agent' })
+ * await workers.send(worker.id, otherWorkerId, 'task', { data: 'hello' })
+ * ```
+ */
+export declare class DigitalWorkersService extends WorkerEntrypoint<Env> {
+    /**
+     * Connect to the digital workers service
+     *
+     * @returns DigitalWorkersServiceCore instance for RPC calls
+     */
+    connect(): DigitalWorkersServiceCore;
+}
+/**
+ * Default export for Cloudflare Workers
+ */
+export default DigitalWorkersService;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

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