@ironflow/browser 0.20.0 → 0.20.2

package/LICENSE

@@ -0,0 +1,181 @@
+# Ironflow License
+
+**Version 1.0 — 2026-05-08**
+
+This file contains the binding legal terms under which Ironflow is offered.
+A plain-English summary lives at `docs/explanation/licensing.md`. If the two
+disagree, this file controls.
+
+> **Lawyer review status:** v1 DIY-substitute. Pending counsel review before
+> the first paid customer ships (issue #777). All of the following MUST be
+> resolved before this license is published on the public release mirror:
+>
+>   - `[LICENSOR_ENTITY]` placeholder filled with the legal entity name
+>   - `[LICENSE_EMAIL]` placeholder filled with the commercial-licensing
+>     contact address
+>   - "Personal-Use and Evaluation Carve-Out" section reviewed by counsel —
+>     this is supplemental to the FSL Permitted Purpose and was added to
+>     match the worked examples in `docs/explanation/licensing.md` per the
+>     plan body. JetBrains Toolbox + Postman free-tier EULAs were the
+>     reference for the carve-out shape, but the wording is original prose
+>     and has not been counsel-reviewed.
+>   - "Governing Law and Venue" + "Commercial Licensing" sections reviewed
+>     by counsel — these are original prose, not part of the FSL template.
+>
+> **Versioning:** revised terms apply on next install. Each release ships
+> the LICENSE that was effective at the time the artifact was built.
+> Continuing to use a previously installed version under its prior terms
+> is permitted; upgrading to a newer release accepts the LICENSE shipped
+> with that release.
+
+---
+
+## Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 [LICENSOR_ENTITY]
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+---
+
+## Personal-Use and Evaluation Carve-Out
+
+> _Supplemental to the FSL Permitted Purpose above. Pending counsel review._
+
+The following uses are explicitly permitted in addition to the FSL Permitted
+Purposes listed above:
+
+1. **Personal use.** Use of the Software by a natural person for that
+   person's personal, non-commercial purposes — including hobby projects,
+   self-education, and side projects that do not generate revenue or
+   commercial advantage.
+
+2. **Evaluation.** Use of the Software by any individual or organization for
+   the purpose of evaluating the Software prior to a commercial purchase
+   decision, for a period of up to ninety (90) days from first install.
+   Evaluation use does not require notification.
+
+These carve-outs are non-transferable and do not extend to redistribution,
+sublicensing, or any Competing Use as defined in the FSL Permitted Purpose
+section.
+
+---
+
+## Governing Law and Venue
+
+These Terms and Conditions are governed by the laws of the State of Delaware,
+United States of America, without regard to its conflict-of-laws provisions.
+Any dispute arising out of or relating to these Terms and Conditions shall be
+brought exclusively in the state or federal courts located in Delaware, and
+you consent to the personal jurisdiction of those courts.
+
+## Commercial Licensing
+
+For uses that fall outside the Permitted Purpose — including any Competing
+Use, or any commercial use case for which a separate paid license is required
+under our Cloud or Enterprise terms — contact `[LICENSE_EMAIL]` to discuss
+a commercial license.
+
+## SPDX Identifier
+
+`LicenseRef-Ironflow-EULA`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ironflow/browser",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "description": "Browser client for Ironflow event-driven backend platform - real-time subscriptions, workflow triggers, and event emission",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,16 +18,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@bufbuild/protobuf": "^2.5.1",
+    "@bufbuild/protobuf": "^2.12.0",
     "@connectrpc/connect": "^2.1.1",
     "@connectrpc/connect-web": "^2.1.1",
-    "zod": "^4.3.5",
-    "@ironflow/core": "^0.20.0"
+    "zod": "^4.4.3",
+    "@ironflow/core": "^0.20.2"
   },
   "devDependencies": {
-    "@types/node": "^22.14.0",
-    "esbuild": "^0.27.2",
-    "jsdom": "^26.0.0",
+    "@types/node": "^22.19.18",
+    "esbuild": "^0.27.7",
+    "jsdom": "^26.1.0",
     "typescript": "^5.9.3",
     "vitest": "^2.1.9"
   },
@@ -51,14 +51,14 @@
     "subscriptions"
   ],
   "author": "Ironflow",
