agent-bober 0.17.1 → 0.18.0

package/dist/medical/refusal.js

@@ -0,0 +1,131 @@
+/**
+ * RefusalDetector — pure, synchronous, 0-LLM non-emergency content-policy refusal.
+ *
+ * Classifies prescription / specific-dosing / individualized-treatment-plan requests.
+ * Conservative phrase matching: accept FALSE-NEGATIVES (fall through to 'none'),
+ * NEVER false-positive into giving medical advice. Pattern set is versioned for audit.
+ *
+ * NO async. NO fs. NO network. NO LLM import. Identical input => identical output.
+ */
+// ── Version constant ─────────────────────────────────────────────────
+/** Versioned pattern-set identifier recorded in the audit log. */
+export const REFUSAL_PATTERNSET_VERSION = "refusal-2026.06.17";
+// ── Canned refuse reason strings (NEVER model-generated) ─────────────
+// Decline + see-a-licensed-clinician. DISTINCT from 911/988 escalations —
+// no "911", "988", or "emergency" so refuse text is byte-distinct from escalation text.
+const REFUSE_PRESCRIPTION = "I can't provide a prescription or recommend a specific prescription medication. " +
+    "Please consult a licensed clinician who can evaluate you and prescribe appropriately.";
+const REFUSE_DOSING = "I can't provide a specific medication dose or dosing schedule for you. " +
+    "Please consult a licensed clinician or pharmacist for personalised dosing guidance.";
+const REFUSE_TREATMENT_PLAN = "I can't create an individualised treatment or care plan. " +
+    "Please consult a licensed clinician who can evaluate your situation and develop a plan for you.";
+/**
+ * Fixed canned reason strings per refusal category.
+ * Exported so callers can assert byte-equality (proving non-model-generation).
+ */
+export const REFUSAL_REASONS = {
+    prescription: REFUSE_PRESCRIPTION,
+    "specific-dosing": REFUSE_DOSING,
+    "individualized-treatment-plan": REFUSE_TREATMENT_PLAN,
+};
+/**
+ * Conservative rule list. Order: prescription → specific-dosing → treatment-plan.
+ * Accept false-negatives freely; NEVER fire on benign informational prompts.
+ *
+ * bober: phrase-include matching for now; upgrade to word-boundary regex or
+ *        a trie if the pattern count grows to > 50 rules.
+ */
+const RULES = [
+    // ── prescription ────────────────────────────────────────────────────
+    {
+        ruleId: "rx-request-modal",
+        category: "prescription",
+        test: (n) => n.includes("can you prescribe") || n.includes("could you prescribe"),
+    },
+    {
+        ruleId: "rx-request-write",
+        category: "prescription",
+        test: (n) => n.includes("write me a prescription") ||
+            n.includes("get me a prescription") ||
+            n.includes("prescription for me"),
+    },
+    {
+        ruleId: "rx-request-direct",
+        category: "prescription",
+        test: (n) => n.includes("prescribe me") ||
+            (n.includes("prescribe") && (n.includes(" me ") || n.includes(" me?") || n.includes(" i "))),
+    },
+    // ── specific-dosing ──────────────────────────────────────────────────
+    {
+        ruleId: "dose-quantity-mg",
+        category: "specific-dosing",
+        test: (n) => n.includes("how many mg") || n.includes("how many milligrams"),
+    },
+    {
+        ruleId: "dose-query-what",
+        category: "specific-dosing",
+        test: (n) => n.includes("what dose") || n.includes("what dosage"),
+    },
+    {
+        ruleId: "dose-query-take-mg",
+        category: "specific-dosing",
+        test: (n) => /should i take\s+\d/.test(n) ||
+            (n.includes("should i take") && (n.includes("mg") || n.includes("milligram"))),
+    },
+    {
+        ruleId: "dose-query-how-much-take",
+        category: "specific-dosing",
+        test: (n) => n.includes("how much") && n.includes("should i take"),
+    },
+    // ── individualized-treatment-plan ────────────────────────────────────
+    {
+        ruleId: "txplan-for-me",
+        category: "individualized-treatment-plan",
+        test: (n) => n.includes("treatment plan for me") || n.includes("my treatment plan"),
+    },
+    {
+        ruleId: "txplan-what-to-do",
+        category: "individualized-treatment-plan",
+        test: (n) => n.includes("what should i do to treat my") || n.includes("how do i treat my"),
+    },
+    {
+        ruleId: "txplan-personalized",
+        category: "individualized-treatment-plan",
+        test: (n) => n.includes("personalized treatment") ||
+            n.includes("personalised treatment") ||
+            n.includes("personal treatment plan"),
+    },
+    {
+        ruleId: "txplan-care-plan",
+        category: "individualized-treatment-plan",
+        test: (n) => n.includes("care plan for my") || n.includes("care plan for me"),
+    },
+];
+// ── RefusalDetector ──────────────────────────────────────────────────
+/**
+ * Detects non-emergency content-policy refusal phrases in a medical prompt.
+ *
+ * PURE + SYNCHRONOUS. No async, no fs, no network, no LLM import.
+ * Identical input => identical RefusalMatch output.
+ *
+ * bober: conservative phrase matching; novel or indirect phrasing may return
+ *        'none' and fall through to normal SOP handling (accepted risk; false-negative
+ *        is safer than false-positive into refused advice).
+ */
+export class RefusalDetector {
+    patternsetVersion = REFUSAL_PATTERNSET_VERSION;
+    /**
+     * Returns the first matching RefusalMatch, or { category: 'none' } if no
+     * rule fires. Evaluation order is prescription → specific-dosing → treatment-plan.
+     */
+    detect(prompt) {
+        const norm = prompt.toLowerCase().trim();
+        for (const rule of RULES) {
+            if (rule.test(norm)) {
+                return { category: rule.category, ruleId: rule.ruleId };
+            }
+        }
+        return { category: "none" };
+    }
+}
+//# sourceMappingURL=refusal.js.map

