@rome-os/app-runtime 0.3.0 → 0.3.1

package/dist/proxies.js

@@ -0,0 +1,92 @@
+// Worker-side typed proxies for main-process services.
+//
+// An action worker is a forked subprocess that holds no live reference to the
+// main-process singletons (RoutineEngine, EventBus, EventCatalog, AppManager) —
+// those own in-memory state (trigger timers, subscriber sets, child-process
+// handles) that cannot be duplicated across processes. Each proxy below
+// presents the action-facing surface of one service but forwards every call to
+// the main process over the WorkerRPC IPC channel (see `getWorkerRpc`), where
+// the real service does the work.
+//
+// They are one half of a pair: in the main process an action receives the real
+// service; in a worker it receives the matching `*Proxy`. The naming mirrors
+// the original (`FooEngine` -> `FooEngineProxy`) so the pair is obvious at a
+// callsite. Each proxy owns the RPC method string (and timeout) for its calls,
+// keeping that stringly-typed seam in one typed place instead of scattered
+// across action bodies.
+import { getWorkerRpc } from "./worker-rpc.js";
+/** apps.* operations install/pack on the main process — minutes, not seconds. */
+const APP_INSTALL_RPC_TIMEOUT_MS = 3 * 60 * 1000;
+/** A flag flip with no filesystem work. */
+const SHORT_RPC_TIMEOUT_MS = 30 * 1000;
+/**
+ * Worker-side stand-in for the main-process `RoutineEngine`. Implements the
+ * `RoutineEngine` surface an action depends on, so the same `deps.routineEngine`
+ * works whether the action runs in the main process (real engine) or a worker
+ * (this proxy).
+ */
+export class RoutineEngineProxy {
+    /** Bring a persisted routine live. The main process re-reads the row by id
+     * and activates it, so only the id needs to cross the wire. */
+    async activate(routine) {
+        await getWorkerRpc().call("routines.schedule", { routineId: routine.id });
+    }
+    /** Tear down a routine's triggers in the main process. */
+    async deactivate(routineId) {
+        await getWorkerRpc().call("routines.cancel", { routineId });
+    }
+}
+/**
+ * Worker-side stand-in for the main-process `EventBus`. Publishing a domain
+ * event also declares its type to the event catalog (RFC 020) — both happen in
+ * the main process's `events.publish` handler.
+ */
+export class EventBusProxy {
+    async publish(event) {
+        // No `?? {}` here: the `events.publish` Zod schema defaults a missing
+        // payload to `{}` at the (validated) wire boundary, so defaulting again on
+        // the way in is redundant.
+        return await getWorkerRpc().call("events.publish", {
+            name: event.name,
+            source: event.source,
+            payload: event.payload,
+        });
+    }
+}
+/** Worker-side stand-in for the main-process `EventCatalog` (read side). */
+export class EventCatalogProxy {
+    /** Find emittable event types matching `query`, best matches first, capped at
+     * `limit`. `total` is the full match count before truncation. */
+    async search(query, limit) {
+        return await getWorkerRpc().call("events.searchCatalog", { query, limit });
+    }
+}
+/**
+ * Worker-side stand-in for the main-process app lifecycle authority. Each method
+ * owns its RPC method string and timeout. Results are app-local shapes the
+ * action knows, so they return as `unknown` and the caller narrows them —
+ * keeping those result types out of this SDK.
+ */
+export class AppManagerProxy {
+    async create(params) {
+        return await getWorkerRpc().call("apps.create", params, {
+            timeoutMs: APP_INSTALL_RPC_TIMEOUT_MS,
+        });
+    }
+    async install(params) {
+        return await getWorkerRpc().call("apps.install", params, {
+            timeoutMs: APP_INSTALL_RPC_TIMEOUT_MS,
+        });
+    }
+    async uninstall(params) {
+        return await getWorkerRpc().call("apps.uninstall", params, {
+            timeoutMs: APP_INSTALL_RPC_TIMEOUT_MS,
+        });
+    }
+    async setEnabled(params) {
+        return await getWorkerRpc().call("apps.setEnabled", params, {
+            timeoutMs: SHORT_RPC_TIMEOUT_MS,
+        });
+    }
+}
+//# sourceMappingURL=proxies.js.map

