@swirls/looms 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# @swirls/looms
+
+## 0.1.0
+
+### Minor Changes
+
+- 2176eac: Add `defineKind` and `createKind` so custom startable types share the same `{ kind, name }` builder as `defineAgent` and `defineWorkflow`.
+- a879e8b: Add `@swirls/looms/evaluator` so typed questions can score a run and branch a workflow. Pass a model id such as `typesafe-ai/jev`; the thread kind stays `evaluator`.
+
+## 0.0.2
+
+### Patch Changes
+
+- 9f3fd62: Include the package changelog in published npm artifacts.
+
+## 0.0.1
+
+### Patch Changes
+
+- e83496a: **BREAKING**: Modules own their definitions. Pass `workflow({ definitions: [checkout] })` / `agent({ definitions: [...] })` instead of a top-level `definitions` list on `createLooms`, `createRuntime`, actor cells/hosts, or Durable Objects. Omitting `modules` installs none (no longer defaults to agent/workflow/approval).
+
+  **BREAKING**: `defineModule(options, setup)` returns the finished module. Returned `effects` / `threads` / `projections` / `definitions` are registered and exposed (e.g. `payments.effects.charge`). The old scope-only + `.build()` form is replaced by `createModuleScope` for multi-file authoring.
+
+  Compose rejects duplicate definitions and definitions whose owning module does not implement the thread kind. Starting or spawning an unsupported kind fails before run events are written; folding an unsupported kind marks the thread failed instead of inventing empty state.
+
+- ee5f92f: Initial 0.0.1 OSS release: durable Effect runtime for agents and workflows, S2 adapter, HTTP client, React bindings, CLI, optional projectors, and demo app.
+- 4c8410e: Looms DX overhaul:
+
+  - Add Standard Schema `input` typing and runtime validation for `defineAgent`, `defineWorkflow`, and `defineTool`.
+  - Provide Promise-based `createLooms()` facade with lazy init, typed start overloads, and universal `fetch(req) -> Response | null`.
+  - Add Looms-native event streaming directly against EventStore and `/runs/:id/events` (eliminating the dual-log S2 bridge).
+  - Add `s2Lite()` / `startS2Lite()` auto-starting dev process manager.
+  - Typed client generics for `createLoomsClient<typeof definitions>()`.
+  - Single server setup for dev and prod in demo app with no `effect` dependency.
+
+- 4c8410e: Introduce the generic `@swirls/looms/projectors` module. Implement `Projector` or use `memory()`,
+  `postgres({ url })`, and `sqlite({ path })`. `createLooms({ projectors })` initializes projectors,
+  wraps append, and disposes them. S2 helpers now take an explicit environment bag; `serveHttp` no
+  longer reads `PORT`.
+- f1cceb0: Optimize React SDK and Debugger for high-velocity event streaming:
+
+  - **BREAKING (`@swirls/looms/react`)**: `useRunStore(runId, options)` is now a non-subscribing handle. Subscribe via fine-grained hooks (`useProjection`, `useRunEvents`, `useRunSummary`, `useThreadTree`, `useEventCounts`, `useEventBySeq`, `useLatestEvent`, `useEventFold`, `useRunSelector`). Removed `createLoomsHooks` and `pollIntervalMs` — use `LoomsRegister` or explicit `EventsOf<…>` generics instead.
+  - **BREAKING (`@swirls/looms/react`)**: Materialized tables no longer include `events_log`; the event log lives only in `store.events()` / `EventIndex`. `StoreListener` is now `() => void` (re-read via store APIs).
+  - **Incremental Projection Caching (`@swirls/looms/react`)**: `store.project(def)` and `useProjection` fold newly arrived events from cached state (O(batch)), preserving references when unchanged.
+  - **Adaptive Coalescing (`@swirls/looms/react`)**: Default `coalesce: 'adaptive'` (macrotask when quiet, animation-frame under burst); also `frame`, `immediate`, `{ delayMs }`. Notify scheduling lives in `createNotifyScheduler`. Added `store.flush()`.
+  - **Shared `EventIndex` (`@swirls/looms/core`)**: Append-only thread/seq/count/latest indexes with lazy snapshots; used by the React client store and the debugger.
+  - **Debugger (`@swirls/looms/debugger`)**: Virtualized `EventStream` with stable default catalog, catalog-aware meta cache, and `useMemo` visibility filtering.
+
+- e398380: Publish the React integration at `@swirls/looms/react` and drop the former LiveStore protocol names.
+
+  - Package and React provider are now `@swirls/looms/react` / `LoomsProvider`.
+  - Live event HTTP is `GET /runs/:id/events` with SSE content negotiation. Wire batches are Looms event envelopes.
+  - `LiveStoreGlobalEncoded` is now `EncodedLoomsEvent`.