package/dist/medical/refusal.js.map

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

package/dist/medical/retrieval/grounding-critic.d.ts

@@ -0,0 +1,34 @@
+/** GroundingCritic — fail-closed faithfulness+completeness judge for medical synthesis output. */
+import { z } from "zod";
+import type { LLMClient } from "../../providers/types.js";
+import type { Passage } from "./medline-source.js";
+export declare const GROUNDING_PARSE_MAX_RETRIES = 1;
+export declare const GROUNDING_MAX_LLM_CALLS: number;
+export declare const GroundingVerdictSchema: z.ZodObject<{
+    verdict: z.ZodEnum<["approve", "reject"]>;
+    feedback: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    feedback: string;
+    verdict: "approve" | "reject";
+}, {
+    feedback: string;
+    verdict: "approve" | "reject";
+}>;
+export type GroundingVerdict = z.infer<typeof GroundingVerdictSchema>;
+export type ValidateGroundingResult = {
+    ok: true;
+    verdict: GroundingVerdict;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateGroundingVerdict(rawText: string): ValidateGroundingResult;
+export declare function buildGroundingSystemPrompt(question: string, answerBody: string, passages: Passage[]): string;
+export declare function getGroundingVerdict(input: {
+    llm: LLMClient;
+    model: string;
+    question: string;
+    answerBody: string;
+    passages: Passage[];
+}): Promise<GroundingVerdict>;
+//# sourceMappingURL=grounding-critic.d.ts.map

package/dist/medical/retrieval/grounding-critic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding-critic.d.ts","sourceRoot":"","sources":["../../../src/medical/retrieval/grounding-critic.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAkBvE,eAAO,MAAM,sBAAsB;;;;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAIjC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,CAgDjF;AAYD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,OAAO,EAAE,GAClB,MAAM,CAeR;AAmDD,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+B5B"}

package/dist/medical/retrieval/grounding-critic.js

@@ -0,0 +1,153 @@
+/** GroundingCritic — fail-closed faithfulness+completeness judge for medical synthesis output. */
+import { z } from "zod";
+// ── Constants ────────────────────────────────────────────────────────
+export const GROUNDING_PARSE_MAX_RETRIES = 1;
+export const GROUNDING_MAX_LLM_CALLS = 1 + GROUNDING_PARSE_MAX_RETRIES;
+// ── Prompts ──────────────────────────────────────────────────────────
+const GROUNDING_COERCION_INSTRUCTION = `Your previous response was not a valid grounding verdict.
+Output ONLY a single JSON object (no prose, no markdown fences, no tool calls) with EXACTLY this shape:
+{
+  "verdict": "approve" | "reject",
+  "feedback": "<concise feedback; empty string if approving>"
+}
+
+Rules:
+- "verdict" must be exactly "approve" or "reject".
+- "feedback" must be a string.
+- Output the JSON object and nothing else.`;
+// ── Schema + types ───────────────────────────────────────────────────
+export const GroundingVerdictSchema = z.object({
+    verdict: z.enum(["approve", "reject"]),
+    feedback: z.string(),
+});
+// ── validateGroundingVerdict (NEVER throws) ──────────────────────────
+export function validateGroundingVerdict(rawText) {
+    let parsed;
+    // Try direct parse first
+    try {
+        parsed = JSON.parse(rawText.trim());
+    }
+    catch {
+        // Try extracting JSON from markdown code fences
+        const fenceMatch = /```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/.exec(rawText);
+        if (fenceMatch) {
+            try {
+                parsed = JSON.parse(fenceMatch[1].trim());
+            }
+            catch {
+                // Fall through
+            }
+        }
+        // Try finding the first { ... } block
+        if (!parsed) {
+            const braceStart = rawText.indexOf("{");
+            const braceEnd = rawText.lastIndexOf("}");
+            if (braceStart !== -1 && braceEnd > braceStart) {
+                try {
+                    parsed = JSON.parse(rawText.slice(braceStart, braceEnd + 1));
+                }
+                catch {
+                    return {
+                        ok: false,
+                        error: `No valid JSON object found in response. Raw: ${rawText.slice(0, 200)}`,
+                    };
+                }
+            }
+            else {
+                return {
+                    ok: false,
+                    error: `No JSON object found in response. Raw: ${rawText.slice(0, 200)}`,
+                };
+            }
+        }
+    }
+    const result = GroundingVerdictSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        return { ok: false, error: issues };
+    }
+    return { ok: true, verdict: result.data };
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+function formatPassageBlock(passages) {
+    return passages
+        .map((p, i) => `[${i + 1}] ${p.title}\n${p.text}\nSource: ${p.url}`)
+        .join("\n\n");
+}
+// ── buildGroundingSystemPrompt ────────────────────────────────────────
+export function buildGroundingSystemPrompt(question, answerBody, passages) {
+    const passageBlock = formatPassageBlock(passages);
+    return (`You are an independent reviewer. The answer below was produced by another assistant ` +
+        `from ONLY the retrieved passages listed here. ` +
+        `Approve ONLY if EVERY claim in the answer is directly supported by a cited passage ` +
+        `AND the answer addresses the core of the question. ` +
+        `Reject if any claim is unsupported (faithfulness) OR the answer omits the central part ` +
+        `of the question (completeness). ` +
+        `Output ONLY {"verdict":"approve"|"reject","feedback":"..."}\n\n` +
+        `Question: ${question}\n\n` +
+        `Answer to review:\n${answerBody}\n\n` +
+        `Retrieved passages:\n${passageBlock}`);
+}
+// ── Internal: one grounding-critic call ─────────────────────────────
+async function callGroundingCritic(input) {
+    const { llm, model, question, answerBody, passages, priorText, formattedError } = input;
+    // Fresh message array — NEVER extends the prior synthesis conversation (LOCK1)
+    const firstUserContent = `Review this answer as an independent reviewer.\n\n` +
+        `Question: ${question}\n\n` +
+        `Answer to review:\n${answerBody}\n\n` +
+        `Cited passages:\n${formatPassageBlock(passages)}`;
+    let messages;
+    if (priorText !== undefined && formattedError !== undefined) {
+        // Coercion retry: 3-message shape [user, assistant, user]
+        messages = [
+            { role: "user", content: firstUserContent },
+            { role: "assistant", content: priorText },
+            {
+                role: "user",
+                content: `${GROUNDING_COERCION_INSTRUCTION}\n\nPrevious validation error:\n${formattedError}`,
+            },
+        ];
+    }
+    else {
+        // First turn: single user message
+        messages = [{ role: "user", content: firstUserContent }];
+    }
+    const response = await llm.chat({
+        model,
+        system: buildGroundingSystemPrompt(question, answerBody, passages),
+        messages,
+        jsonObjectMode: true,
+    });
+    return response.text;
+}
+// ── getGroundingVerdict (FAIL-CLOSED on parse exhaustion) ────────────
+export async function getGroundingVerdict(input) {
+    const { llm, model, question, answerBody, passages } = input;
+    const maxAttempts = GROUNDING_MAX_LLM_CALLS;
+    let lastError = "Unknown error";
+    let priorText;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const rawText = await callGroundingCritic({
+            llm,
+            model,
+            question,
+            answerBody,
+            passages,
+            priorText: attempt > 0 ? priorText : undefined,
+            formattedError: attempt > 0 ? lastError : undefined,
+        });
+        const validated = validateGroundingVerdict(rawText);
+        if (validated.ok) {
+            return validated.verdict;
+        }
+        lastError = validated.error;
+        priorText = rawText;
+    }
+    // FAIL-CLOSED inversion of critic-deep.ts:199-201 (which returns approve on exhaustion).
+    // bober: reject on parse exhaustion; this is intentional for medical safety — Sprint 2
+    //        maps a reject to re-synthesis / abstain rather than letting an unverified answer through.
+    return { verdict: "reject", feedback: "<unparseable critic output>" };
+}
+//# sourceMappingURL=grounding-critic.js.map

package/dist/medical/retrieval/grounding-critic.js.map

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

package/dist/medical/retrieval/literature.d.ts

@@ -0,0 +1,78 @@
+/** LiteratureRetriever — checks the literature-retrieval axis; returns {disabled} sync when off (ADR-6). */
+import type { EgressGuard } from "../egress.js";
+import { MedlineSource, type RetrievalOutcome } from "./medline-source.js";
+import type { LLMClient } from "../../providers/types.js";
+import type { MedicalAnswer, CriticVerdict } from "../types.js";
+/**
+ * Orchestrates literature retrieval behind the literature-retrieval egress gate.
+ *
+ * SYNCHRONOUS short-circuit: if the axis is off, return {disabled} — NO network
+ * attempt and NO MedlineSource method is called. This is the zero-egress proof.
+ */
+export declare class LiteratureRetriever {
+    private readonly egress;
+    private readonly source;
+    constructor(egress: EgressGuard, source?: MedlineSource);
+    /**
+     * Retrieve literature passages for the given query.
+     *
+     * When literature-retrieval is OFF: returns { kind: "disabled" } IMMEDIATELY,
+     * before MedlineSource is consulted — guarantees zero outbound bytes.
+     *
+     * When literature-retrieval is ON: delegates to MedlineSource.fetchPassages.
+     * Any throw from the source is caught and maps to abstain{source-error} (belt-and-braces;
+     * MedlineSource.fetchPassages itself is already fail-closed).
+     */
+    retrieve(query: string): Promise<RetrievalOutcome>;
+}
+/** Return type for synthesizeGrounded — widens MedicalAnswer with the critic gate verdict (Sprint 3). */
+export interface GroundedResult {
+    answer: MedicalAnswer;
+    verdict: CriticVerdict;
+}
+/**
+ * synthesize — single LLM call that grounds the answer in retrieved passages.
+ *
+ * Rules (non-negotiable, enforced here):
+ * - disabled/abstain outcome => abstained MedicalAnswer, citations: [], no clinical assertion.
+ * - grounded outcome => one llm.chat call; if the model abstains or returns empty => abstained.
+ * - Every non-abstained answer carries >= 1 citation derived from the passages.
+ * - LLM error (e.g. Ollama unreachable) => abstained + "model unavailable" footer, NO cloud fallback.
+ * - Never emits an uncited clinical claim.
+ *
+ * @param query - The original user question.
+ * @param outcome - The RetrievalOutcome from LiteratureRetriever.retrieve.
+ * @param llm - Injectable LLMClient (tests pass {chat: vi.fn()}).
+ * @param footer - DisclaimerComposer footer string included in every answer.
+ * @param model - Model identifier to use for synthesis (default: SYNTHESIS_MODEL).
+ */
+export declare function synthesize(query: string, outcome: RetrievalOutcome, llm: LLMClient, footer: string, model?: string): Promise<MedicalAnswer>;
+/**
+ * Worst-case LLM call budget for the grounded gate:
+ *   1 synth + GROUNDING_MAX_LLM_CALLS critic + 1 re-synth + GROUNDING_MAX_LLM_CALLS re-critic
+ * Computed from the imported constant so it tracks future changes to the critic budget.
+ */
+export declare const GROUNDED_GATE_MAX_LLM_CALLS: number;
+/**
+ * synthesizeGrounded — fail-closed gate: synthesize → critic → one re-synth → abstain.
+ *
+ * For non-grounded outcomes, delegates to synthesize (disabled/abstain handled there).
+ * For grounded outcomes:
+ *   1. synthesize → if abstained, return it
+ *   2. getGroundingVerdict → if approve, return answer
+ *   3. synthesizeWithFeedback (one re-synth with critic feedback)
+ *   4. getGroundingVerdict again → if approve, return re-synth answer
+ *   5. else → return abstainAnswer (fail-closed)
+ *
+ * Any thrown error from synthesize or the critic maps to abstainAnswer (fail-closed).
+ * Bounded by GROUNDED_GATE_MAX_LLM_CALLS (= 6 worst case today).
+ *
+ * Returns { answer, verdict } where verdict is one of:
+ *   'approve'          — gate returned an approved answer
+ *   'reject-abstained' — gate abstained after a critic reject (second reject)
+ *   'error-abstained'  — gate abstained due to a thrown error or model unavailable
+ *
+ * @param model - Model identifier to use (default: SYNTHESIS_MODEL for back-compat).
+ */
+export declare function synthesizeGrounded(query: string, outcome: RetrievalOutcome, llm: LLMClient, footer: string, model?: string): Promise<GroundedResult>;
+//# sourceMappingURL=literature.d.ts.map

package/dist/medical/retrieval/literature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literature.d.ts","sourceRoot":"","sources":["../../../src/medical/retrieval/literature.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAgB,MAAM,qBAAqB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAY,aAAa,EAAE,MAAM,aAAa,CAAC;AAK1E;;;;;GAKG;AACH,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,MAAM,EAAE,WAAW,EACnB,MAAM,gBAA4B;IAGrD;;;;;;;;;OASG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAWzD;AAQD,yGAAyG;AACzG,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;CACxB;AAqCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAwB,GAC9B,OAAO,CAAC,aAAa,CAAC,CA0ExB;AAID;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,QACmB,CAAC;AA0D5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAwB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAyDzB"}