nuabase 2.3.3 → 2.3.5

package/README.md

@@ -146,33 +146,43 @@ Every call returns a discriminated union. When `success` is `false`, you get an
 
 **Success**
 
-| 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).                 |
+| 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).            |
 
 **Gateway-specific metadata** (`meta` when `source` is `'gateway'`):
 
-| 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.                 |
+| 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.            |
+
+**Direct-specific metadata** (`meta` when `source` is `'direct'`):
+
+| 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'` | `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.       |
 
 **Error**
 
-| 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.                      |
+| 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. |
 
 ## SDK API
 
@@ -185,10 +195,65 @@ Creates a client that connects to the Nuabase API gateway. Use this for producti
 - `baseUrl?: string` – Override the API host. Defaults to `https://api.nuabase.com`.
 
 **`Nua.direct(config)`**
-Creates a client that calls LLM providers directly (in-process). Use this for serverless, edge functions, or CLI tools where you don't need the gateway infrastructure.
+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.
+
+With API keys for LLM providers:
+
+- `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' }`.
+
+Model inputs are objects, not provider-prefixed strings:
+
+```ts
+await nua.get('Extract the company name', {
+  output: { name: 'companyName', schema: z.string() },
+  model: { provider: 'openrouter', model: 'z-ai/glm-5.2' },
+});
+
+await nua.get('Extract the company name', {
+  output: { name: 'companyName', schema: z.string() },
+  model: { alias: 'fast' },
+});
+```
+
+With a coding agent on this machine (Node.js only):
+
+- `localAgent: LocalAgent` – Created with `localAgent()` or `findLocalAgent()` from `nuabase/local-agent`.
+
+```ts
+import { Nua } from 'nuabase';
+import { detectLocalAgents, findLocalAgent, localAgent } from 'nuabase/local-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() });
+
+const agents = await detectLocalAgents();
+// [{ 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` or `codex exec`). Calls use the user's own Claude or ChatGPT subscription, 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.
+
+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)`** 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.
+
+- `agent: 'claude-code' | 'codex'`
+- `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.
+
+**`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).
+- `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.
 
-- `model: string` – The model to use (e.g., `'gpt-4o-mini'`).
-- `providers: { openai?: { apiKey: string }, ... }` – Provider credentials.
+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. 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.
 
 ### Methods
 
@@ -196,7 +261,7 @@ Creates a client that calls LLM providers directly (in-process). Use this for se
 Returns a simple string response from the LLM.
 
 ```ts
-const result = await nua.get("Tell me a joke");
+const result = await nua.get('Tell me a joke');
 if (result.success) console.log(result.data); // string
 ```
 
@@ -208,8 +273,8 @@ Returns a typed single value. Parameters:
 - `options.output: { name: string; schema: ZodSchema }` – Output name and Zod schema.
 
 ```ts
-const result = await nua.get("Extract the address", {
-  input: "123 Main St, Springfield, IL 62701",
+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>
@@ -224,20 +289,20 @@ Processes an array of items. Parameters:
 - `options.output: { name: string; schema: ZodSchema }` – Output configuration.
 
 ```ts
-const result = await nua.list("Classify each lead", {
+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));
+  result.data.forEach((row) => console.log(row.id, row.classification));
 }
 ```
 
-**`nua.queueGet(prompt, options?)`** *(Gateway mode only)*
+**`nua.queueGet(prompt, options?)`** _(Gateway mode only)_
 Submits an async job for single-value operations. Returns `{ success: true, jobId }`.
 
-**`nua.queueList(prompt, options)`** *(Gateway mode only)*
+**`nua.queueList(prompt, options)`** _(Gateway mode only)_
 Submits an async job for array operations. Returns `{ success: true, jobId }`.
 
 ## Next Steps

package/dist/cjs/chunks/logger-Co5uZG0A.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+var logger = {};
+
+var hasRequiredLogger;
+function requireLogger() {
+  if (hasRequiredLogger) return logger;
+  hasRequiredLogger = 1;
+  Object.defineProperty(logger, "__esModule", { value: true });
+  logger.logLlmCallError = logger.logLlmCallComplete = logger.logLlmCallStart = logger.generateSpanId = logger.ConsoleLogger = void 0;
+  logger.pickHeaders = pickHeaders;
+  logger.normalizeError = normalizeError;
+  class ConsoleLogger {
+    debug(message, context) {
+      console.debug(`[DEBUG] ${message}`, context || "");
+    }
+    info(message, context) {
+      console.info(`[INFO] ${message}`, context || "");
+    }
+    warn(message, context) {
+      console.warn(`[WARN] ${message}`, context || "");
+    }
+    error(message, context) {
+      console.error(`[ERROR] ${message}`, context || "");
+    }
+  }
+  logger.ConsoleLogger = ConsoleLogger;
+  const generateSpanId = () => crypto.randomUUID();
+  logger.generateSpanId = generateSpanId;
+  function pickHeaders(headers, allowlist, redactSet) {
+    const result = {};
+    for (const [key, value] of Object.entries(headers)) {
+      const lowerKey = key.toLowerCase();
+      if (redactSet?.has(lowerKey)) {
+        result[key] = "[REDACTED]";
+      } else if (allowlist.has(lowerKey)) {
+        result[key] = Array.isArray(value) ? value.join(", ") : value ?? "";
+      }
+    }
+    return result;
+  }
+  function normalizeError(error) {
+    return error instanceof Error ? { message: error.message, stack: error.stack } : String(error);
+  }
+  const LLM_RESPONSE_HEADER_ALLOWLIST = /* @__PURE__ */ new Set([
+    "x-request-id",
+    "x-ratelimit-limit-requests",
+    "x-ratelimit-limit-tokens",
+    "x-ratelimit-remaining-requests",
+    "x-ratelimit-remaining-tokens",
+    "x-groq-region"
+  ]);
+  const logLlmCallStart = (logger2, spanId, service, method, request) => {
+    logger2.info("LLM call started", {
+      type: "llm_call_start",
+      span_id: spanId,
+      service,
+      method,
+      ...request
+    });
+  };
+  logger.logLlmCallStart = logLlmCallStart;
+  const logLlmCallComplete = (logger2, spanId, service, method, response, duration) => {
+    const { headers, ...rest } = response;
+    logger2.info("LLM call completed", {
+      type: "llm_call_complete",
+      span_id: spanId,
+      service,
+      method,
+      ...rest,
+      ...pickHeaders(headers, LLM_RESPONSE_HEADER_ALLOWLIST),
+      duration_ms: duration
+    });
+  };
+  logger.logLlmCallComplete = logLlmCallComplete;
+  const logLlmCallError = (logger2, spanId, service, method, error, duration) => {
+    logger2.error("LLM call failed", {
+      type: "llm_call_error",
+      span_id: spanId,
+      service,
+      method,
+      error: normalizeError(error),
+      duration_ms: duration
+    });
+  };
+  logger.logLlmCallError = logLlmCallError;
+  return logger;
+}
+
+exports.requireLogger = requireLogger;