@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/dist/resources/models/Models.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.models = exports.ModelPendingNotSupportedError = exports.ModelCapabilityError = exports.Models = void 0;
+const globals_js_1 = require("../../globals.js");
+const transaction_ts_1 = require("../transaction.js");
+const backendRegistry_ts_1 = require("./backendRegistry.js");
+const analyticsTable_ts_1 = require("./analyticsTable.js");
+const write_ts_1 = require("../analytics/write.js");
+const hdbError_ts_1 = require("../../utility/errors/hdbError.js");
+const agentLoop_ts_1 = require("./agentLoop.js");
+/**
+ * Process-wide singleton. One shared instance serves all Scopes — `scope.models`,
+ * `global.models`, and `import { models } from 'harperdb'` all alias the same object.
+ *
+ * On every call:
+ * - Resolves the configured backend via `backendRegistry`.
+ * - Reads the ALS-bound request `Context` to extract accounting context
+ *   (tenantId, handlerPath) and an `AbortSignal`. Outside an ALS scope
+ *   (app-init, internal jobs), accounting is empty and signal is undefined.
+ * - Records the call to `hdb_model_calls` via the buffered writer — both
+ *   successful and failed calls land in the table for billing visibility.
+ *   Pre-call resolution / capability errors land too, with `backend: 'unknown'`.
+ *
+ * The ALS pattern matches `resources/Table.ts:3517` and is rooted at
+ * `resources/transaction.ts:6`.
+ */
+class Models {
+    #analyticsWriter;
+    #emit;
+    constructor(analyticsWriter = (0, analyticsTable_ts_1.getModelCallAnalyticsWriter)(), 
+    // DI'd for unit tests; production wires up the module-scope `recordAction`.
+    metricEmitter = write_ts_1.recordAction) {
+        this.#analyticsWriter = analyticsWriter;
+        this.#emit = metricEmitter;
+    }
+    async embed(input, opts = {}) {
+        const { accounting, signal } = resolveCallContext(opts.signal);
+        const startedAt = performance.now();
+        let backend;
+        try {
+            backend = (0, backendRegistry_ts_1.resolveEmbedding)(opts.model);
+            requireCapability(backend, 'embed');
+            const backendOpts = { ...opts, signal, accounting };
+            const result = await backend.embed(input, backendOpts);
+            // Throw on `pending` BEFORE recording success — otherwise we'd write a
+            // success row followed by a failure row from the catch (duplicate).
+            if (result.status !== 'completed')
+                throw new ModelPendingNotSupportedError(backend.name);
+            this.#record(backend, 'embed', opts.model, accounting, undefined, result, startedAt);
+            return result.output;
+        }
+        catch (err) {
+            this.#recordFailure(backend, 'embed', opts.model, accounting, undefined, startedAt, err);
+            throw err;
+        }
+    }
+    async generate(input, opts = {}) {
+        if (opts.toolMode === 'auto') {
+            // The loop calls back through `this.generate(..., {toolMode: 'return'})` per
+            // iteration, so each backend round still flows through the single-shot path
+            // below and writes its own `hdb_model_calls` row. The outer auto call itself
+            // stays out of the analytics table — counting it would double-bill the round.
+            const { accounting, signal } = resolveCallContext(opts.signal);
+            // Fail loud, never silent: an auto loop that declares tools against a
+            // tools-incapable backend would run as a plain generation — the backend never
+            // receives the tool definitions (e.g. ollama drops them), so the model can't
+            // call anything and the loop returns a first-round answer, silently ignoring
+            // the caller's tools. Check up front rather than no-op.
+            if (inputHasTools(input))
+                requireCapability((0, backendRegistry_ts_1.resolveGenerative)(opts.model), 'tools');
+            return (0, agentLoop_ts_1.runAgentLoop)({ models: this, input, opts, accounting, signal });
+        }
+        const { accounting, signal } = resolveCallContext(opts.signal);
+        const startedAt = performance.now();
+        let backend;
+        try {
+            backend = (0, backendRegistry_ts_1.resolveGenerative)(opts.model);
+            requireCapability(backend, 'generate');
+            const backendOpts = { ...opts, signal, accounting };
+            const result = await backend.generate(input, backendOpts);
+            if (result.status !== 'completed')
+                throw new ModelPendingNotSupportedError(backend.name);
+            this.#record(backend, 'generate', opts.model, accounting, opts, result, startedAt);
+            // Propagate usage onto the returned GenerateResult so callers (notably the
+            // `toolMode: 'auto'` loop's budget tracker) can read cumulative tokens without
+            // re-querying analytics. Pure pass-through — backend usage is the source of truth.
+            return result.usage ? { ...result.output, usage: result.usage } : result.output;
+        }
+        catch (err) {
+            this.#recordFailure(backend, 'generate', opts.model, accounting, opts, startedAt, err);
+            throw err;
+        }
+    }
+    generateStream(input, opts = {}) {
+        if (opts.toolMode === 'auto') {
+            // Same rationale as `generate`: per-iteration analytics happen inside the loop
+            // when it dispatches to `this.generateStream(..., {toolMode: 'return'})`.
+            const { accounting, signal } = resolveCallContext(opts.signal);
+            // Same fail-loud guard as `generate` — a tools-incapable backend would silently
+            // stream a plain generation, ignoring the declared tools. Throws synchronously
+            // (before the iterable is returned), matching the capability-check posture below.
+            if (inputHasTools(input))
+                requireCapability((0, backendRegistry_ts_1.resolveGenerative)(opts.model), 'tools');
+            return (0, agentLoop_ts_1.runAgentLoopStream)({ models: this, input, opts, accounting, signal });
+        }
+        const { accounting, signal } = resolveCallContext(opts.signal);
+        const startedAt = performance.now();
+        let backend;
+        try {
+            backend = (0, backendRegistry_ts_1.resolveGenerative)(opts.model);
+            requireCapability(backend, 'stream');
+        }
+        catch (err) {
+            // Record pre-call failure synchronously so callers that hold but never
+            // iterate the returned iterable still produce a billing row, then rethrow.
+            // Pass `backend` (not `undefined`): when the registry hit but the capability
+            // check failed, `backend` is the resolved instance and its name belongs in
+            // the row. Only registry misses leave `backend` undefined → 'unknown'.
+            this.#recordFailure(backend, 'generateStream', opts.model, accounting, opts, startedAt, err);
+            throw err;
+        }
+        const backendOpts = { ...opts, signal, accounting };
+        return this.#wrapStream(backend, input, backendOpts, opts, accounting, startedAt);
+    }
+    async *#wrapStream(backend, input, backendOpts, opts, accounting, startedAt) {
+        let caught;
+        let completed = false;
+        try {
+            for await (const chunk of backend.generateStream(input, backendOpts)) {
+                yield chunk;
+            }
+            completed = true;
+        }
+        catch (err) {
+            caught = err;
+            throw err;
+        }
+        finally {
+            if (completed) {
+                this.#record(backend, 'generateStream', opts.model, accounting, opts, undefined, startedAt);
+            }
+            else if (caught) {
+                this.#recordFailure(backend, 'generateStream', opts.model, accounting, opts, startedAt, caught);
+            }
+            else {
+                // Stream terminated by the consumer (break / iter.return()) without an error
+                // from the backend. Treat as an aborted call rather than success — the model
+                // did real work that the caller didn't consume.
+                this.#recordFailure(backend, 'generateStream', opts.model, accounting, opts, startedAt, 'aborted');
+            }
+        }
+    }
+    #record(backend, method, model, accounting, opts, result, startedAt) {
+        const usage = result?.status === 'completed' ? result.usage : undefined;
+        this.#analyticsWriter.write(buildRecord(backend, method, model, accounting, opts, usage, startedAt, true));
+        // Also emit aggregate analytics into hdb_raw_analytics so model usage rolls up
+        // into the same per-period analytics that license enforcement and admin
+        // dashboards consume — mirrors the `db-read` pattern in Table.ts. The detailed
+        // per-call row in hdb_model_calls (above) is for forensics; this is for billing.
+        // Path is the backend name (analogous to tableName for db-read) so dashboards
+        // can break usage down by backend.
+        this.#emit(1, `model-${method}`, backend.name);
+        if (usage) {
+            const tokens = (usage.embeddingTokens ?? 0) + (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0);
+            if (tokens > 0)
+                this.#emit(tokens, `model-${method}-tokens`, backend.name);
+        }
+    }
+    #recordFailure(backend, method, model, accounting, opts, startedAt, errOrCode) {
+        const error_code = typeof errOrCode === 'string' ? errOrCode : classifyError(errOrCode);
+        this.#analyticsWriter.write({
+            ...buildRecord(backend, method, model, accounting, opts, undefined, startedAt, false),
+            error_code,
+        });
+    }
+}
+exports.Models = Models;
+function buildRecord(backend, method, model, accounting, opts, usage, startedAt, success) {
+    const record = {
+        backend: backend?.name ?? 'unknown',
+        method,
+        model,
+        tenant: accounting.tenantId,
+        app: accounting.app,
+        adapter: opts?.adapter,
+        conversation_id: opts?.conversationId,
+        latency_ms: performance.now() - startedAt,
+        success,
+    };
+    if (usage) {
+        if (usage.promptTokens !== undefined)
+            record.prompt_tokens = usage.promptTokens;
+        if (usage.completionTokens !== undefined)
+            record.completion_tokens = usage.completionTokens;
+        if (usage.embeddingTokens !== undefined)
+            record.embedding_tokens = usage.embeddingTokens;
+        if (usage.gpuMs !== undefined)
+            record.gpu_ms = usage.gpuMs;
+    }
+    return record;
+}
+function resolveCallContext(callerSignal) {
+    const ctx = transaction_ts_1.contextStorage.getStore();
+    return {
+        accounting: {
+            tenantId: extractTenantId(ctx?.user),
+            app: ctx?.handlerPath,
+        },
+        signal: callerSignal ?? ctx?.signal,
+    };
+}
+function extractTenantId(user) {
+    return user?.tenant ?? user?.tenantId ?? undefined;
+}
+/** True when `input` is the object form carrying a non-empty `tools` array. */
+function inputHasTools(input) {
+    return typeof input === 'object' && !Array.isArray(input) && Array.isArray(input.tools) && input.tools.length > 0;
+}
+function requireCapability(backend, capability) {
+    if (!backend.capabilities()[capability])
+        throw new ModelCapabilityError(backend.name, capability);
+}
+function classifyError(err) {
+    if (err && typeof err === 'object') {
+        const e = err;
+        if (e.name === 'AbortError' || e.code === 'ABORT_ERR')
+            return 'aborted';
+        if (e.name === 'ModelCapabilityError')
+            return 'capability_unsupported';
+        if (e.name === 'ModelBackendNotFoundError')
+            return 'backend_not_found';
+        if (e.name === 'ModelPendingNotSupportedError')
+            return 'pending_unsupported';
+    }
+    return 'backend_error';
+}
+class ModelCapabilityError extends hdbError_ts_1.ServerError {
+    // Deliberately does not name the requested capability beyond what was asked for —
+    // avoids enumerating what the backend *does* support in error responses.
+    constructor(backendName, capability) {
+        super(`Backend '${backendName}' does not support '${capability}'`);
+        this.name = 'ModelCapabilityError';
+    }
+}
+exports.ModelCapabilityError = ModelCapabilityError;
+class ModelPendingNotSupportedError extends hdbError_ts_1.ServerError {
+    constructor(backendName) {
+        super(`Backend '${backendName}' returned 'pending'; long-running operations are not yet supported`);
+        this.name = 'ModelPendingNotSupportedError';
+    }
+}
+exports.ModelPendingNotSupportedError = ModelPendingNotSupportedError;
+/**
+ * Process-wide `Models` singleton exposed to user code as the `models` global
+ * (and as `import { models } from 'harperdb'`).  The Models class itself holds
+ * no per-Scope or per-ApplicationScope state — the backend registry it reads
+ * from is process-wide and accounting context comes from ALS — so one shared
+ * instance is observationally identical to the per-Scope instances built in
+ * `components/Scope.ts`, with the advantage that user resources can call
+ * `models.embed(...)` without writing a `handleApplication` shim that stashes
+ * `scope.models` on a global.
+ */
+exports.models = new Models();
+(0, globals_js_1._assignPackageExport)('models', exports.models);
+//# sourceMappingURL=Models.js.map

