agent-bober 0.18.0 → 0.19.0

package/dist/hub/gmail-to-task.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Gmail-to-task bridge — egress-gated.
+ *
+ * Provides:
+ *   - parseGmailThread (PURE — no clock, no network)
+ *   - sanitizeConnectorError (replicates external-client.ts:69 regex)
+ *   - fromGmailTask (DI: egressAllowed + injected MCP + store + now)
+ *
+ * Egress guarantee: when egressAllowed=false, fromGmailTask throws BEFORE
+ * calling mcp.start() or mcp.callTool() — the stub callTool stays uncalled.
+ *
+ * Write path: captureTask (from task-inbox.ts) is the ONLY write path.
+ * This module never calls writeFinding/ingestFinding directly.
+ */
+import type { Finding } from "./finding.js";
+import type { FactStore } from "../state/facts.js";
+/**
+ * Minimal MCP surface fromGmailTask needs. ExternalMcpServer matches it
+ * structurally; tests inject a fake whose callTool is a vi.fn() spy.
+ */
+export interface GmailMcpLike {
+    start(): Promise<void>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    stop(): Promise<void>;
+}
+/** Default MCP tool name to read one Gmail thread. Override per connector. */
+export declare const DEFAULT_GMAIL_READ_TOOL = "gmail_read_thread";
+/** The clock-independent, id-independent subset of a Finding a thread yields. */
+export interface ParsedGmailThread {
+    title: string;
+    kind: "action";
+    status: "open";
+    tags: string[];
+}
+/**
+ * Parse a raw Gmail thread payload into a Finding-shaped record.
+ * PURE: never calls the network, never reads the clock.
+ */
+export declare function parseGmailThread(payload: unknown): ParsedGmailThread;
+/**
+ * Strip KEY=VALUE env assignments so connector tokens never surface in
+ * error messages. Matches UPPERCASE_KEY=anything-without-whitespace.
+ * Replicates the inline regex from src/mcp/external-client.ts:69 —
+ * there is no exported sanitizer to import.
+ */
+export declare function sanitizeConnectorError(msg: string): string;
+/**
+ * Fetch a Gmail thread via the injected MCP connector, parse it locally,
+ * and capture it as an open action Finding through captureTask.
+ *
+ * sc-6-2 contract: when egressAllowed is false, this function throws BEFORE
+ * calling mcp.start() or mcp.callTool() — zero network, zero MCP construction.
+ *
+ * @param args.egressAllowed - resolved from config.taskInbox?.gmailEgress
+ * @param args.mcp           - injected MCP connector (stubbed in tests)
+ * @param args.threadRef     - opaque thread reference passed to the connector
+ * @param args.store         - open FactStore for persistence
+ * @param args.now           - ISO timestamp injected at the CLI boundary (never internal)
+ * @param args.toolName      - override tool name (defaults to DEFAULT_GMAIL_READ_TOOL)
+ */
+export declare function fromGmailTask(args: {
+    egressAllowed: boolean;
+    mcp: GmailMcpLike;
+    threadRef: string;
+    store: FactStore;
+    now: string;
+    toolName?: string;
+}): Promise<Finding>;
+//# sourceMappingURL=gmail-to-task.d.ts.map

package/dist/hub/gmail-to-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmail-to-task.d.ts","sourceRoot":"","sources":["../../src/hub/gmail-to-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAKnD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAID,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAI3D,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAyCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAGpE;AAID;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,aAAa,EAAE,OAAO,CAAC;IACvB,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBnB"}

package/dist/hub/gmail-to-task.js

