@jxburros/ai-nugget 0.3.1

package/nugget/src/tokens.ts

@@ -0,0 +1,21 @@
+import type { Usage } from './types.js';
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+export function estimatedUsage(inputText: string, outputText: string): Usage {
+  return {
+    inputTokens: estimateTokens(inputText),
+    outputTokens: estimateTokens(outputText),
+    estimated: true,
+  };
+}
+
+export function mergeUsage(a: Usage, b: Usage): Usage {
+  return {
+    inputTokens: (a.inputTokens ?? 0) + (b.inputTokens ?? 0),
+    outputTokens: (a.outputTokens ?? 0) + (b.outputTokens ?? 0),
+    estimated: a.estimated || b.estimated,
+  };
+}

package/nugget/src/transport.ts

@@ -0,0 +1,148 @@
+import { AIError, classify, fromUnknown } from './errors.js';
+
+export function withTimeout(ms: number, external?: AbortSignal): {
+  signal: AbortSignal;
+  done(): void;
+  timedOut(): boolean;
+} {
+  const controller = new AbortController();
+  let didTimeOut = false;
+  const timer = setTimeout(() => {
+    didTimeOut = true;
+    controller.abort(new AIError(`Request timed out after ${ms}ms`, { kind: 'timeout' }));
+  }, ms);
+  const onAbort = () => controller.abort(external?.reason);
+  if (external) {
+    if (external.aborted) onAbort();
+    else external.addEventListener('abort', onAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    done() {
+      clearTimeout(timer);
+      external?.removeEventListener('abort', onAbort);
+    },
+    timedOut() {
+      return didTimeOut;
+    },
+  };
+}
+
+export async function fetchJson(url: string, init: RequestInit & { timeoutMs: number; provider?: string }): Promise<{
+  data: unknown;
+  status: number;
+  totalMs: number;
+}> {
+  const timeout = withTimeout(init.timeoutMs, init.signal ?? undefined);
+  const started = Date.now();
+  try {
+    const res = await fetch(url, { ...init, signal: timeout.signal });
+    const raw = await res.text().catch(() => '');
+    if (!res.ok) throw classify(res.status, raw, init.provider, res.headers);
+    return { data: raw.trim() ? tolerantJson(raw) : null, status: res.status, totalMs: Date.now() - started };
+  } catch (error) {
+    if (timeout.timedOut()) throw new AIError(`Request timed out after ${init.timeoutMs}ms`, { kind: 'timeout', provider: init.provider });
+    throw fromUnknown(error, init.provider);
+  } finally {
+    timeout.done();
+  }
+}
+
+/**
+ * POST a JSON body and return the raw {@link Response} for streaming.
+ *
+ * The caller owns the abort/timeout `signal` and is responsible for keeping it
+ * alive until the response body has been fully consumed — passing a
+ * `withTimeout()` signal here and cleaning it up only after the stream ends is
+ * what lets external cancellation and the timeout apply for the *whole* stream,
+ * not merely the connection handshake. Non-2xx responses are classified and
+ * thrown before the body is handed back.
+ */
+export async function postResponse(
+  url: string,
+  body: unknown,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+  provider: string,
+): Promise<Response> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+      signal,
+    });
+  } catch (error) {
+    throw fromUnknown(error, provider);
+  }
+  if (!res.ok) {
+    const raw = await res.text().catch(() => '');
+    throw classify(res.status, raw, provider, res.headers);
+  }
+  return res;
+}
+
+export async function* sseLines(res: Response): AsyncIterable<string> {
+  for await (const line of textLines(res)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith(':')) continue;
+    if (!trimmed.startsWith('data:')) continue;
+    const data = trimmed.slice(5).trim();
+    if (!data || data === '[DONE]') continue;
+    yield data;
+  }
+}
+
+export async function* ndjsonLines(res: Response): AsyncIterable<unknown> {
+  for await (const line of textLines(res)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      yield JSON.parse(trimmed) as unknown;
+    } catch {
+      throw new AIError('Provider returned malformed NDJSON', { kind: 'invalid_response' });
+    }
+  }
+}
+
+export async function* textLines(res: Response): AsyncIterable<string> {
+  if (!res.body) {
+    const raw = await res.text().catch(() => '');
+    for (const line of raw.split(/\r?\n/)) yield line;
+    return;
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let completed = false;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) {
+        completed = true;
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      let newlineIndex: number;
+      while ((newlineIndex = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+        yield line;
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.trim()) yield buffer;
+  } finally {
+    if (!completed) await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}
+
+function tolerantJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return { text: raw };
+  }
+}

package/nugget/src/types.ts