package/dist/proxies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxies.js","sourceRoot":"","sources":["../src/proxies.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,4EAA4E;AAC5E,wEAAwE;AACxE,+EAA+E;AAC/E,8EAA8E;AAC9E,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,2EAA2E;AAC3E,wBAAwB;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAU/C,iFAAiF;AACjF,MAAM,0BAA0B,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACjD,2CAA2C;AAC3C,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IAC7B;mEAC+D;IAC/D,KAAK,CAAC,QAAQ,CAAC,OAAgB;QAC7B,MAAM,YAAY,EAAE,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,MAAM,YAAY,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC9D,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACxB,KAAK,CAAC,OAAO,CAAC,KAIb;QACC,sEAAsE;QACtE,2EAA2E;QAC3E,2BAA2B;QAC3B,OAAO,MAAM,YAAY,EAAE,CAAC,IAAI,CAAqB,gBAAgB,EAAE;YACrE,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;IACL,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,iBAAiB;IAC5B;qEACiE;IACjE,KAAK,CAAC,MAAM,CACV,KAAa,EACb,KAAa;QAEb,OAAO,MAAM,YAAY,EAAE,CAAC,IAAI,CAC9B,sBAAsB,EACtB,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,MAAM,CAAC,MAA2C;QACtD,OAAO,MAAM,YAAY,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE;YACtD,SAAS,EAAE,0BAA0B;SACtC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAA6D;QACzE,OAAO,MAAM,YAAY,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE;YACvD,SAAS,EAAE,0BAA0B;SACtC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAA0C;QACxD,OAAO,MAAM,YAAY,EAAE,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,EAAE;YACzD,SAAS,EAAE,0BAA0B;SACtC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAA2C;QAC1D,OAAO,MAAM,YAAY,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,EAAE;YAC1D,SAAS,EAAE,oBAAoB;SAChC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/worker-rpc.d.ts