@@ -0,0 +1,102 @@
+/**
+ * Gmail-to-task bridge — egress-gated.
+ *
+ * Provides:
+ *   - parseGmailThread (PURE — no clock, no network)
+ *   - sanitizeConnectorError (replicates external-client.ts:69 regex)
+ *   - fromGmailTask (DI: egressAllowed + injected MCP + store + now)
+ *
+ * Egress guarantee: when egressAllowed=false, fromGmailTask throws BEFORE
+ * calling mcp.start() or mcp.callTool() — the stub callTool stays uncalled.
+ *
+ * Write path: captureTask (from task-inbox.ts) is the ONLY write path.
+ * This module never calls writeFinding/ingestFinding directly.
+ */
+import { captureTask } from "./task-inbox.js";
+// ── Constants ─────────────────────────────────────────────────────────
+/** Default MCP tool name to read one Gmail thread. Override per connector. */
+export const DEFAULT_GMAIL_READ_TOOL = "gmail_read_thread";
+/**
+ * Extract the subject from a raw Gmail thread payload.
+ * Tolerant: accepts { subject }, { messages: [{ subject }] }, or
+ * an SDK envelope { content: [{ text: '<json>' }] }.
+ * Returns "(no subject)" when nothing parseable is found.
+ */
+function extractSubject(payload) {
+    if (payload === null || typeof payload !== "object")
+        return "(no subject)";
+    const p = payload;
+    // Direct subject field
+    if (typeof p["subject"] === "string" && p["subject"].length > 0) {
+        return p["subject"];
+    }
+    // messages array
+    if (Array.isArray(p["messages"]) && p["messages"].length > 0) {
+        const first = p["messages"][0];
+        if (typeof first["subject"] === "string" && first["subject"].length > 0) {
+            return first["subject"];
+        }
+    }
+    // MCP SDK envelope: { content: [{ type: "text", text: "<json>" }] }
+    if (Array.isArray(p["content"]) && p["content"].length > 0) {
+        const item = p["content"][0];
+        if (typeof item["text"] === "string") {
+            try {
+                const inner = JSON.parse(item["text"]);
+                return extractSubject(inner);
+            }
+            catch {
+                // not JSON — ignore
+            }
+        }
+    }
+    return "(no subject)";
+}
+/**
+ * Parse a raw Gmail thread payload into a Finding-shaped record.
+ * PURE: never calls the network, never reads the clock.
+ */
+export function parseGmailThread(payload) {
+    const subject = extractSubject(payload);
+    return { title: subject, kind: "action", status: "open", tags: ["source:gmail"] };
+}
+// ── Error sanitization (replicates external-client.ts:69) ─────────────
+/**
+ * Strip KEY=VALUE env assignments so connector tokens never surface in
+ * error messages. Matches UPPERCASE_KEY=anything-without-whitespace.
+ * Replicates the inline regex from src/mcp/external-client.ts:69 —
+ * there is no exported sanitizer to import.
+ */
+export function sanitizeConnectorError(msg) {
+    return msg.replace(/\b[A-Z_][A-Z0-9_]*=\S+/g, "[redacted]");
+}
+// ── fromGmailTask ─────────────────────────────────────────────────────
+/**
+ * Fetch a Gmail thread via the injected MCP connector, parse it locally,
+ * and capture it as an open action Finding through captureTask.
+ *
+ * sc-6-2 contract: when egressAllowed is false, this function throws BEFORE
+ * calling mcp.start() or mcp.callTool() — zero network, zero MCP construction.
+ *
+ * @param args.egressAllowed - resolved from config.taskInbox?.gmailEgress
+ * @param args.mcp           - injected MCP connector (stubbed in tests)
+ * @param args.threadRef     - opaque thread reference passed to the connector
+ * @param args.store         - open FactStore for persistence
+ * @param args.now           - ISO timestamp injected at the CLI boundary (never internal)
+ * @param args.toolName      - override tool name (defaults to DEFAULT_GMAIL_READ_TOOL)
+ */
+export async function fromGmailTask(args) {
+    // sc-6-2: refuse BEFORE touching mcp — the stub's callTool must stay unused.
+    if (!args.egressAllowed) {
+        throw new Error("Gmail egress not enabled — set taskInbox.gmailEgress: true in bober.config.json to opt in.");
+    }
+    await args.mcp.start();
+    const raw = await args.mcp.callTool(args.toolName ?? DEFAULT_GMAIL_READ_TOOL, {
+        thread: args.threadRef,
+    });
+    const parsed = parseGmailThread(raw);
+    // captureTask is the ONLY write path (contract non-goal). It sets kind=action/
+    // status=open and stamps id/surfacedAt from `now`. Provenance via domain tag.
+    return captureTask(args.store, parsed.title, { domain: "gmail", now: args.now });
+}
+//# sourceMappingURL=gmail-to-task.js.map

package/dist/hub/gmail-to-task.js.map

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

