nuabase 2.3.4 → 2.3.7

package/README.md

@@ -165,6 +165,16 @@ Every call returns a discriminated union. When `success` is `false`, you get an
 | `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'` \| `'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.       |
+
 **Error**
 
 | Field       | Type                      | Description                         |
@@ -185,10 +195,12 @@ 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:
 
-- `model?: ModelInput` – Optional default model. Omit it to use `{ alias: 'fast' }`.
 - `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:
 
@@ -204,6 +216,45 @@ await nua.get('Extract the company name', {
 });
 ```
 
+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`, `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.
+
+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' | '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.
+
+**`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.
+
+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.
+
 ### Methods
 
 **`nua.get(prompt)`**

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;