@@ -0,0 +1,35 @@
+export interface RpcResponseMessage {
+    type: "rpc_response";
+    clientId: string;
+    id: number;
+    result?: unknown;
+    error?: string;
+}
+export declare class WorkerRpcTimeoutError extends Error {
+    constructor(method: string, timeoutMs: number);
+}
+export declare class WorkerRpcDisconnectError extends Error {
+    constructor();
+}
+declare class WorkerRpcClient {
+    private readonly clientId;
+    private pending;
+    private nextId;
+    private processHandlersInstalled;
+    call<T = unknown>(method: string, params?: unknown, options?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    handleResponse(message: RpcResponseMessage): void;
+    private ensureProcessHandlers;
+}
+export declare function getWorkerRpc(): WorkerRpcClient;
+export type WorkerRpcInProcessDispatcher = (method: string, params: unknown) => Promise<unknown>;
+/**
+ * Register (or clear, with `null`) the main-process dispatcher used as a
+ * fallback when there is no parent IPC channel. Called once during main-process
+ * wiring with a handler backed by the live WorkerRpcServer.
+ */
+export declare function setWorkerRpcInProcessDispatcher(dispatcher: WorkerRpcInProcessDispatcher | null): void;
+export declare function isWorkerRpcResponse(message: unknown): message is RpcResponseMessage;
+export {};
+//# sourceMappingURL=worker-rpc.d.ts.map

package/dist/worker-rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-rpc.d.ts","sourceRoot":"","sources":["../src/worker-rpc.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAI9C;AAED,qBAAa,wBAAyB,SAAQ,KAAK;;CAKlD;AAoBD,cAAM,eAAe;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,wBAAwB,CAAS;IAEnC,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,OAAO,CAAC,CAAC,CAAC;IAgEb,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAYjD,OAAO,CAAC,qBAAqB;CAkB9B;AAID,wBAAgB,YAAY,IAAI,eAAe,CAK9C;AAWD,MAAM,MAAM,4BAA4B,GAAG,CACzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,KACZ,OAAO,CAAC,OAAO,CAAC,CAAC;AAItB;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,4BAA4B,GAAG,IAAI,GAC9C,IAAI,CAEN;AAQD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,kBAAkB,CAOnF"}

package/dist/worker-rpc.js

@@ -0,0 +1,149 @@
+// Worker-side RPC client for calling main-process services.
+//
+// The main process owns live references to ChannelManager, RoutineEngine,
+// and related services. Worker processes reach them over Node's child-process
+// IPC channel via this client — a replacement for the former HTTP callbacks
+// to the internal API.
+import { randomUUID } from "node:crypto";
+export class WorkerRpcTimeoutError extends Error {
+    constructor(method, timeoutMs) {
+        super(`WorkerRPC timeout: ${method} (${timeoutMs}ms)`);
+        this.name = "WorkerRpcTimeoutError";
+    }
+}
+export class WorkerRpcDisconnectError extends Error {
+    constructor() {
+        super("WorkerRPC main process disconnected");
+        this.name = "WorkerRpcDisconnectError";
+    }
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+// There may be more than one copy of this module loaded in the same process
+// (e.g. when an installed app ships its own physical copy of @rome-os/app-runtime
+// under node_modules/, producing a distinct ESM URL from the monorepo source).
+// Each copy constructs its own WorkerRpcClient with a distinct `clientId`.
+// Every instance installs its own process.on("message") listener; the main
+// process echoes `clientId` back on responses, so each listener only resolves
+// responses originating from its own pending map. This keeps pending maps
+// fully isolated across copies and avoids id-space collisions (nextId starts
+// from 1 independently in each copy).
+class WorkerRpcClient {
+    clientId = randomUUID();
+    pending = new Map();
+    nextId = 1;
+    processHandlersInstalled = false;
+    async call(method, params, options) {
+        if (!process.send) {
+            // Main process: no parent IPC channel, but it directly holds the real
+            // services. If a dispatcher is registered, run the call in-process
+            // instead of failing. Worker processes always have `process.send` and
+            // take the IPC path below — the two paths are mutually exclusive.
+            const dispatcher = getInProcessDispatcher();
+            if (dispatcher) {
+                // Enforce the same deadline as the IPC path so both transports share
+                // identical timeout semantics. Without this, callers like
+                // AppManagerProxy (which set multi-minute deadlines for
+                // apps.install/create/uninstall) would hang forever if an in-process
+                // service operation stalls.
+                const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+                let timer;
+                const timeout = new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new WorkerRpcTimeoutError(method, timeoutMs)), timeoutMs);
+                });
+                try {
+                    return (await Promise.race([dispatcher(method, params), timeout]));
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            }
+            throw new Error(`WorkerRPC: not running in a Node.js child process (method=${method})`);
+        }
+        this.ensureProcessHandlers();
+        const id = this.nextId++;
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        return await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new WorkerRpcTimeoutError(method, timeoutMs));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+                timeout,
+                method,
+            });
+            const request = {
+                type: "rpc_request",
+                clientId: this.clientId,
+                id,
+                method,
+                params,
+            };
+            process.send(request, (err) => {
+                if (err) {
+                    clearTimeout(timeout);
+                    this.pending.delete(id);
+                    reject(err);
+                }
+            });
+        });
+    }
+    handleResponse(message) {
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.id);
+        if (message.error !== undefined) {
+            pending.reject(new Error(message.error));
+        }
+        else {
+            pending.resolve(message.result);
+        }
+    }
+    ensureProcessHandlers() {
+        if (this.processHandlersInstalled)
+            return;
+        this.processHandlersInstalled = true;
+        process.on("message", (message) => {
+            if (isWorkerRpcResponse(message) && message.clientId === this.clientId) {
+                this.handleResponse(message);
+            }
+        });
+        process.on("disconnect", () => {
+            for (const pending of this.pending.values()) {
+                clearTimeout(pending.timeout);
+                pending.reject(new WorkerRpcDisconnectError());
+            }
+            this.pending.clear();
+        });
+    }
+}
+let singleton = null;
+export function getWorkerRpc() {
+    if (!singleton) {
+        singleton = new WorkerRpcClient();
+    }
+    return singleton;
+}
+const IN_PROCESS_DISPATCHER_KEY = Symbol.for("rome.workerRpc.inProcessDispatcher");
+/**
+ * Register (or clear, with `null`) the main-process dispatcher used as a
+ * fallback when there is no parent IPC channel. Called once during main-process
+ * wiring with a handler backed by the live WorkerRpcServer.
+ */
+export function setWorkerRpcInProcessDispatcher(dispatcher) {
+    globalThis[IN_PROCESS_DISPATCHER_KEY] = dispatcher ?? undefined;
+}
+function getInProcessDispatcher() {
+    return globalThis[IN_PROCESS_DISPATCHER_KEY];
+}
+export function isWorkerRpcResponse(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        message.type === "rpc_response" &&
+        typeof message.clientId === "string");
+}
+//# sourceMappingURL=worker-rpc.js.map