package/dist/hub/hub-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * kb-hub output vault path resolution.
+ *
+ * Reads config.hub.outVault from the raw config file (bypassing Zod which
+ * strips unknown keys). Falls back to <parentOfProjectRoot>/kb-hub.
+ * Never throws.
+ */
+/**
+ * Resolve the kb-hub output vault to an ABSOLUTE path.
+ * Reads config.hub.outVault if present (resolved against projectRoot), else
+ * falls back to <parentOfProjectRoot>/kb-hub. Never throws.
+ *
+ * @param projectRoot  Absolute path to the current project root.
+ */
+export declare function resolveOutVault(projectRoot: string): Promise<string>;
+/** Target priority.md path inside the resolved out vault. */
+export declare function priorityMdPath(outVault: string): string;
+//# sourceMappingURL=hub-config.d.ts.map

package/dist/hub/hub-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-config.d.ts","sourceRoot":"","sources":["../../src/hub/hub-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc1E;AAID,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/hub/hub-config.js

@@ -0,0 +1,40 @@
+/**
+ * kb-hub output vault path resolution.
+ *
+ * Reads config.hub.outVault from the raw config file (bypassing Zod which
+ * strips unknown keys). Falls back to <parentOfProjectRoot>/kb-hub.
+ * Never throws.
+ */
+import { dirname, join, resolve } from "node:path";
+import { readJson } from "../utils/fs.js";
+// ── Config candidates ─────────────────────────────────────────────────
+const CONFIG_CANDIDATES = ["bober.config.json", ".bober/config.json"];
+// ── resolveOutVault ───────────────────────────────────────────────────
+/**
+ * Resolve the kb-hub output vault to an ABSOLUTE path.
+ * Reads config.hub.outVault if present (resolved against projectRoot), else
+ * falls back to <parentOfProjectRoot>/kb-hub. Never throws.
+ *
+ * @param projectRoot  Absolute path to the current project root.
+ */
+export async function resolveOutVault(projectRoot) {
+    for (const candidate of CONFIG_CANDIDATES) {
+        try {
+            const raw = await readJson(join(projectRoot, candidate));
+            const ov = raw.hub?.outVault;
+            if (typeof ov === "string" && ov.length > 0)
+                return resolve(projectRoot, ov);
+            break; // config existed but no outVault → fall to default
+        }
+        catch {
+            /* not found / invalid JSON → try next candidate */
+        }
+    }
+    return join(dirname(projectRoot), "kb-hub");
+}
+// ── priorityMdPath ────────────────────────────────────────────────────
+/** Target priority.md path inside the resolved out vault. */
+export function priorityMdPath(outVault) {
+    return join(outVault, "priority.md");
+}
+//# sourceMappingURL=hub-config.js.map

package/dist/hub/hub-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-config.js","sourceRoot":"","sources":["../../src/hub/hub-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,yEAAyE;AAEzE,MAAM,iBAAiB,GAAG,CAAC,mBAAmB,EAAE,oBAAoB,CAAU,CAAC;AAE/E,yEAAyE;AAEzE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,WAAmB;IACvD,KAAK,MAAM,SAAS,IAAI,iBAAiB,EAAE,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CACxB,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAC7B,CAAC;YACF,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC;YAC7B,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;YAC7E,MAAM,CAAC,mDAAmD;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAED,yEAAyE;AAEzE,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AACvC,CAAC"}

