@swirls/looms 0.2.0 → 0.4.0

package/dist/client/client.d.ts

@@ -37,6 +37,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -160,6 +164,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -281,6 +289,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -402,6 +414,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -553,6 +569,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -674,6 +694,266 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
+            readonly threads: {
+                readonly [x: string]: {
+                    readonly threadId: string;
+                    readonly kind: string;
+                    readonly definitionName: string;
+                    readonly definitionVersion: string;
+                    readonly parentThreadId: string | null;
+                    readonly status: "cancelled" | "completed" | "failed" | "running" | "waiting";
+                    readonly input: Schema.Json;
+                    readonly output: Schema.Json;
+                    readonly error: string | null;
+                    readonly state: Schema.Json;
+                };
+            };
+            readonly waits: {
+                readonly [x: string]: {
+                    readonly waitId: string;
+                    readonly threadId: string;
+                    readonly on: {
+                        readonly type: string | readonly string[];
+                        readonly match?: Schema.Json | undefined;
+                    } | {
+                        readonly timerAt: number;
+                    };
+                    readonly tag?: Schema.Json | undefined;
+                };
+            };
+            readonly outstandingEffects: readonly {
+                readonly effectId: string;
+                readonly threadId: string;
+                readonly causingSeq: number;
+                readonly causingEventId: string;
+                readonly effect: {
+                    readonly type: "runtime.spawn";
+                    readonly childThreadId: string;
+                    readonly kind: string;
+                    readonly definitionName: string;
+                    readonly definitionVersion: string;
+                    readonly input: Schema.Json;
+                } | {
+                    readonly type: "runtime.wait";
+                    readonly waitId: string;
+                    readonly on: {
+                        readonly type: string | readonly string[];
+                        readonly match?: Schema.Json | undefined;
+                    } | {
+                        readonly timerAt: number;
+                    };
+                    readonly tag?: Schema.Json | undefined;
+                } | {
+                    readonly type: "runtime.emit";
+                    readonly event: {
+                        readonly type: string;
+                        readonly payload: Schema.Json;
+                        readonly threadId?: string | null | undefined;
+                        readonly parentThreadId?: string | null | undefined;
+                        readonly causationId?: string | null | undefined;
+                        readonly correlationId?: string | null | undefined;
+                        readonly effectId?: string | null | undefined;
+                        readonly origin?: {
+                            readonly type: "thread";
+                            readonly threadId: string;
+                        } | {
+                            readonly type: "external";
+                            readonly actorId?: string | undefined;
+                        } | {
+                            readonly type: "system";
+                        } | undefined;
+                        readonly ephemeral?: boolean | undefined;
+                        readonly id?: string | undefined;
+                        readonly ts?: number | undefined;
+                        readonly idempotencyKey?: string | null | undefined;
+                    };
+                    readonly tag?: string | undefined;
+                } | {
+                    readonly type: "runtime.complete";
+                    readonly output: Schema.Json;
+                } | {
+                    readonly type: "runtime.fail";
+                    readonly error: string;
+                } | {
+                    readonly type: "runtime.cancel";
+                    readonly threadId: string;
+                    readonly tag?: string | undefined;
+                } | {
+                    readonly type: string;
+                    readonly input: Schema.Json;
+                    readonly tag?: string | undefined;
+                };
+            }[];
+            readonly effectExecutions: {
+                readonly [x: string]: {
+                    readonly effectId: string;
+                    readonly attempt: number;
+                    readonly status: "ambiguous" | "cancel_requested" | "dispatched" | "heartbeat" | "queued" | "retry_wait" | "running" | "started" | "timed_out";
+                    readonly nextAttemptAt: number | null;
+                    readonly deadlineAt: number | null;
+                    readonly startedAt: number | null;
+                    readonly lastHeartbeatAt: number | null;
+                    readonly lastError: string | null;
+                };
+            };
+            readonly completedEffectIds: readonly string[];
+            readonly processedIdempotencyKeys: readonly string[];
+        };
+        readonly appended: number;
+    }>;
+    /** Cancel a thread and its descendants; omit `threadId` to cancel the whole run. */
+    cancel: (runId: string, threadId?: string) => Promise<{
+        readonly runId: string;
+        readonly state: {
+            readonly runId: string;
+            readonly status: "cancelled" | "completed" | "failed" | "running";
+            readonly rootThreadId: string | null;
+            readonly startIdentity: {
+                readonly kind: string;
+                readonly definitionName: string;
+                readonly definitionVersion: string;
+                readonly input: Schema.Json;
+                readonly requestedThreadId: string | null;
+                readonly idempotencyKey: string | null;
+                readonly rootThreadId: string;
+            } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
+            readonly threads: {
+                readonly [x: string]: {
+                    readonly threadId: string;
+                    readonly kind: string;
+                    readonly definitionName: string;
+                    readonly definitionVersion: string;
+                    readonly parentThreadId: string | null;
+                    readonly status: "cancelled" | "completed" | "failed" | "running" | "waiting";
+                    readonly input: Schema.Json;
+                    readonly output: Schema.Json;
+                    readonly error: string | null;
+                    readonly state: Schema.Json;
+                };
+            };
+            readonly waits: {
+                readonly [x: string]: {
+                    readonly waitId: string;
+                    readonly threadId: string;
+                    readonly on: {
+                        readonly type: string | readonly string[];
+                        readonly match?: Schema.Json | undefined;
+                    } | {
+                        readonly timerAt: number;
+                    };
+                    readonly tag?: Schema.Json | undefined;
+                };
+            };
+            readonly outstandingEffects: readonly {
+                readonly effectId: string;
+                readonly threadId: string;
+                readonly causingSeq: number;
+                readonly causingEventId: string;
+                readonly effect: {
+                    readonly type: "runtime.spawn";
+                    readonly childThreadId: string;
+                    readonly kind: string;
+                    readonly definitionName: string;
+                    readonly definitionVersion: string;
+                    readonly input: Schema.Json;
+                } | {
+                    readonly type: "runtime.wait";
+                    readonly waitId: string;
+                    readonly on: {
+                        readonly type: string | readonly string[];
+                        readonly match?: Schema.Json | undefined;
+                    } | {
+                        readonly timerAt: number;
+                    };
+                    readonly tag?: Schema.Json | undefined;
+                } | {
+                    readonly type: "runtime.emit";
+                    readonly event: {
+                        readonly type: string;
+                        readonly payload: Schema.Json;
+                        readonly threadId?: string | null | undefined;
+                        readonly parentThreadId?: string | null | undefined;
+                        readonly causationId?: string | null | undefined;
+                        readonly correlationId?: string | null | undefined;
+                        readonly effectId?: string | null | undefined;
+                        readonly origin?: {
+                            readonly type: "thread";
+                            readonly threadId: string;
+                        } | {
+                            readonly type: "external";
+                            readonly actorId?: string | undefined;
+                        } | {
+                            readonly type: "system";
+                        } | undefined;
+                        readonly ephemeral?: boolean | undefined;
+                        readonly id?: string | undefined;
+                        readonly ts?: number | undefined;
+                        readonly idempotencyKey?: string | null | undefined;
+                    };
+                    readonly tag?: string | undefined;
+                } | {
+                    readonly type: "runtime.complete";
+                    readonly output: Schema.Json;
+                } | {
+                    readonly type: "runtime.fail";
+                    readonly error: string;
+                } | {
+                    readonly type: "runtime.cancel";
+                    readonly threadId: string;
+                    readonly tag?: string | undefined;
+                } | {
+                    readonly type: string;
+                    readonly input: Schema.Json;
+                    readonly tag?: string | undefined;
+                };
+            }[];
+            readonly effectExecutions: {
+                readonly [x: string]: {
+                    readonly effectId: string;
+                    readonly attempt: number;
+                    readonly status: "ambiguous" | "cancel_requested" | "dispatched" | "heartbeat" | "queued" | "retry_wait" | "running" | "started" | "timed_out";
+                    readonly nextAttemptAt: number | null;
+                    readonly deadlineAt: number | null;
+                    readonly startedAt: number | null;
+                    readonly lastHeartbeatAt: number | null;
+                    readonly lastError: string | null;
+                };
+            };
+            readonly completedEffectIds: readonly string[];
+            readonly processedIdempotencyKeys: readonly string[];
+        };
+    }>;
+    /** Start a new run that continues where a finished run ended. */
+    fork: (sourceRunId: string, forkOptions?: {
+        runId?: string;
+    }) => Promise<{
+        readonly runId: string;
+        readonly threadId: string;
+        readonly state: {
+            readonly runId: string;
+            readonly status: "cancelled" | "completed" | "failed" | "running";
+            readonly rootThreadId: string | null;
+            readonly startIdentity: {
+                readonly kind: string;
+                readonly definitionName: string;
+                readonly definitionVersion: string;
+                readonly input: Schema.Json;
+                readonly requestedThreadId: string | null;
+                readonly idempotencyKey: string | null;
+                readonly rootThreadId: string;
+            } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -795,6 +1075,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -960,6 +1244,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                     readonly idempotencyKey: string | null;
                     readonly rootThreadId: string;
                 } | null;
+                readonly forkedFrom: {
+                    readonly runId: string;
+                    readonly seq: number;
+                } | null;
                 readonly threads: {
                     readonly [x: string]: {
                         readonly threadId: string;
@@ -1078,6 +1366,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                     readonly idempotencyKey: string | null;
                     readonly rootThreadId: string;
                 } | null;
+                readonly forkedFrom: {
+                    readonly runId: string;
+                    readonly seq: number;
+                } | null;
                 readonly threads: {
                     readonly [x: string]: {
                         readonly threadId: string;

package/dist/client/client.js

@@ -14,6 +14,12 @@ const StartResultSchema = Schema.Struct({
     state: RunStateSchema,
 });
 const RunResultSchema = Schema.Struct({ runId: Schema.String, state: RunStateSchema });
+/** `appended` counts the events the run gained while the wake ran. */
+const WakeResultSchema = Schema.Struct({
+    runId: Schema.String,
+    state: RunStateSchema,
+    appended: Schema.Finite,
+});
 const EventsResultSchema = Schema.Struct({
     runId: Schema.String,
     events: Schema.Array(EventEnvelopeSchema),
@@ -157,7 +163,17 @@ export function createLoomsClient(options = {}) {
             method: 'POST',
             body: stringifyJson({ events }),
         }),
-        wake: (runId) => request(`/runs/${encodeURIComponent(runId)}/wake`, RunResultSchema, { method: 'POST' }),
+        wake: (runId) => request(`/runs/${encodeURIComponent(runId)}/wake`, WakeResultSchema, { method: 'POST' }),
+        /** Cancel a thread and its descendants; omit `threadId` to cancel the whole run. */
+        cancel: (runId, threadId) => request(`/runs/${encodeURIComponent(runId)}/cancel`, RunResultSchema, {
+            method: 'POST',
+            body: stringifyJson(threadId === undefined ? {} : { threadId }),
+        }),
+        /** Start a new run that continues where a finished run ended. */
+        fork: (sourceRunId, forkOptions) => request(`/runs/${encodeURIComponent(sourceRunId)}/fork`, StartResultSchema, {
+            method: 'POST',
+            body: stringifyJson(forkOptions?.runId === undefined ? {} : { runId: forkOptions.runId }),
+        }),
         workerCallback,
         listRunSummaries: () => request('/runs/summaries', RunSummariesSchema),
         listDefinitions: () => request('/definitions', DefinitionCatalogSchema),

package/dist/cloudflare/router.d.ts

@@ -6,7 +6,7 @@ export interface DurableObjectNamespaceLike<T extends DurableObjectStubLike = Du
 }
 /**
  * Routes incoming HTTP requests to the appropriate Durable Object actor cell.
- * Handles `/health` locally, returns 501 for global run lists, and forwards
+ * Handles `/health` locally, returns 501 for global run lists and forks, and forwards
  * all other run and event-stream requests to `namespace.getByName(runId)`.
  */
 export declare function routeToDurableObject(namespace: DurableObjectNamespaceLike, req: Request): Promise<Response | null>;

package/dist/cloudflare/router.js

@@ -1,18 +1,16 @@
-import { resolveRunTarget, RunTargetError } from '@swirls/looms/actor';
+import { crossRunResponse, resolveRunTarget, RunTargetError } from '@swirls/looms/actor';
 /**
  * Routes incoming HTTP requests to the appropriate Durable Object actor cell.
- * Handles `/health` locally, returns 501 for global run lists, and forwards
+ * Handles `/health` locally, returns 501 for global run lists and forks, and forwards
  * all other run and event-stream requests to `namespace.getByName(runId)`.
  */
 export function routeToDurableObject(namespace, req) {
-    const url = new URL(req.url);
-    if (url.pathname === '/health') {
+    if (new URL(req.url).pathname === '/health') {
         return Promise.resolve(Response.json({ ok: true }));
     }
-    if (req.method === 'GET' && (url.pathname === '/runs' || url.pathname === '/runs/summaries')) {
-        return Promise.resolve(Response.json({
-            error: 'Global run listing is not supported in the Durable Object backend without a global index',
-        }, { status: 501 }));
+    const unsupported = crossRunResponse(req, 'the Durable Object backend');
+    if (unsupported) {
+        return Promise.resolve(unsupported);
     }
     return resolveRunTarget(req)
         .then(({ runId, request }) => namespace.getByName(runId).fetch(request))

package/dist/core/attempts.d.ts

@@ -0,0 +1,8 @@
+import type { AnyEventEnvelope } from './register';
+/** The effect a `runtime.effect.retry.scheduled` event retries, or `undefined` for other events. */
+export declare function retriedEffectId(event: AnyEventEnvelope): string | undefined;
+/**
+ * Drops ephemeral events from effect attempts that a later retry in `events` superseded. Durable
+ * events and ephemeral events from the current attempt are kept.
+ */
+export declare function dropSupersededAttempts<E extends AnyEventEnvelope>(events: readonly E[]): readonly E[];

package/dist/core/attempts.js

@@ -0,0 +1,27 @@
+import { Schema } from 'effect';
+import { protocolCatalog } from './protocol.js';
+const RETRY_SCHEDULED = 'runtime.effect.retry.scheduled';
+const isRetryPayload = Schema.is(protocolCatalog.entries['effect.retry.scheduled']);
+/** The effect a `runtime.effect.retry.scheduled` event retries, or `undefined` for other events. */
+export function retriedEffectId(event) {
+    return event.type === RETRY_SCHEDULED && isRetryPayload(event.payload)
+        ? event.payload.effectId
+        : undefined;
+}
+/**
+ * Drops ephemeral events from effect attempts that a later retry in `events` superseded. Durable
+ * events and ephemeral events from the current attempt are kept.
+ */
+export function dropSupersededAttempts(events) {
+    const lastRetry = new Map();
+    events.forEach((event, index) => {
+        const effectId = retriedEffectId(event);
+        if (effectId !== undefined) {
+            lastRetry.set(effectId, index);
+        }
+    });
+    if (lastRetry.size === 0) {
+        return events;
+    }
+    return events.filter((event, index) => !event.ephemeral || !event.effectId || (lastRetry.get(event.effectId) ?? -1) < index);
+}

package/dist/core/effects.d.ts

@@ -166,6 +166,11 @@ export interface EffectDefinition<TInput = JsonValue, R = Context.Service.Any, E
     readonly execution?: EffectExecution;
     /** Whether `execute` runs a user handler. Without one, the effect can only complete through a worker. */
     readonly hasHandler: boolean;
+    /**
+     * The outcome follows from the input alone, like scheduling from state already folded. Forking
+     * a failed run retries the effect that produced the failure, not a deterministic one passing it on.
+     */
+    readonly deterministic?: boolean;
     readonly [effectInputType]?: (input: TInput) => TInput;
     execute(input: JsonValue, ctx: EffectContext): Effect.Effect<ReadonlyArray<E>, InvalidInputError | EffectHandlerError, R>;
 }
@@ -182,6 +187,7 @@ export declare function defineEffect<TSchema extends SchemaInput, R = never, E e
     input: TSchema;
     retry?: RetryPolicy;
     execution?: EffectExecution;
+    deterministic?: boolean;
     execute?: (input: InferDefinedSchema<TSchema>, ctx: EffectContext) => EffectHandlerResult<R, E, HandlerError>;
 }): EffectDefinition<InferDefinedSchema<TSchema>, R, E>;
 export declare function defineEffect<R = never, E extends EventInput = EventInput, HandlerError = never>(def: {
@@ -189,6 +195,7 @@ export declare function defineEffect<R = never, E extends EventInput = EventInpu
     input?: undefined;
     retry?: RetryPolicy;
     execution?: EffectExecution;
+    deterministic?: boolean;
     execute?: (input: JsonValue, ctx: EffectContext) => EffectHandlerResult<R, E, HandlerError>;
 }): EffectDefinition<JsonValue, R, E>;
 export declare function spawn(args: {

package/dist/core/effects.js

@@ -106,6 +106,7 @@ export function defineEffect(def) {
         retry: def.retry,
         execution: def.execution,
         hasHandler: handler !== undefined,
+        deterministic: def.deterministic,
         execute: (raw, ctx) => Effect.gen(function* () {
             const input = schema ? yield* validateInputEffect(schema, raw) : raw;
             return handler ? yield* liftHandlerResult(handler(input, ctx)) : noOutput;

package/dist/core/fold.js

@@ -2,7 +2,7 @@ import { Option, Predicate, Schema, Stream } from 'effect';
 import { isWithdrawnError, WaitConditionSchema } from './effects.js';
 import { createEffectId } from './ids.js';
 import { DEFAULT_DEFINITION_VERSION } from './module.js';
-import { emptyRunState } from './state.js';
+import { completedRunStatus, emptyRunState } from './state.js';
 import { isTerminalStatus } from './thread.js';
 const decodeWaitCondition = Schema.decodeUnknownOption(WaitConditionSchema);
 function payloadObject(event) {
@@ -25,6 +25,7 @@ function cloneState(state) {
         status: state.status,
         rootThreadId: state.rootThreadId,
         startIdentity: state.startIdentity,
+        forkedFrom: state.forkedFrom,
         threads: { ...state.threads },
         waits: { ...state.waits },
         outstandingEffects: [...state.outstandingEffects],
@@ -104,13 +105,18 @@ function applyProtocol(state, event, registry) {
                 status: 'running',
             };
         }
-        case 'runtime.run.completed': {
-            const error = payload.error;
-            const status = Predicate.isString(error) && error.length > 0 ? 'failed' : 'completed';
-            return { ...state, status };
-        }
+        case 'runtime.run.completed':
+            return { ...state, status: completedRunStatus(payload) };
         case 'runtime.run.cancelled':
             return { ...state, status: 'cancelled' };
+        case 'runtime.run.forked': {
+            const sourceRunId = readString(payload, 'sourceRunId');
+            const sourceSeq = payload.sourceSeq;
+            // Attempts recorded in the copied history belong to the source run's processes.
+            return sourceRunId && Predicate.isNumber(sourceSeq)
+                ? { ...state, forkedFrom: { runId: sourceRunId, seq: sourceSeq }, effectExecutions: {} }
+                : state;
+        }
         case 'runtime.thread.started': {
             const threadId = readString(payload, 'threadId') ?? event.threadId;
             const kind = readString(payload, 'kind');

package/dist/core/fork.d.ts

@@ -0,0 +1,35 @@
+import { Effect } from 'effect';
+import { type EffectDefinition } from './effects';
+import { type EventEnvelope } from './envelope';
+import { type FoldRegistry } from './fold';
+declare const ForkSourceError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ForkSourceError";
+} & Readonly<A>;
+export declare class ForkSourceError extends ForkSourceError_base<{
+    readonly runId: string;
+    readonly message: string;
+}> {
+    constructor(runId: string, message: string);
+}
+export interface ForkRegistry extends FoldRegistry {
+    readonly effects: ReadonlyMap<string, Pick<EffectDefinition, 'deterministic'>>;
+}
+export interface ForkPlan {
+    /** The fork's history: the copied prefix, keeping source seqs, then the `runtime.run.forked` marker. */
+    readonly events: readonly EventEnvelope[];
+    /** Last source seq the fork copied. */
+    readonly sourceSeq: number;
+    readonly rootThreadId: string;
+}
+/**
+ * Plan a new run that continues where the source run ended. The fork copies the source's
+ * history up to the point the run finished, keeping sequence numbers so effect ids still
+ * line up, and its next wake re-issues whatever effects were outstanding there.
+ */
+export declare function planFork(input: {
+    readonly sourceRunId: string;
+    readonly runId: string;
+    readonly events: readonly EventEnvelope[];
+    readonly registry: ForkRegistry;
+}): Effect.Effect<ForkPlan, ForkSourceError>;
+export {};