package/dist/worker-rpc.js.map

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

package/dist/workflow.d.ts

@@ -0,0 +1,61 @@
+export type Json = unknown;
+/** What a step's body can reach: the action runner (to invoke any registered
+ * action, including `summon`) and a logger. */
+export interface StepContext {
+    runAction(name: string, args: Record<string, unknown>): Promise<Json>;
+    log: {
+        info(message: string, data?: Record<string, unknown>): void;
+        warn(message: string, data?: Record<string, unknown>): void;
+    };
+    /** True on a verification/preview run. A step that writes to the outside world
+     * (sends a message, posts to a SaaS API) must short-circuit when this is set,
+     * so building or testing a workflow never performs a real external write. The
+     * interpreter threads it unchanged to every leaf. */
+    dryRun: boolean;
+}
+/** A leaf body: transform the input, optionally calling actions via `ctx`. */
+export type StepFn = (input: Json, ctx: StepContext) => Json | Promise<Json>;
+export type Workflow = {
+    kind: "step";
+    label: string;
+    run: StepFn;
+} | {
+    kind: "pipeline";
+    steps: Workflow[];
+} | {
+    kind: "parallel";
+    branches: Workflow[];
+} | {
+    kind: "branch";
+    label: string;
+    predicate: (input: Json) => boolean;
+    then: Workflow;
+    otherwise?: Workflow;
+} | {
+    kind: "map";
+    label: string;
+    items?: (input: Json) => Json[];
+    each: Workflow;
+};
+/** A leaf: author-written code. Transform the input and/or call actions via
+ * `ctx.runAction(name, args)` — including `ctx.runAction("summon", …)` to hand
+ * the step to an LLM agent when it needs judgment. Keep `summon` to a single
+ * step; don't fan it across a `map`/`parallel` (see issue #639). */
+export declare function step(label: string, run: StepFn): Workflow;
+/** Run steps in order, threading each step's output into the next step's input. */
+export declare function pipeline(...steps: Workflow[]): Workflow;
+/** Run branches concurrently on the same input; resolve to the array of outputs. */
+export declare function parallel(...branches: Workflow[]): Workflow;
+/** Run `then` when the predicate holds; otherwise run `otherwise` (or pass the
+ * input through unchanged when there is no else arm). */
+export declare function branch(label: string, predicate: (input: Json) => boolean, then: Workflow, otherwise?: Workflow): Workflow;
+/** A one-armed branch: run `then` only when the predicate holds. */
+export declare function when(label: string, predicate: (input: Json) => boolean, then: Workflow): Workflow;
+/** Fan `each` out over a runtime list, concurrently; resolve to the per-item
+ * outputs. Keep `each` deterministic — don't fan a `summon` step across a map
+ * (see issue #639). */
+export declare function map(label: string, each: Workflow, items?: (input: Json) => Json[]): Workflow;
+/** Walk the workflow, running each leaf through its `run` function and threading
+ * values according to the combinators. Returns the workflow's final output. */
+export declare function execute(wf: Workflow, input: Json, ctx: StepContext): Promise<Json>;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC;AAE3B;+CAC+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,GAAG,EAAE;QACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC7D,CAAC;IACF;;;yDAGqD;IACrD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,8EAA8E;AAC9E,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7E,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC1C;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,OAAO,CAAC;IACpC,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,QAAQ,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,EAAE,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAIpF;;;oEAGoE;AACpE,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAEzD;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAEvD;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAE1D;AAED;yDACyD;AACzD,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,OAAO,EACnC,IAAI,EAAE,QAAQ,EACd,SAAS,CAAC,EAAE,QAAQ,GACnB,QAAQ,CAEV;AAED,oEAAoE;AACpE,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAEjG;AAED;;uBAEuB;AACvB,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,EAAE,GAAG,QAAQ,CAE5F;AA4BD;+EAC+E;AAC/E,wBAAsB,OAAO,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBxF"}

package/dist/workflow.js