package/dist/hub/judge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Two-pass hub prioritization judge.
+ *
+ * Pass 1 (relevance): For filtered scope, applies pure-JS applyFilter with zero LLM calls.
+ * For general/decision scopes, calls the injected LLM per finding and parses with
+ * validateRelevanceVerdict (fail-closed: null drops the finding; decision scope additionally
+ * drops findings whose relevantTo is "neither" or undefined).
+ *
+ * Pass 2 (prioritization): For each survivor, fans out the four hub lenses (urgency, impact,
+ * effort, deadline-risk). Aggregate score = SUM of per-lens scores (0–40; 4 × 0–10). Reconcile:
+ * STRICT MAJORITY, FAIL-CLOSED ON TIE: passVotes > failVotes → normal ranking;
+ * passVotes ≤ failVotes → kept but tagged "flagged-for-review" (immutable copy, never mutate input).
+ *
+ * Final order: deterministic JS sort — aggregate score DESC, urgency DESC, severity DESC,
+ * dueBy ASC (undefined LAST, treated as +Infinity), id ASC. LLM never emits the final order.
+ */
+import type { LLMClient } from "../providers/types.js";
+import type { Finding } from "./finding.js";
+import { type Scope } from "./scope.js";
+/**
+ * Two-pass hub prioritization judge.
+ *
+ * @param findings  Pool of Finding[] to rank (input array and Finding objects are never mutated).
+ * @param scope     Ephemeral query scope — not persisted anywhere.
+ * @param llm       Injected LLMClient. Tests pass a ScriptedClient fake; Sprint 4 passes a real client.
+ * @param now       Injected clock for dueWithinDays math in filtered mode. Never call Date.now() here.
+ * @returns         Ranked Finding[]; tie-voted findings carry the "flagged-for-review" tag.
+ */
+export declare function rankFindings(findings: Finding[], scope: Scope, llm: LLMClient, now: Date): Promise<Finding[]>;
+//# sourceMappingURL=judge.d.ts.map

package/dist/hub/judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/hub/judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,YAAY,CAAC;AAkJrD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,OAAO,EAAE,EACnB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,OAAO,EAAE,CAAC,CAmDpB"}

package/dist/hub/judge.js

