@swirls/looms 0.1.0 → 0.3.0

package/dist/approval/module.d.ts

@@ -138,6 +138,11 @@ export declare function approval(): import("@swirls/looms/core").RuntimeModule<"
             readonly attempt: number;
             readonly deadlineAt: number | null;
         };
+    }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+        readonly type: "runtime.fork.elided";
+        readonly payload: {
+            readonly type: string;
+        };
     }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
         readonly type: "runtime.run.cancelled";
         readonly payload: {
@@ -149,6 +154,12 @@ export declare function approval(): import("@swirls/looms/core").RuntimeModule<"
             readonly output: import("effect/Schema").Json;
             readonly error: string | null;
         };
+    }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+        readonly type: "runtime.run.forked";
+        readonly payload: {
+            readonly sourceRunId: string;
+            readonly sourceSeq: number;
+        };
     }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
         readonly type: "runtime.run.started";
         readonly payload: {
@@ -181,6 +192,7 @@ export declare function approval(): import("@swirls/looms/core").RuntimeModule<"
         readonly payload: {
             readonly threadId: string;
             readonly reason?: string | undefined;
+            readonly resumeSeq?: number | undefined;
         };
     }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
         readonly type: "runtime.thread.completed";
@@ -372,6 +384,11 @@ export declare function approval(): import("@swirls/looms/core").RuntimeModule<"
                 readonly attempt: number;
                 readonly deadlineAt: number | null;
             };
+        }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+            readonly type: "runtime.fork.elided";
+            readonly payload: {
+                readonly type: string;
+            };
         }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
             readonly type: "runtime.run.cancelled";
             readonly payload: {
@@ -383,6 +400,12 @@ export declare function approval(): import("@swirls/looms/core").RuntimeModule<"
                 readonly output: import("effect/Schema").Json;
                 readonly error: string | null;
             };
+        }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+            readonly type: "runtime.run.forked";
+            readonly payload: {
+                readonly sourceRunId: string;
+                readonly sourceSeq: number;
+            };
         }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
             readonly type: "runtime.run.started";
             readonly payload: {
@@ -415,6 +438,7 @@ export declare function approval(): import("@swirls/looms/core").RuntimeModule<"
             readonly payload: {
                 readonly threadId: string;
                 readonly reason?: string | undefined;
+                readonly resumeSeq?: number | undefined;
             };
         }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
             readonly type: "runtime.thread.completed";

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;
@@ -901,6 +1185,24 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
             readonly processedIdempotencyKeys: readonly string[];
         };
     }>;
+    listRunSummaries: () => Promise<{
+        readonly runs: readonly {
+            readonly runId: string;
+            readonly status: "cancelled" | "completed" | "failed" | "running";
+            readonly kind: string | null;
+            readonly definitionName: string | null;
+        }[];
+    }>;
+    listDefinitions: () => Promise<{
+        readonly definitions: readonly {
+            readonly kind: string;
+            readonly name: string;
+            readonly version: string;
+            readonly description?: string | undefined;
+            readonly inputSchema?: Schema.Json | undefined;
+        }[];
+        readonly projections: readonly string[];
+    }>;
     replayTo: (runId: string, seq: number) => Promise<{
         readonly runId: string;
         readonly step: {
@@ -942,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;
@@ -1060,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

@@ -1,5 +1,5 @@
 import { Data, Effect, Option, Schema, Stream } from 'effect';
-import { createRunId, EventEnvelopeSchema, ReplayStepSchema, RunStateSchema, stringifyJson, } from '@swirls/looms/core';
+import { createRunId, DefinitionCatalogSchema, EventEnvelopeSchema, ReplayStepSchema, RunStateSchema, RunSummariesSchema, stringifyJson, } from '@swirls/looms/core';
 import { consumeSseStreamEffect, eventsFromSseData, sseFrames } from './sse.js';
 class LoomsClientError extends Data.TaggedError('LoomsClientError') {
     constructor(message, cause) {
@@ -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,8 +163,20 @@ 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),
         replayTo: (runId, seq) => request(`/runs/${encodeURIComponent(runId)}/replay?seq=${seq}`, ReplayResultSchema),
         project: (runId, name) => request(`/runs/${encodeURIComponent(runId)}/projections/${encodeURIComponent(name)}`, ProjectionResultSchema),
         subscribeEvents,

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 `GET /runs`, 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 `GET /runs`, 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') {
-        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/compose.js

@@ -57,6 +57,7 @@ export function composeModules(modules) {
                 name: definition.name,
                 version,
                 input: definition.input,
+                description: definition.description,
                 value: definition,
             });
         }

package/dist/core/debugger-host.d.ts

@@ -0,0 +1,16 @@
+/** A request the runtime has matched and authorized under the debugger mount. */
+export interface DebuggerRequest {
+    /** Mount path without a trailing slash, such as `/debugger`. */
+    readonly basePath: string;
+    /** Path below the mount: empty for the mount itself, otherwise it starts with `/`. */
+    readonly path: string;
+}
+/**
+ * Serves a debugger UI under `basePath`. The runtime matches, authorizes, and strips the mount
+ * path; the host only serves files.
+ */
+export interface DebuggerHost {
+    /** Absolute mount path, such as `/debugger`. Must not overlap the HTTP API. */
+    readonly basePath: string;
+    fetch(req: Request, mount: DebuggerRequest): Promise<Response | null>;
+}

package/dist/core/debugger-host.js

@@ -0,0 +1 @@
+export {};

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 {};