Browser & Webview Runtimes

The Agent module runs anywhere JavaScript runs — browsers, Electron renderers, Tauri webviews, and React Native — because its import graph has no Node.js builtins. praisonai-ts stays loadable in a mobile / browser webview from a dedicated entry point, and CI fails any pull request that breaks it.

Quick Start

Create an agent (runs identically in Node and a browser)

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: "You are a helpful assistant",
  apiKey: process?.env?.OPENAI_API_KEY ?? window.__OPENAI_KEY,
});

const reply = await agent.chat("Hello from anywhere!");
console.log(reply);
console.log(agent.getRunId()); // RFC-4122 v4 UUID from WebCrypto

Import from the mobile entry (webview bundles)

import { Agent } from 'praisonai/mobile';

const agent = new Agent({ instructions: "You are a helpful assistant" });
const response = await agent.chat("Hello from a webview!");
console.log(response);

Install

npm install praisonai

Import from praisonai/mobile in a webview bundle — the package root (praisonai) re-exports the CLI, the MCP server, and the tool registry, which are not webview-safe by design.

How It Works

A static Node-builtin import (e.g. import { readFile } from 'fs') is evaluated the moment a module loads, so in a webview it kills the whole bundle at import time — before any code runs, with no error boundary and a blank screen. CI bundles the mobile entry for the browser and fails if any forbidden builtin is imported statically.

CI now runs npm run build before the gate, so the gate sees the compiled dist/esm/… artifacts too, not just the TypeScript sources. This closes a historic hole where the gate reported OK on an input that was not what actually shipped.

The Agent constructs the same way in every runtime — credentials are read at call time, and random IDs come from WebCrypto.

Webview support contract

praisonai-ts is guaranteed by CI to remain loadable in a mobile / browser webview from one dedicated entry point.

Which entry is safe

Two entries are verified by CI to have no static Node-builtin imports: the mobile entry (praisonai/mobile) and the deep agent entry (praisonai/agent/simple). Use praisonai/mobile — it is the curated allowlist of everything that runs in a browser.

// ✅ webview-safe (guaranteed by CI)
import { Agent } from 'praisonai/mobile';

// ✅ also verified by CI (deep agent entry)
import { Agent } from 'praisonai/agent/simple';

// ❌ pulls in CLI + MCP + tool registry; not for mobile
import { Agent } from 'praisonai';

The mobile entry also re-exports randomUUID and getEnv, browser-safe replacements for the Node originals you would otherwise reach for.

Supported browsers

CI builds for safari16 and chrome108. These are the floors — newer runtimes are fine.

Runtime	Baseline	Why
iOS WKWebView	Safari 16+	iOS ships WKWebView with the OS; the floor is the oldest iOS worth supporting.
Android WebView	Chrome 108+	Matches the equivalent Android WebView era.
Desktop Chrome / Edge	Chrome 108+	Same target.
Desktop Safari	Safari 16+	Same target.
Electron renderer	Chromium ≥ 108 (Electron ≥ 22)	Ships its own Chromium; anything ≥ 108 works.
Tauri	WebView2 (Windows) / WKWebView (macOS) / WebKitGTK (Linux)	Bound by the host OS’s webview; Safari 16 / Chrome 108 is the floor.
React Native	—	Not a webview, but the same import-time constraints apply.

Targeting an older webview (e.g. iOS 15) is outside the supported baseline. Don’t file a load bug for a runtime below the floor.

What CI guarantees absent from your bundle

The Agent graph is guaranteed to have no static import of any of these Node builtins.

Forbidden Node builtins (static imports)

assert, buffer, child_process, cluster, crypto, dgram, dns, events, fs, http, http2, https, module, net, os, path, perf_hooks, process, querystring, readline, repl, stream, string_decoder, timers, tls, tty, url, util, v8, vm, worker_threads, zlib.

Static vs dynamic — the carve-out