package/dist/resources/models/Models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Models.js","sourceRoot":"","sources":["../../../resources/models/Models.ts"],"names":[],"mappings":"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"}

package/dist/resources/models/TestBackend.d.ts

@@ -0,0 +1,15 @@
+import type { BackendOpts, EmbedOpts, GenerateChunk, GenerateInput, GenerateOpts, GenerateResult, ModelBackend, ModelCallResult, ModelCapabilities } from './types.ts';
+/**
+ * Deterministic in-memory backend for Phase 1 tests.
+ *
+ * Same input always produces the same output — no external services, no model
+ * files, no network. Lets the facade, registry, accounting, and analytics
+ * paths be exercised end-to-end without an Ollama / OpenAI / fabric backend.
+ */
+export declare class TestBackend implements ModelBackend {
+    readonly name = "test";
+    capabilities(): ModelCapabilities;
+    embed(input: string | string[], _opts: BackendOpts<EmbedOpts>): Promise<ModelCallResult<Float32Array[]>>;
+    generate(input: GenerateInput, _opts: BackendOpts<GenerateOpts>): Promise<ModelCallResult<GenerateResult>>;
+    generateStream(input: GenerateInput, _opts: BackendOpts<GenerateOpts>): AsyncIterable<GenerateChunk>;
+}

