@jxburros/ai-nugget 0.3.1 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@ talking to AI model providers through one pipeline:
 policy → key resolution → beforeCall hook → concurrency/retry → provider adapter → redacted telemetry
 ```
 
-It runs identically in Node ≥ 20, the browser main thread, and Web Workers using
+It runs identically in Node 20.19+/22.12+, the browser main thread, and Web Workers using
 only `fetch`, `ReadableStream`, `AbortController`, and `TextDecoder`. It is
 intentionally **not** a router, prompt library, memory system, or secrets vault:
 apps choose models, own prompts, store secrets, and decide what policy to enforce.
@@ -58,6 +58,13 @@ with a `baseUrl` resolve to the `openai-compat` escape hatch. **Grok/xAI is not
 blocked and is never officially integrated** — point `openai-compat` at any
 endpoint if you must; that is your configuration, not a supported profile.
 
+**Wire URL for `openai-compat` and the other local runtimes.** `openai-compat`,
+`lmstudio`, `llamacpp`, and `vllm` have no `urlTemplate` in the profile table,
+so the `openaiChat` engine falls back to `POST {baseUrl}/chat/completions`
+(no `/v1` prefix — include it in `baseUrl` yourself if your server needs it,
+e.g. `http://localhost:8080/v1`). This matters most when standing up a local
+mock or test server: it has to listen on that exact path.
+
 Model identity is always `(source, model)` — `modelRef(source, model)` gives the
 canonical `provider/model` key so the same weights served by different hosts stay
 distinct and comparable.
@@ -139,6 +146,96 @@ AI Nugget handler:
 See `examples/model-picker.mjs` for a minimal runnable reference implementing
 this pattern.
 
