@yadsh/dsh-qa-surface 0.12.0 → 0.14.0

package/lib/admin/service.js

@@ -1,9 +1,11 @@
 import { QaAccountsError } from "../accounts/store.js";
 import { defaultCapabilityConfig, normalizeUserAccess, resolveSkillAccess, } from "../access/model.js";
+import { expertMemoryReasonOf } from "../integration/expert-memory.js";
 import { allows } from "./permissions.js";
 import { aggregateQuality } from "./metrics.js";
 import { paginate } from "./paging.js";
 import { deriveQueue } from "./queue.js";
+import { QA_FEEDBACK_RATINGS } from "./quality-store.js";
 import { defaultAdminRedactor } from "./redaction.js";
 import { projectTranscript, } from "./conversation-log.js";
 /**
@@ -22,9 +24,36 @@ export const QA_ADMIN_PAGE_MAX = 100;
  * says so; moving these counters onto a real index is the next iteration.
  */
 export const QA_ADMIN_SCAN_LIMIT = 200;
-/** How long one projected log may serve the list and metrics before re-reading. */
+/**
+ * How long one projected log may serve the list and metrics before it is read
+ * again — and only while the Harness still holds that conversation. A log no
+ * process holds cannot gain events, so re-reading it is pure cost: on a
+ * deployment with a durable store one read pays for a listing of every stored
+ * session and a replay of the whole log before it reaches the one conversation
+ * asked for. Reading the scan window again on every page load is what took the
+ * aggregate pages minutes; keeping what cannot have changed is what makes the
+ * next load free.
+ */
 const TRANSCRIPT_TTL_MS = 30_000;
-const TRANSCRIPT_CACHE_MAX = 128;
+/**
+ * How many projections the cache holds. It has to cover one scan window with
+ * room for a page of summaries: a cache narrower than the window evicts the
+ * conversations a pass has already read, and the next pass pays for them again.
+ */
+const TRANSCRIPT_CACHE_MAX = QA_ADMIN_SCAN_LIMIT + QA_ADMIN_PAGE_MAX;
+/**
+ * What one harvest request may carry. The browser replays its ratings in
+ * batches far below this; the ceiling is what a caller that ignored them is
+ * refused outright, rather than half-applied.
+ */
+const MAX_HARVEST_BATCH = 500;
+/** One harvested identifier, or undefined when the entry cannot be filed. */
+function harvestId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
 /**
  * Every session one conversation owns: the chat itself and everything
  * delegated from it, transitively. A subagent's session is part of the answer
@@ -87,9 +116,26 @@ function reviewStatusOf(reviews, conversationId) {
         ? "needs_followup"
         : "reviewed";
 }
+/**
+ * Whether a running pass has no caller left to answer. A caller that passed no
+ * cancellation cannot leave, so it keeps the pass alive.
+ */
+function nobodyWaits(waiting) {
+    for (const signal of waiting) {
+        if (signal === undefined || !signal.aborted)
+            return false;
+    }
+    return true;
+}
+function sameWindow(left, right) {
+    return (left.length === right.length &&
+        left.every((id, index) => id === right[index]));
+}
 export class QaAdminService {
     options;
     redactor;
+    /** The aggregate pass running now, shared by the callers waiting for it. */
+    scanning;
     transcripts = new Map();
     constructor(options) {
         this.options = options;
@@ -176,30 +222,116 @@ export class QaAdminService {
         })
             .filter((row) => row !== undefined);
     }