package/dist/resources/models/TestBackend.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestBackend = void 0;
+/**
+ * Deterministic in-memory backend for Phase 1 tests.
+ *
+ * Same input always produces the same output — no external services, no model
+ * files, no network. Lets the facade, registry, accounting, and analytics
+ * paths be exercised end-to-end without an Ollama / OpenAI / fabric backend.
+ */
+class TestBackend {
+    name = 'test';
+    capabilities() {
+        return { embed: true, generate: true, stream: true, tools: false, adapters: false };
+    }
+    async embed(input, _opts) {
+        const texts = Array.isArray(input) ? input : [input];
+        const vectors = texts.map((t) => deterministicVector(t, 16));
+        const embeddingTokens = texts.reduce((sum, t) => sum + t.length, 0);
+        return { status: 'completed', output: vectors, usage: { embeddingTokens, latencyMs: 0 } };
+    }
+    async generate(input, _opts) {
+        const text = stringFromInput(input);
+        const content = `[TestBackend echoed]: ${text}`;
+        return {
+            status: 'completed',
+            output: { content, finishReason: 'stop' },
+            usage: { promptTokens: text.length, completionTokens: content.length, latencyMs: 0 },
+        };
+    }
+    async *generateStream(input, _opts) {
+        const text = stringFromInput(input);
+        const words = `[TestBackend stream]: ${text}`.split(' ');
+        for (const word of words) {
+            yield { deltaContent: word + ' ' };
+        }
+        yield { finishReason: 'stop' };
+    }
+}
+exports.TestBackend = TestBackend;
+function stringFromInput(input) {
+    if (typeof input === 'string')
+        return input;
+    const messages = Array.isArray(input) ? input : input.messages;
+    return messages.map((m) => m.content).join(' ');
+}
+/**
+ * Hash text into a deterministic Float32Array of the given dimension.
+ *
+ * Uses FNV-1a to seed a Mulberry32 PRNG; values are mapped to [-1, 1).
+ * Same input → same vector across runs and platforms; not a cryptographic hash.
+ */
+function deterministicVector(text, dim) {
+    let seed = 2166136261 >>> 0; // FNV-1a 32-bit offset basis
+    for (let i = 0; i < text.length; i++) {
+        seed ^= text.charCodeAt(i);
+        seed = Math.imul(seed, 16777619) >>> 0;
+    }
+    const vec = new Float32Array(dim);
+    let state = seed;
+    for (let i = 0; i < dim; i++) {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1) >>> 0;
+        t = (t + Math.imul(t ^ (t >>> 7), t | 61)) >>> 0;
+        const r = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        vec[i] = r * 2 - 1; // map [0, 1) → [-1, 1)
+    }
+    return vec;
+}
+//# sourceMappingURL=TestBackend.js.map

