agent-nuvira 3.1.3 → 3.2.0

package/dist/learning/credential-fingerprint.js

@@ -0,0 +1,126 @@
+/**
+ * Credential Fingerprint — notice when the user's keys change, and re-probe.
+ *
+ * WHY THIS EXISTS. The routing pool can only contain models a probe has
+ * VERIFIED, and a probe only ever ran on a cold start or a maintenance command.
+ * So a purchase made mid-session — the exact case where a user expects the new
+ * models to appear — changed nothing: the credential was fine, the catalog was
+ * stale, and the next run would have picked the models up only if it happened to
+ * cold-start. There is no per-model entitlement API to ask ("may I buy
+ * `meta-llama/...`?" is not a question OpenRouter answers); the only honest
+ * signal is *"we sent one token with this key and it answered"*. But it is
+ * genuinely cheap to notice that the KEY SET changed and force that probe
+ * instead of waiting for an accident.
+ *
+ * WHAT IS STORED: a SHA-256 digest of the credential SHAPE — which providers are
+ * configured, a digest of each key, each base URL, each env-var presence. Never
+ * a key, not even truncated, and the digest is one-way, so the file is safe to
+ * read, copy or commit by accident. Its only job is equality.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+import { CATALOG_PROVIDER_IDS, catalogEnvVar, getCatalogProvider } from '../inference/provider-catalog.js';
+/** Sidecar file (under the memory dir) holding the last-seen credential shape. */
+export const CREDENTIAL_FINGERPRINT_FILENAME = 'credential-fingerprint.json';
+const DEFAULT_MEMORY_DIR = join(resolveNuviraHome(), 'memory');
+function memoryDir() {
+    return envBuff('MEMORY_DIR') || DEFAULT_MEMORY_DIR;
+}
+/** Path of the fingerprint sidecar (exported so tests can redirect it). */
+export function credentialFingerprintPath() {
+    return join(memoryDir(), CREDENTIAL_FINGERPRINT_FILENAME);
+}
+/** One-way digest of a secret — never the secret itself. */
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+/**
+ * The credential SHAPE, as a list of comparable lines.
+ *
+ * Exported (and separate from the hashing) so a test — or a support call — can
+ * see exactly which inputs are considered without needing to reverse a digest.
+ * The lines carry digests, never keys.
+ */
+export function credentialShapeInputs(configManager) {
+    const lines = [];
+    for (const provider of [...CATALOG_PROVIDER_IDS].sort()) {
+        const parts = [provider];
+        // 1. Config-resolved key (vault refs resolved by getProviderConfig, so a
+        //    key that moved from plaintext into the vault is NOT a change).
+        let configKey;
+        let baseUrl;
+        try {
+            const { config } = configManager.getProviderConfig(provider);
+            configKey = typeof config?.apiKey === 'string' ? config.apiKey : undefined;
+            baseUrl = typeof config?.baseUrl === 'string' ? config.baseUrl : undefined;
+        }
+        catch {
+            // A provider the manager cannot describe contributes only its env state.
+        }
+        if (configKey)
+            parts.push(`cfg:${digest(configKey)}`);
+        if (baseUrl)
+            parts.push(`url:${baseUrl}`);
+        // 2. The standard env var — presence AND digest, so replacing a key in the
+        //    environment is a change while an unrelated env tweak is not.
+        const envVar = catalogEnvVar(provider);
+        if (envVar) {
+            const fromEnv = process.env[envVar];
+            if (fromEnv)
+                parts.push(`env:${digest(fromEnv)}`);
+        }
+        // 3. Reachability class: keyless runners appear/disappear from the probe
+        //    set when their catalog entry changes, not when a key changes.
+        const entry = getCatalogProvider(provider);
+        if (entry?.keyless)
+            parts.push('keyless');
+        lines.push(parts.join('|'));
+    }
+    return lines;
+}
+/** SHA-256 digest of the credential shape. Safe to log. */
+export function credentialFingerprint(configManager) {
+    return digest(credentialShapeInputs(configManager).join('\n'));
+}
+/**
+ * Compare the current credential shape against the last one recorded and RECORD
+ * the new one.
+ *
+ * Recording on every call is what makes this fire once per change rather than
+ * once per cycle: the caller sees `changed: true` a single time and can force a
+ * probe, and every later call in the same process is a no-op. `firstRun` is
+ * reported separately because "no previous record" is not evidence of a change —
+ * a fresh machine must not be treated as though a purchase just landed.
+ */
+export function detectCredentialChange(configManager, options = {}) {
+    const path = options.path ?? credentialFingerprintPath();
+    const fingerprint = credentialFingerprint(configManager);
+    let previous;
+    try {
+        if (existsSync(path)) {
+            const raw = JSON.parse(readFileSync(path, 'utf-8'));
+            if (typeof raw?.fingerprint === 'string')
+                previous = raw.fingerprint;
+        }
+    }
+    catch {
+        // A corrupt sidecar is treated as absent — the worst case is one extra
+        // catalog probe, which is cheap and idempotent.
+    }
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify({ fingerprint, at: Date.now() }), 'utf-8');
+    }
+    catch {
+        // Best-effort: failing to record must never break a run.
+    }
+    return {
+        changed: previous !== undefined && previous !== fingerprint,
+        firstRun: previous === undefined,
+        fingerprint,
+        previous,
+    };
+}
+//# sourceMappingURL=credential-fingerprint.js.map