A static import { x } from 'fs' kills a webview bundle at import time — that is what the gate blocks. A dynamic await import('readline') inside a function only fails if that function is called. readline is reached only from the CLI approval prompt, which a phone never calls, so it is allowed. Build your own path that calls it in a webview and that is on you — the gate cannot see it.

Which import to use

Reproducing the check locally

cd src/praisonai-ts
npm install --legacy-peer-deps
npm run build
npm run check:webview

Run npm run build first so the gate checks what ships (dist/esm/…), not just the sources. Expected output:

OK   src/mobile.ts               loadable in a webview
OK   src/agent/simple.ts         loadable in a webview
OK   dist/esm/mobile.js          loadable in a webview
OK   dist/esm/agent/simple.js    loadable in a webview

On a fresh clone with no dist/, the gate prints a note and checks the sources only — handy when auditing a PR before running the build. Run npm run build to also gate the built artifacts.

Bundling & compatibility

The Agent import graph is free of Node.js builtins, so bundlers ship it as-is to any JS runtime.

Bundler	Works out of the box?	Notes
Vite	✅	No polyfills needed
esbuild	✅	No polyfills needed
webpack 5	✅	`resolve.fallback` not required for `crypto` or `events`
Metro (React Native)	✅	No shim for `crypto` or `events` needed
Rollup	✅	No plugin needed for `crypto` or `events`

Random IDs come from WebCrypto (globalThis.crypto.randomUUID, with a getRandomValues fallback), and internal event dispatch uses a small in-tree emitter — the Agent module never imports Node’s crypto or events.

Configuration

Pass credentials per-agent so browsers never depend on environment variables.

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: "You are a helpful assistant",
  apiKey: window.__OPENAI_KEY,
  baseURL: "https://api.openai.com/v1",
});

Best Practices

Import from praisonai/mobile in any webview bundle

The package root re-exports the CLI, MCP server, and tool registry, which pull in Node builtins. praisonai/mobile is the curated, CI-verified allowlist for browsers, Electron renderers, Tauri, and React Native.

Pass credentials per-agent in browsers

Browsers have no environment variables. Provide apiKey (and baseURL if needed) directly on the agent instead of relying on process.env.

Use the browser-safe helpers, not the Node originals

The mobile entry exports randomUUID and getEnv. Use them instead of crypto.randomUUID() or process.env, which are the kind of Node dependencies that would break a bundle.

Understand where random IDs come from

On modern browsers and Node ≥ 19, IDs come from globalThis.crypto.randomUUID. On older webviews without it, PraisonAI falls back to getRandomValues and still produces a valid RFC-4122 v4 UUID. On the very oldest webviews without WebCrypto at all, IDs fall back to Math.random() — a weak source, but the Agent still constructs (no ReferenceError at import).

No polyfills required

Do not add crypto or events shims to your bundler config — the Agent import graph does not reference them.

Stay on or above the supported baseline

CI targets Safari 16 and Chrome 108. Test against those floors; runtimes below them are unsupported and may fail for reasons the gate cannot catch.

Run build + check:webview before shipping a fork

If you patch praisonai-ts in a fork, run npm run build && npm run check:webview so a stray static Node import surfaces on your PR, not on a device. Building first means the gate inspects the shipped dist/esm/… artifacts, not just the sources.

Agent

The core Agent class and its full configuration.

Approval

Human-in-the-loop tool approval

TypeScript Agents

Getting started with the TypeScript SDK.

​Quick Start

​How It Works

​Webview support contract

​Which entry is safe

​Supported browsers

​What CI guarantees absent from your bundle

​Static vs dynamic — the carve-out

​Which import to use

​Reproducing the check locally

​Bundling & compatibility

​Configuration

​Best Practices

​Related

Agent

Approval

TypeScript Agents

Quick Start

How It Works

Webview support contract

Which entry is safe

Supported browsers

What CI guarantees absent from your bundle

Static vs dynamic — the carve-out

Which import to use

Reproducing the check locally

Bundling & compatibility

Configuration

Best Practices

Related