@ironflow/browser 0.19.2 → 0.20.0

package/dist/agents/subscribe.js

@@ -0,0 +1,117 @@
+/**
+ * `ironflow.agents.subscribe()` — typed wrapper over `client.subscribe()`
+ * for an agent run's event stream.
+ *
+ * Spec: see ./spec.md
+ */
+import { ValidationError, } from "@ironflow/core";
+const MAX_RUN_ID_LENGTH = 128;
+// Permits server-issued runIds (e.g., `run_<uuid>`, `run-2025-...`) but
+// rejects NATS subject metacharacters that would widen the subscribe to
+// other runs (`*`, `>`, `.`) or break the topic shape.
+const RUN_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+function validateRunId(runId) {
+    if (typeof runId !== "string" || runId.length === 0) {
+        throw new ValidationError("agents.subscribe: runId must be a non-empty string");
+    }
+    if (runId.length > MAX_RUN_ID_LENGTH) {
+        throw new ValidationError(`agents.subscribe: runId exceeds ${MAX_RUN_ID_LENGTH} chars`);
+    }
+    if (!RUN_ID_PATTERN.test(runId)) {
+        throw new ValidationError("agents.subscribe: runId may only contain [A-Za-z0-9_-] (no NATS metacharacters)");
+    }
+}
+/**
+ * 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 async function subscribe(client, runId, callbacks, opts = {}) {
+    validateRunId(runId);
+    const sub = await client.subscribe(`system.run.${runId}.>`, {
+        // Default replay 1000 covers events emitted between `agents.invoke`
+        // returning a runId via `onRunStarted` and this subscribe attaching.
+        replay: opts.replay ?? 1000,
+        onEvent: (event) => dispatch(event, runId, callbacks),
+        onError: callbacks.onError,
+    });
+    // Wrap the underlying unsubscribe to make it idempotent.
+    let unsubscribed = false;
+    const wrapped = {
+        id: sub.id ?? "",
+        pattern: sub.pattern ?? `system.run.${runId}.>`,
+        connectionState: sub.connectionState ?? "connected",
+        unsubscribe() {
+            if (unsubscribed)
+                return;
+            unsubscribed = true;
+            try {
+                sub.unsubscribe();
+            }
+            catch {
+                /* swallow — idempotent */
+            }
+        },
+    };
+    return wrapped;
+}
+function dispatch(event, runId, callbacks) {
+    const topic = event.topic;
+    const stepPrefix = `system.run.${runId}.step.`;
+    if (topic.startsWith(stepPrefix)) {
+        if (!callbacks.onStep)
+            return;
+        const remainder = topic.slice(stepPrefix.length); // "{stepId}.{type}"
+        const dotIdx = remainder.indexOf(".");
+        const stepId = dotIdx === -1 ? remainder : remainder.slice(0, dotIdx);
+        const type = dotIdx === -1 ? "" : remainder.slice(dotIdx + 1);
+        const stepEvent = {
+            topic,
+            stepId,
+            type,
+            data: event.data,
+        };
+        callbacks.onStep(stepEvent);
+        return;
+    }
+    if (topic.endsWith(".completed")) {
+        callbacks.onComplete?.({ output: event.data?.output });
+        return;
+    }
+    if (topic.endsWith(".failed")) {
+        const err = event.data?.error;
+        if (typeof err === "string") {
+            callbacks.onFailed?.({ message: err });
+        }
+        else if (err && typeof err === "object") {
+            callbacks.onFailed?.({
+                message: err.message ?? "Run failed",
+                code: err.code,
+            });
+        }
+        else {
+            callbacks.onFailed?.({ message: "Run failed" });
+        }
+        return;
+    }
+    if (topic.endsWith(".cancelled")) {
+        callbacks.onCancelled?.();
+        return;
+    }
+    // Non-terminal: created / updated / resumed.
+    if (callbacks.onProgress) {
+        const progressEvent = {
+            topic,
+            status: event.data?.status,
+            data: event.data,
+        };
+        callbacks.onProgress(progressEvent);
+    }
+}
+//# sourceMappingURL=subscribe.js.map

package/dist/agents/subscribe.js.map

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