@@ -0,0 +1,175 @@
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface ContentPart {
+  type: 'text' | 'image';
+  text?: string;
+  imageBase64?: string;
+  mimeType?: string;
+}
+
+export interface ChatMessage {
+  role: Role;
+  content: string | ContentPart[];
+  toolCalls?: ToolCall[];        // role: 'assistant'
+  toolCallId?: string;           // role: 'tool' — answers a specific call
+  name?: string;                 // role: 'tool' — the tool's name (Gemini keys
+                                 // function responses by name, not id)
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: unknown;
+  raw?: string;
+}
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  parameters: object;
+}
+
+export interface ChatRequest {
+  model: string;
+  messages: ChatMessage[];
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  responseFormat?: { type: 'text' } | { type: 'json'; schema?: object };
+  tools?: ToolSchema[];
+  toolChoice?: 'auto' | 'none' | { name: string };
+  stopSequences?: string[];
+  signal?: AbortSignal;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Connection {
+  id: string;
+  provider: string;
+  baseUrl?: string;
+  keyRef?: KeyRef;
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+}
+
+export type KeyRef =
+  | { kind: 'none' }
+  | { kind: 'env'; name: string }
+  | { kind: 'literal'; value: string }
+  | { kind: 'stored'; ref: string }
+  | { kind: 'brokered'; ref: string };
+
+export interface KeySource {
+  resolve(ref: KeyRef): Promise<
+    | { ok: true; apiKey: string | null }
+    | { ok: false; reason: 'missing' | 'locked' | 'denied' }
+  >;
+}
+
+export interface ResolvedConnection extends Connection {
+  baseUrl: string;
+  apiKey: string | null;
+  headers: Record<string, string>;
+}
+
+export interface Usage {
+  inputTokens?: number;
+  outputTokens?: number;
+  estimated: boolean;
+}
+
+export interface ChatResult {
+  text: string;
+  toolCalls?: ToolCall[];
+  finishReason: 'stop' | 'length' | 'tool' | 'content_filter' | 'error' | 'canceled';
+  usage: Usage;
+  timing: { firstTokenMs: number | null; totalMs: number };
+  model: string;
+  source: ModelSource;
+  raw?: unknown;
+}
+
+export interface ModelSource {
+  provider: string;
+  connectionId: string;
+  baseUrl?: string;
+}
+
+export function modelRef(source: ModelSource, model: string): string {
+  return `${source.provider}/${model}`;
+}
+
+export type AIErrorKind =
+  | 'auth'
+  | 'rate_limit'
+  | 'timeout'
+  | 'network'
+  | 'server'
+  | 'invalid_request'
+  | 'invalid_response'
+  | 'context_length'
+  | 'canceled'
+  | 'policy_blocked'
+  | 'key_unavailable'
+  | 'tool_error'
+  | 'budget_exceeded';
+
+export type StreamEvent =
+  | { type: 'start'; callId: string; provider: string; model: string }
+  | { type: 'delta'; text: string }
+  | { type: 'tool_call'; call: ToolCall }
+  | { type: 'context'; kind: string; data: unknown }
+  | { type: 'retry'; attempt: number; reason: AIErrorKind; delayMs: number }
+  | { type: 'done'; result: ChatResult }
+  | { type: 'error'; error: import('./errors.js').AIError };
+
+export interface ProviderAdapter {
+  readonly provider: string;
+  chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
+  stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
+  listModels?(conn: ResolvedConnection): Promise<ModelInfo[]>;
+  health?(conn: ResolvedConnection): Promise<{ ok: boolean; detail?: string }>;
+}
+
+export interface ModelInfo {
+  id: string;
+  source: ModelSource;
+  contextWindow?: number;
+  capabilities?: string[];
+}
+
+export interface GovernancePolicy {
+  checkModel(provider: string, model: string): { allowed: true } | { allowed: false; reason: string };
+}
+
+export interface Redactor {
+  redact(text: string): string;
+}
+
+export interface TelemetrySink {
+  record(r: CallRecord): void | Promise<void>;
+}
+
+export interface CallInfo {
+  callId: string;
+  connection: Connection;
+  provider: string;
+  model: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CallRecord {
+  callId: string;
+  connectionId: string;
+  provider: string;
+  model: string;
+  startedAt: number;
+  timing: ChatResult['timing'];
+  usage: Usage;
+  finishReason: ChatResult['finishReason'];
+  error?: { kind: AIErrorKind; status?: number; message: string };
+  attempts: number;
+  metadata?: Record<string, unknown>;
+  promptChars: number;
+  responseChars: number;
+}

package/nugget/src/util.ts

@@ -0,0 +1,51 @@
+import type { ChatMessage } from './types.js';
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+export function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+export function promptChars(messages: ChatMessage[]): number {
+  return messages.reduce((sum, message) => {
+    if (typeof message.content === 'string') return sum + message.content.length;
+    return sum + message.content.reduce((partSum, part) => partSum + (part.text?.length ?? 0) + (part.imageBase64?.length ?? 0), 0);
+  }, 0);
+}
+
+export function textFromMessages(messages: ChatMessage[]): string {
+  return messages.map((message) => {
+    if (typeof message.content === 'string') return message.content;
+    return message.content.map((part) => part.text ?? '').join('');
+  }).join('\n');
+}
+
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal?.removeEventListener('abort', onAbort);
+    const timer = setTimeout(() => {
+      settled = true;
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanup();
+      reject(new DOMException('Sleep aborted', 'AbortError'));
+    };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@jxburros/ai-nugget",
+  "version": "0.3.1",
+  "private": false,
+  "type": "module",
+  "description": "Small isomorphic AI model nugget for provider calls, policy, redaction, telemetry, and agent loops.",
+  "license": "MIT",
+  "author": "jxburros",
+  "keywords": [
+    "ai",
+    "llm",
+    "openai",
+    "anthropic",
+    "gemini",
+    "ollama",
+    "typescript",
+    "telemetry"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxburros/AI-Nugget.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jxburros/AI-Nugget/issues"
+  },
+  "homepage": "https://github.com/jxburros/AI-Nugget#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "import": "./dist/agent/index.js",
+      "default": "./dist/agent/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "nugget",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
+    "test:live": "vitest run tests/live-smoke.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build:nugget": "node scripts/build-nugget.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",
+    "playwright": "^1.61.1",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.5"
+  }
+}