package/README.md

@@ -7,3 +7,5 @@ bun add @swirls/looms
 ```
 
 Import the core runtime from `@swirls/looms`, or use explicit modules such as `@swirls/looms/agent` and `@swirls/looms/react`. See the [repository README](https://github.com/ByteSliceHQ/looms#readme) for the full guide.
+
+Release notes are available in [`CHANGELOG.md`](./CHANGELOG.md).

package/dist/actor/cell.d.ts

@@ -1,5 +1,5 @@
-import { type AnyRuntimeModule, type EventStore, type RunState, type SnapshotStore } from '@swirls/looms/core';
-import { type LoomsRuntime, type WakeScheduler } from '@swirls/looms/runtime';
+import { type AnyRuntimeModule, type EventStore, type EventStoreTrimCoverage, type RunState, type SnapshotStore } from '@swirls/looms/core';
+import { type Authorize, type LoomsRuntime, type WakeScheduler } from '@swirls/looms/runtime';
 export interface ActorCellOptions<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     readonly runId: string;
     readonly store: EventStore;
@@ -7,10 +7,14 @@ export interface ActorCellOptions<TModules extends readonly AnyRuntimeModule[] =
     readonly modules: TModules;
     readonly snapshotEvery?: number;
     readonly maxWakeIterations?: number;
+    readonly maxPendingRunOperations?: number;
     readonly snapshotStore?: SnapshotStore;
     readonly trimAfterSnapshot?: {
-        keepSnapshots: number;
+        readonly keepSnapshots: number;
+        readonly coverage?: (runId: string) => EventStoreTrimCoverage | Promise<EventStoreTrimCoverage>;
     };
+    /** Authorizes the cell's HTTP API; see `createFetchHandler`. */
+    readonly authorize?: Authorize;
 }
 export interface ActorCell<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     readonly runId: string;
@@ -18,7 +22,8 @@ export interface ActorCell<TModules extends readonly AnyRuntimeModule[] = readon
     readonly store: EventStore;
     fetch(req: Request): Promise<Response>;
     wake(): Promise<RunState>;
-    dispose(): void;
+    recoverWake(): Promise<number>;
+    dispose(): Promise<void>;
 }
 /**
  * Creates an in-process actor cell that owns a single `runId`.

package/dist/actor/cell.js

@@ -14,28 +14,24 @@ export function createActorCell(options) {
         scheduler,
         snapshotEvery: options.snapshotEvery,
         maxWakeIterations: options.maxWakeIterations,
+        maxPendingRunOperations: options.maxPendingRunOperations,
         snapshotStore: options.snapshotStore,
         trimAfterSnapshot: options.trimAfterSnapshot,
     });
-    const fetchHandler = createFetchHandler({ runtime, store });
+    const fetchHandler = createFetchHandler({ runtime, store, authorize: options.authorize });
     return {
         runId,
         runtime,
         store,
-        fetch: async (req) => {
+        fetch: (req) => {
             const targetRunId = runIdFromRequest(req);
             if (targetRunId && targetRunId !== runId) {
-                return new Response('Not Found', { status: 404 });
+                return Promise.resolve(new Response('Not Found', { status: 404 }));
             }
-            const res = await fetchHandler(req);
-            if (res === null) {
-                return new Response('Not Found', { status: 404 });
-            }
-            return res;
+            return fetchHandler(req).then((res) => res ?? new Response('Not Found', { status: 404 }));
         },
         wake: () => Effect.runPromise(Effect.provideService(runtime.wake(runId), EventStoreTag, store)),
-        dispose: () => {
-            runtime.dispose();
-        },
+        recoverWake: () => Effect.runPromise(Effect.provideService(runtime.rescanTimers, EventStoreTag, store)),
+        dispose: () => Effect.runPromise(runtime.dispose),
     };
 }

package/dist/actor/host.d.ts

@@ -1,4 +1,5 @@
-import type { AnyRuntimeModule, EventStore, SnapshotStore } from '@swirls/looms/core';
+import type { AnyRuntimeModule, EventStore, EventStoreTrimCoverage, SnapshotStore } from '@swirls/looms/core';
+import { type Authorize } from '@swirls/looms/runtime';
 import { type ActorCell } from './cell';
 export interface LocalActorHostOptions<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     readonly createStore: (runId: string) => EventStore | Promise<EventStore>;
@@ -7,18 +8,21 @@ export interface LocalActorHostOptions<TModules extends readonly AnyRuntimeModul
     readonly snapshotEvery?: number;
     readonly maxWakeIterations?: number;
     readonly trimAfterSnapshot?: {
-        keepSnapshots: number;
+        readonly keepSnapshots: number;
+        readonly coverage?: (runId: string) => EventStoreTrimCoverage | Promise<EventStoreTrimCoverage>;
     };
     /**
      * After creating a cell, rescan its store for pending timers (process restart).
      * Default true. No-op for empty in-memory stores.
      */
     readonly rescanTimers?: boolean;
+    /** Authorizes each cell's HTTP API; see `createFetchHandler`. */
+    readonly authorize?: Authorize;
 }
 export interface LocalActorHost<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     getCell(runId: string): Promise<ActorCell<TModules>>;
     fetch(req: Request): Promise<Response | null>;
-    dispose(): void;
+    dispose(): Promise<void>;
 }
 /**
  * Creates an in-process host that routes requests to distinct actor cells.

package/dist/actor/host.js

@@ -1,8 +1,26 @@
-import { Effect } from 'effect';
+import { Data, Effect } from 'effect';
 import { EventStoreTag } from '@swirls/looms/core';
 import { createTimeoutScheduler, isLoomsApiPath } from '@swirls/looms/runtime';
 import { createActorCell } from './cell.js';
-import { resolveRunTarget } from './routing.js';
+import { resolveRunTarget, RunTargetError } from './routing.js';
+class ActorWakeError extends Data.TaggedError('ActorWakeError') {
+    constructor(cause) {
+        super({
+            cause,
+            message: cause instanceof Error ? cause.message : String(cause),
+        });
+        this.name = 'ActorWakeError';
+    }
+}
+class ActorHostError extends Data.TaggedError('ActorHostError') {
+    constructor(cause) {
+        super({
+            cause,
+            message: cause instanceof Error ? cause.message : String(cause),
+        });
+        this.name = 'ActorHostError';
+    }
+}
 /**
  * Creates an in-process host that routes requests to distinct actor cells.
  * Useful for local Bun actor backends, tests, and lightweight simulation.
@@ -15,18 +33,19 @@ export function createLocalActorHost(options) {
         if (existing) {
             return existing;
         }
-        const cellPromise = (async () => {
-            const store = await options.createStore(runId);
+        const cellPromise = Effect.runPromise(Effect.gen(function* () {
+            const store = yield* Effect.tryPromise({
+                try: () => Promise.resolve(options.createStore(runId)),
+                catch: (cause) => new ActorHostError(cause),
+            });
             // Assign after createActorCell so the scheduler never closes over an unassigned cell.
             let wake;
-            const scheduler = createTimeoutScheduler((scheduledRunId) => {
-                if (scheduledRunId !== runId) {
-                    return;
-                }
-                void wake?.().catch((err) => {
-                    console.error('[actor host wake error]', err);
-                });
-            });
+            const scheduler = createTimeoutScheduler((scheduledRunId) => scheduledRunId === runId && wake
+                ? Effect.tryPromise({
+                    try: wake,
+                    catch: (cause) => new ActorWakeError(cause),
+                }).pipe(Effect.tapError(Effect.logError), Effect.ignore)
+                : Effect.void);
             const cell = createActorCell({
                 runId,
                 store,
@@ -36,47 +55,51 @@ export function createLocalActorHost(options) {
                 snapshotEvery: options.snapshotEvery,
                 maxWakeIterations: options.maxWakeIterations,
                 trimAfterSnapshot: options.trimAfterSnapshot,
+                authorize: options.authorize,
             });
             wake = () => cell.wake();
             if (rescanTimers) {
-                await Effect.runPromise(Effect.provideService(cell.runtime.rescanTimers(), EventStoreTag, store)).catch((err) => {
-                    console.error('[actor host rescan timers error]', err);
-                });
+                yield* Effect.provideService(cell.runtime.rescanTimers, EventStoreTag, store).pipe(Effect.tapError(Effect.logError), Effect.ignore);
             }
             return cell;
-        })();
+        }));
         cells.set(runId, cellPromise);
         return cellPromise;
     };
     return {
         getCell,
-        fetch: async (req) => {
+        fetch: (req) => {
             const url = new URL(req.url);
             if (!isLoomsApiPath(url.pathname)) {
-                return null;
+                return Promise.resolve(null);
             }
             if (url.pathname === '/health') {
-                return Response.json({ ok: true });
+                return Promise.resolve(Response.json({ ok: true }));
             }
             if (req.method === 'GET' && url.pathname === '/runs') {
-                return Response.json({
+                return Promise.resolve(Response.json({
                     error: 'Global run listing is not supported in the actor host without a global index',
-                }, { status: 501 });
-            }
-            try {
-                const { runId, request } = await resolveRunTarget(req);
-                const cell = await getCell(runId);
-                return cell.fetch(request);
-            }
-            catch {
-                return new Response('Not Found', { status: 404 });
+                }, { status: 501 }));
             }
+            return Effect.runPromise(Effect.gen(function* () {
+                const { runId, request } = yield* Effect.tryPromise({
+                    try: () => resolveRunTarget(req),
+                    catch: (cause) => new ActorHostError(cause),
+                });
+                const cell = yield* Effect.tryPromise({
+                    try: () => getCell(runId),
+                    catch: (cause) => new ActorHostError(cause),
+                });
+                return yield* Effect.tryPromise({
+                    try: () => cell.fetch(request),
+                    catch: (cause) => new ActorHostError(cause),
+                });
+            }).pipe(Effect.catchIf((error) => error.cause instanceof RunTargetError, () => Effect.succeed(new Response('Not Found', { status: 404 })))));
         },
         dispose: () => {
-            for (const promise of cells.values()) {
-                void promise.then((cell) => cell.dispose());
-            }
+            const disposals = [...cells.values()].map((promise) => promise.then((cell) => cell.dispose()));
             cells.clear();
+            return Promise.all(disposals).then(() => undefined);
         },
     };
 }

package/dist/actor/index.d.ts

@@ -1,3 +1,3 @@
 export { createActorCell, type ActorCell, type ActorCellOptions } from './cell';
-export { runIdFromRequest, resolveRunTarget, type ResolvedRunTarget } from './routing';
+export { runIdFromRequest, resolveRunTarget, RunTargetError, type ResolvedRunTarget, } from './routing';
 export { createLocalActorHost, type LocalActorHost, type LocalActorHostOptions } from './host';

package/dist/actor/index.js

@@ -1,3 +1,3 @@
 export { createActorCell } from './cell.js';
-export { runIdFromRequest, resolveRunTarget } from './routing.js';
+export { runIdFromRequest, resolveRunTarget, RunTargetError, } from './routing.js';
 export { createLocalActorHost } from './host.js';

package/dist/actor/routing.d.ts

@@ -1,15 +1,26 @@
 /**
  * Extracts the target `runId` from a Looms HTTP request.
- * Inspects `x-looms-run-id`, `/runs/:runId/*`, and `/api/events?runId=*`.
+ * Inspects `x-looms-run-id` and `/runs/:runId/*`.
  */
 export declare function runIdFromRequest(req: Request): string | null;
 export interface ResolvedRunTarget {
     readonly runId: string;
     readonly request: Request;
 }