package/dist/learning/credential-fingerprint.js.map

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

package/dist/learning/deliverable-class.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Deliverable classification — what KIND of thing did the user actually ask
+ * for? (enterprise-grade hardening, G7.)
+ *
+ * WHY THIS EXISTS (the WhatsApp story audit):
+ * A user asked, over WhatsApp, for a 100-page Harry-Potter-style story as a
+ * PDF. Six orchestrator runs over 32 minutes ALL failed, and the reason was
+ * not model availability (507 models were eligible). The reasoner — the
+ * technical-decision layer that runs BEFORE the planner — read "write a story"
+ * and emitted:
+ *
+ *   {"language":"python","framework":"none","deliverable":"markdown_file",
+ *    "reasoning":"…a Python script is the most efficient way to read existing
+ *                 chapters, process the outline, and update the target file…"}
+ *
+ * The planner then produced ZERO prose steps: step-02 was "Create a Python
+ * script to append the story continuation", step-03 "Run the Python script".
+ * The agent built a TOOL to write the story instead of writing the story, and
+ * because the tool-creation step itself failed, nothing was written at all —
+ * the target directory did not exist afterwards.
+ *
+ * The decision layer had no vocabulary for authored work: every branch of its
+ * taxonomy (language/framework/buildCommand/architecture/deliverable) assumes
+ * the deliverable is a PROGRAM. So a creative ask could only ever be expressed
+ * as a program that emits the creative artifact.
+ *
+ * This module is the missing vocabulary. It is deliberately DETERMINISTIC and
+ * LLM-free — the classifier is a safety net that the LLM's own decision is
+ * checked against, so a weak model cannot reintroduce the category error. It
+ * runs on the raw goal before planning, and for `document`/`creative` the
+ * orchestrator plans SECTIONS instead of a program.
+ */
+/**
+ * The five kinds of work the planner knows how to plan.
+ *
+ * `code` is the historical default and keeps every software ask on its
+ * existing path — this module must never change how a code task is planned.
+ */
+export type DeliverableClass = 'code' | 'document' | 'creative' | 'data' | 'research';
+/**
+ * What a deliverable is physically MADE OF.
+ *
+ * Added for the hybrid asks: "develop a web based book which might require
+ * Python for voice assistance or interactiveness" is not one thing — it is
+ * prose + a web experience + (optionally) a Python narration service. A single
+ * `class` cannot express that, and forcing a choice is how the original audit
+ * produced a Python script instead of a story: the taxonomy only had room for
+ * one answer, and it picked the program.
+ */
+export type Substrate = 'prose' | 'web' | 'python' | 'asset' | 'data';
+/** The result of classifying a goal. */
+export interface DeliverableVerdict {
+    /** The winning class. */
+    class: DeliverableClass;
+    /** 0–1. Below `AUTHORED_CONFIDENCE_FLOOR` the caller should not override the LLM. */
+    confidence: number;
+    /** Which words drove the decision (auditable, shown in logs/traces). */
+    signals: string[];
+    /**
+     * True when the deliverable IS authored content (prose), as opposed to a
+     * program/library that manipulates it. This is the flag that switches the
+     * pipeline from "plan code steps" to "plan sections".
+     */
+    authored: boolean;
+    /**
+     * Ordered materials, primary first. A plain story is `['prose']`; an
+     * interactive web book is `['web', 'prose']` (+ `'python'` when a narration
+     * service was asked for). Always at least one entry.
+     */
+    substrates: Substrate[];
+    /**
+     * True when the deliverable is MORE THAN ONE thing joined — a book AND the
+     * site that presents it. Composite asks need a PHASED plan (scaffold first,
+     * then the content, then the experience layer), not a single-mode plan.
+     */
+    composite: boolean;
+    /**
+     * True when the deliverable must be experienced, not just read: a site to
+     * navigate, narration to play, chapters to flip through. Drives the
+     * interactivity phase and the end-to-end verification step.
+     */
+    interactive: boolean;
+}
+/**
+ * Below this the verdict is a hint, not a ruling: the caller keeps the LLM's
+ * own decision. Set high enough that a passing mention ("write a report about
+ * the API I built") cannot hijack a genuine engineering task.
+ */
+export declare const AUTHORED_CONFIDENCE_FLOOR = 0.55;
+/**
+ * Classify a goal into a deliverable class.
+ *
+ * Scoring is additive with per-signal weights rather than first-match, so a
+ * goal that mixes signals ("write a story AND package it as a CLI") resolves
+ * on the balance of evidence. Confidence is derived from the winning margin,
+ * so a clear call scores high and a coin-flip stays low — which is exactly
+ * what the caller needs to decide whether to override the LLM.
+ *
+ * Defaults to `code` when nothing matches: that preserves today's behaviour
+ * for every goal this module does not understand.
+ */
+export declare function classifyDeliverable(goal: string): DeliverableVerdict;
+/**
+ * Convenience: is this goal asking for authored content (prose) rather than a
+ * program? The orchestrator uses this one predicate to switch planning modes.
+ */
+export declare function isAuthoredGoal(goal: string): boolean;
+/**
+ * Is this a HYBRID deliverable — content plus a way to experience it?
+ *
+ * The orchestrator uses this one predicate to switch from "plan the content" to
+ * "plan the phases" (scaffold → content → experience → assets → verify). Kept
+ * here rather than in the planner so the intent vocabulary lives in one place.
+ */
+export declare function isCompositeGoal(goal: string): boolean;
+/** Human-readable substrate list, for logs, traces and prompts. */
+export declare function describeSubstrates(verdict: DeliverableVerdict): string;
+/** Human-readable label for logs, traces and prompts. */
+export declare function deliverableClassLabel(cls: DeliverableClass): string;
+/**
+ * The instruction handed to the reasoner so its technical-decision document
+ * stops pretending an authored ask is a program.
+ *
+ * This is the fix for the exact reasoning string the audit captured
+ * ("a Python script is the most efficient way to…"): the reasoner is told, in
+ * its own JSON vocabulary, that `language` must NOT be a programming language
+ * for these classes, and that building a generator is the wrong deliverable.
+ */
+export declare function authoredDeliverableGuidance(cls: DeliverableClass, substrates?: Substrate[]): string;
+//# sourceMappingURL=deliverable-class.d.ts.map

package/dist/learning/deliverable-class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliverable-class.d.ts","sourceRoot":"","sources":["../../src/learning/deliverable-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtF;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAEtE,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,KAAK,EAAE,gBAAgB,CAAC;IACxB,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAiI9C;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAqFpE;AA0FD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAEtE;AAED,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAanE;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,gBAAgB,EAAE,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,MAAM,CA0BnG"}