@jxburros/ai-nugget 0.3.1 → 0.6.0

package/nugget/src/types.ts

@@ -1,3 +1,7 @@
+import type { KnownProvider } from './adapters/profiles.js';
+
+export type { KnownProvider };
+
 export type Role = 'system' | 'user' | 'assistant' | 'tool';
 
 export interface ContentPart {
@@ -41,15 +45,40 @@ export interface ChatRequest {
   stopSequences?: string[];
   signal?: AbortSignal;
   metadata?: Record<string, unknown>;
+  /**
+   * Provider-native request fields the nugget does not model as first-class
+   * options — an escape hatch so a caller can reach a capability without waiting
+   * for a library release. Merged into the outgoing provider request body:
+   * shallow at the top level, and one level deep into the provider's own nested
+   * option container (Ollama `options`, Google `generationConfig`). Examples:
+   * `{ options: { num_ctx: 8192 }, keep_alive: '30m' }` (Ollama),
+   * `{ reasoning_effort: 'high' }` (OpenAI), `{ thinking: { type: 'enabled' } }`
+   * (Anthropic), `{ safetySettings: [...] }` (Google). Values here win over the
+   * nugget's own fields on a key collision, so use with care.
+   */
+  providerOptions?: Record<string, unknown>;
 }
 
 export interface Connection {
   id: string;
-  provider: string;
+  /**
+   * A provider with a profile in the table, or any other string — an unknown
+   * key with a `baseUrl` resolves through the `openai-compat` escape hatch.
+   * The union is there for autocomplete and typo-catching; the `string & {}`
+   * arm keeps the escape hatch open.
+   */
+  provider: KnownProvider | (string & {});
   baseUrl?: string;
   keyRef?: KeyRef;
   timeoutMs?: number;
   headers?: Record<string, string>;
+  /**
+   * Idle timeout for streaming calls: aborts the stream only if no bytes arrive
+   * for this many milliseconds, resetting on every chunk. Distinct from
+   * `timeoutMs`, which bounds the total call lifetime. Set this (and a generous
+   * `timeoutMs`) for long local generations that stream slowly but healthily.
+   */
+  idleTimeoutMs?: number;
 }
 
 export type KeyRef =
@@ -95,6 +124,25 @@ export interface ModelSource {
   baseUrl?: string;
 }
 
+export interface EmbedRequest {
+  model: string;
+  /** One string, or a batch of strings embedded in a single call. */
+  input: string | string[];
+  signal?: AbortSignal;
+  metadata?: Record<string, unknown>;
+  /** Provider-native passthrough, same contract as {@link ChatRequest.providerOptions}. */
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface EmbedResult {
+  /** One vector per input, in input order. */
+  embeddings: number[][];
+  model: string;
+  usage: Usage;
+  source: ModelSource;
+  raw?: unknown;
+}
+
 export function modelRef(source: ModelSource, model: string): string {
   return `${source.provider}/${model}`;
 }
@@ -107,6 +155,8 @@ export type AIErrorKind =
   | 'server'
   | 'invalid_request'
   | 'invalid_response'
+  /** 404/410 — endpoint, deployment, or model not found (wrong baseUrl/model, or a misrouted edge). */
+  | 'not_found'
   | 'context_length'
   | 'canceled'
   | 'policy_blocked'
@@ -117,6 +167,11 @@ export type AIErrorKind =
 export type StreamEvent =
   | { type: 'start'; callId: string; provider: string; model: string }
   | { type: 'delta'; text: string }
+  // Reasoning/thinking tokens surfaced as their own channel so callers can show
+  // or discard them without them polluting `delta` (the user-facing answer).
+  // Emitted from Anthropic `thinking_delta` and OpenAI-compat `reasoning`/
+  // `reasoning_content` deltas; providers that don't stream reasoning never emit it.
+  | { type: 'reasoning'; text: string }
   | { type: 'tool_call'; call: ToolCall }
   | { type: 'context'; kind: string; data: unknown }
   | { type: 'retry'; attempt: number; reason: AIErrorKind; delayMs: number }
@@ -129,6 +184,7 @@ export interface ProviderAdapter {
   stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
   listModels?(conn: ResolvedConnection): Promise<ModelInfo[]>;
   health?(conn: ResolvedConnection): Promise<{ ok: boolean; detail?: string }>;
+  embed?(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult>;
 }
 
 export interface ModelInfo {
@@ -156,6 +212,15 @@ export interface CallInfo {
   provider: string;
   model: string;
   metadata?: Record<string, unknown>;
+  /**
+   * The fully resolved connection for this call — base URL defaulted from the
+   * provider profile and auth headers applied. Present whenever `beforeCall`
+   * runs after resolution (chat/stream and probes), letting a hook validate the
+   * *effective* endpoint (e.g. a request-time SSRF/DNS-rebinding re-check on the
+   * resolved `baseUrl`) without duplicating profile logic. The resolved
+   * `apiKey` is intentionally not exposed here.
+   */
+  resolved?: Omit<ResolvedConnection, 'apiKey'>;
 }
 
 export interface CallRecord {
@@ -172,4 +237,34 @@ export interface CallRecord {
   metadata?: Record<string, unknown>;
   promptChars: number;
   responseChars: number;
+  /**
+   * Estimated cost of this call in USD, computed by the optional `pricing` hook
+   * passed to the handler. Undefined when no pricing hook is configured or the
+   * hook returns nothing for this provider/model.
+   */
+  costUsd?: number;
+}
+
+/**
+ * Minimal [Standard Schema](https://standardschema.dev) validator surface. Any
+ * Zod / Valibot / ArkType schema (v1+) satisfies this via its `~standard`
+ * property, so `chatParsed` can validate model output against a schema the app
+ * already owns — with zero dependency added to this library.
+ */
+export interface StandardSchemaV1<Output = unknown> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+  };
+}
+
+export type StandardSchemaResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> }> };
+
+/** Output of {@link AIHandler.chatParsed}: the validated value plus the raw chat result. */
+export interface ParsedResult<T> {
+  data: T;
+  result: ChatResult;
 }

package/nugget/src/util.ts

@@ -26,6 +26,61 @@ export function textFromMessages(messages: ChatMessage[]): string {
   }).join('\n');
 }
 