@@ -0,0 +1,177 @@
+import { applyFilter } from "./scope.js";
+import { HUB_LENS_NAMES, resolveHubLensFocus, validateRelevanceVerdict, validateLensScore, } from "./lenses.js";
+// ── Prompt helper ─────────────────────────────────────────────────────
+function buildFindingSummary(finding) {
+    const dueStr = finding.dueBy !== undefined ? `\nDue by: ${finding.dueBy}` : "";
+    const tagsStr = finding.tags.length > 0 ? `\nTags: ${finding.tags.join(", ")}` : "";
+    return (`ID: ${finding.id}\n` +
+        `Title: ${finding.title}\n` +
+        `Domain: ${finding.domain}\n` +
+        `Kind: ${finding.kind}\n` +
+        `Urgency: ${finding.urgency}/5\n` +
+        `Severity: ${finding.severity}/5\n` +
+        `Evidence: ${finding.evidence.join("; ")}` +
+        dueStr +
+        tagsStr);
+}
+// ── Pass 1: LLM relevance (general and decision scopes only) ──────────
+/**
+ * Ask the injected LLM for a per-finding relevance verdict.
+ * Returns null on parse failure (fail-closed: caller treats null as "drop").
+ * For filtered scope this function is never called (caller fast-paths).
+ */
+async function askRelevance(finding, scope, llm) {
+    const summary = buildFindingSummary(finding);
+    let system;
+    let userContent;
+    if (scope.mode === "decision") {
+        system =
+            "You are a relevance filter for a personal priority hub helping evaluate a decision. " +
+                "Determine which named option (if any) this finding informs. " +
+                'Respond ONLY with a JSON object: ' +
+                '{ "relevant": boolean, "relevantTo": "optionA" | "optionB" | "both" | "neither", "reason": string }';
+        userContent =
+            `Decision:\nOption A: ${scope.optionA}\nOption B: ${scope.optionB}\n\n` +
+                `Finding:\n${summary}\n\n` +
+                "Which option does this finding inform, if any? Respond with JSON only.";
+    }
+    else {
+        // general (filtered is handled by caller fast path and never reaches here)
+        system =
+            "You are a relevance filter for a personal priority hub. " +
+                "Evaluate whether this finding deserves attention in a general priority review. " +
+                'Respond ONLY with a JSON object: { "relevant": boolean, "reason": string }';
+        userContent =
+            `Finding:\n${summary}\n\n` +
+                "Is this finding relevant for a general priority review? Respond with JSON only.";
+    }
+    const messages = [{ role: "user", content: userContent }];
+    const response = await llm.chat({
+        model: "hub-relevance",
+        system,
+        messages,
+        jsonObjectMode: true,
+    });
+    return validateRelevanceVerdict(response.text);
+}
+// ── Pass 2: hub lens fan-out ──────────────────────────────────────────
+/**
+ * Fan out all hub prioritization lenses for a single finding.
+ * Aggregate score = SUM of per-lens scores (range 0–40 across 4 lenses).
+ * Null lens response → {include:false, score:0} (fail-closed, contributes to failVotes).
+ */
+async function scoreFindingWithLenses(finding, llm) {
+    const summary = buildFindingSummary(finding);
+    let passVotes = 0;
+    let failVotes = 0;
+    let aggregateScore = 0;
+    for (const lens of HUB_LENS_NAMES) {
+        const lensFocus = resolveHubLensFocus(lens);
+        const system = `${lensFocus} ` +
+            "You are evaluating a finding for a personal priority hub. " +
+            'Respond ONLY with a JSON object: { "include": boolean, "score": number, "reason": string } ' +
+            "where score is an integer 0–10 (0 = lowest priority, 10 = highest priority).";
+        const userContent = `Finding:\n${summary}\n\n` +
+            "Should this finding be prioritized? Provide a score and reason. Respond with JSON only.";
+        const messages = [{ role: "user", content: userContent }];
+        const response = await llm.chat({
+            model: "hub-lens",
+            system,
+            messages,
+            jsonObjectMode: true,
+        });
+        // null → fail-closed default: contribute to failVotes, add 0 to aggregate
+        const lensScore = validateLensScore(response.text) ?? { include: false, score: 0 };
+        aggregateScore += lensScore.score;
+        if (lensScore.include) {
+            passVotes += 1;
+        }
+        else {
+            failVotes += 1;
+        }
+    }
+    return { passVotes, failVotes, aggregateScore };
+}
+// ── Deterministic sort comparator ──────────────────────────────────────
+/**
+ * Deterministic comparator for the final sort step.
+ * Order: aggregateScore DESC → urgency DESC → severity DESC →
+ *        dueBy ASC (undefined treated as +Infinity → LAST) → id ASC.
+ */
+function compareFindings(a, b) {
+    // 1. aggregateScore DESC
+    if (b.aggregateScore !== a.aggregateScore)
+        return b.aggregateScore - a.aggregateScore;
+    // 2. urgency DESC
+    if (b.finding.urgency !== a.finding.urgency)
+        return b.finding.urgency - a.finding.urgency;
+    // 3. severity DESC
+    if (b.finding.severity !== a.finding.severity)
+        return b.finding.severity - a.finding.severity;
+    // 4. dueBy ASC; undefined → +Infinity → sorts LAST
+    const dueA = a.finding.dueBy !== undefined ? Date.parse(a.finding.dueBy) : Infinity;
+    const dueB = b.finding.dueBy !== undefined ? Date.parse(b.finding.dueBy) : Infinity;
+    if (dueA !== dueB)
+        return dueA - dueB;
+    // 5. id ASC (lexicographic)
+    if (a.finding.id < b.finding.id)
+        return -1;
+    if (a.finding.id > b.finding.id)
+        return 1;
+    return 0;
+}
+// ── rankFindings ───────────────────────────────────────────────────────
+/**
+ * Two-pass hub prioritization judge.
+ *
+ * @param findings  Pool of Finding[] to rank (input array and Finding objects are never mutated).
+ * @param scope     Ephemeral query scope — not persisted anywhere.
+ * @param llm       Injected LLMClient. Tests pass a ScriptedClient fake; Sprint 4 passes a real client.
+ * @param now       Injected clock for dueWithinDays math in filtered mode. Never call Date.now() here.
+ * @returns         Ranked Finding[]; tie-voted findings carry the "flagged-for-review" tag.
+ */
+export async function rankFindings(findings, scope, llm, now) {
+    // ── Filtered fast path: pure JS, ZERO LLM calls ────────────────────
+    if (scope.mode === "filtered") {
+        const filtered = applyFilter(findings, scope, now);
+        // Sort deterministically without aggregate score (no lens pass for filtered mode)
+        return [...filtered].sort((a, b) => compareFindings({ finding: a, aggregateScore: 0 }, { finding: b, aggregateScore: 0 }));
+    }
+    // ── Pass 1: LLM relevance filter (general / decision) ─────────────
+    const survivors = [];
+    for (const finding of findings) {
+        const verdict = await askRelevance(finding, scope, llm);
+        // null → fail-closed: drop the finding
+        if (verdict === null || !verdict.relevant)
+            continue;
+        // Decision scope: drop "neither" and undefined relevantTo
+        if (scope.mode === "decision") {
+            const rt = verdict.relevantTo;
+            if (rt !== "optionA" && rt !== "optionB" && rt !== "both")
+                continue;
+        }
+        survivors.push(finding);
+    }
+    // ── Pass 2: lens scoring + strict-majority reconcile ──────────────
+    const scored = [];
+    for (const finding of survivors) {
+        const { passVotes, failVotes, aggregateScore } = await scoreFindingWithLenses(finding, llm);
+        // Reconcile: strict majority, fail-closed on tie.
+        // bober: hub inverts the eval/medical panel DROP: a tie/fail-majority keeps the finding
+        //        and tags it "flagged-for-review" rather than dropping it (lens-panel.md:80-84).
+        let out;
+        if (passVotes > failVotes) {
+            out = finding; // strict majority → normal ranking, no tag change
+        }
+        else {
+            // Tie or fail-majority → keep but tag; append to a COPY to avoid mutating input
+            out = finding.tags.includes("flagged-for-review")
+                ? finding
+                : { ...finding, tags: [...finding.tags, "flagged-for-review"] };
+        }
+        scored.push({ finding: out, aggregateScore });
+    }
+    // ── Deterministic sort: LLM never emits the final order ───────────
+    return [...scored].sort(compareFindings).map((s) => s.finding);
+}
+//# sourceMappingURL=judge.js.map