package/dist/resources/models/TestBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestBackend.js","sourceRoot":"","sources":["../../../resources/models/TestBackend.ts"],"names":[],"mappings":"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"}

package/dist/resources/models/agentLoop.d.ts

@@ -0,0 +1,125 @@
+/**
+ * In-process tool-call agent loop for `Models.generate({ toolMode: 'auto' })`.
+ *
+ * Each iteration: (1) call `models.generate` with the running message list,
+ * (2) if the model emitted tool calls, dispatch each via `opts.toolHandlers`,
+ * (3) append the tool results to the message list, repeat. Terminate when the
+ * model returns a non-`tool_calls` finish reason or when the iteration cap trips.
+ *
+ * Analytics: the loop calls back through `models.generate(..., {toolMode: 'return'})`
+ * per iteration so each backend round flows the single-shot path in `Models.ts` and
+ * writes its own `hdb_model_calls` row. The outer auto call stays out of the table.
+ *
+ * **Abort wiring** (commit 3). Each invocation creates a loop-level
+ * `AbortController` composed with the caller's signal via `AbortSignal.any`. The
+ * composed signal flows to both the inner `models.generate` call and the
+ * `ToolHandlerContext.signal` handlers receive. Today the loop-level controller is
+ * only fired externally (caller aborts → composed signal aborts); commit 4 wires
+ * it to also fire on budget trips so an in-flight LLM call cancels cleanly.
+ *
+ * Streaming auto path + `opts.conversation.append` hook on both sync and streaming.
+ * The streaming loop yields each round's content / tool-call deltas to the caller as
+ * they arrive, accumulates the round's tool-call assembly internally, and treats
+ * `finishReason` as an INTERNAL signal: it is stripped from every forwarded chunk and
+ * re-emitted as exactly one terminal chunk AFTER the terminal assistant turn has been
+ * persisted, so a consumer that stops on the finish-reason chunk can never race past
+ * the conversation append. Tools run between rounds; the next backend stream resumes.
+ * Budget / abort / error-mode semantics match the sync path, with one streaming-specific
+ * gap: `maxToolTokens` / `maxCostUsd` are not yet enforced for streamed calls because
+ * `GenerateChunk` doesn't expose `usage` in v1 (follow-up to extend the chunk shape +
+ * backend final-chunk handling).
+ *
+ * Resilience posture (this module is foundational infra — fail loud, never silent):
+ *   - Handler lookup uses `Object.hasOwn` + a callable check; a model-emitted tool name
+ *     that collides with an Object prototype member (`toString`, `constructor`, …) does
+ *     NOT resolve a built-in as a handler.
+ *   - Missing handler splits two ways: a name the caller DECLARED in `tools` but didn't
+ *     supply a handler for is a caller config bug (hard `ClientError(400)`); an UNdeclared
+ *     name is a model hallucination, surfaced as a recoverable tool error (`toolErrorMode`
+ *     decides recover-vs-abort).
+ *   - A token/cost budget set against a backend that reports no `usage` warns once that it
+ *     is unenforceable rather than silently no-opping.
+ *   - An incomplete streamed tool call (id without a name) is recorded in the trace + warned,
+ *     not silently dropped.
+ *   - `toolErrorMode: 'abort'` throws BEFORE the conversation sink sees the round's tool
+ *     turns, so the store never holds a recover-style error turn the model never consumed.
+ *
+ * Modes still deferred to follow-ups throw 501 at entry:
+ *   - `toolArgValidation: 'strict' | 'lenient'`  → JSON Schema validator (TBD)
+ *   - `maxToolTokens` / `maxCostUsd` (streaming) → backend `usage` on chunks (TBD)
+ *
+ * Registry seam: v1 dispatches via caller-supplied `opts.toolHandlers`. #615 replaces
+ * that lookup with a `scope.resources` resolution using the same call signature — the
+ * declared-vs-undeclared split maps onto resolvable-but-misconfigured vs unknown.
+ */
+import { ClientError, ServerError } from '../../utility/errors/hdbError.ts';
+import type { AccountingContext, GenerateChunk, GenerateInput, GenerateOpts, GenerateResult, Models, TokenUsage, ToolTraceEntry } from './types.ts';
+export interface RunAgentLoopArgs {
+    models: Models;
+    input: GenerateInput;
+    opts: GenerateOpts;
+    accounting: AccountingContext;
+    signal?: AbortSignal;
+}
+export declare function runAgentLoop(args: RunAgentLoopArgs): Promise<GenerateResult>;
+export declare function runAgentLoopStream(args: RunAgentLoopArgs): AsyncIterable<GenerateChunk>;
+/**
+ * Loop tripped one of its budgets (iterations, tokens, cost). The trace built so
+ * far rides along on `partialTrace` so callers can inspect what already ran. The
+ * loop always populates this regardless of `opts.includeToolTrace` so debugging an
+ * exhausted budget never needs a second run with tracing turned on.
+ *
+ * Extends `ClientError` — the caller set the budget, so exceeding it is a 4xx
+ * caller-bounds condition, not a Harper-internal fault. Anything that branches on
+ * `err instanceof ClientError` (e.g. "don't page on this") classifies it correctly.
+ */
+export declare class BudgetExceededError extends ClientError {
+    kind: 'iterations' | 'tokens' | 'cost';
+    partialTrace: ToolTraceEntry[];
+    constructor(kind: 'iterations' | 'tokens' | 'cost', message: string, partialTrace: ToolTraceEntry[]);
+}
+/**
+ * Surfaced under `toolErrorMode: 'abort'` when a tool handler throws (or its
+ * result fails to serialize). Carries the original throw on `.cause` and the
+ * partial trace — including the failing entry — on `.partialTrace` so callers
+ * always have the full picture on the abort path.
+ *
+ * `statusCode` mirrors the underlying error when it carries one (e.g. a handler
+ * throwing `ClientError(400)` surfaces as `ToolHandlerError(400)`), otherwise
+ * defaults to 500.
+ *
+ * **`instanceof` caveat:** extends `ServerError` regardless of `statusCode`, so a
+ * handler-thrown `ClientError(403)` becomes a `ToolHandlerError` whose `statusCode`
+ * is 403 but where `instanceof ClientError === false`. Callers that route on
+ * client-vs-server class should branch on `err.statusCode` or
+ * `err.cause instanceof ClientError`, not on `err instanceof ClientError` directly.
+ */
+export declare class ToolHandlerError extends ServerError {
+    toolName: string;
+    toolCallId: string;
+    partialTrace: ToolTraceEntry[];
+    constructor(toolName: string, toolCallId: string, partialTrace: ToolTraceEntry[], cause: unknown);
+}
+/**
+ * Test-only override. Public callers must not depend on this — it exists so unit
+ * tests can prove the `maxCostUsd` trip path works end-to-end before a real rate
+ * card lands. Leading underscore marks the intent.
+ */
+export declare function _setComputeCallCostUsdForTests(fn: (usage: TokenUsage | undefined, model: string | undefined) => number): void;
+/**
+ * Reset the cost function to the v1 stub. Pair with `_setComputeCallCostUsdForTests`
+ * in test `afterEach` so suites don't leak state into each other.
+ */
+export declare function _resetComputeCallCostUsdForTests(): void;
+/**
+ * `toolArgValidation: 'strict'` rejected a tool call's arguments against its
+ * declared `parameters` JSON Schema. Surfaces as a 400 — the model produced output
+ * that doesn't satisfy the contract the caller declared. Reserved for the
+ * validator wiring (currently the strict mode is itself gated at loop entry).
+ */
+export declare class ToolValidationError extends ClientError {
+    toolName: string;
+    toolCallId: string;
+    validationErrors: object[];
+    constructor(toolName: string, toolCallId: string, validationErrors: object[], message: string);
+}