+export function globalEnv(): Record<string, string | undefined> {
+  const maybeProcess = globalThis as typeof globalThis & { process?: { env?: Record<string, string | undefined> } };
+  return maybeProcess.process?.env ?? {};
+}
+
+/**
+ * Merges app-supplied {@link ChatRequest.providerOptions} into a provider
+ * request body: shallow at the top level, and one level deep for each key in
+ * `nestedKeys` where both sides are plain objects (Ollama `options`, Google
+ * `generationConfig`). Values in `providerOptions` win on collision.
+ */
+export function applyProviderOptions(
+  body: Record<string, unknown>,
+  providerOptions: Record<string, unknown> | undefined,
+  nestedKeys: readonly string[] = [],
+): Record<string, unknown> {
+  if (!providerOptions) return body;
+  const merged: Record<string, unknown> = { ...body };
+  for (const [key, value] of Object.entries(providerOptions)) {
+    const base = asRecord(merged[key]);
+    if (nestedKeys.includes(key) && base && asRecord(value)) {
+      merged[key] = { ...base, ...(value as Record<string, unknown>) };
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+/** Joins a base URL and path without producing a double slash, even if `base` ends with `/`. */
+export function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+
+/**
+ * Runs `fn` over `items` with at most `limit` in flight at once, preserving
+ * input order in the returned array. Used to probe many local models
+ * concurrently without opening an unbounded number of sockets.
+ */
+export async function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  const workerCount = Math.max(1, Math.min(limit, items.length));
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const index = next;
+      next += 1;
+      if (index >= items.length) return;
+      results[index] = await fn(items[index]!, index);
+    }
+  };
+  await Promise.all(Array.from({ length: workerCount }, worker));
+  return results;
+}
+
 export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxburros/ai-nugget",
-  "version": "0.3.1",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "Small isomorphic AI model nugget for provider calls, policy, redaction, telemetry, and agent loops.",
@@ -17,7 +17,7 @@
     "telemetry"
   ],
   "engines": {
-    "node": ">=20"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,36 +34,50 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
       "default": "./dist/index.js"
     },
     "./agent": {
       "types": "./dist/agent/index.d.ts",
       "import": "./dist/agent/index.js",
+      "require": "./dist/cjs/agent/index.js",
       "default": "./dist/agent/index.js"
     }
   },
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "dist/cjs/package.json",
     "nugget",
     "README.md",
+    "UPGRADING.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/finalize-cjs.mjs",
     "test": "vitest run",
     "test:browser": "vitest run --config vitest.browser.config.ts",
     "test:live": "vitest run tests/live-smoke.test.ts",
+    "test:coverage": "vitest run --coverage",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
     "build:nugget": "node scripts/build-nugget.mjs",
+    "demo:steel-chat": "npm run build && node examples/steel-chat/server.mjs",
     "prepublishOnly": "npm run build && npm run build:nugget"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",
-    "@vitest/browser": "^4.1.9",
-    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^9.18.0",
     "playwright": "^1.61.1",
     "typescript": "^5.8.3",
-    "vitest": "^4.1.5"
+    "typescript-eslint": "^8.21.0",
+    "vitest": "^4.1.10"
+  },
+  "overrides": {
+    "nanoid": "^3.3.17",
+    "postcss": "^8.5.23"
   }
 }