+## Recipes
+
+Small server apps built directly on `AIHandler` (see
+`examples/npm-mini-apps/`) tend to hit the same three points of friction:
+resolving connection config, turning a JSON-mode reply into a validated app
+object, and mapping a failure into an HTTP response. None of this is policy —
+it's just the boilerplate every consumer re-derives — so here's the
+canonical shape for each.
+
+### Env-based connection setup
+
+`envConnection()` resolves a `Connection` plus a default `model` from
+app-owned env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` by
+default):
+
+```ts
+import { AIHandler, envConnection, envKeySource } from '@jxburros/ai-nugget';
+
+const handler = new AIHandler({ keySource: envKeySource() });
+const { connection, model } = envConnection({ id: 'my-app', defaultProvider: 'openai', defaultModel: 'gpt-4o-mini' });
+
+const result = await handler.chat(connection, { model, messages: [{ role: 'user', content: 'Hello!' }] });
+```
+
+It only reads the server's own environment — `provider`/`baseUrl` never come
+from client input this way either, same as the manual pattern it replaces.
+Pass `env`, `providerVar`/`modelVar`/`keyEnvVar`/`baseUrlVar`, or
+`defaultProvider`/`defaultModel`/`defaultKeyEnv` to override the var names or
+fallbacks an app already uses.
+
+### JSON output + validation
+
+Ask for JSON in the prompt (and set `responseFormat: { type: 'json' }` for
+providers with `capabilities.jsonMode`), then run the raw text through
+`extractJsonWithSchema` with a small parse function built from the
+`require*` guards in `json.ts` — don't hand-roll a `/\{[\s\S]*\}/` regex plus
+`JSON.parse`, which silently accepts the first brace-looking substring and
+gives no useful error on a malformed or schema-incomplete reply:
+
+```ts
+import { extractJsonWithSchema, requireNumber, requireString } from '@jxburros/ai-nugget';
+
+function parseSprint(raw: unknown) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Expected a JSON object');
+  const record = raw as Record<string, unknown>;
+  return { headline: requireString(record, 'headline'), minutes: requireNumber(record, 'minutes') };
+}
+
+const sprint = extractJsonWithSchema(result.text, parseSprint);
+```
+
+`extractJsonWithSchema` recovers JSON from fenced code blocks or prose the
+model wrapped around it, and throws a typed `AIError` with
+`kind: 'invalid_response'` on anything that doesn't parse or doesn't match
+the schema — no JSON found, an array where an object was expected, a missing
+field, a string where a number belongs. That error flows into the same
+`AIError`-kind switch as any other provider failure (see below), so JSON
+validation doesn't need its own error path. `require*` covers scalars and
+string arrays only — validate array length, numeric ranges, or nested shapes
+yourself, same as `parseSprint` above; this is deliberately not a full
+schema validator (see Non-goals).
+
+### Error handling matrix
+
+Every failure that reaches your `catch` around `handler.chat()`/`stream()` —
+including a JSON-validation failure from `extractJsonWithSchema` — is (or is
+normalized to) an `AIError` with a `kind`. Map `kind` to an HTTP status and a
+user-facing message once, log the raw `error.message` server-side, and never
+forward it to the client:
+
+| `kind` | Suggested status | Example user-facing message |
+|---|---|---|
+| `invalid_request` | 400 | "That request was invalid." |
+| `context_length` | 413 | "Your input is too long. Please shorten it and try again." |
+| `auth` | 502 | "The AI service is not configured correctly." |
+| `key_unavailable` | 500 | "The AI service is not configured correctly." |
+| `policy_blocked` | 403 | "This request was blocked by policy." |
+| `rate_limit` | 429 | "The AI service is busy. Please try again shortly." |
+| `timeout` | 504 | "The request took too long. Please try again." |
+| `canceled` | 499 | "The request was canceled." |
+| `invalid_response` | 502 | "The AI response wasn't in the expected format. Please try again." |
+| `network` / `server` | 502 | "The AI service is temporarily unavailable." |
+| `tool_error` | 500 | "Something went wrong running a tool." |
+| `budget_exceeded` | 429 | "This request used too many steps/tokens. Please try again." |
+
+`auth` and `key_unavailable` map to 5xx, not 401/403, because it's the
+*server's* credential that's wrong, not the caller's — the distinction
+matters for who should act on the error. `examples/npm-mini-apps/*/ai-error-map.mjs`
+is a copyable implementation of this table.
+
 ## What's implemented
 
 - **Core:** message-based contracts (`types.ts`), typed `AIError` + `classify()`,
@@ -170,7 +267,10 @@ this pattern.
   `allowlistPolicy` fails closed for providers omitted from the configured map;
   use `'*'` in a provider's prefix list to allow non-chat operation IDs.
   The default redactor covers common provider token formats and generic bearer
-  tokens, with session-resolved keys always added exactly.
+  tokens, with session-resolved keys always added exactly. `envConnection()`
+  (`connect.ts`) resolves a `Connection` + default `model` from app-owned env
+  vars — config-resolution convenience only, not a new seam or a policy
+  default (see Recipes above).
 - **Agent layer (`@jxburros/ai-nugget/agent`):** `defineTool` + light JSON-schema
   arg validation (object-ness, `required`, top-level `properties[key].type` —
   not full JSON Schema: no `enum`, nested schemas, `oneOf`, bounds, `pattern`,
@@ -198,11 +298,16 @@ import { runAgent, defineTool } from '@jxburros/ai-nugget/agent';
 ```bash
 npm install
 npm test            # Vitest contract suite in Node (97 tests; live tests skipped unless env-gated)
+npx playwright install chromium   # one-time, before test:browser
 npm run test:browser   # same suite in headless Chromium (proves isomorphism)
 npm run build       # tsc → dist/ (also the typecheck)
 npm run build:nugget   # writes a vendorable nugget/ stamped with version + content hash
 ```
 
+Requires Node `^20.19.0` or `>=22.12.0` (see `engines` in `package.json` and
+`.nvmrc`) — the toolchain's build step (`vitest` → `rolldown`) needs a native
+binding unavailable on older Node 20 patch releases.
+
 ### Live smoke tests (optional, env-gated)
 
 `tests/live-smoke.test.ts` exercises the real wire path against a live provider.
@@ -293,9 +398,20 @@ bundler hits this, vendor `dist/` (real `.js` + `.d.ts` pairs) instead of
 ## Examples
 
 `examples/` has runnable scripts against local Ollama and llama.cpp servers,
-`promptJson` vs. native tool-calling, an `ApprovalGate`, and telemetry — see
+`promptJson` vs. native tool-calling, an `ApprovalGate`, telemetry, and a small
+industrial-themed chatbot demo under `examples/steel-chat/` — see
 `examples/README.md`.
 
+If you want a compact end-to-end app example instead of a single script, run:
+
+```bash
+npm run demo:steel-chat
+```
+
+That demo exposes a simple browser chat UI backed by `AIHandler`, discovers
+allowed connections/models server-side, and displays the current package
+version in the interface so the example stays aligned with the installed nugget.
+
 ## Agent skills
 
 `.claude/skills/` contains Agent Skills — task-specific guides that Claude Code

package/dist/adapters/engines/google.d.ts

@@ -4,5 +4,15 @@ export declare class GoogleAdapter implements ProviderAdapter {
     constructor(provider: string);
     chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
     stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
+    /**
+     * `GoogleAdapter` has no `listModels`, so without a `health` probe
+     * `AIHandler.testConnection` would report `ok: true` without ever making a
+     * network call. `/v1beta/models` is a lightweight, key-authenticated GET
+     * that gives an honest connectivity/auth check.
+     */
+    health(conn: ResolvedConnection): Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
 }
 //# sourceMappingURL=google.d.ts.map