-  "license": "MIT",
+  "license": "LicenseRef-Ironflow-EULA",
   "repository": {
     "type": "git",
     "url": "https://github.com/ironflowapp/ironflow.git",
     "directory": "sdk/js/browser"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "scripts": {
     "build": "tsc --build tsconfig.build.json",

package/dist/agents/index.d.ts

@@ -1,34 +0,0 @@
-/**
- * `ironflow.agents` namespace.
- *
- * Browser-facing helpers for `agent()` functions: fire-and-wait `invoke`,
- * typed `subscribe` for run/step events, and `readMemory` for typed
- * projection state reads.
- *
- * Spec: ./spec.md
- */
-import type { Subscription } from "@ironflow/core";
-import type { AgentClientLike, AgentInvokeOptions, AgentInvokeResult, AgentMemoryResult, AgentReadMemoryOptions, AgentSubscribeCallbacks } from "./types.js";
-export type { AgentClientLike, AgentInvokeOptions, AgentInvokeResult, AgentMemoryResult, AgentProgressEvent, AgentReadMemoryOptions, AgentStepEvent, AgentSubscribeCallbacks, } from "./types.js";
-/**
- * The shape exposed as `ironflow.agents`.
- */
-export interface AgentSubscribeRuntimeOptions {
-    /**
-     * Number of historical events to replay on attach. Default: 1000.
-     * Covers events emitted between `agents.invoke()` returning a runId
-     * via `onRunStarted` and this subscribe attaching.
-     */
-    replay?: number;
-}
-export interface AgentsNamespace {
-    invoke<TOutput = unknown>(name: string, payload: unknown, opts?: AgentInvokeOptions): Promise<AgentInvokeResult<TOutput>>;
-    subscribe(runId: string, callbacks: AgentSubscribeCallbacks, opts?: AgentSubscribeRuntimeOptions): Promise<Subscription>;
-    readMemory<TState = unknown>(projection: string, opts?: AgentReadMemoryOptions): Promise<AgentMemoryResult<TState>>;
-}
-/**
- * Build the `agents` namespace bound to a specific client. Called by
- * the IronflowClient constructor.
- */
-export declare function createAgentsNamespace(client: AgentClientLike): AgentsNamespace;
-//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAInD,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,OAAO,GAAG,OAAO,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IAEvC,SAAS,CACP,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,uBAAuB,EAClC,IAAI,CAAC,EAAE,4BAA4B,GAClC,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB,UAAU,CAAC,MAAM,GAAG,OAAO,EACzB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,sBAAsB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,GACtB,eAAe,CAOjB"}

package/dist/agents/index.js

@@ -1,24 +0,0 @@
-/**
- * `ironflow.agents` namespace.
- *
- * Browser-facing helpers for `agent()` functions: fire-and-wait `invoke`,
- * typed `subscribe` for run/step events, and `readMemory` for typed
- * projection state reads.
- *
- * Spec: ./spec.md
- */
-import { invoke as agentInvoke } from "./invoke.js";
-import { readMemory as agentReadMemory } from "./readMemory.js";
-import { subscribe as agentSubscribe } from "./subscribe.js";
-/**
- * Build the `agents` namespace bound to a specific client. Called by
- * the IronflowClient constructor.
- */
-export function createAgentsNamespace(client) {
-    return {
-        invoke: (name, payload, opts) => agentInvoke(client, name, payload, opts),
-        subscribe: (runId, callbacks, opts) => agentSubscribe(client, runId, callbacks, opts),
-        readMemory: (projection, opts) => agentReadMemory(client, projection, opts),
-    };
-}
-//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,UAAU,IAAI,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,SAAS,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAoD7D;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAuB;IAEvB,OAAO;QACL,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC;QACzE,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CACpC,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC;QAChD,UAAU,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC;KAC5E,CAAC;AACJ,CAAC"}

package/dist/agents/invoke.d.ts

@@ -1,16 +0,0 @@
-/**
- * `ironflow.agents.invoke()` — fire-and-wait against an agent function.
- *
- * Composes the existing async `client.invoke()` + `client.subscribe()` to
- * deliver a single Promise<{runId, output, durationMs}>.
- *
- * Race window between Trigger return and subscribe attach is covered by
- * `subscribe({replay})` — see ./spec.md.
- */
-import type { AgentClientLike, AgentInvokeOptions, AgentInvokeResult } from "./types.js";
-/**
- * Fire-and-wait: trigger the named agent function, subscribe to its run
- * events, and resolve when a terminal event arrives.
- */
-export declare function invoke<TOutput = unknown>(client: AgentClientLike, name: string, payload: unknown, opts?: AgentInvokeOptions): Promise<AgentInvokeResult<TOutput>>;
-//# sourceMappingURL=invoke.d.ts.map

package/dist/agents/invoke.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/agents/invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAsEpB;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAG,OAAO,EAC5C,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAiKrC"}

package/dist/agents/invoke.js

@@ -1,222 +0,0 @@
-/**
- * `ironflow.agents.invoke()` — fire-and-wait against an agent function.
- *
- * Composes the existing async `client.invoke()` + `client.subscribe()` to
- * deliver a single Promise<{runId, output, durationMs}>.
- *
- * Race window between Trigger return and subscribe attach is covered by
- * `subscribe({replay})` — see ./spec.md.
- */
-import { AgentInvokeTimeoutError, NoRunCreatedError, RunCancelledError, RunFailedError, ValidationError, } from "@ironflow/core";
-const DEFAULT_TIMEOUT_MS = 30_000;
-// Match the server-side `ReplayMaxEvents` default (1000). Replay-from-zero
-// against a per-run subject is bounded by the run's own emission rate, so
-// 1000 covers ~500 steps (each emits `created`+`completed`) plus run
-// lifecycle events. Step-heavier agents should raise both this option and
-// the server's `ReplayMaxEvents` config.
-const DEFAULT_REPLAY = 1000;
-const MAX_NAME_LENGTH = 256;
-// Defense-in-depth: even though the server is the source of `runId`, we
-// guard against a misbehaving server or mock returning NATS metacharacters
-// (`*`, `>`, `.`) that would widen the subscribe pattern.
-const RUN_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
-/**
- * Validate the function name argument. Server validates the rest; we just
- * catch the obviously broken cases client-side to fail fast.
- */
-function validateName(name) {
-    if (typeof name !== "string" || name.length === 0) {
-        throw new ValidationError("agents.invoke: name must be a non-empty string");
-    }
-    if (name.length > MAX_NAME_LENGTH) {
-        throw new ValidationError(`agents.invoke: name exceeds ${MAX_NAME_LENGTH} chars`);
-    }
-}
-/**
- * Extract terminal-event verdict from a topic suffix. Returns null for
- * non-terminal events.
- *
- * Topics: `system.run.{runId}.{event}` where event ∈
- *   { created, updated, resumed, completed, failed, cancelled }.
- * Step events live under `.step.{stepId}.{type}`.
- */
-function classifyTerminal(topic) {
-    if (topic.includes(".step."))
-        return null;
-    if (topic.endsWith(".completed"))
-        return "completed";
-    if (topic.endsWith(".failed"))
-        return "failed";
-    if (topic.endsWith(".cancelled"))
-        return "cancelled";
-    return null;
-}
-function extractError(data) {
-    if (data && typeof data === "object" && "error" in data) {
-        const err = data.error;
-        if (typeof err === "string") {
-            return { message: err };
-        }
-        if (err && typeof err === "object") {
-            return {
-                message: err.message ?? "Run failed",
-                code: err.code,
-            };
-        }
-    }
-    return { message: "Run failed" };
-}
-/**
- * Fire-and-wait: trigger the named agent function, subscribe to its run
- * events, and resolve when a terminal event arrives.
- */
-export async function invoke(client, name, payload, opts = {}) {
-    validateName(name);
-    // Pre-flight abort: throw before any network I/O.
-    if (opts.signal?.aborted) {
-        throw new DOMException("Aborted", "AbortError");
-    }
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const replay = opts.replay ?? DEFAULT_REPLAY;
-    const startedAt = Date.now();
-    // 1) Trigger the agent. Server returns runId.
-    const triggerResult = await client.invoke(name, {
-        data: payload,
-        idempotencyKey: opts.idempotencyKey,
-    });
-    const runId = triggerResult.runIds?.[0];
-    if (!runId) {
-        throw new NoRunCreatedError(name);
-    }
-    // Defense-in-depth: server is the source of truth, but reject obviously
-    // malformed runIds before interpolating them into a NATS subject.
-    if (!RUN_ID_PATTERN.test(runId)) {
-        throw new ValidationError(`agents.invoke: server returned invalid runId "${runId}" (must match ${RUN_ID_PATTERN})`);
-    }
-    // Single deferred. resolve/reject from subscribe callback, timeout, or abort.
-    let settled = false;
-    let resolveOuter = () => { };
-    let rejectOuter = () => { };
-    const settle = (fn) => {
-        if (settled)
-            return;
-        settled = true;
-        fn();
-    };
-    const outer = new Promise((res, rej) => {
-        resolveOuter = res;
-        rejectOuter = rej;
-    });
-    // Attach a no-op handler eagerly so a fast settle() (e.g., synchronous
-    // timer or pre-subscribe abort) does not surface as an unhandled
-    // rejection before the awaiter below attaches. The original `outer`
-    // promise is unchanged and will still reject through `await outer`.
-    outer.catch(() => {
-        /* observed; real consumer is `await outer` below */
-    });
-    // Arm timeout + abort BEFORE running the user-provided onRunStarted hook
-    // so a hanging hook cannot bypass `timeoutMs` / `signal`.
-    const timeoutHandle = setTimeout(() => {
-        settle(() => rejectOuter(new AgentInvokeTimeoutError(runId, timeoutMs)));
-    }, timeoutMs);
-    const abortHandler = () => {
-        settle(() => rejectOuter(new DOMException("Aborted", "AbortError")));
-    };
-    opts.signal?.addEventListener("abort", abortHandler, { once: true });
-    // Surface runId immediately so callers can attach a separate progress
-    // subscription via agents.subscribe(runId) without waiting for terminal.
-    // We await onRunStarted so the caller's async hook (e.g., attaching a
-    // watcher) completes before the SDK starts dispatching terminal events,
-    // preventing late events from leaking into a subsequent run's UI. The
-    // hook is bounded by the timeout/abort armed above.
-    if (opts.onRunStarted && !settled) {
-        try {
-            await opts.onRunStarted(runId);
-        }
-        catch {
-            /* swallow — caller's bug is not ours */
-        }
-    }
-    // Subscribe and wire dispatch. Race the attach against the deferred so
-    // a hung subscribe call cannot wedge the invoke past `timeoutMs`/abort.
-    let unsubscribe;
-    const subscribePromise = client
-        .subscribe(`system.run.${runId}.>`, {
-        replay,
-        onEvent: (event) => {
-            if (settled)
-                return;
-            const verdict = classifyTerminal(event.topic);
-            if (!verdict)
-                return;
-            if (verdict === "completed") {
-                const output = event.data?.output;
-                settle(() => resolveOuter({
-                    runId,
-                    output,
-                    durationMs: Date.now() - startedAt,
-                }));
-                return;
-            }
-            if (verdict === "failed") {
-                const err = extractError(event.data);
-                settle(() => rejectOuter(new RunFailedError(runId, event.data, err.message)));
-                return;
-            }
-            settle(() => rejectOuter(new RunCancelledError(runId)));
-        },
-        onError: (subErr) => {
-            settle(() => rejectOuter(new Error(`agents.invoke subscription error: ${subErr.message}`)));
-        },
-    })
-        .then((sub) => {
-        unsubscribe = () => {
-            try {
-                sub.unsubscribe();
-            }
-            catch {
-                /* idempotent */
-            }
-        };
-        // Race already settled before subscribe attached: clean up now.
-        if (settled)
-            unsubscribe();
-    })
-        .catch((err) => {
-        settle(() => rejectOuter(err));
-    });
-    // Don't block on subscribePromise; the outer race continues to fire on
-    // timeout/abort even if the attach never resolves.
-    void subscribePromise;
-    try {
-        return await outer;
-    }
-    catch (err) {
-        // Property check on `name` instead of `instanceof DOMException` for
-        // cross-runtime compatibility (some test runners and older Node
-        // builds don't share a DOMException prototype).
-        const isAbort = typeof err === "object" &&
-            err !== null &&
-            "name" in err &&
-            err.name === "AbortError";
-        if (err instanceof AgentInvokeTimeoutError || isAbort) {
-            // Fire-and-forget: do NOT await the cancel. A hanging cancelRun
-            // would block propagation of the original timeout/abort error to
-            // the caller. The unhandled-rejection guard preserves error
-            // observability without blocking.
-            void client
-                .cancelRun(runId, "agents.invoke aborted")
-                .catch(() => {
-                /* swallow — best-effort */
-            });
-        }
-        throw err;
-    }
-    finally {
-        clearTimeout(timeoutHandle);
-        opts.signal?.removeEventListener("abort", abortHandler);
-        if (unsubscribe)
-            unsubscribe();
-    }
-}
-//# sourceMappingURL=invoke.js.map

package/dist/agents/invoke.js.map

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

package/dist/agents/readMemory.d.ts

@@ -1,18 +0,0 @@
-/**
- * `ironflow.agents.readMemory()` — typed read of an agent memory
- * projection with optional read-your-writes catchup.
- *
- * Composes `client.waitForProjectionCatchup` (when `opts.minSeq` is set)
- * + `client.getProjection`. See ./spec.md.
- */
-import type { AgentClientLike, AgentMemoryResult, AgentReadMemoryOptions } from "./types.js";
-/**
- * Read materialized projection state for an agent memory.
- *
- * When `opts.minSeq` is provided, waits for the projection to catch up
- * before reading. This delivers read-your-writes semantics for callers
- * that just appended an event (use the seq returned from
- * `streams.append`).
- */
-export declare function readMemory<TState = unknown>(client: AgentClientLike, projection: string, opts?: AgentReadMemoryOptions): Promise<AgentMemoryResult<TState>>;
-//# sourceMappingURL=readMemory.d.ts.map

package/dist/agents/readMemory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"readMemory.d.ts","sourceRoot":"","sources":["../../src/agents/readMemory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAsDpB;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,MAAM,GAAG,OAAO,EAC/C,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CA4CpC"}

package/dist/agents/readMemory.js

@@ -1,87 +0,0 @@
-/**
- * `ironflow.agents.readMemory()` — typed read of an agent memory
- * projection with optional read-your-writes catchup.
- *
- * Composes `client.waitForProjectionCatchup` (when `opts.minSeq` is set)
- * + `client.getProjection`. See ./spec.md.
- */
-import { MemoryCatchupTimeoutError, ValidationError, } from "@ironflow/core";
-const DEFAULT_TIMEOUT_MS = 30_000;
-const MAX_NAME_LENGTH = 256;
-function validateProjection(name) {
-    if (typeof name !== "string" || name.length === 0) {
-        throw new ValidationError("agents.readMemory: projection must be a non-empty string");
-    }
-    if (name.length > MAX_NAME_LENGTH) {
-        throw new ValidationError(`agents.readMemory: projection exceeds ${MAX_NAME_LENGTH} chars`);
-    }
-}
-function throwIfAborted(signal) {
-    if (signal?.aborted) {
-        throw new DOMException("Aborted", "AbortError");
-    }
-}
-/**
- * Race a Promise against a caller-supplied AbortSignal. Resolves with
- * the original promise unless the signal aborts first, in which case
- * an AbortError is thrown. The original promise is left to settle in
- * the background — its result is discarded.
- */
-function raceAbort(p, signal) {
-    if (!signal)
-        return p;
-    return new Promise((resolve, reject) => {
-        const onAbort = () => {
-            reject(new DOMException("Aborted", "AbortError"));
-        };
-        if (signal.aborted) {
-            onAbort();
-            return;
-        }
-        signal.addEventListener("abort", onAbort, { once: true });
-        p.then((v) => {
-            signal.removeEventListener("abort", onAbort);
-            resolve(v);
-        }, (err) => {
-            signal.removeEventListener("abort", onAbort);
-            reject(err);
-        });
-    });
-}
-/**
- * Read materialized projection state for an agent memory.
- *
- * When `opts.minSeq` is provided, waits for the projection to catch up
- * before reading. This delivers read-your-writes semantics for callers
- * that just appended an event (use the seq returned from
- * `streams.append`).
- */
-export async function readMemory(client, projection, opts = {}) {
-    validateProjection(projection);
-    throwIfAborted(opts.signal);
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    // Treat `minSeq=0` / `0n` as "no catchup required" per the spec —
-    // saves a no-op round trip when callers default the param.
-    const minSeqProvided = opts.minSeq !== undefined && opts.minSeq !== 0 && opts.minSeq !== 0n;
-    if (minSeqProvided) {
-        const waitResult = await raceAbort(client.waitForProjectionCatchup(projection, {
-            minSeq: opts.minSeq,
-            timeoutMs,
-            partition: opts.partition,
-        }), opts.signal);
-        if (waitResult.timedOut) {
-            throw new MemoryCatchupTimeoutError(projection, BigInt(opts.minSeq), timeoutMs);
-        }
-    }
-    throwIfAborted(opts.signal);
-    const stateResult = await raceAbort(client.getProjection(projection, {
-        partition: opts.partition,
-    }), opts.signal);
-    return {
-        state: stateResult.state,
-        version: stateResult.version,
-        lastEventId: stateResult.lastEventId || undefined,
-        caughtUp: true,
-    };
-}
-//# sourceMappingURL=readMemory.js.map

package/dist/agents/readMemory.js.map

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