package/dist/agents/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Public types for `ironflow.agents.{invoke, subscribe, readMemory}`.
+ *
+ * Spec: see ./spec.md
+ */
+import type { InvokeResult, ProjectionStateResult, Run, Subscription, SubscriptionCallbacks, SubscriptionErrorInfo, WaitResult } from "@ironflow/core";
+/**
+ * Options for `ironflow.agents.invoke()`.
+ */
+export interface AgentInvokeOptions {
+    /**
+     * Local timeout in milliseconds. When elapsed, throws
+     * `AgentInvokeTimeoutError` and best-effort calls
+     * `cancelRun(runId)` server-side. Default: 30000.
+     */
+    timeoutMs?: number;
+    /**
+     * Caller cancellation. When the signal aborts, throws an `AbortError`
+     * (DOMException) and best-effort calls `cancelRun(runId)`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Server-side dedup. Same key → same `runId` returned across retries.
+     * Wires to existing event-idempotency path.
+     */
+    idempotencyKey?: string;
+    /**
+     * Number of historical events to replay on subscribe. Default: 100.
+     * Replay covers the race window between Trigger return and subscribe attach.
+     */
+    replay?: number;
+    /**
+     * Called once with the runId as soon as `Trigger` returns and before
+     * the wait begins. Lets callers attach a separate progress subscription
+     * (e.g., `agents.subscribe(runId)`) without waiting for the terminal
+     * event. May return a Promise; the SDK awaits it so any async setup
+     * (subscription attach) completes before terminal events dispatch.
+     */
+    onRunStarted?: (runId: string) => void | Promise<void>;
+}
+/**
+ * Result returned from a successful `ironflow.agents.invoke()`.
+ */
+export interface AgentInvokeResult<TOutput = unknown> {
+    runId: string;
+    output: TOutput | undefined;
+    durationMs: number;
+}
+/**
+ * Callbacks for `ironflow.agents.subscribe()`.
+ */
+export interface AgentSubscribeCallbacks {
+    /** Non-terminal run lifecycle events (created, updated, resumed). */
+    onProgress?: (event: AgentProgressEvent) => void;
+    /** Step lifecycle events (created, completed, etc.). */
+    onStep?: (event: AgentStepEvent) => void;
+    /** Terminal `run.completed`. */
+    onComplete?: (result: {
+        output: unknown;
+    }) => void;
+    /** Terminal `run.failed`. */
+    onFailed?: (error: {
+        message: string;
+        code?: string;
+    }) => void;
+    /** Terminal `run.cancelled`. */
+    onCancelled?: () => void;
+    /** Transport / parse error. */
+    onError?: (err: SubscriptionErrorInfo) => void;
+}
+export interface AgentProgressEvent {
+    topic: string;
+    status?: string;
+    data?: unknown;
+}
+export interface AgentStepEvent {
+    topic: string;
+    stepId: string;
+    type: string;
+    data?: unknown;
+}
+/**
+ * Options for `ironflow.agents.readMemory()`.
+ */
+export interface AgentReadMemoryOptions {
+    /**
+     * Sequence number returned by an earlier `streams.append`. When set,
+     * `readMemory` calls `waitForProjectionCatchup` before reading state
+     * so the result reflects events up to and including `minSeq`
+     * (read-your-writes).
+     *
+     * If `minSeq` exceeds the projection's eventual `last_event_seq`, the
+     * catchup blocks until `timeoutMs` and throws
+     * `MemoryCatchupTimeoutError`.
+     */
+    minSeq?: number | bigint;
+    /**
+     * Catchup timeout in milliseconds. Default 30000. Ignored when
+     * `minSeq` is not provided.
+     */
+    timeoutMs?: number;
+    /**
+     * Caller cancellation. Throws an `AbortError` (DOMException) if the
+     * signal aborts before the call completes.
+     */
+    signal?: AbortSignal;
+    /**
+     * Partition key for partitioned projections. Passed through to both
+     * the catchup wait and the state read.
+     */
+    partition?: string;
+}
+/**
+ * Result returned from a successful `ironflow.agents.readMemory()`.
+ */
+export interface AgentMemoryResult<TState = unknown> {
+    /** Materialized projection state. */
+    state: TState;
+    /** Projection version. */
+    version: number;
+    /** Last event id applied to the state, if any. */
+    lastEventId?: string;
+    /**
+     * `true` when `minSeq` was honored or skipped (no `minSeq` provided).
+     * Always `true` on a successful return — the catchup throws on timeout.
+     */
+    caughtUp: boolean;
+}
+/**
+ * Minimum surface that `ironflow.agents.{invoke, subscribe, readMemory}`
+ * need from the client. Defining it as an interface lets the helpers be
+ * unit-tested with a mock client and keeps the public client surface
+ * tight.
+ */
+export interface AgentClientLike {
+    invoke<T = unknown>(functionId: string, options: {
+        data: T;
+        idempotencyKey?: string;
+    }): Promise<InvokeResult>;
+    subscribe<T = unknown>(pattern: string | string[], callbacks: SubscriptionCallbacks<T> & {
+        replay?: number;
+        includeMetadata?: boolean;
+    }): Promise<Subscription | {
+        unsubscribe(): void;
+    }>;
+    cancelRun(runId: string, reason?: string): Promise<Run>;
+    getProjection<TState = unknown>(name: string, options?: {
+        partition?: string;
+    }): Promise<ProjectionStateResult<TState>>;
+    waitForProjectionCatchup(name: string, opts: {
+        minSeq: number | bigint;
+        timeoutMs?: number;
+        partition?: string;
+    }): Promise<WaitResult>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/agents/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public types for `ironflow.agents.{invoke, subscribe, readMemory}`.
+ *
+ * Spec: see ./spec.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/client.d.ts

@@ -9,6 +9,7 @@ import type { IronflowConfig, IronflowConfigOptions } from "./config.js";
 import { type BrowserSubscribeOptions, type SubscriptionGroup } from "./subscription.js";
 import { BrowserKVClient } from "./kv.js";
 import { BrowserConfigClient } from "./config-client.js";
+import { type AgentsNamespace } from "./agents/index.js";
 /**
  * Ironflow browser client singleton
  */
@@ -18,6 +19,21 @@ declare class IronflowClient {
     private transport;
     private subscriptionManager;
     private visibilityHandler;
+    /**
+     * `agents` namespace — browser helpers for `agent()` functions.
+     *
+     * @example
+     * ```typescript
+     * const result = await ironflow.agents.invoke("my-agent", { task: "..." });
+     * console.log(result.runId, result.output);
+     *
+     * const sub = await ironflow.agents.subscribe(runId, {
+     *   onStep: (e) => console.log("step", e.stepId, e.type),
+     *   onComplete: (r) => console.log("done", r.output),
+     * });
+     * ```
+     */
+    readonly agents: AgentsNamespace;
     /**
      * Configure the client
      *
@@ -103,6 +119,11 @@ declare class IronflowClient {
      * Register a global error handler
      */
     onError(callback: (error: SubscriptionErrorInfo) => void): () => void;
+    /**
+     * Number of currently active subscriptions. Useful for leak audits and
+     * diagnostics. Returns 0 if the client is not configured.
+     */
+    getActiveSubscriptionCount(): number;
     /**
      * Invoke a workflow function by ID
      *
@@ -115,6 +136,7 @@ declare class IronflowClient {
      */
     invoke<TInput = unknown>(functionId: string, options: {
         data: TInput;
+        idempotencyKey?: string;
     }): Promise<InvokeResult>;
     /**
      * Get run status

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -3,7 +3,7 @@
  *
  * Singleton client for browser-based real-time interactions with Ironflow.
  */
-import { NotConfiguredError, IronflowError, RunFailedError, RunCancelledError, UnauthenticatedError, EnterpriseRequiredError, UnauthorizedError, ValidationError, createLogger, createNoopLogger, DEFAULT_TIMEOUTS, HEADERS, TriggerResponseSchema, TriggerSyncResponseSchema, RunResponseSchema, ListRunsResponseSchema, RunStatusSchema, ErrorResponseSchema, safeJsonParse, patterns, } from "@ironflow/core";
+import { NotConfiguredError, IronflowError, RunFailedError, RunCancelledError, UnauthenticatedError, EnterpriseRequiredError, UnauthorizedError, ValidationError, createLogger, createNoopLogger, DEFAULT_TIMEOUTS, HEADERS, TriggerResponseSchema, TriggerSyncResponseSchema, RunResponseSchema, ListRunsResponseSchema, RunStatusSchema, ErrorResponseSchema, safeJsonParse, patterns, peelProjectionEnvelope, } from "@ironflow/core";
 import { mergeConfig } from "./config.js";
 import { SubscriptionManager, } from "./subscription.js";
 import { createWebSocketTransport } from "./transport/websocket.js";
@@ -11,6 +11,7 @@ import { createConnectRPCTransport } from "./transport/connectrpc.js";
 import { filterWaitStreamFrames } from "./projection-stream.js";
 import { BrowserKVClient } from "./kv.js";
 import { BrowserConfigClient } from "./config-client.js";
+import { createAgentsNamespace } from "./agents/index.js";
 /**
  * Ironflow browser client singleton
  */
@@ -20,6 +21,27 @@ class IronflowClient {
     transport = null;
     subscriptionManager = null;
     visibilityHandler = null;
+    /**
+     * `agents` namespace — browser helpers for `agent()` functions.
+     *
+     * @example
+     * ```typescript
+     * const result = await ironflow.agents.invoke("my-agent", { task: "..." });
+     * console.log(result.runId, result.output);
+     *
+     * const sub = await ironflow.agents.subscribe(runId, {
+     *   onStep: (e) => console.log("step", e.stepId, e.type),
+     *   onComplete: (r) => console.log("done", r.output),
+     * });
+     * ```
+     */
+    agents = createAgentsNamespace({
+        invoke: (functionId, options) => this.invoke(functionId, options),
+        subscribe: (pattern, cbs) => this.subscribe(pattern, cbs),
+        cancelRun: (runId, reason) => this.cancelRun(runId, reason),
+        getProjection: (name, options) => this.getProjection(name, options),
+        waitForProjectionCatchup: (name, opts) => this.waitForProjectionCatchup(name, opts),
+    });
     /**
      * Configure the client
      *
@@ -214,6 +236,13 @@ class IronflowClient {
         this.ensureConfigured();
         return this.subscriptionManager.onError(callback);
     }
+    /**
+     * Number of currently active subscriptions. Useful for leak audits and
+     * diagnostics. Returns 0 if the client is not configured.
+     */
+    getActiveSubscriptionCount() {
+        return this.subscriptionManager?.activeSubscriptionCount ?? 0;
+    }
     // ============================================================================
     // Workflow Operations
     // ============================================================================
@@ -232,6 +261,7 @@ class IronflowClient {
         const response = await this.request(TriggerResponseSchema, "POST", "/ironflow.v1.IronflowService/Trigger", {
             event: functionId,
             data: options.data,
+            idempotency_key: options.idempotencyKey,
         });
         return {
             runIds: response.runIds ?? [],
@@ -1001,9 +1031,12 @@ class IronflowClient {
      */
     async getProjection(name, options) {
         this.ensureConfigured();
+        // Normalize empty-string partition to undefined so peel falls back to
+        // "__global__" instead of returning empty-string partition.
+        const partition = options?.partition ? options.partition : undefined;
         let url = `${this.config.serverUrl}/api/v1/projections/${encodeURIComponent(name)}`;
-        if (options?.partition) {
-            url += `?partition=${encodeURIComponent(options.partition)}`;
+        if (partition) {
+            url += `?partition=${encodeURIComponent(partition)}`;
         }
         const timeout = this.config.timeout ?? DEFAULT_TIMEOUTS.CLIENT;
         const controller = new AbortController();
@@ -1025,17 +1058,7 @@ class IronflowClient {
                 throw new IronflowError(error?.message || `Get projection failed: ${response.status}`, { code: error?.code || "GET_PROJECTION_FAILED" });
             }
             const data = await response.json();
-            return {
-                name: data.name,
-                partition: data.state?.partition_key ?? "__global__",
-                state: data.state?.state ?? {},
-                lastEventId: data.state?.last_event_id ?? "",
-                lastEventTime: data.state?.last_event_time
-                    ? new Date(data.state.last_event_time)
-                    : new Date(0),
-                version: data.state?.version ?? 0,
-                mode: data.mode,
-            };
+            return peelProjectionEnvelope(data, partition);
         }
         finally {
             clearTimeout(timeoutId);