@ironflow/browser 0.19.2 → 0.20.0

package/README.md

@@ -12,6 +12,7 @@ This is a **private npm package**. This README is the sole reference for coding
 - [Events and Subscriptions](#events-and-subscriptions)
 - [Emitting Events](#emitting-events)
 - [Workflow Operations](#workflow-operations)
+- [Agents (`ironflow.agents.*`)](#agents-ironflowagents)
 - [Entity Streams (Event Sourcing)](#entity-streams-event-sourcing)
 - [Projections](#projections)
 - [KV Store](#kv-store)
@@ -442,6 +443,101 @@ console.log(output.output);
 console.log(output.patched);  // Whether output was injected
 ```
 
+## Agents (`ironflow.agents.*`)
+
+Browser helpers for `agent()` functions. Mirror the `@ironflow/node/agent` shape so the same agent runs in browser-driven UIs and server workers without divergence.
+
+Spec: `src/agents/spec.md`. Issue #625.
+
+### `agents.invoke(name, payload, opts?)`
+
+Fire-and-wait. Triggers the agent, subscribes to its run events, resolves on the terminal `system.run.{runId}.completed` event.
+
+```typescript
+import { ironflow } from '@ironflow/browser';
+
+const result = await ironflow.agents.invoke<{ category: string }>(
+  'doc-processor',
+  { docId: 'doc-1', imageUrl: 'https://example.com/x.png' },
+  {
+    timeoutMs: 60_000,             // default 30s
+    idempotencyKey: 'click-abc',   // server-side dedup
+    signal: ac.signal,             // AbortController
+    replay: 1000,                  // default; covers the race window
+    onRunStarted: (runId) => {},   // optional: surfaces runId before terminal
+  }
+);
+console.log(result.runId, result.output, result.durationMs);
+```
+
+Errors:
+
+| Throws | When |
+|---|---|
+| `ValidationError` | empty/oversized `name` |
+| `AbortError` (DOMException) | `signal` aborts; SDK calls `cancelRun(runId)` server-side |
+| `AgentInvokeTimeoutError` | local `timeoutMs` elapsed; SDK calls `cancelRun(runId)` |
+| `NoRunCreatedError` | server returned empty `runIds` |
+| `RunFailedError` | `system.run.{runId}.failed` |
+| `RunCancelledError` | `system.run.{runId}.cancelled` |
+
+### `agents.subscribe(runId, callbacks)`
+
+Typed wrapper over the broader `subscribe(pattern)` API. Dispatches by topic.
+
+```typescript
+const sub = await ironflow.agents.subscribe(runId, {
+  onProgress: (e) => console.log('progress', e.topic, e.status),
+  onStep: (e) => console.log('step', e.stepId, e.type),
+  onComplete: (r) => console.log('done', r.output),
+  onFailed: (err) => console.warn('failed', err.message),
+  onCancelled: () => console.warn('cancelled'),
+  onError: (err) => console.error('transport', err),
+});
+
+// Unsubscribe is idempotent.
+sub.unsubscribe();
+```
+
+### `agents.readMemory(projection, opts?)`
+
+Typed read of an agent memory projection. Optional read-your-writes via `minSeq` from a prior `streams.append`.
+
+```typescript
+interface DocMemory {
+  docs: Record<string, { status: 'ocr' | 'classified' | 'published'; category?: string }>;
+}
+
+// Read current state — eventual consistency.
+const mem = await ironflow.agents.readMemory<DocMemory>('doc-processor-memory');
+console.log(mem.state.docs, mem.version);
+
+// Read-your-writes: pass the seq returned by a prior append so the
+// projection has caught up before the read.
+const { sequence } = await ironflow.streams.append('agent-memory:doc-1', {
+  name: 'DocProcessed',
+  data: { docId: 'doc-1', status: 'classified' },
+});
+const fresh = await ironflow.agents.readMemory<DocMemory>('doc-processor-memory', {
+  minSeq: sequence,
+  timeoutMs: 5_000,
+});
+```
+
+Throws `MemoryCatchupTimeoutError` if the projection cannot catch up to `minSeq` within `timeoutMs`. Throws `AbortError` on caller cancellation.
+
+### React example
+
+A complete browser-driven demo lives at `examples/agents/doc-processor-agent/web/`. It exercises `agents.invoke` + `agents.subscribe` against the doc-processor agent's crash-resume flow, and `agents.readMemory` to render per-doc state.
+
+### Server compatibility
+
+Requires Ironflow server with `waitForProjectionCatchup` (#473) and the unified Trigger path. Any server built from `main` after #608 (Lane D) supports the full surface.
+
+### Stuck or hanging?
+
+See `docs/runbooks/runbook-browser-agent-stuck.md` for triage.
+
 ## Entity Streams (Event Sourcing)
 
 Entity streams store domain events per entity with optimistic concurrency control.
@@ -540,11 +636,15 @@ const result = await ironflow.getProjection<{ totalOrders: number }>('order-stat
 
 console.log(result.name);           // 'order-stats'
 console.log(result.state);          // { totalOrders: 42 }
-console.log(result.partition);       // '__global__' or partition key
+console.log(result.partition);      // '__global__' or partition key
 console.log(result.lastEventId);    // Last processed event ID
-console.log(result.lastEventTime);  // Date
+console.log(result.lastEventTime);  // Date | undefined (undefined before first event)
+console.log(result.lastEventSeq);   // Last processed sequence number
 console.log(result.version);        // Projection version
 console.log(result.mode);           // 'managed' | 'external'
+console.log(result.status);         // 'active' | 'rebuilding' | 'paused' | 'error'
+console.log(result.errorMessage);   // Error string when status is 'error', else undefined
+console.log(result.updatedAt);      // Date
 
 // Get partitioned projection state
 const result = await ironflow.getProjection('order-stats', {
@@ -736,16 +836,18 @@ await config.delete('app-settings');
 // all reach the subscriber. Payload includes `revision`; drop events whose
 // revision is lower than the last one you applied to guard against rare
 // out-of-order deliveries under retry.
-const sub = await config.watch('app-settings', {
-  onEvent: (configResponse) => {
-    console.log('Config updated:', configResponse.data, configResponse.revision);
+const watcher = await config.watch('app-settings', {
+  onUpdate: (event) => {
+    // event: ConfigWatchEvent ({ type: "config_update", name, data, revision, updatedAt })
+    console.log('Config updated:', event.data, event.revision);
   },
   onError: (error) => {
     console.error('Watch error:', error);
   },
 });
 
-sub.unsubscribe();
+// `watcher` is a Subscription — call unsubscribe() to stop watching.
+watcher.unsubscribe();
 ```
 
 When the tab is backgrounded long enough that the browser silently kills the

package/dist/agents/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,24 @@
+/**
+ * `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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,16 @@
+/**
+ * `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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,222 @@
+/**
+ * `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

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

package/dist/agents/readMemory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,87 @@
+/**
+ * `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

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

package/dist/agents/subscribe.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `ironflow.agents.subscribe()` — typed wrapper over `client.subscribe()`
+ * for an agent run's event stream.
+ *
+ * Spec: see ./spec.md
+ */
+import { type Subscription } from "@ironflow/core";
+import type { AgentClientLike, AgentSubscribeCallbacks } from "./types.js";
+/**
+ * Promise-returning wrapper. Returns a Subscription whose `unsubscribe()`
+ * is idempotent.
+ *
+ * Topic dispatch:
+ *   system.run.{runId}.completed             → onComplete
+ *   system.run.{runId}.failed                → onFailed
+ *   system.run.{runId}.cancelled             → onCancelled
+ *   system.run.{runId}.{created|updated|resumed} → onProgress
+ *   system.run.{runId}.step.{stepId}.{type}  → onStep
+ */
+export declare function subscribe(client: AgentClientLike, runId: string, callbacks: AgentSubscribeCallbacks, opts?: {
+    replay?: number;
+}): Promise<Subscription>;
+//# sourceMappingURL=subscribe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../src/agents/subscribe.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EACV,eAAe,EAGf,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAiCpB;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,uBAAuB,EAClC,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,OAAO,CAAC,YAAY,CAAC,CAiCvB"}