@swirls/looms 0.4.0 → 0.5.0

package/dist/runtime/child-run.js

@@ -0,0 +1,58 @@
+import { Effect } from 'effect';
+import { descendantThreadIds, isTerminalStatus, } from '@swirls/looms/core';
+/** Tell the launching run that this child has reached a terminal status. */
+export function notifyLaunchingParent(launcher, runId, state) {
+    const launchedBy = state.startIdentity?.launchedBy;
+    const status = state.status;
+    if (!launchedBy || status === 'running') {
+        return Effect.void;
+    }
+    const root = state.rootThreadId ? state.threads[state.rootThreadId] : undefined;
+    const error = status === 'completed' ? null : (root?.error ?? status);
+    return launcher.signal(launchedBy.runId, [
+        {
+            type: 'runtime.child.settled',
+            payload: {
+                runId,
+                status,
+                output: root?.output ?? null,
+                error,
+            },
+            threadId: launchedBy.threadId,
+            idempotencyKey: `child-settled:${runId}`,
+            origin: { type: 'run', runId },
+        },
+    ], { idempotencyKey: `child-settled:${runId}` });
+}
+/**
+ * When a run asked to wait for child cancellation and those children are gone, cancel the
+ * run's own threads. The caller appends these events from the parent wake, which must not
+ * call `runtime.cancel` on itself.
+ */
+export function childCloseCancellations(state) {
+    if (!state.closeWaiting || state.launchedRuns.some((run) => run.close === 'wait')) {
+        return [];
+    }
+    const rootId = state.rootThreadId;
+    if (!rootId) {
+        return [];
+    }
+    const root = state.threads[rootId];
+    if (!root || isTerminalStatus(root.status)) {
+        return [];
+    }
+    const ids = [...descendantThreadIds(state, rootId).toReversed(), rootId];
+    return ids.flatMap((threadId) => {
+        const record = state.threads[threadId];
+        if (!record || isTerminalStatus(record.status)) {
+            return [];
+        }
+        return [
+            {
+                type: 'runtime.thread.cancelled',
+                payload: { threadId, reason: 'cancelled' },
+                threadId,
+            },
+        ];
+    });
+}

package/dist/runtime/deadline-transition-planner.js