package/dist/hub/judge.js.map

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

package/dist/hub/lenses.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+export declare const HUB_LENS_NAMES: readonly ["urgency", "impact", "effort", "deadline-risk"];
+export type HubLensName = (typeof HUB_LENS_NAMES)[number];
+/**
+ * Resolve a hub lens name to its focus fragment.
+ * Returns the catalog entry for a known lens, or a generic non-empty
+ * fallback for any unknown custom string — never throws.
+ */
+export declare function resolveHubLensFocus(lens: string): string;
+/**
+ * Schema for pass-1 relevance verdict (general and decision scopes).
+ * For decision scope: relevantTo disambiguates which option the finding supports.
+ */
+export declare const RelevanceVerdictSchema: z.ZodObject<{
+    relevant: z.ZodBoolean;
+    relevantTo: z.ZodOptional<z.ZodEnum<["optionA", "optionB", "both", "neither"]>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    relevant: boolean;
+    relevantTo?: "optionA" | "optionB" | "both" | "neither" | undefined;
+    reason?: string | undefined;
+}, {
+    relevant: boolean;
+    relevantTo?: "optionA" | "optionB" | "both" | "neither" | undefined;
+    reason?: string | undefined;
+}>;
+export type RelevanceVerdict = z.infer<typeof RelevanceVerdictSchema>;
+/**
+ * Schema for pass-2 per-lens score/vote.
+ * include=true counts as a pass-vote; include=false counts as fail-vote.
+ * score (0-10) contributes to aggregate score for final ordering.
+ * An unparseable lens response is treated as { include: false, score: 0 } (fail-closed).
+ */
+export declare const LensScoreSchema: z.ZodObject<{
+    include: z.ZodBoolean;
+    score: z.ZodNumber;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    include: boolean;
+    score: number;
+    reason?: string | undefined;
+}, {
+    include: boolean;
+    score: number;
+    reason?: string | undefined;
+}>;
+export type LensScore = z.infer<typeof LensScoreSchema>;
+/**
+ * Parse a raw LLM text into a RelevanceVerdict.
+ * Returns null on parse failure (fail-closed: treated as irrelevant / no-vote).
+ * NEVER throws.
+ */
+export declare function validateRelevanceVerdict(rawText: string): RelevanceVerdict | null;
+/**
+ * Parse a raw LLM text into a LensScore.
+ * Returns null on parse failure (fail-closed: contributes to failCount, score=0).
+ * NEVER throws.
+ */
+export declare function validateLensScore(rawText: string): LensScore | null;
+//# sourceMappingURL=lenses.d.ts.map

package/dist/hub/lenses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lenses.d.ts","sourceRoot":"","sources":["../../src/hub/lenses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,eAAO,MAAM,cAAc,2DAKjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAI1D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxD;AAID;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;EAIjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;EAI1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AA4CxD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAQjF;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQnE"}