-    /** One conversation's projected log, cached for the TTL unless asked fresh. */
+    /**
+     * One conversation's projected log, held across calls.
+     *
+     * A log the Harness no longer holds is finished — nothing can append to it —
+     * so its projection stays valid until the cache evicts it or the conversation
+     * is deleted. Only a log this process is still writing is re-read once the TTL
+     * expires. A cache hit counts as a use: an aggregate pass walks the whole
+     * window, and evicting by read time would drop the conversations the pages ask
+     * for most often and then read them again.
+     *
+     * The one answer this can hold back is a conversation resumed and finished
+     * between two page loads: its counters lag until the log is read for another
+     * reason. The conversation itself is never affected — the detail view always
+     * reads the log — and what the aggregate pages show instead is the newest
+     * projection of every finished conversation, which is the cheaper lie.
+     */
     async transcript(conversationId, fresh = false) {
         const cached = this.transcripts.get(conversationId);
         const now = this.options.clock?.now() ?? Date.now();
-        if (!fresh && cached !== undefined && now - cached.at < TRANSCRIPT_TTL_MS) {
-            return { ok: true, project: cached.project };
+        if (cached !== undefined) {
+            const stale = fresh ||
+                (this.options.sessionLog.live(conversationId) &&
+                    now - cached.at >= TRANSCRIPT_TTL_MS);
+            if (!stale) {
+                this.retain(conversationId, cached);
+                return { ok: true, project: cached.project };
+            }
+            this.transcripts.delete(conversationId);
         }
         const result = await this.options.sessionLog.read(conversationId);
         if (!result.ok) {
-            this.transcripts.delete(conversationId);
             return { ok: false, reason: result.reason };
         }
         const project = projectTranscript(result.events, this.redactor);
-        this.transcripts.set(conversationId, { at: now, project });
-        if (this.transcripts.size > TRANSCRIPT_CACHE_MAX) {
-            const oldest = [...this.transcripts.entries()].sort((left, right) => left[1].at - right[1].at)[0];
-            if (oldest !== undefined)
-                this.transcripts.delete(oldest[0]);
-        }
+        this.retain(conversationId, {
+            at: this.options.clock?.now() ?? Date.now(),
+            project,
+        });
         return { ok: true, project };
     }
-    async facts(rows) {
+    /** Insert or re-touch one projection, keeping the cache inside its budget. */
+    retain(conversationId, entry) {
+        this.transcripts.delete(conversationId);
+        this.transcripts.set(conversationId, entry);
+        while (this.transcripts.size > TRANSCRIPT_CACHE_MAX) {
+            const oldest = this.transcripts.keys().next();
+            if (oldest.done === true)
+                break;
+            this.transcripts.delete(oldest.value);
+        }
+    }
+    /**
+     * The aggregate rows of the newest scan window, read in one pass.
+     *
+     * The message counts and the tool failures come from the same projections, so
+     * one walk fills both. While a walk runs, a caller that wants the same window
+     * joins it rather than starting a second scan of the deployment's logs, and the
+     * walk stops once no caller waits for it: a scan nobody is reading is only ever
+     * a load on the store.
+     */
+    async scanOf(rows, signal) {
+        signal?.throwIfAborted();
+        const window = [...rows]
+            .sort((left, right) => right.createdAt - left.createdAt)
+            .slice(0, QA_ADMIN_SCAN_LIMIT);
+        const ids = window.map((row) => row.conversationId);
+        const running = this.scanning;
+        if (running !== undefined &&
+            !nobodyWaits(running.waiting) &&
+            sameWindow(running.window, ids)) {
+            running.waiting.add(signal);
+            try {
+                return await running.promise;
+            }
+            finally {
+                running.waiting.delete(signal);
+            }
+        }
         const facts = [];
-        for (const row of rows) {
+        const failures = [];
+        const waiting = new Set([signal]);
+        const promise = this.walk(window, waiting, facts, failures);
+        const pass = { window: ids, promise, waiting };
+        this.scanning = pass;
+        void promise
+            .catch(() => undefined)
+            .then(() => {
+            if (this.scanning === pass)
+                this.scanning = undefined;
+        });
+        try {
+            return await promise;
+        }
+        finally {
+            waiting.delete(signal);
+        }
+    }
+    /**
+     * Walk one scan window, filling the counts and the failure signals as it goes.
+     *
+     * `waiting` is the caller set of the pass this walk belongs to: the walk gives
+     * up between two reads once every caller has left, so a reviewer who abandons a
+     * page that has not answered does not keep the deployment reading logs for an
+     * answer nobody will see.
+     */
+    async walk(window, waiting, facts, failures) {
+        for (const row of window) {
+            if (nobodyWaits(waiting)) {
+                throw new Error("qa admin aggregate scan abandoned: no caller left");
+            }
             const transcript = await this.transcript(row.conversationId);
             facts.push({
                 conversationId: row.conversationId,
@@ -210,18 +342,21 @@ export class QaAdminService {
                     : 0,
                 createdAt: row.createdAt,
             });
+            if (transcript.ok) {
+                failures.push(...this.failuresOf(row.conversationId, transcript.project));
+            }
         }
-        return facts;
+        return { facts, failures };
     }
     // -------------------------------------------------------------------------
     // Overview and metrics
     // -------------------------------------------------------------------------
-    async overview(token) {
+    async overview(token, signal) {
         this.require(token, "conversations.read.all");
         const rows = await this.index();
-        const metrics = await this.metricsOf(rows);
+        const metrics = await this.metricsOf(rows, signal);
         const fresh = [...this.options.quality().allFeedback()].sort((left, right) => right.createdAt.localeCompare(left.createdAt));
-        const queue = await this.queueRows(rows);
+        const queue = await this.queueRows(rows, signal);
         return Object.freeze({
             metrics,
             alerts: this.alertsOf(metrics),
@@ -229,19 +364,16 @@ export class QaAdminService {
             queue: queue.slice(0, 5),
         });
     }
-    async metrics(token) {
+    async metrics(token, signal) {
         this.require(token, "analytics.read");
-        return this.metricsOf(await this.index());
+        return this.metricsOf(await this.index(), signal);
     }
-    async metricsOf(rows) {
+    async metricsOf(rows, signal) {
         const quality = this.options.quality();
         // Feedback and reviews are exact; the message counts come from the bounded
         // log scan and are labelled as such where they are shown.
-        const scanned = [...rows]
-            .sort((left, right) => right.createdAt - left.createdAt)
-            .slice(0, QA_ADMIN_SCAN_LIMIT);
         return aggregateQuality({
-            conversations: await this.facts(scanned),
+            conversations: (await this.scanOf(rows, signal)).facts,
             feedback: quality.allFeedback(),
             reviews: quality.allReviews(),
         });
@@ -534,8 +666,9 @@ export class QaAdminService {
     // -------------------------------------------------------------------------
     // Conversations
     // -------------------------------------------------------------------------
-    async conversations(token, query, cursor, limit) {
+    async conversations(token, query, cursor, limit, signal) {
         this.require(token, "conversations.read.all");
+        signal?.throwIfAborted();
         const rows = await this.index();
         const quality = this.options.quality();
         const feedback = quality.allFeedback();
@@ -545,17 +678,23 @@ export class QaAdminService {
         const ratingFilter = given(query.rating);
         const reviewFilter = given(query.reviewStatus);
         const search = given(query.search) ?? "";
+        const searching = search.trim() !== "";
         const from = epochOf(given(query.from) ?? undefined);
         const to = epochOf(given(query.to) ?? undefined);
         // A search may name a title, which only the log knows, so the candidate
-        // set is bounded by the newest logs before the text is available.
-        const searchable = search.trim() === ""
-            ? rows
-            : [...rows]
+        // set is bounded by the newest logs before the text is available. Without
+        // search text no filter here needs a log at all — and reading one per
+        // candidate to answer a page of twenty-five rows made this call cost every
+        // conversation the deployment stores, each read paying for a listing of all
+        // of them before it reaches the one log asked for.
+        const searchable = searching
+            ? [...rows]
                 .sort((left, right) => right.createdAt - left.createdAt)
-                .slice(0, QA_ADMIN_SCAN_LIMIT);
+                .slice(0, QA_ADMIN_SCAN_LIMIT)
+            : rows;
         const candidates = [];
         for (const row of searchable) {
+            signal?.throwIfAborted();
             if (userIdFilter !== undefined && row.userId !== userIdFilter)
                 continue;
             if (subroleFilter !== undefined && row.subroleId !== subroleFilter) {
@@ -574,10 +713,13 @@ export class QaAdminService {
                 reviewStatusOf(reviews, row.conversationId) !== reviewFilter) {
                 continue;
             }
-            // One projection per candidate, reused by the search match and then by
-            // the summary of a page row: the read is cached either way.
-            const transcript = await this.transcript(row.conversationId);
-            const title = transcript.ok ? transcript.project.title : undefined;
+            // Only a search reads a candidate's log, and the projection stays cached
+            // for the summary of the rows that survive the filter.
+            let title;
+            if (searching) {
+                const transcript = await this.transcript(row.conversationId);
+                title = transcript.ok ? transcript.project.title : undefined;
+            }
             if (!matches(search, row.displayName, row.email, row.userId, row.conversationId, title)) {
                 continue;
             }
@@ -593,6 +735,7 @@ export class QaAdminService {
         });
         const items = [];
         for (const row of page.items) {
+            signal?.throwIfAborted();
             items.push(await this.summaryOf(row, feedback, reviews));
         }
         return {
@@ -741,7 +884,10 @@ export class QaAdminService {
         const qualityRows = this.options.quality().dropConversations(targets);
         for (const sessionId of targets)
             this.options.dropSources?.(sessionId);
-        this.transcripts.delete(conversationId);
+        // A removed log is never read again, so its projection must not survive to
+        // answer a later page: the cache holds it as if the conversation existed.
+        for (const sessionId of targets)
+            this.transcripts.delete(sessionId);
         this.options.quality().appendAudit({
             actorId: actor.id,
             action: "conversation.deleted",
@@ -783,16 +929,6 @@ export class QaAdminService {
         }
         return signals;
     }
-    async failureSignals(rows) {
-        const signals = [];
-        for (const row of rows) {
-            const transcript = await this.transcript(row.conversationId);
-            if (!transcript.ok)
-                continue;
-            signals.push(...this.failuresOf(row.conversationId, transcript.project));
-        }
-        return signals;
-    }
     // -------------------------------------------------------------------------
     // Feedback
     // -------------------------------------------------------------------------
@@ -817,6 +953,74 @@ export class QaAdminService {
         });
         return record;
     }
+    /**
+     * Replay the ratings a browser still holds from the window in which a thumbs
+     * never reached the Host.
+     *
+     * A harvest never overwrites. The browser's map stores no timestamp, so an
+     * entry may well be a rating the same user has since filed together with a
+     * reason and a comment; replacing that record with the bare thumbs would
+     * delete exactly what a reviewer reads. An entry the Host already answers for
+     * is counted as present and left alone.
+     *
+     * One unusable or foreign entry costs that entry alone: a browser keeps
+     * ratings of chats it no longer owns, and the rest of the replay must not be
+     * lost because of them.
+     */
+    harvestFeedback(token, entries) {
+        const { accounts, actor } = this.require(token, "conversations.read.own");
+        if (!Array.isArray(entries)) {
+            throw new TypeError("entries must be an array");
+        }
+        if (entries.length > MAX_HARVEST_BATCH) {
+            throw new QaAccountsError("auth-required", "harvest batch is too large");
+        }
+        const quality = this.options.quality();
+        let recorded = 0;
+        let present = 0;
+        let rejected = 0;
+        for (const entry of entries) {
+            const conversationId = harvestId(entry?.conversationId);
+            const messageId = harvestId(entry?.messageId);
+            const rating = entry?.rating;
+            if (conversationId === undefined ||
+                messageId === undefined ||
+                !QA_FEEDBACK_RATINGS.includes(rating)) {
+                rejected += 1;
+                continue;
+            }
+            if (accounts.ownerIdOf(conversationId) !== actor.id) {
+                rejected += 1;
+                continue;
+            }
+            if (quality.feedbackOf(conversationId, messageId, actor.id) !== undefined) {
+                present += 1;
+                continue;
+            }
+            try {
+                quality.rateFeedback({ conversationId, messageId, userId: actor.id }, { rating });
+                recorded += 1;
+            }
+            catch (error) {
+                // The store re-validates what it is given, and one row it refuses is
+                // that row's problem rather than the batch's.
+                this.options.logger.warn("admin.feedback-harvest-entry-refused", {
+                    conversationId,
+                    messageId,
+                    userId: actor.id,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+                rejected += 1;
+            }
+        }
+        this.options.logger.info("admin.feedback-harvested", {
+            userId: actor.id,
+            recorded,
+            present,
+            rejected,
+        });
+        return { recorded, present, rejected };
+    }
     async feedback(token, query, cursor, limit) {
         this.require(token, "reviews.read");
         const rows = await this.index();
@@ -893,7 +1097,7 @@ export class QaAdminService {
     // -------------------------------------------------------------------------
     // Review queue and results
     // -------------------------------------------------------------------------
-    async queueRows(rows) {
+    async queueRows(rows, signal) {
         const conversations = rows ?? (await this.index());
         const quality = this.options.quality();
         const reviews = quality.allReviews();
@@ -902,12 +1106,11 @@ export class QaAdminService {
             feedback: quality.allFeedback(),
             reviews,
             manual: quality.manualQueue(),
-            failures: await this.failureSignals([...conversations]
-                .sort((left, right) => right.createdAt - left.createdAt)
-                .slice(0, QA_ADMIN_SCAN_LIMIT)),
+            failures: (await this.scanOf(conversations, signal)).failures,
         });
         const result = [];
         for (const item of queue) {
+            signal?.throwIfAborted();
             const row = byId.get(item.conversationId);
             if (row === undefined)
                 continue;
@@ -931,9 +1134,9 @@ export class QaAdminService {
         }
         return Object.freeze(result);
     }
-    async reviewQueue(token, cursor, limit) {
+    async reviewQueue(token, cursor, limit, signal) {
         this.require(token, "reviews.read");
-        const rows = await this.queueRows();
+        const rows = await this.queueRows(await this.index(), signal);
         return paginate({
             rows,
             keyOf: (row) => `${row.priority}:${row.raisedAt}`,
@@ -1134,6 +1337,183 @@ export class QaAdminService {
         return this.options.skills().get(target.scope, name);
     }
     // -------------------------------------------------------------------------
+    // Expert memory
+    // -------------------------------------------------------------------------
+    /**
+     * The domain-experts maintenance seam, or the refusal that says this stand
+     * runs no experts.
+     *
+     * Reach is host-plane on purpose: the sibling plugin's remotes carry no token
+     * and check no permission, because inside the Harness their caller is already
+     * a trusted component. This console answers a browser on a LAN port, so it
+     * calls the service directly and gates every call with its own `require`.
+     */
+    expertMemory() {
+        const admin = this.options.domainExperts?.()?.memoryAdmin;
+        if (admin === undefined) {
+            throw new QaAccountsError("memory-unavailable", "no domain-experts plugin is composed on this deployment");
+        }
+        return admin;
+    }
+    /**
+     * Run one memory call, translating the sibling plugin's refusal.
+     *
+     * The reason crosses the wire, never the message: a memory refusal names
+     * namespaces, and a storage failure names the database file behind them.
+     */
+    async memoryCall(action, operation) {
+        const admin = this.expertMemory();
+        try {
+            return await operation(admin);
+        }
+        catch (error) {
+            if (error instanceof QaAccountsError)
+                throw error;
+            const reason = expertMemoryReasonOf(error);
+            this.options.logger.warn("admin.memory-refused", {
+                action,
+                reason: reason ?? "unknown",
+            });
+            if (reason === undefined)
+                throw error;
+            throw new QaAccountsError(reason, `expert memory refused the ${action}`);
+        }
+    }
+    /**
+     * What an audit row keeps about one record.
+     *
+     * A remembered line runs to a few pages, and the trail holds a capped JSON
+     * snapshot; the identity of the record and the head of its text is what an
+     * operator reads back to decide whether the deletion was wrong.
+     */
+    memoryImage(record) {
+        return {
+            namespace: record.namespace,
+            key: record.key,
+            tags: record.tags,
+            updatedAt: record.updatedAt,
+            text: record.text.slice(0, 200),
+        };
+    }
+    /** The record one key holds now, if it still holds one. */
+    async rememberedRecord(admin, namespace, key) {
+        const page = await admin.search(namespace, key, QA_ADMIN_PAGE_MAX, 0);
+        return page.records.find((record) => record.key === key);
+    }
+    /** Every expert memory namespace on the stand, with its owner and size. */
+    async memoryScopes(token) {
+        this.require(token, "memory.read");
+        return await this.memoryCall("scopes", (admin) => admin.scopes());
+    }
+    /** One page of one namespace, newest first, with the filter's match count. */
+    async memoryRecords(token, namespace, query, limit, offset) {
+        this.require(token, "memory.read");
+        const size = clampLimit(limit === null ? undefined : limit);
+        const from = Number.isFinite(offset) ? Math.max(0, Math.floor(offset)) : 0;
+        const page = await this.memoryCall("search", (admin) => admin.search(namespace, query, size, from));
+        return {
+            records: page.records,
+            total: page.total,
+            offset: from,
+            limit: size,
+        };
+    }
+    /**
+     * Rewrite one remembered line.
+     *
+     * The key is not editable: it is what the expert's own notes and the audit
+     * trail point at, and a console that renamed it would orphan both. The write
+     * refuses a record that vanished meanwhile rather than re-creating it — an
+     * operator editing a stale row should reload, not resurrect.
+     */
+    async correctMemory(token, namespace, key, draft) {
+        const { actor } = this.require(token, "memory.manage");
+        const before = await this.memoryCall("read-before", (admin) => this.rememberedRecord(admin, namespace, key));
+        const record = await this.memoryCall("correct", (admin) => admin.correct({ namespace, key, text: draft.text, tags: draft.tags }));
+        this.options.quality().appendAudit({
+            actorId: actor.id,
+            action: "memory.corrected",
+            targetType: "expert-memory",
+            targetId: `${namespace}/${key}`,
+            ...(before === undefined ? {} : { before: this.memoryImage(before) }),
+            after: this.memoryImage(record),
+        });
+        this.options.logger.info("admin.memory-corrected", {
+            actor: actor.id,
+            namespace,
+            key,
+        });
+        return record;
+    }
+    /**
+     * Drop one or several remembered lines.
+     *
+     * A single deletion keeps the text it removed; a bulk one keeps only the
+     * count and the keys, because an audit trail that copies every page of memory
+     * it deletes becomes the thing an operator has to clean up.
+     */
+    async forgetMemory(token, namespace, keys) {
+        const { actor } = this.require(token, "memory.manage");
+        const wanted = [
+            ...new Set(keys.map((key) => key.trim()).filter((key) => key !== "")),
+        ];
+        if (wanted.length === 0) {
+            throw new QaAccountsError("invalid-memory", "a memory deletion needs at least one record key");
+        }
+        const sole = wanted.length === 1 ? wanted[0] : undefined;
+        const before = sole === undefined
+            ? undefined
+            : await this.memoryCall("read-before", (admin) => this.rememberedRecord(admin, namespace, sole));
+        const removed = await this.memoryCall("forget", async (admin) => sole === undefined
+            ? await admin.removeMany(namespace, wanted)
+            : (await admin.remove(namespace, sole))
+                ? 1
+                : 0);
+        this.options.quality().appendAudit({
+            actorId: actor.id,
+            action: "memory.deleted",
+            targetType: "expert-memory",
+            targetId: namespace,
+            before: before === undefined
+                ? { keys: wanted, count: wanted.length }
+                : this.memoryImage(before),
+        });
+        this.options.logger.info("admin.memory-deleted", {
+            actor: actor.id,
+            namespace,
+            named: wanted.length,
+            removed,
+        });
+        return removed;
+    }
+    /** Empty one expert's private namespace. */
+    async wipeMemory(token, namespace, expectedRecords) {
+        const { actor } = this.require(token, "memory.manage");
+        const page = await this.memoryCall("read-before", (admin) => admin.search(namespace, "", 1, 0));
+        if (expectedRecords !== null &&
+            Number.isFinite(expectedRecords) &&
+            expectedRecords >= 0 &&
+            page.total !== expectedRecords) {
+            // The console asks for the count it showed. Memory an expert wrote while
+            // the operator was deciding is not memory the operator agreed to erase.
+            throw new QaAccountsError("memory-record-unknown", "the namespace holds a different number of records than the one confirmed");
+        }
+        const cleared = await this.memoryCall("wipe", (current) => current.wipe(namespace));
+        this.options.quality().appendAudit({
+            actorId: actor.id,
+            action: "memory.wiped",
+            targetType: "expert-memory",
+            targetId: namespace,
+            after: { cleared },
+        });
+        this.options.logger.info("admin.memory-wiped", {
+            actor: actor.id,
+            namespace,
+            cleared,
+        });
+        return cleared;
+    }
+    // -------------------------------------------------------------------------
     // Audit
     // -------------------------------------------------------------------------
     /**