aiwatcher

Universal JavaScript/TypeScript SDK for AIWatcher — AI agent observability and control.

Works in browser (Vite, React) and Node.js (Next.js, Express) with the same API. Zero external dependencies.

Installation

npm install aiwatcher

Setup — one time per app

Browser / Vite / React

// src/lib/aiwatcher.js
import { AIWatcher } from 'aiwatcher'

export const aw = new AIWatcher({
  apiKey: import.meta.env.VITE_AIWATCHER_API_KEY,
  appName: 'my-app',
  framework: 'react',
  getUserId: () => getCurrentUser()?.email ?? null,
})

Node.js / Next.js / Express

// lib/aiwatcher.ts
import { AIWatcher } from 'aiwatcher'

export const aw = new AIWatcher({
  apiKey: process.env.AIWATCHER_API_KEY!,
  appName: 'my-app',
  framework: 'nextjs',
  getUserId: async () => (await getServerUser())?.id ?? null,
})

Usage — one wrapper per AI call

Regular (awaited) call

// Before:
const result = await myAIFunction(input)

// After — trackLLM for LLM calls, track for any other AI action:
const result = await aw.trackLLM('feature-name', () => myAIFunction(input))

With metadata

const result = await aw.trackLLM(
  'feature-name',
  () => myAIFunction(input),
  { model: 'claude-sonnet-4-20250514', input: { query: userQuery } },
)

Streaming call

// Before:
const stream = myAIClient.stream(params)
for await (const chunk of stream) { /* ... */ }

// After — identical usage, just wrapped:
const stream = aw.trackStream('feature-name', () => myAIClient.stream(params))
for await (const chunk of stream) { /* ... */ }

Multi-step workflow (each step shares the same session automatically)

const searchResults = await aw.track('web-search', () => exa.search(query))
const analysis = await aw.trackLLM('analyze', () =>
  claude.messages.create({ model: 'claude-sonnet-4-20250514', messages: [...] }),
)

Advanced streaming with custom usage extraction

const stream = aw.trackStream(
  'generate',
  () => aiClient.stream(params),
  {
    model: 'gpt-4o',
    onComplete: (lastChunk) => ({
      tokensIn:  lastChunk.usage?.prompt_tokens,
      tokensOut: lastChunk.usage?.completion_tokens,
    }),
  },
)
for await (const chunk of stream) {
  process.stdout.write(chunk.delta ?? '')
}

Optional: explicit session control

Most apps never need this — sessions are managed automatically per user.

await aw.startSession('my-agent')
// ... do work ...
await aw.endSession()

Environment variables

AIWATCHER_API_KEY=aw_live_...          # from AIWatcher dashboard → Your Apps
AIWATCHER_API_URL=https://agentwatch-pi.vercel.app   # optional, default shown

Design

• Never throws — all AIWatcher errors are caught silently; your app always gets the AI result
• Lazy sessions — POST /session/start only fires when the first event is logged
• Hash chain — every event is chained with SHA-256 for tamper detection (matches Python SDK)
• Auto token extraction — detects Anthropic and OpenAI response shapes automatically
• Auto cost estimation — estimates USD cost from model name + token counts

API

new AIWatcher(config)

| Field | Type | Required | Description | |---|---|---|---| | apiKey | string | ✓ | aw_live_... from dashboard | | appName | string | ✓ | Shown in dashboard | | getUserId | () => string \| null \| Promise<string \| null> | ✓ | Current user identity | | apiUrl | string | | Default: https://agentwatch-pi.vercel.app | | framework | string | | e.g. 'react', 'nextjs' | | debug | boolean | | Log to console |

aw.track(action, fn, options?) → Promise<T>

Wraps any async call. Logs tool_call before and tool_result after.

aw.trackLLM(action, fn, options?) → Promise<T>

Same as track but logs llm_call and auto-extracts token usage + cost.

aw.trackStream(action, fn, options?) → AsyncGenerator<T>

Wraps a streaming call. Chunks pass through unchanged. Logs usage on completion.

TrackOptions

| Field | Type | Description | |---|---|---| | model | string | e.g. 'claude-sonnet-4-20250514' | | input | object | Input sent to the AI (truncated to 500 chars) | | actionClass | string | 'read' | 'write' | 'send' | 'delete' | | dataScope | string | 'any' | 'pii' | 'financial' | 'health' |