react-observer-agent 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ This is an experimental project by a solo developer. I am exploring whether an A
 
 - Zero runtime dependencies (adapters use raw `fetch`, no SDKs)
 - TypeScript, dual ESM/CJS builds with types included
-- React >= 18 (peer dependency)
+- React >= 18 (peer dependency); CI runs the suite against React 18 and 19
 - Works with any state manager: Zustand, Redux, vanilla React state
 
 ## Install
@@ -19,18 +19,35 @@ This is an experimental project by a solo developer. I am exploring whether an A
 npm install react-observer-agent
 ```
 
+The bundle starts with a `'use client'` directive, so importing it from a Next.js App Router component needs no wrapper file.
+
 ## Quick start
 
 ```tsx
 import { AIAgentProvider, registerTool, openAIAdapter, useAgent } from 'react-observer-agent';
 import { useStore } from './store';
 
-// 1. Register tools: actions the agent is allowed to perform
+// 1. Register tools: actions the agent is allowed to perform.
+//    A handler receives (args, context); context?.signal aborts when the
+//    interaction is cancelled, so forward it to anything long-running.
 const tools = [
   registerTool('goToPage', (args: { path: string }) => navigate(args.path), {
     description: 'Navigate to a page in the app',
     parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
   }),
+  registerTool(
+    'searchProducts',
+    async (args: { query: string }, context) => {
+      const res = await fetch(`/api/search?q=${encodeURIComponent(args.query)}`, {
+        signal: context?.signal,
+      });
+      return res.json();
+    },
+    {
+      description: 'Search the product catalog',
+      parameters: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+    },
+  ),
   registerTool('submitForm', () => handleSubmit(), {
     description: 'Submit the current form',
     confirm: true, // requires user approval before executing
@@ -55,7 +72,7 @@ export default function App() {
       tools={tools}
       permissions={{
         canAccess: ['user', 'cart'],
-        canExecute: ['goToPage', 'submitForm'],
+        canExecute: ['goToPage', 'searchProducts', 'submitForm'],
         stateDescriptions: {
           user: 'Current logged-in user profile',
           cart: 'Shopping cart items and quantities',
@@ -76,6 +93,7 @@ function ChatPanel() {
   // send("What's in my cart?") -> agent reads state, responds with text
   // send("Go to settings")     -> agent calls goToPage({ path: '/settings' })
   // send(text, { signal })     -> pass an AbortSignal to cancel mid-flight
+  // Two sends in a row queue up and run one at a time, in call order.
 }
 ```
 
@@ -109,7 +127,9 @@ Two things fall out of this:
 - **Token cost scales with what the agent actually reads**, not with the size of your state tree.
 - **Unread state never leaves the client.** A key the agent does not ask for is never serialized into a request.
 
-`__readState` is invisible to you as a consumer. It never appears in `AgentResponse.toolCalls`, the `onToolCall` callback, or `history`. The rationale and a worked example are in [docs/internals.md](docs/internals.md).
+A read is resolved from your state source at the moment the model asks, so the model sees current values, and `options.maxStateBytes` can cap how much any single key contributes (see [Security model](#security-model)).
+
+`__readState` is invisible to you as a consumer. It never appears in `AgentResponse.toolCalls`, the `onToolCall` callback, or `history`. The `state_read` event (below) is the one place you can watch it happen. The rationale and a worked example are in [docs/internals.md](docs/internals.md).
 
 ## Security model
 
@@ -122,9 +142,34 @@ The library treats the LLM as an untrusted planner inside a capability sandbox.
 1. *Visibility*: the model never sees unlisted keys or tools, so it cannot request what it cannot see.
 2. *Execution*: names are re-validated after the model responds. A hallucinated or injected tool name is rejected with status `denied`, and `__readState` requests are re-filtered against `canAccess`.
 
-**Argument validation.** Tool arguments are checked against the tool's `parameters` JSON Schema before the handler runs, and before the confirmation prompt, so nobody is asked to approve a malformed call. Validation covers a deliberate subset (`type`, `properties`, `required`, `items`, `enum`) and ignores keywords outside it, so a richer schema validates on the parts the library understands instead of failing outright. Handlers should still treat args as untrusted, since unvalidated keywords pass through.
+**Argument validation.** Tool arguments are checked before the handler runs, and before the confirmation prompt, so nobody is asked to approve a malformed call. Two validators are available:
+
+- The default checks arguments against the tool's `parameters` JSON Schema. It covers a deliberate subset (`type`, `properties`, `required`, `items`, `enum`) and ignores keywords outside it, so a richer schema validates on the parts the library understands instead of failing outright. Handlers should still treat args as untrusted, since unvalidated keywords pass through.
+- Passing a [Standard Schema](https://standardschema.dev) validator as `schema` (Zod 3.24+, Valibot 1+, ArkType 2+) replaces the subset check with the real thing. The handler receives the validated value, so defaults and transforms apply, and its argument type is inferred from the schema output. `parameters` still supplies the JSON Schema the model sees; the library does not derive one from the schema.
+
+```ts
+import { z } from 'zod';
+
+const AddToCart = z.object({ productId: z.string(), qty: z.number().int().positive().default(1) });
+
+registerTool('addToCart', (args) => addToCart(args.productId, args.qty), {
+  description: 'Add a product to the cart',
+  parameters: {
+    type: 'object',
+    properties: { productId: { type: 'string' }, qty: { type: 'integer' } },
+    required: ['productId'],
+  },
+  schema: AddToCart, // args is { productId: string; qty: number }
+});
+```
+
+Annotating the handler is allowed when the annotation matches the schema output. An annotation that disagrees with it is a compile error rather than a silent fallback to the untyped signature. An explicit type argument (`registerTool<T>(...)`) next to an inline `schema` is also a compile error, whether or not the two agree, since the type argument turns inference off; drop it and let the schema supply the type.
+
+**Human confirmation.** Tools registered with `confirm: true` route through your `onConfirm` handler before running. You own the UI: modal, toast, `window.confirm`, anything that resolves a boolean. The handler receives `{ toolName, args, description, signal }`, where `args` is the validated value and `signal` aborts if the interaction is cancelled while your prompt is open. If no handler is provided, the tool is skipped with status `cancelled`. Confirmation is never silently bypassed. Use it for anything irreversible or user-visible.
 
-**Human confirmation.** Tools registered with `confirm: true` route through your `onConfirm` handler before running. You own the UI: modal, toast, `window.confirm`, anything that resolves a boolean. If no handler is provided, the tool is skipped with status `cancelled`. Confirmation is never silently bypassed. Use it for anything irreversible or user-visible.
+Abort and confirmation interact in a few ways worth knowing. An approval that arrives after the interaction was aborted does not run the tool; the call is recorded as `cancelled`. If `onConfirm` rejects with an `AbortError`, the call is cancelled the same way. Any other rejection counts as a tool error: the call is recorded with status `error`, the model is told, and the interaction continues.
+
+**State size guard.** One oversized key (a product catalog, a log buffer) can spend the whole context window on a single read. `options.maxStateBytes` caps the serialized size of each key returned by `__readState`; a value over the cap is replaced with a marker carrying the size, the limit, and a preview of the JSON. Unset means no limit.
 
 **Prompt injection.** State often contains user-generated content (reviews, messages, profile fields). Once serialized into the conversation, that content can attempt prompt injection. The permission and confirmation layers are the backstop: an injected instruction can at worst invoke allowlisted tools, and confirmed tools still require a human yes.
 
@@ -143,21 +188,48 @@ The backend holds the real key, applies auth and rate limits, and forwards to th
 
 | Adapter | Status | Defaults |
 |---------|--------|----------|
-| `openAIAdapter` | Built in | OpenAI chat completions; model `gpt-4o`, temperature `0.2` |
-| `claudeAdapter` | Built in | Anthropic Messages API; model `claude-opus-5`, `maxTokens` `16000` |
-| `ollamaAdapter` | Planned | Local models via Ollama |
+| `openAIAdapter` | Built in | OpenAI chat completions; model `gpt-4o`, temperature `0.2` (`null` omits it) |
+| `claudeAdapter` | Built in | Anthropic Messages API; model `claude-opus-5`, `maxTokens` `16000`, prompt caching on |
+| Ollama | Recipe below | `openAIAdapter` pointed at Ollama's OpenAI-compatible endpoint |
 | Custom | Supported | Implement `ModelAdapter` and pass it to the provider |
 
-Both built-in adapters are raw `fetch`, no SDK dependency. Both require either `apiKey` or `baseURL` and throw at construction with neither. `claudeAdapter` sends no sampling parameters, since current Claude models reject them.
+Both built-in adapters are raw `fetch`, no SDK dependency. Both require either `apiKey` or `baseURL` and throw at construction with neither. A non-2xx response, a network failure, or an unparseable body throws an `AdapterError` carrying `status` and the raw `body` when there was a response; the provider surfaces it as `error.code: 'ADAPTER_ERROR'` with `error.status`, so a 401 and a 429 are telling apart without parsing messages. Both map the provider's stop reason so a truncated or refused answer is reported (see below), and both report cached prompt tokens in `usage.cacheReadTokens` when the API does.
+
+`claudeAdapter` sends the system prompt as a text block with a `cache_control` breakpoint, which caches the tools and system prompt together across calls; `cache: false` sends a plain string instead. Its `promptTokens` is the total input for the call, cached tokens included, with `cacheReadTokens` and `cacheWriteTokens` broken out. The raw content blocks of each assistant response are kept as `providerData` and replayed verbatim on later turns, which is what keeps thinking blocks and their signatures intact (Anthropic rejects a modified one). Failed tool results go back flagged `is_error`. It sends no sampling parameters, since current Claude models reject them.
+
+`openAIAdapter` sends `temperature: 0.2` unless you pass `temperature: null`, which omits the field; reasoning models reject any value other than their own default. Cached prompt tokens come from `prompt_tokens_details.cached_tokens` and are already inside `promptTokens`.
+
+**Ollama.** Ollama exposes an OpenAI-compatible endpoint, so a local model needs no separate adapter:
+
+```ts
+const model = openAIAdapter({
+  baseURL: 'http://localhost:11434/v1',
+  model: 'llama3.1', // pick a model whose Ollama page lists tool support
+});
+```
+
+The model has to support tool calling, or the agent cannot read state or run anything. I have not run this recipe myself; it follows from the endpoint being OpenAI-compatible, and reports either way are welcome.
 
 ## How `send()` behaves
 
 Each `send()` runs a turn loop of at most `options.maxTurns` model round trips (default 5). A few behaviors worth knowing:
 
-- **Conversation memory.** The prior LLM transcript is replayed with tool calls and their results intact across `send()` calls, so the agent remembers what it already did. `clearHistory()` resets it.
-- **Cancellation.** `send(message, { signal })` takes an `AbortSignal`. Aborts resolve with `error.code: 'ABORTED'` rather than throwing, and deliberately do not fire `onError`, since a cancel is a caller decision, not a failure.
-- **Turn budget.** When `maxTurns` runs out while the model is still calling tools, `send()` resolves with `error.code: 'MAX_TURNS'` and whatever tool calls accumulated.
-- **Token usage.** `AgentResponse.usage` totals prompt and completion tokens across every model call in the interaction, when the adapter reports them.
+- **One at a time.** Concurrent `send()` calls queue and run strictly in call order, each starting from the transcript the previous one left. `history` therefore always alternates user, assistant, and `isProcessing` stays true from the first call until the last queued one settles.
+- **Conversation memory.** The prior LLM transcript is replayed with tool calls and their results intact across `send()` calls, so the agent remembers what it already did. `clearHistory()` resets it. Calling `clearHistory()` while an interaction is running discards that interaction's records: its `send()` still resolves and `onError` still fires, but nothing it produced lands in `history`, `lastResponse`, or the transcript.
+- **Events.** `options.onEvent` receives `turn_start`, `state_read`, `tool_start`, and `tool_end` as the loop runs, for progress UI and logging. Every `tool_start` gets exactly one `tool_end`; `tool_start` carries the raw arguments from the model and `tool_end` the validated value plus the final status.
+- **Cancellation.** `send(message, { signal })` takes an `AbortSignal`. A signal linked to it reaches the adapter, `onConfirm`, and every tool handler as `context.signal`. An abort ends the wait on the adapter, on `onConfirm`, and on the handler even when they ignore the signal; forwarding the signal to `fetch` or whatever else the handler awaits is what stops the work itself, since a promise cannot be cancelled from outside. Aborts resolve with `error.code: 'ABORTED'` rather than throwing, and deliberately do not fire `onError`, since a cancel is a caller decision, not a failure.
+- **Unmount.** Unmounting the provider aborts everything it owns. In-flight and queued interactions end with `error.code: 'ABORTED'` the same way a cancel does: `onConfirm`'s `signal` fires, handlers see `context.signal` aborted, `onError` is not called, and `send()` still settles, even when a confirmation UI unmounted without answering or a handler never looks at its signal. A `send()` reached through a stale reference after unmount resolves `ABORTED` without calling the model. StrictMode's simulated unmount in development gets a fresh controller and does not affect later sends.
+- **Typed errors.** `error.code` is one of the codes below. Every code except `ABORTED` reaches `onError`. An exception that is not an `AdapterError` (a throwing `onToolCall` callback, for example) produces an error with no code. `send()` resolves with all of these; the one thing that makes it reject is `onError` itself throwing, and by then `history` and `lastResponse` are already written.
+- **History carries errors.** The assistant entry of an interaction that ended with an error has that error on `entry.error`, `ABORTED` included, so a chat UI can render a failed turn in place.
+- **Token usage.** `AgentResponse.usage` totals tokens across every model call in the interaction, when the adapter reports them. `promptTokens` is the total input including any cached portion; `cacheReadTokens` and `cacheWriteTokens` are subsets of it, present only when a provider reported them.
+
+| `error.code` | Meaning |
+|--------------|---------|
+| `ABORTED` | The signal fired. Partial tool calls are kept; `onError` is not called |
+| `MAX_TURNS` | `maxTurns` ran out while the model was still calling tools; `message` is empty |
+| `ADAPTER_ERROR` | The adapter threw an `AdapterError`; `error.status` carries the HTTP status when there was one |
+| `TRUNCATED` | The model hit its output token limit; `message` holds the partial text |
+| `REFUSED` | The model declined to answer (Anthropic `refusal`, OpenAI `content_filter`); `message` holds whatever text came back |
 
 ## API reference
 
@@ -170,10 +242,12 @@ Everything the package exports:
 | `registerTool(name, handler, options?)` | Creates a validated tool definition |
 | `openAIAdapter(config)` | OpenAI chat completions adapter |
 | `claudeAdapter(config)` | Anthropic Messages API adapter |
+| `AdapterError` | Error class thrown by the built-in adapters, with `status` and `body` |
+| `validateToolArgs(tool, args)` | Runs a tool's `schema` or `parameters` check and returns the validated value; exported for custom wiring |
 | `validateToolNames`, `filterState`, `filterTools`, `validateToolCall` | Building blocks for testing and custom wiring; typical apps never call these |
-| Types | `ModelAdapter`, `AgentResponse`, `ToolDefinition`, and the rest of `src/types.ts` |
+| Types | `ModelAdapter`, `AgentResponse`, `ToolDefinition`, `ToolHandler`, `ToolContext`, `AgentEvent`, `AgentErrorCode`, `TokenUsage`, `StopReason`, `StandardSchemaV1`, and the rest of `src/types.ts` |
 
-On `registerTool`: a tool needs a `description` to be shown to the model, and omitting `parameters` substitutes the empty object schema. Names beginning with `__` are reserved for internal tools (`__readState`) and rejected on mount, as are duplicate names.
+On `registerTool`: a tool needs a `description` to be shown to the model, and omitting `parameters` substitutes the empty object schema. `schema` takes a Standard Schema validator and types the handler from its output. Names beginning with `__` are reserved for internal tools (`__readState`) and rejected on mount, as are duplicate names.
 
 ### `<AIAgentProvider>` props
 
@@ -200,22 +274,54 @@ On `registerTool`: a tool needs a `description` to be shown to the model, and om
 |-------|------|-------|
 | `debug` | `boolean` | Verbose console logging, prefixed `[react-observer-agent]` (default `false`) |
 | `maxTurns` | `number` | Max LLM round trips per `send()` (default `5`) |
+| `maxStateBytes` | `number` | Per-key size cap on `__readState` results; oversized values become a truncation marker (default: no limit) |
 | `systemPrompt` | `string` | Prepended to the generated state manifest prompt |
 | `onError` | `(error: AgentError) => void` | Called when an interaction fails (except `ABORTED`) |
 | `onToolCall` | `(call: ToolCallEvent) => void` | Observer for every user-tool outcome |
-| `onConfirm` | `(call: PendingToolCall) => Promise<boolean>` | Approval handler for `confirm: true` tools |
+| `onConfirm` | `(call: PendingToolCall) => Promise<boolean>` | Approval handler for `confirm: true` tools; `call.signal` aborts with the interaction |
+| `onEvent` | `(event: AgentEvent) => void` | Observer for `turn_start`, `state_read`, `tool_start`, `tool_end` |
+
+### `AgentEvent`
+
+| `type` | Fields | When |
+|--------|--------|------|
+| `turn_start` | `turn`, `maxTurns` | Right before each model call |
+| `state_read` | `requested`, `keys` | After a `__readState` call resolves; `keys` is the allowed subset actually read |
+| `tool_start` | `toolName`, `args` | Before the permission check, with the raw arguments |
+| `tool_end` | `toolName`, `args`, `result`, `status` | Once per `tool_start`, with the validated arguments and final status |
 
 ### `useAgent()` returns
 
 | Field | Type | Notes |
 |-------|------|-------|
-| `send` | `(message, options?) => Promise<AgentResponse>` | `options.signal` cancels; resolves rather than rejects on errors |
-| `isProcessing` | `boolean` | True while an interaction is in flight |
-| `history` | `ConversationEntry[]` | User-facing conversation history for this provider instance |
+| `send` | `(message, options?) => Promise<AgentResponse>` | Queued; `options.signal` cancels; resolves rather than rejects on errors, unless `onError` itself throws |
+| `isProcessing` | `boolean` | True while any `send()` is pending or running |
+| `history` | `ConversationEntry[]` | User-facing conversation history; assistant entries carry `error` when the interaction failed |
 | `clearHistory` | `() => void` | Resets history, the LLM transcript, and `lastResponse` |
 | `lastResponse` | `AgentResponse \| null` | Most recent response, including error responses |
 
-Tool call statuses in `AgentResponse.toolCalls` and `onToolCall`: `success`, `confirmed`, `cancelled`, `denied`, `error`.
+### `AgentError`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `message` | `string` | |
+| `code` | `AgentErrorCode` | `'ABORTED' \| 'MAX_TURNS' \| 'ADAPTER_ERROR' \| 'TRUNCATED' \| 'REFUSED'`; absent for other thrown exceptions |
+| `status` | `number` | HTTP status, when the failure came from an adapter with one |
+| `cause` | `unknown` | The original exception, when there was one |
+
+### Adapter config
+
+| Option | `openAIAdapter` | `claudeAdapter` |
+|--------|-----------------|-----------------|
+| `apiKey` | Dev only | Dev only |
+| `baseURL` | Proxy or alternate endpoint | Proxy or alternate endpoint |
+| `model` | Default `gpt-4o` | Default `claude-opus-5` |
+| `headers` | Extra request headers | Extra request headers, spread last |
+| `temperature` | Default `0.2`; `null` omits the field | Not sent |
+| `maxTokens` | Not sent | Default `16000` |
+| `cache` | Not applicable | Default `true`; `false` disables prompt caching |
+
+Tool call statuses in `AgentResponse.toolCalls`, `onToolCall`, and `tool_end`: `success`, `confirmed`, `cancelled`, `denied`, `error`. When a handler throws or `onConfirm` rejects, `result` keeps the text of what was thrown: an `Error`'s message, a thrown string as is, the `message` of a rejected object, other objects JSON-stringified, `'Unknown error'` for `null` or `undefined`. The model is told the same text.
 
 The full contracts, including the `ModelAdapter` interface for writing custom adapters, are in [SPEC.md](SPEC.md).
 
@@ -223,11 +329,9 @@ The full contracts, including the `ModelAdapter` interface for writing custom ad
 
 In rough priority order:
 
-1. `ollamaAdapter` for local models
-2. Streaming responses
-3. Deeper argument validation
-4. Transcript compaction, so long sessions stay under the context window
-5. Per-tool permission scoping
+1. Streaming responses
+2. Transcript compaction, so long sessions stay under the context window
+3. Per-tool permission scoping
 
 Explicit non-goals for now: DOM awareness and page context mapping, automatic state detection, multi-agent orchestration, persistent memory, built-in rate limiting.
 
@@ -236,7 +340,7 @@ Explicit non-goals for now: DOM awareness and page context mapping, automatic st
 - [reactobserveragent.sudo-ezekiel.com](https://reactobserveragent.sudo-ezekiel.com): guides, API reference, and live examples you can click through
 - [sudo-ezekiel/react-observer-agent-examples](https://github.com/sudo-ezekiel/react-observer-agent-examples): the source for that site, including a runnable Zustand shopping app that proxies both providers
 - [SPEC.md](SPEC.md): the full technical spec
-- [docs/internals.md](docs/internals.md): pull-based state rationale and execution loop detail
+- [docs/internals.md](docs/internals.md): pull-based state rationale, the interaction queue, events, and execution loop detail
 - [CHANGELOG.md](CHANGELOG.md)
 
 ## Disclaimer