package/dist/adapters/engines/google.js

@@ -1,8 +1,8 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
-import { postResponse, sseLines } from '../../transport.js';
+import { fetchJson, postResponse, sseLines } from '../../transport.js';
 import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { streamError, streamTimeout } from './base.js';
+import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
 export class GoogleAdapter {
     provider;
     constructor(provider) {
@@ -84,6 +84,26 @@ export class GoogleAdapter {
             timeout.done();
         }
     }
+    /**
+     * `GoogleAdapter` has no `listModels`, so without a `health` probe
+     * `AIHandler.testConnection` would report `ok: true` without ever making a
+     * network call. `/v1beta/models` is a lightweight, key-authenticated GET
+     * that gives an honest connectivity/auth check.
+     */
+    async health(conn) {
+        try {
+            await fetchJson(`${conn.baseUrl}/v1beta/models`, {
+                method: 'GET',
+                headers: conn.headers,
+                timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 10_000),
+                provider: conn.provider,
+            });
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, detail: error instanceof Error ? error.message : 'Health check failed' };
+        }
+    }
 }
 function body(req) {
     const systemText = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n');

package/dist/agent/loop.js

@@ -216,7 +216,7 @@ function callsFromPromptJson(text) {
         if (typeof record.tool !== 'string')
             continue;
         calls.push({
-            id: crypto.randomUUID(),
+            id: randomId(),
             name: record.tool,
             arguments: record.input && typeof record.input === 'object' ? record.input : {},
             raw: JSON.stringify(record.input ?? {}),
@@ -224,6 +224,9 @@ function callsFromPromptJson(text) {
     }
     return calls;
 }
+function randomId() {
+    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
 function textContent(content) {
     if (typeof content === 'string')
         return content;

package/dist/connect.d.ts

@@ -0,0 +1,31 @@
+import type { Connection } from './types.js';
+export interface EnvConnectionOptions {
+    /** Read from this env-like object instead of the process/global environment. */
+    env?: Record<string, string | undefined>;
+    /** Connection id. Defaults to `'app'`. */
+    id?: string;
+    /** Env var names to read (override if an app already uses different names). */
+    providerVar?: string;
+    modelVar?: string;
+    keyEnvVar?: string;
+    baseUrlVar?: string;
+    /** Fallbacks used when the corresponding env var is unset. */
+    defaultProvider?: string;
+    defaultModel?: string;
+    defaultKeyEnv?: string;
+}
+export interface EnvConnection {
+    connection: Connection;
+    model: string;
+}
+/**
+ * Resolves a server-side `Connection` plus a default `model` from app-owned
+ * env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` unless
+ * overridden). This only collapses the config-reading boilerplate that was
+ * being hand-rolled the same way in every small server app; it does not add
+ * policy. `provider`/`baseUrl` still come from the server's own environment,
+ * never from client input, and the returned `keyRef` still resolves through
+ * `KeySource` at call time like any other `Connection`.
+ */
+export declare function envConnection(options?: EnvConnectionOptions): EnvConnection;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.js

@@ -0,0 +1,25 @@
+import { globalEnv } from './util.js';
+/**
+ * Resolves a server-side `Connection` plus a default `model` from app-owned
+ * env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` unless
+ * overridden). This only collapses the config-reading boilerplate that was
+ * being hand-rolled the same way in every small server app; it does not add
+ * policy. `provider`/`baseUrl` still come from the server's own environment,
+ * never from client input, and the returned `keyRef` still resolves through
+ * `KeySource` at call time like any other `Connection`.
+ */
+export function envConnection(options = {}) {
+    const env = options.env ?? globalEnv();
+    const provider = env[options.providerVar ?? 'AI_PROVIDER']?.trim() || options.defaultProvider || 'openai';
+    const model = env[options.modelVar ?? 'AI_MODEL']?.trim() || options.defaultModel || 'gpt-4o-mini';
+    const keyEnvName = env[options.keyEnvVar ?? 'AI_KEY_ENV']?.trim() || options.defaultKeyEnv || 'OPENAI_API_KEY';
+    const baseUrl = env[options.baseUrlVar ?? 'AI_BASE_URL']?.trim();
+    const connection = {
+        id: options.id ?? 'app',
+        provider,
+        keyRef: { kind: 'env', name: keyEnvName },
+        ...(baseUrl ? { baseUrl } : {}),
+    };
+    return { connection, model };
+}
+//# sourceMappingURL=connect.js.map

package/dist/handler.js

@@ -241,14 +241,20 @@ export class AIHandler {
         }
         this.active += 1;
         const minInterval = this.opts.limits?.minIntervalMs ?? 0;
-        const wait = Math.max(0, this.lastStarted + minInterval - Date.now());
-        this.lastStarted = Date.now() + wait;
+        const previousLastStarted = this.lastStarted;
+        const wait = Math.max(0, previousLastStarted + minInterval - Date.now());
+        const reserved = Date.now() + wait;
+        this.lastStarted = reserved;
         try {
             if (wait)
                 await sleep(wait, signal);
         }
         catch (error) {
             this.release();
+            // Only undo our own reservation — a later caller may have already
+            // paced itself off `reserved` and must keep that spacing.
+            if (this.lastStarted === reserved)
+                this.lastStarted = previousLastStarted;
             throw error;
         }
     }

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './transport.js';
 export * from './json.js';
 export * from './tokens.js';
 export * from './keys.js';
+export * from './connect.js';
 export * from './redact.js';
 export * from './policy.js';
 export * from './handler.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from './transport.js';
 export * from './json.js';
 export * from './tokens.js';
 export * from './keys.js';
+export * from './connect.js';
 export * from './redact.js';
 export * from './policy.js';
 export * from './handler.js';

package/dist/keys.js

@@ -1,3 +1,4 @@
+import { globalEnv } from './util.js';
 export function parseKeyRef(value) {
     const trimmed = value?.trim();
     if (!trimmed)
@@ -71,8 +72,4 @@ export function chainKeySources(...sources) {
         },
     };
 }
-function globalEnv() {
-    const maybeProcess = globalThis;
-    return maybeProcess.process?.env ?? {};
-}
 //# sourceMappingURL=keys.js.map

package/dist/util.d.ts

@@ -4,5 +4,6 @@ export declare function asString(value: unknown): string | undefined;
 export declare function asNumber(value: unknown): number | undefined;
 export declare function promptChars(messages: ChatMessage[]): number;
 export declare function textFromMessages(messages: ChatMessage[]): string;
+export declare function globalEnv(): Record<string, string | undefined>;
 export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 //# sourceMappingURL=util.d.ts.map

package/dist/util.js

@@ -21,6 +21,10 @@ export function textFromMessages(messages) {
         return message.content.map((part) => part.text ?? '').join('');
     }).join('\n');
 }
+export function globalEnv() {
+    const maybeProcess = globalThis;
+    return maybeProcess.process?.env ?? {};
+}
 export function sleep(ms, signal) {
     if (ms <= 0)
         return Promise.resolve();

package/nugget/VERSION.txt

@@ -1,2 +1,2 @@
-0.3.1
-a15d2e448ed391c96856ccb9b4f423d229a7bfd684bf394a5c3d93a5fcd876f6
+0.4.1
+4dec12bfcf23c8282cd488a90048ea2a96247d16b84140fad709a3b976ce71e9

package/nugget/src/adapters/engines/google.ts

@@ -1,9 +1,9 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
-import { postResponse, sseLines } from '../../transport.js';
+import { fetchJson, postResponse, sseLines } from '../../transport.js';
 import type { ChatMessage, ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
 import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { streamError, streamTimeout } from './base.js';
+import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
 
 export class GoogleAdapter implements ProviderAdapter {
   readonly provider: string;
@@ -81,6 +81,26 @@ export class GoogleAdapter implements ProviderAdapter {
       timeout.done();
     }
   }
+
+  /**
+   * `GoogleAdapter` has no `listModels`, so without a `health` probe
+   * `AIHandler.testConnection` would report `ok: true` without ever making a
+   * network call. `/v1beta/models` is a lightweight, key-authenticated GET
+   * that gives an honest connectivity/auth check.
+   */
+  async health(conn: ResolvedConnection): Promise<{ ok: boolean; detail?: string }> {
+    try {
+      await fetchJson(`${conn.baseUrl}/v1beta/models`, {
+        method: 'GET',
+        headers: conn.headers,
+        timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 10_000),
+        provider: conn.provider,
+      });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, detail: error instanceof Error ? error.message : 'Health check failed' };
+    }
+  }
 }
 
 function body(req: ChatRequest): Record<string, unknown> {

package/nugget/src/agent/loop.ts

@@ -268,7 +268,7 @@ function callsFromPromptJson(text: string): ToolCall[] {
     const record = entry as Record<string, unknown>;
     if (typeof record.tool !== 'string') continue;
     calls.push({
-      id: crypto.randomUUID(),
+      id: randomId(),
       name: record.tool,
       arguments: record.input && typeof record.input === 'object' ? record.input : {},
       raw: JSON.stringify(record.input ?? {}),
@@ -277,6 +277,10 @@ function callsFromPromptJson(text: string): ToolCall[] {
   return calls;
 }
 
+function randomId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+
 function textContent(content: ChatMessage['content']): string {
   if (typeof content === 'string') return content;
   if (!content) return '';

package/nugget/src/connect.ts

@@ -0,0 +1,48 @@
+import type { Connection } from './types.js';
+import { globalEnv } from './util.js';
+
+export interface EnvConnectionOptions {
+  /** Read from this env-like object instead of the process/global environment. */
+  env?: Record<string, string | undefined>;
+  /** Connection id. Defaults to `'app'`. */
+  id?: string;
+  /** Env var names to read (override if an app already uses different names). */
+  providerVar?: string;
+  modelVar?: string;
+  keyEnvVar?: string;
+  baseUrlVar?: string;
+  /** Fallbacks used when the corresponding env var is unset. */
+  defaultProvider?: string;
+  defaultModel?: string;
+  defaultKeyEnv?: string;
+}
+
+export interface EnvConnection {
+  connection: Connection;
+  model: string;
+}
+
+/**
+ * Resolves a server-side `Connection` plus a default `model` from app-owned
+ * env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` unless
+ * overridden). This only collapses the config-reading boilerplate that was
+ * being hand-rolled the same way in every small server app; it does not add
+ * policy. `provider`/`baseUrl` still come from the server's own environment,
+ * never from client input, and the returned `keyRef` still resolves through
+ * `KeySource` at call time like any other `Connection`.
+ */
+export function envConnection(options: EnvConnectionOptions = {}): EnvConnection {
+  const env = options.env ?? globalEnv();
+  const provider = env[options.providerVar ?? 'AI_PROVIDER']?.trim() || options.defaultProvider || 'openai';
+  const model = env[options.modelVar ?? 'AI_MODEL']?.trim() || options.defaultModel || 'gpt-4o-mini';
+  const keyEnvName = env[options.keyEnvVar ?? 'AI_KEY_ENV']?.trim() || options.defaultKeyEnv || 'OPENAI_API_KEY';
+  const baseUrl = env[options.baseUrlVar ?? 'AI_BASE_URL']?.trim();
+
+  const connection: Connection = {
+    id: options.id ?? 'app',
+    provider,
+    keyRef: { kind: 'env', name: keyEnvName },
+    ...(baseUrl ? { baseUrl } : {}),
+  };
+  return { connection, model };
+}

package/nugget/src/handler.ts

@@ -274,12 +274,17 @@ export class AIHandler {
     }
     this.active += 1;
     const minInterval = this.opts.limits?.minIntervalMs ?? 0;
-    const wait = Math.max(0, this.lastStarted + minInterval - Date.now());
-    this.lastStarted = Date.now() + wait;
+    const previousLastStarted = this.lastStarted;
+    const wait = Math.max(0, previousLastStarted + minInterval - Date.now());
+    const reserved = Date.now() + wait;
+    this.lastStarted = reserved;
     try {
       if (wait) await sleep(wait, signal);
     } catch (error) {
       this.release();
+      // Only undo our own reservation — a later caller may have already
+      // paced itself off `reserved` and must keep that spacing.
+      if (this.lastStarted === reserved) this.lastStarted = previousLastStarted;
       throw error;
     }
   }

package/nugget/src/index.ts

@@ -4,6 +4,7 @@ export * from './transport.js';
 export * from './json.js';
 export * from './tokens.js';
 export * from './keys.js';
+export * from './connect.js';
 export * from './redact.js';
 export * from './policy.js';
 export * from './handler.js';

package/nugget/src/keys.ts

@@ -1,4 +1,5 @@
 import type { KeyRef, KeySource } from './types.js';
+import { globalEnv } from './util.js';
 
 export function parseKeyRef(value?: string | null): KeyRef {
   const trimmed = value?.trim();
@@ -63,8 +64,3 @@ export function chainKeySources(...sources: KeySource[]): KeySource {
     },
   };
 }
-
-function globalEnv(): Record<string, string | undefined> {
-  const maybeProcess = globalThis as typeof globalThis & { process?: { env?: Record<string, string | undefined> } };
-  return maybeProcess.process?.env ?? {};
-}

package/nugget/src/util.ts

@@ -26,6 +26,11 @@ export function textFromMessages(messages: ChatMessage[]): string {
   }).join('\n');
 }
 
+export function globalEnv(): Record<string, string | undefined> {
+  const maybeProcess = globalThis as typeof globalThis & { process?: { env?: Record<string, string | undefined> } };
+  return maybeProcess.process?.env ?? {};
+}
+
 export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxburros/ai-nugget",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "description": "Small isomorphic AI model nugget for provider calls, policy, redaction, telemetry, and agent loops.",
@@ -17,7 +17,7 @@
     "telemetry"
   ],
   "engines": {
-    "node": ">=20"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -56,6 +56,7 @@
     "test:live": "vitest run tests/live-smoke.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build:nugget": "node scripts/build-nugget.mjs",
+    "demo:steel-chat": "npm run build && node examples/steel-chat/server.mjs",
     "prepublishOnly": "npm run build && npm run build:nugget"
   },
   "devDependencies": {