@ironflow/browser 0.19.3 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ironflow/browser",
-  "version": "0.19.3",
+  "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",
-    "@ironflow/core": "^0.19.3",
-    "zod": "^4.3.5"
+    "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,24 +51,24 @@
     "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:bundle": "tsc && node scripts/bundle.mjs",
-    "dev": "tsc --watch",
-    "test": "vitest run",
+    "build": "tsc --build tsconfig.build.json",
+    "build:bundle": "tsc --build tsconfig.build.json && node scripts/bundle.mjs",
+    "dev": "tsc --build tsconfig.build.json --watch",
+    "test": "pnpm typecheck && vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/",
-    "clean": "rm -rf dist dist-bundle tsconfig.tsbuildinfo",
-    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist dist-bundle tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "pack:local": "pnpm build:bundle && cd dist-bundle && pnpm pack --pack-destination /tmp/ironflow-packs"
   }
 }