@@ -0,0 +1,88 @@
+// The workflow combinator eDSL and its interpreter.
+//
+// A workflow is a *description* — a tree of combinators — not a procedure.
+// `execute` walks the tree, running each leaf and threading values between them.
+//
+// A leaf is a `step`: plain author-written code. A step transforms the value
+// flowing in and may reach any registered action — `send_message`, a connector
+// call, or `summon` (hand off to an LLM agent) — through `ctx.runAction`.
+// Control flow — sequencing, concurrency, conditionals, fan-out — lives in the
+// combinators, never in host `if`/`for`, so the structure stays explicit.
+//
+// This engine ships in the published SDK so every workflow app shares one copy:
+// a generated app contributes only its `buildWorkflow()` definition and imports
+// these combinators, rather than carrying its own interpreter.
+// --- constructors -----------------------------------------------------------
+/** A leaf: author-written code. Transform the input and/or call actions via
+ * `ctx.runAction(name, args)` — including `ctx.runAction("summon", …)` to hand
+ * the step to an LLM agent when it needs judgment. Keep `summon` to a single
+ * step; don't fan it across a `map`/`parallel` (see issue #639). */
+export function step(label, run) {
+    return { kind: "step", label, run };
+}
+/** Run steps in order, threading each step's output into the next step's input. */
+export function pipeline(...steps) {
+    return { kind: "pipeline", steps };
+}
+/** Run branches concurrently on the same input; resolve to the array of outputs. */
+export function parallel(...branches) {
+    return { kind: "parallel", branches };
+}
+/** Run `then` when the predicate holds; otherwise run `otherwise` (or pass the
+ * input through unchanged when there is no else arm). */
+export function branch(label, predicate, then, otherwise) {
+    return { kind: "branch", label, predicate, then, otherwise };
+}
+/** A one-armed branch: run `then` only when the predicate holds. */
+export function when(label, predicate, then) {
+    return branch(label, predicate, then);
+}
+/** Fan `each` out over a runtime list, concurrently; resolve to the per-item
+ * outputs. Keep `each` deterministic — don't fan a `summon` step across a map
+ * (see issue #639). */
+export function map(label, each, items) {
+    return { kind: "map", label, each, items };
+}
+// --- interpreter ------------------------------------------------------------
+const asArray = (v) => (Array.isArray(v) ? v : []);
+/** Run concurrent branches like `Promise.all`, but wait for *every* branch to
+ * settle before reporting failure. `Promise.all` rejects on the first failure
+ * while the other branches keep running — and because steps may call
+ * side-effecting actions (`send_message`, connector writes), that would let a
+ * failed run resolve while siblings are still mutating the world in the
+ * background, making a retry unsafe. Waiting for all branches keeps the
+ * workflow's outcome honest: on success it resolves to the per-branch outputs
+ * in order; on any failure it throws once nothing is still in flight. */
+async function runConcurrent(branches, context) {
+    const settled = await Promise.allSettled(branches);
+    const failures = settled.filter((r) => r.status === "rejected");
+    if (failures.length > 0) {
+        throw new AggregateError(failures.map((f) => f.reason), `${context}: ${failures.length}/${settled.length} branch(es) failed`);
+    }
+    return settled.map((r) => r.value);
+}
+/** Walk the workflow, running each leaf through its `run` function and threading
+ * values according to the combinators. Returns the workflow's final output. */
+export async function execute(wf, input, ctx) {
+    switch (wf.kind) {
+        case "step":
+            return await wf.run(input, ctx);
+        case "pipeline": {
+            let value = input;
+            for (const s of wf.steps)
+                value = await execute(s, value, ctx);
+            return value;
+        }
+        case "parallel":
+            return runConcurrent(wf.branches.map((b) => execute(b, input, ctx)), "parallel");
+        case "branch":
+            if (wf.predicate(input))
+                return execute(wf.then, input, ctx);
+            return wf.otherwise ? execute(wf.otherwise, input, ctx) : input;
+        case "map": {
+            const items = wf.items ? wf.items(input) : asArray(input);
+            return runConcurrent(items.map((it) => execute(wf.each, it, ctx)), `map "${wf.label}"`);
+        }
+    }
+}
+//# sourceMappingURL=workflow.js.map

package/dist/workflow.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rome-os/app-runtime",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,6 +9,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
     "./tsconfig.app.json": "./tsconfig.app.json"
   },
   "files": [
@@ -18,11 +22,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc",
-    "prepare": "tsc",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "drizzle-orm": "^0.45.1",
     "ws": "^8.18.0",
@@ -33,5 +32,9 @@
     "@opentelemetry/sdk-trace-base": "^2.5.1",
     "@types/ws": "^8.18.0",
     "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
   }
-}
+}