@jxburros/ai-nugget 0.3.1

package/dist/redact.js

@@ -0,0 +1,46 @@
+const SECRET_PATTERNS = [
+    /sk-[A-Za-z0-9_-]{20,}/g,
+    /sk-proj-[A-Za-z0-9_-]{20,}/g,
+    /sk-ant-[A-Za-z0-9_-]{20,}/g,
+    /AIza[0-9A-Za-z_-]{20,}/g,
+    /gsk_[0-9A-Za-z_-]{20,}/g,
+    /xai-[0-9A-Za-z_-]{20,}/g,
+    /hf_[0-9A-Za-z]{20,}/g,
+    /nvapi-[0-9A-Za-z_-]{20,}/g,
+    /ghp_[0-9A-Za-z_]{20,}/g,
+    /github_pat_[0-9A-Za-z_]{20,}/g,
+    /glpat-[0-9A-Za-z_-]{20,}/g,
+    /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/gi,
+    /xox[baprs]-[0-9A-Za-z-]{10,}/g,
+    /AKIA[0-9A-Z]{16}/g,
+    /ASIA[0-9A-Z]{16}/g,
+    /SG\.[0-9A-Za-z_-]{10,}\.[0-9A-Za-z_-]{10,}/g,
+    /rk_live_[0-9A-Za-z]{20,}/g,
+    /pk_live_[0-9A-Za-z]{20,}/g,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
+];
+export function createDefaultRedactor(extraSecrets = []) {
+    const secrets = new Set([...extraSecrets].filter((value) => value.length >= 6));
+    return {
+        redact(text) {
+            let output = text;
+            for (const pattern of SECRET_PATTERNS)
+                output = output.replace(pattern, '[REDACTED]');
+            for (const secret of secrets)
+                output = output.split(secret).join('[REDACTED]');
+            return output;
+        },
+    };
+}
+export class SessionRedactor {
+    secrets = new Set();
+    addSecret(value) {
+        if (value && value.length >= 6)
+            this.secrets.add(value);
+    }
+    redact(text) {
+        return createDefaultRedactor(this.secrets).redact(text);
+    }
+}
+//# sourceMappingURL=redact.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,5 @@
+import type { Usage } from './types.js';
+export declare function estimateTokens(text: string): number;
+export declare function estimatedUsage(inputText: string, outputText: string): Usage;
+export declare function mergeUsage(a: Usage, b: Usage): Usage;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,18 @@
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function estimatedUsage(inputText, outputText) {
+    return {
+        inputTokens: estimateTokens(inputText),
+        outputTokens: estimateTokens(outputText),
+        estimated: true,
+    };
+}
+export function mergeUsage(a, b) {
+    return {
+        inputTokens: (a.inputTokens ?? 0) + (b.inputTokens ?? 0),
+        outputTokens: (a.outputTokens ?? 0) + (b.outputTokens ?? 0),
+        estimated: a.estimated || b.estimated,
+    };
+}
+//# sourceMappingURL=tokens.js.map

package/dist/transport.d.ts

@@ -0,0 +1,28 @@
+export declare function withTimeout(ms: number, external?: AbortSignal): {
+    signal: AbortSignal;
+    done(): void;
+    timedOut(): boolean;
+};
+export declare function fetchJson(url: string, init: RequestInit & {
+    timeoutMs: number;
+    provider?: string;
+}): Promise<{
+    data: unknown;
+    status: number;
+    totalMs: number;
+}>;
+/**
+ * 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 declare function postResponse(url: string, body: unknown, headers: Record<string, string>, signal: AbortSignal, provider: string): Promise<Response>;
+export declare function sseLines(res: Response): AsyncIterable<string>;
+export declare function ndjsonLines(res: Response): AsyncIterable<unknown>;
+export declare function textLines(res: Response): AsyncIterable<string>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.js

@@ -0,0 +1,145 @@
+import { AIError, classify, fromUnknown } from './errors.js';
+export function withTimeout(ms, external) {
+    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, init) {
+    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, body, headers, signal, provider) {
+    let res;
+    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) {
+    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) {
+    for await (const line of textLines(res)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            yield JSON.parse(trimmed);
+        }
+        catch {
+            throw new AIError('Provider returned malformed NDJSON', { kind: 'invalid_response' });
+        }
+    }
+}
+export async function* textLines(res) {
+    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;
+            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) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return { text: raw };
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/types.d.ts

@@ -0,0 +1,191 @@
+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[];
+    toolCallId?: string;
+    name?: string;
+}
+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 declare function modelRef(source: ModelSource, model: string): string;
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,4 @@
+export function modelRef(source, model) {
+    return `${source.provider}/${model}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/util.d.ts

@@ -0,0 +1,8 @@
+import type { ChatMessage } from './types.js';
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function asString(value: unknown): string | undefined;
+export declare function asNumber(value: unknown): number | undefined;
+export declare function promptChars(messages: ChatMessage[]): number;
+export declare function textFromMessages(messages: ChatMessage[]): string;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.js

@@ -0,0 +1,51 @@
+export function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+export function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+export function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+export function promptChars(messages) {
+    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) {
+    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, signal) {
+    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 });
+        }
+    });
+}
+//# sourceMappingURL=util.js.map

package/nugget/VERSION.txt

@@ -0,0 +1,2 @@
+0.3.1
+a15d2e448ed391c96856ccb9b4f423d229a7bfd684bf394a5c3d93a5fcd876f6