@@ -1,4 +1,4 @@
-import { createEvent, foldRun, isRunTerminal, isWaitOnTimer, } from '@swirls/looms/core';
+import { createEvent, deferredUntil, foldRun, isRunTerminal, isWaitOnTimer, } from '@swirls/looms/core';
 import { waitSatisfiedEvents } from './helpers.js';
 import { planAttemptFailure } from './retry-policy.js';
 const EMPTY_PLAN = {
@@ -122,7 +122,16 @@ export function nextRuntimeDeadline(state, after = Number.NEGATIVE_INFINITY) {
         execution.deadlineAt > after
         ? [execution.deadlineAt]
         : []);
-    const deadlines = [...timers, ...executions];
+    const deferred = terminal
+        ? []
+        : state.outstandingEffects.flatMap((item) => {
+            if (state.effectExecutions[item.effectId]) {
+                return [];
+            }
+            const at = deferredUntil(item.effect);
+            return at !== undefined && at > after ? [at] : [];
+        });
+    const deadlines = [...timers, ...executions, ...deferred];
     return deadlines.length > 0 ? Math.min(...deadlines) : undefined;
 }
 function cancellationAmbiguous(runId, effectId, attempt) {

package/dist/runtime/dispatch-effect.d.ts

@@ -1,4 +1,4 @@
 import type { Context, ManagedRuntime } from 'effect';
 import { Effect } from 'effect';
-import { type ComposedRegistry, type EffectContext, type EventInput, type RegisteredDefinition, type RuntimeEffect } from '@swirls/looms/core';
-export declare function dispatchEffect(registry: ComposedRegistry, services: ManagedRuntime.ManagedRuntime<Context.Service.Any, never>, definitions: ReadonlyMap<string, RegisteredDefinition>, effect: RuntimeEffect, ctx: EffectContext): Effect.Effect<ReadonlyArray<EventInput>, Error>;
+import { type ComposedRegistry, type EffectContext, type EventInput, type DefinitionResolver, type RunLauncher, type RuntimeEffect } from '@swirls/looms/core';
+export declare function dispatchEffect(registry: ComposedRegistry, services: ManagedRuntime.ManagedRuntime<Context.Service.Any, never>, definitions: DefinitionResolver, launcher: RunLauncher, effect: RuntimeEffect, ctx: EffectContext): Effect.Effect<ReadonlyArray<EventInput>, Error>;

package/dist/runtime/dispatch-effect.js

@@ -1,7 +1,28 @@
-import { Effect } from 'effect';
-import { asJson, isPrimitiveEffect, isWaitOnTimer, } from '@swirls/looms/core';
+import { Effect, Predicate } from 'effect';
+import { asJson, isPrimitiveEffect, isWaitOnTimer, readEffectFailure, RunLauncherTag, } from '@swirls/looms/core';
 import { threadStartedEvents } from './helpers.js';
-export function dispatchEffect(registry, services, definitions, effect, ctx) {
+function causeMessage(cause) {
+    if (Predicate.isString(cause)) {
+        return cause;
+    }
+    if (cause instanceof Error) {
+        return cause.message;
+    }
+    return String(cause);
+}
+function failedAttempt(effectId, threadId, cause) {
+    const failure = readEffectFailure(cause);
+    const error = failure?.error ?? causeMessage(cause);
+    const payload = { effectId, error };
+    if (failure?.nonRetryable) {
+        payload.nonRetryable = true;
+    }
+    if (failure?.retryAfterMs !== undefined) {
+        payload.retryAfterMs = failure.retryAfterMs;
+    }
+    return { type: 'runtime.effect.failed', payload, threadId };
+}
+export function dispatchEffect(registry, services, definitions, launcher, effect, ctx) {
     const currentThreadId = ctx.threadId;
     const baseDispatch = (eff, effCtx) => {
         if (isPrimitiveEffect(eff)) {
@@ -67,6 +88,20 @@ export function dispatchEffect(registry, services, definitions, effect, ctx) {
                         },
                     ]);
                 }
+                case 'runtime.launch':
+                    return launcher
+                        .launch({
+                        runId: eff.runId,
+                        kind: eff.kind,
+                        definitionName: eff.definitionName,
+                        definitionVersion: eff.definitionVersion,
+                        input: eff.input,
+                        idempotencyKey: eff.runId,
+                        close: eff.close,
+                    })
+                        .pipe(Effect.map(() => []));
+                case 'runtime.cancelRun':
+                    return launcher.cancel(eff.runId).pipe(Effect.map(() => []));
                 default: {
                     const exhaustiveCheck = eff;
                     return exhaustiveCheck;
@@ -76,28 +111,17 @@ export function dispatchEffect(registry, services, definitions, effect, ctx) {
         const handler = registry.effects.get(eff.type);
         if (!handler) {
             return Effect.succeed([
-                {
-                    type: 'runtime.effect.failed',
-                    payload: { effectId: effCtx.effectId, error: `No handler for ${eff.type}` },
-                    threadId: currentThreadId,
-                },
+                failedAttempt(effCtx.effectId, currentThreadId, `No handler for ${eff.type}`),
             ]);
         }
         const input = 'input' in eff ? eff.input : {};
         const execution = Effect.gen(function* () {
             const serviceContext = yield* services.contextEffect;
-            return yield* handler.execute(input, effCtx).pipe(Effect.provide(serviceContext));
+            return yield* handler
+                .execute(input, effCtx)
+                .pipe(Effect.provideService(RunLauncherTag, launcher), Effect.provide(serviceContext));
         });
-        return execution.pipe(Effect.catch((err) => Effect.succeed([
-            {
-                type: 'runtime.effect.failed',
-                payload: {
-                    effectId: effCtx.effectId,
-                    error: err instanceof Error ? err.message : String(err),
-                },
-                threadId: currentThreadId,
-            },
-        ])));
+        return execution.pipe(Effect.catch((err) => Effect.succeed([failedAttempt(effCtx.effectId, currentThreadId, err)])));
     };
     if (registry.middleware && registry.middleware.length > 0) {
         const pipeline = registry.middleware.reduceRight((next, mw) => (e, c) => mw(e, c, next), baseDispatch);

package/dist/runtime/errors.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue, RunStartIdentity as DurableRunStartIdentity } from '@swirls/looms/core';
+import type { JsonValue, RunAttributes, RunLaunchSource, RunStartIdentity as DurableRunStartIdentity } from '@swirls/looms/core';
 export interface RunStartIdentity {
     readonly kind: string;
     readonly definitionName: string;
@@ -6,6 +6,19 @@ export interface RunStartIdentity {
     readonly input: JsonValue;
     readonly requestedThreadId: string | null;
     readonly idempotencyKey: string | null;
+    readonly launchedBy: RunLaunchSource | null;
+    readonly correlationId: string | null;
+    readonly attributes: RunAttributes;
+}
+declare const SecretContextConflictError_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: "SecretContextConflictError";
+} & Readonly<A>;
+/** The stored secret context differs. The message never includes the secret values. */
+export declare class SecretContextConflictError extends SecretContextConflictError_base<{
+    readonly runId: string;
+    readonly message: string;
+}> {
+    constructor(runId: string);
 }
 declare const StartRunConflictError_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: "StartRunConflictError";

package/dist/runtime/errors.js

@@ -1,4 +1,14 @@
 import { Data } from 'effect';
+/** The stored secret context differs. The message never includes the secret values. */
+export class SecretContextConflictError extends Data.TaggedError('SecretContextConflictError') {
+    constructor(runId) {
+        super({
+            runId,
+            message: `Run "${runId}" already has a different secret context`,
+        });
+        this.name = 'SecretContextConflictError';
+    }
+}
 export class StartRunConflictError extends Data.TaggedError('StartRunConflictError') {
     constructor(runId, requested, existing, mismatches) {
         super({

package/dist/runtime/filesystem-blob-store.d.ts

@@ -0,0 +1,6 @@
+import { type BlobStore } from '@swirls/looms/core';
+/**
+ * Content-addressed blob store rooted at `directory`. For Bun and Node hosts.
+ * A Durable Object should use `r2BlobStore` instead.
+ */
+export declare function filesystemBlobStore(directory: string): BlobStore;

package/dist/runtime/filesystem-blob-store.js

@@ -0,0 +1,59 @@
+import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { Data, Effect, Predicate } from 'effect';
+import { blobStoreFromBytes, BlobStoreError } from '@swirls/looms/core';
+class MissingBlobFile extends Data.TaggedError('MissingBlobFile') {
+}
+/**
+ * Content-addressed blob store rooted at `directory`. For Bun and Node hosts.
+ * A Durable Object should use `r2BlobStore` instead.
+ */
+export function filesystemBlobStore(directory) {
+    return blobStoreFromBytes(filesystemBlobBytes(directory));
+}
+function filesystemBlobBytes(directory) {
+    return {
+        read: (key) => readOptional(`${directory}/${key}`, key),
+        write: (key, body) => Effect.tryPromise({
+            try: () => mkdir(`${directory}/${folderOf(key)}`, { recursive: true }),
+            catch: (cause) => new BlobStoreError(`Unable to create a directory for blob key ${key}`, cause),
+        }).pipe(Effect.andThen(Effect.tryPromise({
+            try: () => writeFile(`${directory}/${key}`, body),
+            catch: (cause) => new BlobStoreError(`Unable to write blob key ${key}`, cause),
+        }))),
+        remove: (key) => Effect.tryPromise({
+            try: () => rm(`${directory}/${key}`, { force: true }),
+            catch: (cause) => new BlobStoreError(`Unable to delete blob key ${key}`, cause),
+        }),
+        exists: (key) => Effect.tryPromise({
+            try: () => stat(`${directory}/${key}`),
+            catch: (cause) => isMissingFile(cause)
+                ? new MissingBlobFile()
+                : new BlobStoreError(`Unable to check blob key ${key}`, cause),
+        }).pipe(Effect.as(true), Effect.catchTag('MissingBlobFile', () => Effect.succeed(false))),
+        list: (prefix) => listFolder(directory, prefix),
+    };
+}
+function readOptional(path, key) {
+    return Effect.tryPromise({
+        try: () => readFile(path),
+        catch: (cause) => isMissingFile(cause)
+            ? new MissingBlobFile()
+            : new BlobStoreError(`Unable to read blob key ${key}`, cause),
+    }).pipe(Effect.catchTag('MissingBlobFile', () => Effect.succeed(null)), Effect.map((body) => (body === null ? null : new Uint8Array(body))));
+}
+function listFolder(directory, prefix) {
+    const folder = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+    return Effect.tryPromise({
+        try: () => readdir(`${directory}/${folder}`),
+        catch: (cause) => isMissingFile(cause)
+            ? new MissingBlobFile()
+            : new BlobStoreError(`Unable to list blob keys ${prefix}`, cause),
+    }).pipe(Effect.catchTag('MissingBlobFile', () => Effect.succeed([])), Effect.map((names) => names.map((name) => `${folder}/${name}`)));
+}
+function folderOf(key) {
+    const slash = key.lastIndexOf('/');
+    return slash < 0 ? '' : key.slice(0, slash);
+}
+function isMissingFile(cause) {
+    return Predicate.isObject(cause) && 'code' in cause && cause.code === 'ENOENT';
+}

package/dist/runtime/helpers.d.ts

@@ -1,8 +1,17 @@
-import { Effect, Layer, type Context } from 'effect';
-import { type AnyRuntimeModule, type AppendableEvent, type EventCatalog, type EventEnvelope, type EventInput, type EventOrigin, type EventStore, InvalidEventError, type JsonValue, type OutstandingEffect, type RegisteredDefinition, type RunCursor, type RunState, type SnapshotStore } from '@swirls/looms/core';
+import { Effect, Layer, type Context, type Types } from 'effect';
+import { type AnyRuntimeModule, type AppendableEvent, type EventCatalog, type EventEnvelope, type EventInput, type EventOrigin, type EventStore, InvalidEventError, type DefinitionResolveError, type DefinitionResolver, type JsonValue, type OutstandingEffect, type RetryPolicy, type SecretContext, type TraceContext, type RunCursor, type RunState, type SnapshotStore } from '@swirls/looms/core';
 import type { EffectWorkerTask } from './types';
-export declare function workerTask(runId: string, item: OutstandingEffect, attempt: number): EffectWorkerTask;
-declare const UnknownDefinitionError_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 & {
+/** What a dispatch carries beyond the effect itself. */
+export interface WorkerTaskExtras {
+    /** Progress from the previous attempt's last heartbeat. */
+    readonly details?: JsonValue | null;
+    readonly secrets?: SecretContext;
+    readonly trace?: TraceContext | null;
+    readonly retry?: RetryPolicy;
+    readonly scheduleToStartAt?: number | null;
+}
+export declare function workerTask(runId: string, item: OutstandingEffect, attempt: number, extras?: WorkerTaskExtras): EffectWorkerTask;
+declare const UnknownDefinitionError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "UnknownDefinitionError";
 } & Readonly<A>;
 export declare class UnknownDefinitionError extends UnknownDefinitionError_base<{
@@ -34,14 +43,14 @@ export declare function groupOutstanding(items: readonly {
  * A future third producer of thread.started must call this; do not emit the
  * event with raw input.
  */
-export declare function threadStartedEvents(definitions: ReadonlyMap<string, RegisteredDefinition>, args: {
+export declare function threadStartedEvents(definitions: DefinitionResolver, args: {
     kind: string;
     definitionName: string;
     definitionVersion: string;
     input: JsonValue;
     threadId: string;
     parentThreadId: string | null;
-}): Effect.Effect<ReadonlyArray<EventInput>, UnknownDefinitionError>;
+}): Effect.Effect<ReadonlyArray<EventInput>, UnknownDefinitionError | DefinitionResolveError>;
 export declare function synthesizedThreadFailed(before: RunState, after: RunState, written: readonly EventEnvelope[]): EventInput[];
 /** Cancel whatever is still live below each thread `written` cancels, deepest first. */
 export declare function cascadedCancellations(state: RunState, written: readonly EventEnvelope[]): EventInput[];

package/dist/runtime/helpers.js

@@ -1,13 +1,40 @@
 import { Data, Effect, Layer, Predicate } from 'effect';
-import { asJson, createEvent, definitionKey, descendantThreadIds, isTerminalStatus, makeMemorySnapshotStore, matchingWaits, snapshotStoreOf, validateEventInput, validateEventsEffect, validateInputEffect, withSnapshotStore, InvalidEventError, } from '@swirls/looms/core';
-export function workerTask(runId, item, attempt) {
-    return {
+import { asJson, createEvent, definitionKey, descendantThreadIds, isTerminalStatus, makeMemorySnapshotStore, matchingWaits, snapshotStoreOf, validateEventInput, validateEventsEffect, validateInputEffect, withSnapshotStore, hasEntries, InvalidEventError, } from '@swirls/looms/core';
+export function workerTask(runId, item, attempt, extras = {}) {
+    const task = {
         runId,
         effectId: item.effectId,
         attempt,
         type: item.effect.type,
         input: 'input' in item.effect ? item.effect.input : null,
     };
+    if (extras.details != null) {
+        task.details = extras.details;
+    }
+    if (extras.secrets && hasEntries(extras.secrets)) {
+        task.secrets = extras.secrets;
+    }
+    if (extras.trace) {
+        task.trace = extras.trace;
+    }
+    const deadlines = workerDeadlines(extras);
+    if (deadlines) {
+        task.deadlines = deadlines;
+    }
+    return task;
+}
+function workerDeadlines(extras) {
+    const deadlines = {};
+    if (extras.scheduleToStartAt != null) {
+        deadlines.scheduleToStartAt = extras.scheduleToStartAt;
+    }
+    if (extras.retry?.startToCloseTimeoutMs) {
+        deadlines.startToCloseTimeoutMs = extras.retry.startToCloseTimeoutMs;
+    }
+    if (extras.retry?.heartbeatTimeoutMs) {
+        deadlines.heartbeatTimeoutMs = extras.retry.heartbeatTimeoutMs;
+    }
+    return Object.keys(deadlines).length > 0 ? deadlines : undefined;
 }
 export class UnknownDefinitionError extends Data.TaggedError('UnknownDefinitionError') {
     constructor(kind, definitionName, definitionVersion) {
@@ -105,15 +132,16 @@ export function groupOutstanding(items) {
  */
 export function threadStartedEvents(definitions, args) {
     return Effect.gen(function* () {
-        const def = definitions.get(definitionKey(args.kind, args.definitionName, args.definitionVersion));
+        const def = yield* definitions.resolve(args.kind, args.definitionName, args.definitionVersion);
         if (!def) {
             return yield* new UnknownDefinitionError(args.kind, args.definitionName, args.definitionVersion);
         }
         const raw = args.input ?? null;
         let startedInput = raw;
         let validationError;
-        if (def?.input) {
-            const validated = yield* validateInputEffect(def.input, raw).pipe(Effect.match({
+        const input = schemaInputOf(def);
+        if (input) {
+            const validated = yield* validateInputEffect(input, raw).pipe(Effect.match({
                 onFailure: (error) => ({ ok: false, error: error.message }),
                 onSuccess: (value) => ({ ok: true, value }),
             }));
@@ -150,6 +178,18 @@ export function threadStartedEvents(definitions, args) {
         ];
     });
 }
+function schemaInputOf(definition) {
+    if (!('input' in definition)) {
+        return undefined;
+    }
+    return isSchemaInput(definition.input) ? definition.input : undefined;
+}
+function isSchemaInput(value) {
+    if (value === null || (!Predicate.isObject(value) && !Predicate.isFunction(value))) {
+        return false;
+    }
+    return '~standard' in value || 'ast' in value;
+}
 export function synthesizedThreadFailed(before, after, written) {
     const out = [];
     for (const [threadId, thread] of Object.entries(after.threads)) {

package/dist/runtime/index.d.ts

@@ -1,5 +1,7 @@
-export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunOverloadedError, RunTerminalError, StartRunConflictError, type CreateRuntimeOptions, type EffectWorker, type EffectWorkerTask, type LoomsRuntime, type RunOperationalStatus, type RegisteredDefinition, type StartRunArgs, type WakeError, type WakeScheduler, type WorkerCallback, type WorkerCallbackInput, } from './runtime';
+export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunOverloadedError, RunTerminalError, StartRunConflictError, type CreateRuntimeOptions, type EffectWorker, type EffectWorkerDeadlines, type EffectWorkerTask, type LoomsRuntime, type RunOperationalStatus, type RegisteredDefinition, type StartRunArgs, type WakeError, type WakeScheduler, type WorkerCallback, type WorkerCallbackInput, type WorkerCallbackResult, } from './runtime';
 export { createLooms, type Looms, type CreateLoomsOptions, type StartResult } from './looms';
-export { serveHttp, createFetchHandler, isLoomsApiPath, type FetchHandlerOptions, authAllowed, authDenied, bearerAuth, defaultAuthorize, type AuthDecision, type AuthorizedAccess, type Authorize, type BearerTokens, type RouteAccess, type RouteInfo, type RunningServer, type LoomsFetchResult, } from './server';
+export { loadSubscriptionOpening, readSubscriptionBounds } from './subscription';
+export { serveHttp, createFetchHandler, isLoomsApiPath, type FetchHandlerOptions, authAllowed, authDenied, authResponse, bearerAuth, defaultAuthorize, grantAuth, issueRunGrant, grantSubprotocol, runGrantToken, verifyRunGrant, GrantError, type GrantAuthOptions, type GrantFailure, type RunGrant, runRouteInfo, type AuthDecision, type AuthorizedAccess, type Authorize, type BearerTokens, type RouteAccess, type RouteInfo, type RunningServer, type LoomsFetchResult, } from './server';
+export { filesystemBlobStore } from './filesystem-blob-store';
 export { createEventStreamResponse, type EventStreamOptions } from './sse';
 export { notifyObserver, type RuntimeObservation, type RuntimeObserver } from './observer';

package/dist/runtime/index.js

@@ -1,5 +1,7 @@
 export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunOverloadedError, RunTerminalError, StartRunConflictError, } from './runtime.js';
 export { createLooms } from './looms.js';
-export { serveHttp, createFetchHandler, isLoomsApiPath, authAllowed, authDenied, bearerAuth, defaultAuthorize, } from './server.js';
+export { loadSubscriptionOpening, readSubscriptionBounds } from './subscription.js';
+export { serveHttp, createFetchHandler, isLoomsApiPath, authAllowed, authDenied, authResponse, bearerAuth, defaultAuthorize, grantAuth, issueRunGrant, grantSubprotocol, runGrantToken, verifyRunGrant, GrantError, runRouteInfo, } from './server.js';
+export { filesystemBlobStore } from './filesystem-blob-store.js';
 export { createEventStreamResponse } from './sse.js';
 export { notifyObserver } from './observer.js';

package/dist/runtime/local-effect-executor.d.ts

@@ -1,19 +1,28 @@
 import { Effect, type Context, type ManagedRuntime } from 'effect';
-import { type ComposedRegistry, type EventEnvelope, type OutstandingEffect, type RegisteredDefinition } from '@swirls/looms/core';
+import { type ComposedRegistry, type EventEnvelope, type DefinitionResolver, type OutstandingEffect, type RunAttributes, type RunLauncher, type SecretContext, type TraceContext } from '@swirls/looms/core';
 import type { RuntimeObserver } from './observer';
 import type { RuntimeRepository } from './repository';
 import type { RunExecutionContext } from './run-execution-context';
 export interface LocalEffectExecutorOptions {
     readonly registry: ComposedRegistry;
     readonly services: ManagedRuntime.ManagedRuntime<Context.Service.Any, never>;
-    readonly definitions: ReadonlyMap<string, RegisteredDefinition>;
+    readonly definitionResolver: DefinitionResolver;
     readonly executionContext: RunExecutionContext;
     readonly liveAppends: RuntimeRepository['liveAppends'];
     readonly runInContext: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
     readonly observe: (event: Parameters<RuntimeObserver['observe']>[0]) => void;
+    readonly launcher: RunLauncher;
+}
+/** Run-level values every effect sees. Runs the effects launch inherit them unless the launch overrides them. */
+export interface RunContext {
+    readonly correlationId: string;
+    readonly attributes: RunAttributes;
+    readonly secrets: SecretContext;
+    readonly trace: TraceContext | null;
 }
 export interface ExecuteLocalEffectsInput {
     readonly runId: string;
+    readonly context: RunContext;
     readonly outstanding: ReadonlyArray<OutstandingEffect>;
     readonly attempts: ReadonlyMap<string, number>;
     readonly now: number;

package/dist/runtime/local-effect-executor.js

@@ -1,9 +1,64 @@
 import { Effect, Option, Predicate } from 'effect';
-import { createEvent, validateEventInput, withdrawnError, } from '@swirls/looms/core';
+import { createEvent, createRunId, DEFAULT_DEFINITION_VERSION, validateEventInput, withdrawnError, } from '@swirls/looms/core';
 import { dispatchEffect } from './dispatch-effect.js';
 import { RuntimeExecutionError } from './errors.js';
 import { createEffectFailedEvent, createLiveEvent, groupOutstanding, materializeEffectOutcome, } from './helpers.js';
 import { planAttemptFailure } from './retry-policy.js';
+function runLaunchedPayload(args, targetRunId, effectId) {
+    const definitionVersion = args.definitionVersion ?? DEFAULT_DEFINITION_VERSION;
+    const base = {
+        runId: targetRunId,
+        kind: args.kind,
+        definitionName: args.definitionName,
+        definitionVersion,
+        effectId,
+    };
+    if (args.close === undefined) {
+        return base;
+    }
+    return { ...base, close: args.close };
+}
+/**
+ * Stamps every launch with the effect that made it, replacing anything the handler passed, and
+ * records a `runtime.run.launched` event for each launch the target accepts.
+ */
+function launcherFor(launcher, runId, context, item, launched) {
+    const launchedBy = {
+        runId,
+        threadId: item.threadId,
+        effectId: item.effectId,
+        causationId: item.causingEventId,
+        causationSeq: item.causingSeq,
+    };
+    return {
+        launch: (args) => {
+            const targetRunId = args.runId ?? createRunId();
+            return launcher
+                .launch({
+                ...args,
+                runId: targetRunId,
+                launchedBy,
+                correlationId: context.correlationId,
+                attributes: args.attributes ?? context.attributes,
+                secrets: args.secrets ?? context.secrets,
+                trace: args.trace ?? context.trace ?? undefined,
+            })
+                .pipe(Effect.tap(() => Effect.sync(() => {
+                launched.push(createEvent(runId, {
+                    type: 'runtime.run.launched',
+                    payload: runLaunchedPayload(args, targetRunId, item.effectId),
+                    threadId: item.threadId,
+                    causationId: item.causingEventId,
+                    correlationId: context.correlationId,
+                    origin: { type: 'thread', threadId: item.threadId },
+                }));
+            })));
+        },
+        status: launcher.status,
+        signal: (targetRunId, events, options) => launcher.signal(targetRunId, events, options),
+        cancel: (targetRunId) => launcher.cancel(targetRunId),
+    };
+}
 function makeAbortController() {
     return new AbortController();
 }
@@ -20,7 +75,7 @@ function abortion(signal) {
     });
 }
 export function executeLocalEffects(options, input) {
-    const { registry, services, definitions, executionContext, liveAppends, runInContext, observe } = options;
+    const { registry, services, definitionResolver, executionContext, liveAppends, runInContext, observe, launcher, } = options;
     return Effect.forEach(groupOutstanding(input.outstanding), (groupKey) => Effect.gen(function* () {
         const group = input.outstanding.filter((item) => `${item.threadId}:${item.causingSeq}` === groupKey);
         const produced = [];
@@ -43,11 +98,15 @@ export function executeLocalEffects(options, input) {
                 threadId: item.threadId,
             });
             const retry = registry.effects.get(item.effect.type)?.retry;
-            const dispatched = dispatchEffect(registry, services, definitions, item.effect, {
+            const launched = [];
+            const dispatched = dispatchEffect(registry, services, definitionResolver, launcherFor(launcher, input.runId, input.context, item, launched), item.effect, {
                 effectId: item.effectId,
                 runId: input.runId,
                 threadId: item.threadId,
                 causingEventId: item.causingEventId,
+                attributes: input.context.attributes,
+                secrets: input.context.secrets,
+                trace: input.context.trace,
                 signal: controller.signal,
                 emit: appendLive,
             }).pipe(Effect.map((outcomes) => ({ _tag: 'completed', outcomes })), Effect.raceFirst(abortion(controller.signal)));
@@ -56,6 +115,8 @@ export function executeLocalEffects(options, input) {
                 : dispatched).pipe(Effect.ensuring(Effect.sync(() => {
                 executionContext.activeEffects.delete(item.effectId);
             })));
+            // A launch the target accepted happened even if the attempt was later aborted or failed.
+            produced.push(...launched);
             if (settled._tag === 'aborted') {
                 continue;
             }
@@ -94,7 +155,19 @@ export function executeLocalEffects(options, input) {
                 continue;
             }
             const { outcomes } = settled;
-            if (outcomes.length === 0) {
+            const sideEffect = item.effect.type === 'runtime.launch' || item.effect.type === 'runtime.cancelRun';
+            if (outcomes.length === 0 && sideEffect) {
+                const attempt = input.attempts.get(item.effectId) ?? 1;
+                produced.push(createEvent(input.runId, {
+                    type: 'runtime.effect.completed',
+                    payload: { effectId: item.effectId, attempt },
+                    threadId: item.threadId,
+                    effectId: item.effectId,
+                    causationId: item.causingEventId,
+                    origin: { type: 'system' },
+                }));
+            }
+            else if (outcomes.length === 0) {
                 produced.push(createEffectFailedEvent(input.runId, item, 'empty-outcome'));
             }
             for (const outcome of outcomes) {
@@ -102,6 +175,7 @@ export function executeLocalEffects(options, input) {
                     const attempt = input.attempts.get(item.effectId) ?? 1;
                     const payload = Predicate.isObject(outcome.payload) ? outcome.payload : {};
                     const error = Predicate.isString(payload.error) ? payload.error : 'effect failed';
+                    const retryAfterMs = payload.retryAfterMs;
                     const failure = planAttemptFailure({
                         runId: input.runId,
                         item,
@@ -110,6 +184,8 @@ export function executeLocalEffects(options, input) {
                         now: input.now,
                         retry,
                         origin: { type: 'system' },
+                        nonRetryable: payload.nonRetryable === true,
+                        retryAfterMs: Predicate.isNumber(retryAfterMs) ? retryAfterMs : undefined,
                     });
                     if (failure.retrying) {
                         observe({