+declare const RunTargetError_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: "RunTargetError";
+} & Readonly<A>;
+export declare class RunTargetError extends RunTargetError_base<{
+    readonly method: string;
+    readonly path: string;
+    readonly message: string;
+}> {
+    constructor(method: string, path: string);
+}
 /**
  * Resolves the destination `runId` for routing to an actor cell.
  * For `POST /runs` without a `runId`, creates a fresh `runId`, injects it
  * into the body, and sets `x-looms-run-id`.
  */
 export declare function resolveRunTarget(req: Request): Promise<ResolvedRunTarget>;
+export {};

package/dist/actor/routing.js

@@ -1,5 +1,5 @@
-import { Option, Schema } from 'effect';
-import { createRunId, isJsonObject } from '@swirls/looms/core';
+import { Data, Effect, Option, Schema } from 'effect';
+import { createRunId, isJsonObject, stringifyJson } from '@swirls/looms/core';
 const RunTargetBodySchema = Schema.Struct({
     runId: Schema.optional(Schema.NonEmptyString),
 });
@@ -7,7 +7,7 @@ const decodeRunTargetBody = Schema.decodeUnknownOption(Schema.fromJsonString(Run
 const decodePayloadRecord = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Record(Schema.String, Schema.Json)));
 /**
  * Extracts the target `runId` from a Looms HTTP request.
- * Inspects `x-looms-run-id`, `/runs/:runId/*`, and `/api/events?runId=*`.
+ * Inspects `x-looms-run-id` and `/runs/:runId/*`.
  */
 export function runIdFromRequest(req) {
     const header = req.headers.get('x-looms-run-id');
@@ -20,61 +20,67 @@ export function runIdFromRequest(req) {
     if (runsMatch && runsMatch[1]) {
         return decodeURIComponent(runsMatch[1]);
     }
-    if (path.startsWith('/api/events')) {
-        const runId = url.searchParams.get('runId');
-        if (runId) {
-            return runId;
-        }
-    }
     return null;
 }
+export class RunTargetError extends Data.TaggedError('RunTargetError') {
+    constructor(method, path) {
+        super({
+            method,
+            path,
+            message: `Cannot resolve runId from request: ${method} ${path}`,
+        });
+        this.name = 'RunTargetError';
+    }
+}
 /**
  * Resolves the destination `runId` for routing to an actor cell.
  * For `POST /runs` without a `runId`, creates a fresh `runId`, injects it
  * into the body, and sets `x-looms-run-id`.
  */
-export async function resolveRunTarget(req) {
-    const existing = runIdFromRequest(req);
-    if (existing) {
-        if (req.headers.get('x-looms-run-id') === existing) {
-            return { runId: existing, request: req };
+export function resolveRunTarget(req) {
+    return Effect.runPromise(Effect.gen(function* () {
+        const existing = runIdFromRequest(req);
+        if (existing) {
+            if (req.headers.get('x-looms-run-id') === existing) {
+                return { runId: existing, request: req };
+            }
+            const headers = new Headers(req.headers);
+            headers.set('x-looms-run-id', existing);
+            const request = new Request(req.url, {
+                method: req.method,
+                headers,
+                body: req.body,
+                // SAFETY: duplex 'half' is required when streaming request body in standard Fetch.
+                // @ts-expect-error duplex is supported in modern runtimes
+                duplex: req.body ? 'half' : undefined,
+            });
+            return { runId: existing, request };
         }
-        const headers = new Headers(req.headers);
-        headers.set('x-looms-run-id', existing);
-        const request = new Request(req.url, {
-            method: req.method,
-            headers,
-            body: req.body,
-            // SAFETY: duplex 'half' is required when streaming request body in standard Fetch.
-            // @ts-expect-error duplex is supported in modern runtimes
-            duplex: req.body ? 'half' : undefined,
-        });
-        return { runId: existing, request };
-    }
-    const url = new URL(req.url);
-    if (req.method === 'POST' && url.pathname === '/runs') {
-        const text = await req.clone().text();
-        const decoded = decodeRunTargetBody(text);
-        let runId;
-        if (Option.isSome(decoded) && decoded.value.runId) {
-            runId = decoded.value.runId;
-        }
-        else {
-            runId = createRunId();
+        const url = new URL(req.url);
+        if (req.method === 'POST' && url.pathname === '/runs') {
+            const text = yield* Effect.promise(() => req.clone().text());
+            const decoded = decodeRunTargetBody(text);
+            let runId;
+            if (Option.isSome(decoded) && decoded.value.runId) {
+                runId = decoded.value.runId;
+            }
+            else {
+                runId = createRunId();
+            }
+            const decodedRecord = decodePayloadRecord(text);
+            const payloadObj = Option.isSome(decodedRecord) && isJsonObject(decodedRecord.value)
+                ? { ...decodedRecord.value, runId }
+                : { runId };
+            const headers = new Headers(req.headers);
+            headers.set('x-looms-run-id', runId);
+            headers.set('content-type', 'application/json');
+            const request = new Request(req.url, {
+                method: req.method,
+                headers,
+                body: stringifyJson(payloadObj),
+            });
+            return { runId, request };
         }
-        const decodedRecord = decodePayloadRecord(text);
-        const payloadObj = Option.isSome(decodedRecord) && isJsonObject(decodedRecord.value)
-            ? { ...decodedRecord.value, runId }
-            : { runId };
-        const headers = new Headers(req.headers);
-        headers.set('x-looms-run-id', runId);
-        headers.set('content-type', 'application/json');
-        const request = new Request(req.url, {
-            method: req.method,
-            headers,
-            body: JSON.stringify(payloadObj),
-        });
-        return { runId, request };
-    }
-    throw new Error(`Cannot resolve runId from request: ${req.method} ${url.pathname}`);
+        return yield* new RunTargetError(req.method, url.pathname);
+    }));
 }

package/dist/agent/agent-session.d.ts

@@ -0,0 +1,5 @@
+import { type DefinitionStore, type ThreadDefinition } from '@swirls/looms/core';
+import type { AgentSessionDefinition } from './definitions';
+import type { AgentSessionSnapshot, AgentSessionState } from './types';
+export declare function createAgentSessionThread(definitions: DefinitionStore<AgentSessionDefinition>): ThreadDefinition<AgentSessionState>;
+export declare function agentSessionSnapshot(state: AgentSessionState): AgentSessionSnapshot;