nuabase 2.3.11 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # nuabase
 
+## 3.0.0
+
+### Major Changes
+
+- be95150: `nuabase` now only runs casts in your process, on LLM providers' APIs with your keys (`Nua.direct({ providers })`) or on a coding agent on your machine (`Nua.direct({ localAgent })`).
+  
+  Removed: `Nua.gateway()`, `nua.queueGet()`, `nua.queueList()`, and the `GatewayConfig`, `GatewayMeta` and `QueueResult` types. A result's `source` is now always `'direct'`.
+  
+  Also removed: the `LlmBackend`, `CastValueParams` and `CastArrayParams` types. `Nua`'s constructor is private, so nothing could implement or pass them.
+  
+  `nuabase` now needs Node.js 18 or later (it said `>=16.6.0`), for the global `fetch` it calls LLM providers with.
+
+### Minor Changes
+
+- 9ed74c9: `nuabase/local-agent` can now start an interactive coding-agent session in the user's project, for the user to carry on in a terminal: `startAgentSession()` writes the first message and a shell launcher that starts Claude Code, Codex or Pi on it (in the agent's auto mode with `approval: 'auto'`), and on macOS opens it in a new terminal window. It answers with what it did: `opened`, `command` (the user runs it in a terminal), `open_failed` (the files are written but the window didn't open, with the error) or `refused` with the reason. `agentSessionMode()` says beforehand which of these the platform allows.
+- 61eaba5: A failed cast now says why on its own: `reason` is the last attempt's failure in the engine's own words (a coding agent's or provider's message, fit to show a user), and `attempts` is how many were made (0 when the request was refused before any). `error` stays the one-line summary for logs. Coding-agent failures no longer prefix the agent's name (`claude: `) to its message, and Codex's API errors are reported by their message instead of as JSON.
+- 5028584: DeepSeek is now a direct provider: pass `providers: { deepseek: { apiKey } }` and name a DeepSeek model such as `deepseek-flash` or `deepseek-v4-pro`. DeepSeek requests run with thinking turned off, and schemas are described in the prompt because DeepSeek has no strict structured outputs. A new `deepseek` alias uses DeepSeek V4 Pro, directly or through OpenRouter.
+  
+  The model aliases now point at current models: `gemini` → Gemini 3.8 Flash, `qwen` → Qwen3.8 2.4T A95B, `kimi` → Kimi K3, `sonnet` → Claude Sonnet 5.5, `opus` → Claude Opus 5.5, `gpt` → GPT-6.1 Sol, and the OpenRouter fallback for `fast` → GLM-5.3 Flash.
+- 25569d9: Local agents take an `effort` option (`'low' | 'medium' | 'high'`), passed to the CLI's own setting: Claude Code `--effort`, Codex `model_reasoning_effort`, Pi `--thinking`. Left out, the CLI's default applies. Codex casts no longer run at low reasoning effort unless you ask for it with `effort: 'low'`.
+- 25569d9: `LocalAgent.with({ model, effort, timeoutMs })` gives the same agent with other call options, sharing its executable, environment, logger and `concurrency` limit. One `localAgent()` per CLI can now serve casts on several of its models, such as Codex models that have no alias, without each getting its own limit on processes running at once.
+- 449e580: `usage` now reports `promptCacheReadTokens` and `promptCacheWriteTokens` when the provider does: the prompt tokens it read from or wrote to its prompt cache. They are part of `promptTokens`. Reported for OpenRouter, DeepSeek and Gemini, and for the Claude Code, Codex and Pi local agents.
+- 3abfeee: Casts and agents now make use of provider prompt caching. Claude on OpenRouter caches the prompt, instructions and schema of a cast, so repeat calls of the same cast read them at about a tenth of the price, and agent turns read the conversation the previous turn sent. Casts through OpenRouter stay on one upstream provider, so models that cache automatically (DeepSeek, GLM, Kimi, GPT) reuse it too.
+- 4f38416: Results are now parsed with your Zod schema instead of being checked against its JSON Schema with AJV. `data` is Zod's parsed output: `.default()`s are filled in, `.transform()`s run, `.refine()` checks apply (a failing answer is retried), and unknown object keys are dropped. The JSON Schema shown to the model now describes the schema's input side, so schemas with `.transform()` no longer throw. AJV is no longer bundled.
+
+### Patch Changes
+
+- b9b5da9: Type declarations now resolve under every module resolution, including `node16`/`nodenext` from ES modules and CommonJS, where nuabase's exports used to type as `any`. Each entry point ships one self-contained `.d.mts` and `.d.cts`, bundled by the same build as the JavaScript. `LlmProviderId` and `Logger` are now exported. The ES module build imports Node's built-ins directly instead of through `createRequire`.
+- dec76aa: Schemas with `$ref`s, such as those using `.meta({ id })` or recursive schemas, now work with native schema enforcement. The schema sent to the engine had refs that pointed nowhere, so engines either rejected it or did not enforce it.
+- 267e07a: Tool-calling agents on Gemini 3 models now work: Gemini's thought signatures are sent back with each function call, which Gemini 3 and later require.
+- 3bbdc4c: `list()` rows are typed by the output's name when it is a literal: with `output: { name: 'account', schema: z.string() }`, each row is `{ id: string | number; account: string }` instead of a row whose every field has the output's type.
+
 ## 2.3.11
 
 ### Patch Changes

package/README.md

@@ -1,76 +1,38 @@
-## Nuabase TypeScript SDK
+# Nuabase TypeScript SDK
 
-Nuabase turns LLM prompts into type-safe functions in under five lines of code. Set up your free account now at [Nuabase](https://nuabase.com).
+Nuabase turns LLM prompts and Zod schemas into type-safe functions. Pass a prompt, input data, and a Zod schema; receive validated, typed data back.
 
-With Nuabase, you write a prompt, specify the output schema, and get back a well-typed function. You can invoke it with input data, like any other code in your application, and receive data that matches the exact schema you specified.
+Every call runs directly in your process—either against the LLM provider API you choose, using your API keys, or via a local coding agent CLI already installed on your machine (`claude`, `codex`, or `pi`).
 
-Example use-cases:
+**Common use cases:**
+- Extract structured fields from free-form text to auto-fill complex forms
+- Enrich arrays of items (e.g., adding nutrition facts to a list of foods)
+- Classify and tag sales leads with company metadata
 
-- Provide free-form text input for faster filling of complex HTML forms
-- Enrich a list of food items with nutrition facts
-- Tag sales leads with more details about the company
-
-Behind the scenes, Nuabase runs the LLM transformation as async jobs, and once ready, call your server API with the results using Webhooks. It can also stream the result directly to your front-end using SSE. You can also see all requests and responses as they happen in the [Nuabase Console](https://console.nuabase.com). All outputs are guaranteed to match the schema you specified.
-
-One major reason I built Nuabase is the need for granular, row-level caching. For example, let's say you want to classify your bank transaction entries, and map them to your chart of accounts. With Nuabase's row-level caching, it will only send new entries to the LLM. Any specific entry that it has seen before will be returned from the cache. This also means you can make LLM requests multiple times with identical values, and after the first time, they will return immediately without needing to go through the LLM.
-
-## Usage at a glance
-
-**1. Input.** Start with the data you want to send to the LLM:
-
-```ts
-const leads = [{ id: 'lead-101', notes: 'Growth-stage SaaS, ~80 employees, wants a demo.' }];
-```
-
-**2. Desired shape.** Describe the structure you expect back:
-
-```ts
-const LeadInsights = z.object({
-  industry: z.string(),
-  company_size: z.enum(['SMB', 'Mid-market', 'Enterprise']),
-});
-```
-
-**3. Call the API.** Use `list()` for array operations:
-
-```ts
-const nua = Nua.gateway({ apiKey: 'YOUR_API_KEY' });
-
-const result = await nua.list('Classify each lead with industry and company_size bucket.', {
-  input: leads,
-  primaryKey: 'id',
-  output: { name: 'leadInsights', schema: LeadInsights },
-});
-```
-
-**4. Use the result.** Check for success and access typed data:
-
-```ts
-if (!result.success) throw new Error(result.error);
-console.log(result.data[0].leadInsights);
-// -> { industry: 'Software', company_size: 'Mid-market' }
-```
+---
 
 ## Quick Start
 
-1. Add the Nuabase SDK along with Zod:
+### 1. Install
 
 ```bash
 npm install nuabase zod
 ```
 
-2. Get your API key from the [Nuabase Console](https://console.nuabase.com/dashboard/api-keys/new).
-
-3. Set `NUABASE_API_KEY` environment variable, or pass it directly in `Nua.gateway({ apiKey: "KEY" })`:
+### 2. Initialize and Call
 
-## Lead Enrichment Example
+Configure `Nua.direct()` with an LLM provider API key (or a [local agent](#2-local-coding-agent-nodejs-only)), define your expected Zod schema, and call `get()` or `list()`:
 
 ```ts
 import { Nua } from 'nuabase';
 import { z } from 'zod';
 
-const nua = Nua.gateway({ apiKey: 'API-KEY' });
+// 1. Initialize client
+const nua = Nua.direct({
+  providers: { openrouter: { apiKey: process.env.OPENROUTER_API_KEY! } },
+});
 
+// 2. Define output schema
 const LeadInsights = z.object({
   company_name: z.string(),
   industry: z.string(),
@@ -78,7 +40,8 @@ const LeadInsights = z.object({
   recommended_follow_up: z.enum(['Call', 'Email', 'Event']),
 });
 
-const rows = [
+// 3. Prepare input data
+const leads = [
   {
     leadId: 'lead-101',
     name: 'Acme Analytics',
@@ -89,34 +52,24 @@ const rows = [
     name: 'Bright Logistics',
     notes: 'Regional freight operator asking for pricing via email. 12 depots across the Midwest.',
   },
-  {
-    leadId: 'lead-103',
-    name: 'Nimbus Retail',
-    notes:
-      'Enterprise retailer. Mentioned they will send the procurement team to our booth at NRF.',
-  },
 ];
 
-const response = await nua.list(
-  'Summarize each inbound lead by extracting company_name, industry, company_size bucket (SMB, Mid-market, Enterprise), and the recommended_follow_up channel (Call, Email, or Event) based on their notes.',
+// 4. Execute batch request (sends all rows in a single LLM request)
+const result = await nua.list(
+  'Extract company_name, industry, company_size, and recommended_follow_up from each lead.',
   {
-    input: rows,
+    input: leads,
     primaryKey: 'leadId',
     output: { name: 'leadInsights', schema: LeadInsights },
   }
 );
 
-if (!response.success) {
-  console.error(response.error);
-  return;
+// 5. Access typed output
+if (!result.success) {
+  throw new Error(result.error);
 }
 
-response.data.forEach(({ leadId, leadInsights }) => {
-  // leadInsights satisfies the LeadInsights schema
-  console.log(leadId, leadInsights.company_name, leadInsights.industry, leadInsights.company_size);
-});
-
-console.log(response.data);
+console.log(result.data);
 // -> [
 //   {
 //     leadId: 'lead-101',
@@ -128,200 +81,280 @@ console.log(response.data);
 //     },
 //   },
 //   // ...
-// ];
+// ]
 ```
 
-The default invocation waits for completion and returns the full result. Use `nua.queueList()` to submit an asynchronous job and receive streaming updates via SSE.
+---
 
-## Why Nuabase
+## Core Methods
 
-- Type-safe from prompt to runtime: Zod schemas compile to JSON Schema, and the SDK re-validates every response before you see it.
-- Zero glue code: Nuabase runs the queueing, retries, webhooks, SSE streaming, and polling so your application code stays clean.
-- Built-in performance: granular caching, cost attribution, and usage metrics come for free on every request.
-- Production visibility: every run shows up in the Nuabase dashboard with logs, prompt/response history, and tracing ids.
+### `nua.get(prompt, options?)`
 
-## API Response
+Generates a single value. Omit `options` to receive a plain `string`, or pass an `output` schema for a typed object or primitive.
 
-Every call returns a discriminated union. When `success` is `false`, you get an error object. Otherwise `success` is `true`, and `data` contains your typed output along with metadata.
+```ts
+// Plain string response
+const joke = await nua.get('Tell me a one-line joke');
+if (joke.success) console.log(joke.data); // string
 
-**Success**
+// Typed structured response
+const address = await nua.get('Extract the postal address', {
+  input: 'Ship to 123 Main St, Springfield, IL 62701',
+  output: { name: 'address', schema: AddressSchema },
+});
+if (address.success) console.log(address.data); // z.infer<typeof AddressSchema>
+```
 
-| Field       | Type                                                                  | Description                                        |
-| ----------- | --------------------------------------------------------------------- | -------------------------------------------------- |
-| `success`   | `true`                                                                | Indicates that the request completed successfully. |
-| `data`      | `T` (for `get`) or `Array<{ [pk]: value; [output]: T }>` (for `list`) | The typed result matching your schema.             |
-| `usage`     | `{ promptTokens, completionTokens, totalTokens }`                     | Token usage statistics for the LLM request.        |
-| `model`     | `string`                                                              | The LLM model used for this request.               |
-| `latencyMs` | `number`                                                              | Request latency in milliseconds.                   |
-| `source`    | `'gateway'` \| `'direct'`                                             | Which backend processed the request.               |
-| `meta`      | `object`                                                              | Additional metadata (varies by source).            |
+**Options:**
 
-**Gateway-specific metadata** (`meta` when `source` is `'gateway'`):
+* `input?: unknown` – Context or data to include with the prompt.
+* `output: { name: string; schema: ZodSchema }` – Identifier and Zod schema for the output.
+* `model?: ModelInput` – Override the client's default model for this call.
 
-| Field        | Type      | Description                               |
-| ------------ | --------- | ----------------------------------------- |
-| `requestId`  | `string`  | Unique identifier for tracing.            |
-| `cached`     | `boolean` | Whether the result was served from cache. |
-| `llmUsage`   | `object`  | Token usage from LLM calls.               |
-| `cacheUsage` | `object`  | Token usage served from cache.            |
+### `nua.list(prompt, options)`
 
-**Direct-specific metadata** (`meta` when `source` is `'direct'`):
+Processes an array of records in a **single request**. Each returned row carries the `primaryKey` value the model echoed back, next to the output. Rows can come back in a different order than the input, so match them to your input by key.
 
-| Field               | Type                         | Description                                                                                               |
-| ------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `engine`            | `'http'` \| `'local-agent'`  | Whether an LLM provider's API or a coding agent on this machine answered.                                 |
-| `schemaEnforcement` | `'in-prompt'` \| `'native'`  | Whether the schema was described in the prompt or enforced by the engine. Output is validated either way. |
-| `provider`          | `string`                     | `engine: 'http'` only. The LLM provider.                                                                  |
-| `agent`             | `'claude-code'` \| `'codex'` \| `'pi'` | `engine: 'local-agent'` only. Which coding agent answered.                                                |
-| `costUsdEstimate`   | `number \| undefined`        | `engine: 'local-agent'` only. The agent's own estimate. On a subscription this is not what you pay.       |
+```ts
+const result = await nua.list('Classify each lead', {
+  input: leads,
+  primaryKey: 'id',
+  output: { name: 'classification', schema: ClassificationSchema },
+});
 
-**Error**
+if (result.success) {
+  result.data.forEach((row) => console.log(row.id, row.classification));
+}
+```
 
-| Field       | Type                      | Description                         |
-| ----------- | ------------------------- | ----------------------------------- |
-| `success`   | `false`                   | Indicates the request failed.       |
-| `error`     | `string`                  | Message describing the error.       |
-| `source`    | `'gateway'` \| `'direct'` | Which backend returned the error.   |
-| `latencyMs` | `number`                  | Time until failure in milliseconds. |
+**Options:**
 
-## SDK API
+* `input: Array<Record<string, unknown>>` – Array of objects to process.
+* `primaryKey: string` – Unique key on each input object. Each output row carries it, so you can match rows to inputs.
+* `output: { name: string; schema: ZodSchema }` – Property name and Zod schema attached to each returned row.
+* `model?: ModelInput` – Override the client's default model for this call.
 
-### Constructors
+---
 
-**`Nua.gateway(config?)`**
-Creates a client that connects to the Nuabase API gateway. Use this for production deployments with caching, request tracking, and async job support.
+## Client Configuration (`Nua.direct`)
 
-- `apiKey?: string` – API key for authentication. Defaults to `process.env.NUABASE_API_KEY`.
-- `baseUrl?: string` – Override the API host. Defaults to `https://api.nuabase.com`.
+`Nua.direct(config)` runs in-process using one of two execution engines: **HTTP Providers** or a **Local Coding Agent**.
 
-**`Nua.direct(config)`**
-Creates a client that runs casts in this process instead of through the gateway. Use this for serverless, edge functions, or CLI tools where you don't need the gateway infrastructure. It runs on one of two kinds of engine, chosen by the config.
+### 1. HTTP Providers
 
-With API keys for LLM providers:
+Call LLM APIs directly using your own API keys:
 
-- `providers: { groq?: { apiKey: string }, cerebras?: { apiKey: string }, gemini?: { apiKey: string }, openrouter?: { apiKey: string } }` – Provider credentials.
-- `model?: ModelInput` – Optional default model. Omit it to use `{ alias: 'fast' }`.
+```ts
+const nua = Nua.direct({
+  providers: {
+    groq: { apiKey: '...' },
+    cerebras: { apiKey: '...' },
+    gemini: { apiKey: '...' },
+    openrouter: { apiKey: '...' },
+    deepseek: { apiKey: '...' },
+  },
+  model: { alias: 'fast' }, // optional default; defaults to { alias: 'fast' }
+});
+```
 
-Model inputs are objects, not provider-prefixed strings:
+**Specifying Models:**
+Models can be set globally on the client or per-call using either a provider-specific model object or an alias. Each alias lists provider models in a fixed order and uses the first one whose provider you supplied an API key for: `{ alias: 'fast' }` tries Cerebras, then Groq, then OpenRouter. If you have a key for none of an alias's providers, the call fails. Some aliases, such as `sonnet`, only go through OpenRouter.
 
 ```ts
-await nua.get('Extract the company name', {
+// Specific provider and model
+await nua.get('Extract company name', {
   output: { name: 'companyName', schema: z.string() },
-  model: { provider: 'openrouter', model: 'z-ai/glm-5.2' },
+  model: { provider: 'openrouter', model: 'z-ai/glm-5.3-flash' },
 });
 
-await nua.get('Extract the company name', {
+// Provider-agnostic alias
+await nua.get('Extract company name', {
   output: { name: 'companyName', schema: z.string() },
   model: { alias: 'fast' },
 });
 ```
 
-With a coding agent on this machine (Node.js only):
+### 2. Local Coding Agent (Node.js only)
+
+Run prompts through a coding agent CLI already installed and logged in on your machine (`claude -p`, `codex exec`, or `pi --mode json`). This uses your existing CLI login or subscription—no API key required.
 
-- `localAgent: LocalAgent` – Created with `localAgent()` or `findLocalAgent()` from `nuabase/local-agent`.
+Import helpers from `nuabase/local-agent` (kept at a separate entry point so the main `nuabase` entry point stays free of Node built-ins, which edge runtimes such as Cloudflare Workers or Vercel Edge lack):
 
 ```ts
 import { Nua } from 'nuabase';
-import { detectLocalAgents, findLocalAgent, localAgent } from 'nuabase/local-agent';
+import { localAgent, findLocalAgent, detectLocalAgents } from 'nuabase/local-agent';
 
-const nua = Nua.direct({ localAgent: localAgent({ agent: 'claude-code', model: 'haiku' }) });
+// Option A: Target a specific agent
+const nua = Nua.direct({
+  localAgent: localAgent({ agent: 'claude-code', model: 'haiku' }),
+});
 
-// Or use the first agent that is installed and logged in:
-const auto = Nua.direct({ localAgent: await findLocalAgent() });
+// Option B: Automatically pick the first installed & logged-in agent (checks Claude Code first)
+const autoNua = Nua.direct({
+  localAgent: await findLocalAgent(),
+});
 
+// Optional: Inspect available agents on the machine (makes no model calls)
 const agents = await detectLocalAgents();
-// [{ agent: 'claude-code', installed: true, loggedIn: true, version: '...', binaryPath: '...' }, ...]
+// -> [{ agent: 'claude-code', installed: true, loggedIn: true, version: '...', binaryPath: '...' }, ...]
 ```
 
-This runs a coding-agent CLI already installed and logged in on this machine, in its headless mode (`claude -p`, `codex exec`, or `pi --mode json`). Calls use the user's own logged-in subscription or provider login, so no API key is needed. `get()` and `list()` behave as with providers: the output is validated against your schema and typed the same way. Queue operations are not supported. `nuabase/local-agent` is a separate entry point so that browser bundles of `nuabase` never include it.
+**Agent Functions & Options:**
 
-The agent is set up once, when you create it. If you install an agent or log in after that, create a new one.
+* `localAgent(config)` – Configures a named agent (`'claude-code' | 'codex' | 'pi'`). Throws immediately if the executable isn't found; fails on the first call if not logged in. Note: Agent lookup happens once at creation.
+* `findLocalAgent(options?)` – Checks version and login status across supported CLIs (without making model calls) and resolves to the first ready agent, or rejects if none are available.
 
-**`localAgent(config)`** sets up a named agent. It throws right away if the agent's executable cannot be found; if the agent is not logged in, the first call fails with that error.
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `agent` | `'claude-code' \| 'codex' \| 'pi'` | Required for `localAgent()` | Which CLI agent to run. |
+| `binaryPath` | `string` | Looked up on `PATH` | Path to executable (`localAgent` only). On Windows, point to a native executable (`.cmd` shims are not supported). |
+| `model` | `string` | Agent's default | The agent's own model name for calls that name no model. Claude Code accepts aliases (`'haiku'`, `'sonnet'`, `'opus'`), and so does a per-call `model: { alias }`. Codex and Pi have no aliases: Codex uses its own model names; Pi uses `'provider/id'` (e.g., `'openrouter/z-ai/glm-5.3-flash'`). |
+| `effort` | `'low' \| 'medium' \| 'high'` | Agent's default | How hard the model thinks, as the CLI's own setting: Claude Code `--effort`, Codex `model_reasoning_effort`, Pi `--thinking`. |
+| `timeoutMs` | `number` | `180000` | Maximum execution time per call in milliseconds. |
+| `concurrency` | `number` | `2` | Maximum concurrent agent processes. |
+| `auth` | `'subscription' \| 'inherit'` | `'subscription'` | `'subscription'` strips env vars like `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` so calls bill your logged-in plan instead of API keys. |
+| `logger` | object | `console` | Object with `debug`, `info`, `warn`, and `error` methods for call and retry logs. |
 
-- `agent: 'claude-code' | 'codex' | 'pi'`
-- `binaryPath?: string` – Path to the agent executable. Defaults to looking it up on `PATH`. On Windows, point this at a native executable; `.cmd` shims are not supported.
-- and the options below.
+`agent.with({ model, effort, timeoutMs })` returns the same agent with other call options. It shares the agent's executable, environment, logger and `concurrency` limit, so one `localAgent()` per CLI can serve casts on several of its models without running more processes at once than the limit allows. Options left out keep the agent's; a `model` or `effort` given as `undefined` is the CLI's default.
 
-**`findLocalAgent(options?)`** returns a promise of the first agent that is installed and logged in, trying Claude Code first. It rejects when there is none. Checking runs each CLI's version and login-status commands, which make no model calls.
-
-Options for both:
-
-- `model?: string` – The agent's own model name, e.g. `'haiku'` for Claude Code, for calls that name no model. Defaults to the agent's default. Per-call `model: { alias }` works for aliases the agent understands (`haiku`, `sonnet`, `opus` for Claude Code). Codex and Pi have no aliases: pass one of their own model names, and for Pi a `provider/id` name such as `'openrouter/z-ai/glm-5.2'`.
-- `timeoutMs?: number` – Per-call limit. Defaults to `180000`.
-- `concurrency?: number` – Maximum agent processes at once. Defaults to `2`.
-- `auth?: 'subscription' | 'inherit'` – `subscription` (default) hides `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and similar variables from the agent so it bills the logged-in plan rather than an API key.
-- `logger?` – An object with `debug`, `info`, `warn` and `error` methods, where calls and retries are logged. Defaults to the console.
+```ts
+const codex = localAgent({ agent: 'codex', concurrency: 2 });
+const quick = Nua.direct({ localAgent: codex.with({ model: 'gpt-5.6-terra', effort: 'low' }) });
+const careful = Nua.direct({ localAgent: codex.with({ model: 'gpt-5.6-sol', timeoutMs: 300_000 }) });
+// Both run on the same two processes at most.
+```
 
-How it works: each call runs the agent in a fresh, empty temporary directory with its tools, project settings and MCP servers turned off. The schema is wrapped as `{ value: ... }` (the agents require an object at the top level) and passed to the agent's own schema option. Codex only accepts OpenAI strict-mode schemas, so a schema with optional properties or open-ended objects is instead described in the prompt, and the output is validated as usual. Pi has no schema flag at all, so its schemas are always described in the prompt. If an agent rejects a schema, the call is retried with the schema in the prompt. `maxTokens` has no CLI equivalent and is ignored. Calls count against the user's plan limits; check each vendor's terms before offering this to other users.
+> **Note:** Local agent calls count against your personal subscription limits. Check each vendor's terms before exposing local-agent execution to end users.
 
-### Methods
+### Interactive Agent Sessions (Node.js only)
 
-**`nua.get(prompt)`**
-Returns a simple string response from the LLM.
+Hand a prompt to the user's coding agent as an interactive session they carry on in a terminal, in their own project (unlike casts, which run in an empty sandbox):
 
 ```ts
-const result = await nua.get('Tell me a joke');
-if (result.success) console.log(result.data); // string
+import { startAgentSession } from 'nuabase/local-agent';
+
+const session = await startAgentSession({
+  agent: 'claude-code',
+  cwd: '/path/to/project',
+  model: 'opus',
+  approval: 'auto',
+  prompt: 'Fix the failing import described in notes.md',
+  dir: '/path/to/project/tmp/agent-sessions',
+});
+
+switch (session.kind) {
+  case 'opened': // macOS: a new terminal window is running the agent
+    break;
+  case 'command': // elsewhere: the user starts it
+    console.log(`Run in a terminal: ${session.files.command}`);
+    break;
+  case 'open_failed': // macOS, but the window didn't open (session.error); the files are written
+    console.log(`Couldn't open a terminal (${session.error}). Run: ${session.files.command}`);
+    break;
+  case 'refused': // 'unsupported_platform' | 'prompt_too_long' | 'agent_not_found'; nothing written
+    console.error(session.message);
+}
 ```
 
-**`nua.get(prompt, options)`**
-Returns a typed single value. Parameters:
+It writes the prompt to its own file (`0600`) and a launcher (`0700`) that passes it to the agent as one argument after `--`. Quotes, backticks and `$NAMES` in the prompt reach the agent as written, and the prompt can't set the agent's flags or run commands. Neither file is ever overwritten or deleted. On macOS the launcher opens in a new window of the user's terminal app (`open`, which needs no Automation permission).
 
-- `prompt: string` – Natural-language instructions sent to the LLM.
-- `options.input?: unknown` – Optional input data to include in the prompt.
-- `options.output: { name: string; schema: ZodSchema }` – Output name and Zod schema.
+Expected failures come back as `kind: 'refused'`, with nothing written: Windows, which can't run the launcher (`unsupported_platform`); a prompt of 128 KiB or more on Linux, which caps a single argument at that size (`prompt_too_long`); and an agent that isn't on `PATH` when no `binaryPath` is given (`agent_not_found`). It throws only for an unknown `agent` or a `name` already used.
 
-```ts
-const result = await nua.get('Extract the address', {
-  input: '123 Main St, Springfield, IL 62701',
-  output: { name: 'address', schema: AddressSchema },
-});
-if (result.success) console.log(result.data); // typed as z.infer<typeof AddressSchema>
-```
+`agentSessionMode(platform?)` says beforehand how a session would start, for showing the right button: `'terminal'` on macOS, `'command'` on other POSIX systems, `'none'` on Windows.
 
-**`nua.list(prompt, options)`**
-Processes an array of items. Parameters:
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `agent` | `'claude-code' \| 'codex' \| 'pi'` | Required | Which CLI agent to start. |
+| `binaryPath` | `string` | Looked up on `PATH` | Path to the executable. The launcher runs it by this absolute path, whatever the terminal's `PATH`. |
+| `cwd` | `string` | Required | The project the agent works in. It loads the project's `AGENTS.md` / `CLAUDE.md`. |
+| `model` | `string` | Agent's default | The agent's own model name. |
+| `approval` | `'ask' \| 'auto'` | `'ask'` | `'auto'` starts the agent's auto mode (Claude Code `--permission-mode auto`, Codex `--approve-for-me`, Pi `--approve`). Its reviewer, not the user, approves routine edits and commands, and stops risky ones. |
+| `prompt` | `string` | Required | The session's first message. |
+| `dir` | `string` | Required | Where both files are written. Created if missing. |
+| `name` | `string` | `<UTC time>-<agent>-<4 hex digits>` | The files' name without extension. Neither file may exist yet. |
+| `platform` | `NodeJS.Platform` | `process.platform` | The platform the launcher is for. |
 
-- `prompt: string` – Natural-language instructions for each item.
-- `options.input: Array<Record<string, unknown>>` – Rows to process.
-- `options.primaryKey: string` – Field that uniquely identifies each row.
-- `options.output: { name: string; schema: ZodSchema }` – Output configuration.
+---
 
-```ts
-const result = await nua.list('Classify each lead', {
-  input: leads,
-  primaryKey: 'id',
-  output: { name: 'classification', schema: ClassificationSchema },
-});
-if (result.success) {
-  result.data.forEach((row) => console.log(row.id, row.classification));
-}
-```
+## Response Format & Error Handling
+
+Every `get()` and `list()` call returns a discriminated union (`result.success`). Every failure of the LLM call itself comes back as `success: false`.
+
+The call rejects (throws) only for invalid arguments, before anything is sent: an empty prompt, a non-array `input`, an empty `primaryKey`, or a Zod schema that JSON Schema can't express (such as `z.date()`).
+
+### Success (`result.success === true`)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `success` | `true` | Request succeeded and passed schema validation. |
+| `data` | `T` or `Array<{ [pk]: K } & { [output]: T }>` | Validated output matching your schema. |
+| `usage` | `{ promptTokens, completionTokens, totalTokens, promptCacheReadTokens?, promptCacheWriteTokens? }` | Token usage stats (`promptCache*` included when reported by the provider as subsets of `promptTokens`). |
+| `model` | `string` | What answered: `provider:model` (e.g., `openrouter:z-ai/glm-5.3-flash`) or `agent:model` (e.g., `claude-code:haiku`; `default` when the agent's model isn't known). |
+| `latencyMs` | `number` | Total request duration in milliseconds, including retries. |
+| `source` | `'direct'` | Indicates the request executed in-process. |
+| `meta` | `DirectMeta` | Execution details (see table below). |
+
+**`DirectMeta` (`result.meta`):**
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `engine` | `'http' \| 'local-agent'` | Execution engine used. |
+| `schemaEnforcement` | `'native' \| 'in-prompt'` | Whether the engine enforced the schema natively or via prompt instructions. The output is validated either way. |
+| `provider` | `string` | *(`engine: 'http'` only)* LLM provider name. |
+| `agent` | `'claude-code' \| 'codex' \| 'pi'` | *(`engine: 'local-agent'` only)* Local agent CLI used. |
+| `model` | `string \| undefined` | The provider's model, or the model the agent reported or was asked for (`undefined` when neither is known). |
+| `costUsdEstimate` | `number \| undefined` | *(`engine: 'local-agent'` only)* The CLI's estimated API cost (does not reflect subscription billing). |
+
+### Error (`result.success === false`)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `success` | `false` | Request failed (see retries below). |
+| `error` | `string` | Error description. |
+| `source` | `'direct'` | Indicates the request executed in-process. |
+| `latencyMs` | `number` | Time elapsed until failure in milliseconds. |
+
+> **💡 Tip: Maximize Prompt Caching**
+> Keep your `prompt` string static across calls and pass dynamic values via `input`. Nuabase places the prompt and schema at the beginning of the payload so providers can cache that prefix. Cache reads are heavily discounted—whereas on providers like Claude, changing the prompt prefix on every call incurs a 25% cache-write premium without ever getting a cache hit.
+
+---
+
+## How It Works Under the Hood
 
-**`nua.queueGet(prompt, options?)`** _(Gateway mode only)_
-Submits an async job for single-value operations. Returns `{ success: true, jobId }`.
+Each `get()` or `list()` call converts your Zod schema to JSON Schema to tell the model the shape, sends it alongside your prompt and input data, and parses the returned payload with your Zod schema. `data` is Zod's parsed output: `.default()`s are filled in, `.transform()`s run, `.refine()` checks apply, and unknown object keys are dropped. The JSON Schema describes what the schema accepts (its input side), so `.transform()` is fine; checks it can't express, such as `.refine()`, aren't shown to the model, but a payload that fails them is retried like any other invalid output.
 
-**`nua.queueList(prompt, options)`** _(Gateway mode only)_
-Submits an async job for array operations. Returns `{ success: true, jobId }`.
+Transient errors and outputs that fail validation are **automatically retried up to 2 times**. Fatal errors fail at once: a bad API key, an agent that isn't logged in, an exhausted quota, a timeout, or a model none of your providers serves.
 
-## Next Steps
+### HTTP Provider Endpoints
 
-- Create an API key or inspect request logs in the [Nuabase Console](https://console.nuabase.com/).
-- Explore more SDK usage patterns (SSE streaming, webhooks, caching) in the full docs at https://docs.nuabase.com.
+When using `Nua.direct({ providers })`, your process makes 1 HTTPS request per call (plus up to 2 retries) directly to the selected provider:
 
-## Support
+| Provider | Endpoint |
+| --- | --- |
+| **Groq** | `https://api.groq.com/openai/v1/chat/completions` |
+| **Cerebras** | `https://api.cerebras.ai/v1/chat/completions` |
+| **Gemini** | `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent` |
+| **OpenRouter** | `https://openrouter.ai/api/v1/chat/completions` |
+| **DeepSeek** | `https://api.deepseek.com/chat/completions` |
 
-Email us at [hello@nuabase.com](mailto:hello@nuabase.com). On X at [@NuabaseHQ](x.com/NuabaseHQ).
+OpenRouter is itself a router: it forwards each request to a provider that hosts the model.
 
-## Tests
+### Local Agent Sandboxing & Schema Handling
 
-See [TESTING.md](TESTING.md)
+When using `Nua.direct({ localAgent })`, each call spawns the CLI in a fresh, empty temporary directory with all tools, project settings, and MCP servers disabled.
 
-## Credits
+* **Schema wrapping:** Because agent CLIs require a top-level object, Nuabase wraps your schema as `{ value: ... }` and passes it to the CLI's schema flag.
+* **Fallback to in-prompt schemas:**
+  * **Codex** only accepts OpenAI strict-mode schemas; schemas with optional properties or open-ended objects are injected into the prompt instead.
+  * **Pi** has no native schema flag, so schemas are always described in the prompt.
+  * If any agent rejects a native schema flag, Nuabase automatically retries with the schema injected into the prompt. The output is parsed with your Zod schema either way.
 
-The template for this package comes from https://github.com/rtivital/ts-package-template
+---
 
-## License
+## Resources & Community
 
-MIT
+* **Documentation:** [docs.nuabase.com](https://docs.nuabase.com)
+* **Testing Guide:** [TESTING.md](TESTING.md)
+* **Support:** [hello@nuabase.com](mailto:hello@nuabase.com) | [@NuabaseHQ on X](https://x.com/NuabaseHQ)
+* **Credits:** Package template based on [rtivital/ts-package-template](https://github.com/rtivital/ts-package-template)
+* **License:** MIT