@unblocklabs/unblock-memory 0.3.15 → 0.3.17

package/dist/src/response-outcome.js

@@ -0,0 +1,51 @@
+// Reporting/composition changes do not require paid re-inference of the same rubric.
+export const RESPONSE_REPORT_VERSION = "response-report-v4";
+/** Compose observed evidence, not a factual-verification or causal agent grade.
+ * Narrow admissions take precedence over praise; missing evidence stays unknown. */
+export function responseOutcome(result) {
+    const later = result.retrospective.judgment;
+    const basis = [];
+    const reasons = [];
+    const reasonDetails = [];
+    const addReason = (reason, strength, source, measure = "choice_confidence") => {
+        reasons.push(reason);
+        reasonDetails.push({ reason, strength, measure, source });
+    };
+    if (result.quality.underdelivery.noul >= 0.8) {
+        basis.push("visible_underdelivery");
+        const reason = result.quality.failureReason;
+        if (reason.confidence >= 0.8 && reason.choice !== "none_or_unclear")
+            addReason(reason.choice, reason.confidence, "visible_quality");
+    }
+    if (later) {
+        const correction = later.correction.noul >= 0.8;
+        const delivery = later.deliveryAdmission.noul >= 0.8;
+        const regression = later.regression.noul >= 0.8;
+        if (correction)
+            basis.push("later_correction");
+        if (delivery) {
+            basis.push("delivery_admission");
+            addReason("failed_delivery", later.deliveryAdmission.noul, "delivery_admission", "yes_probability");
+        }
+        if (regression) {
+            basis.push("regression_admission");
+            addReason("regression", later.regression.noul, "regression_admission", "yes_probability");
+        }
+        const reported = later.outcome.confidence >= 0.8 && later.outcome.choice === "reported_shortfall" && later.scopeClarification.noul <= 0.2;
+        if (reported)
+            basis.push("reported_shortfall");
+        // A narrow admission can establish the shortfall even when the broad outcome
+        // abstains. Its independently confident reason is still useful, not overridden
+        // by a hard-coded assumption that every correction means incorrect_claim.
+        if ((correction || delivery || regression || reported) && later.reason.confidence >= 0.8 && later.reason.choice !== "none_or_unclear") {
+            addReason(later.reason.choice, later.reason.confidence, "retrospective_reason");
+        }
+    }
+    if (basis.length)
+        return { status: "reported_shortfall", basis, reasons: [...new Set(reasons)], reasonDetails,
+            reasonStatus: reasonDetails.length ? "classified" : "uncertain" };
+    if (later?.outcome.choice === "acknowledged_success" && later.outcome.confidence >= 0.8) {
+        return { status: "acknowledged_success", basis: ["human_acknowledgment"], reasons: [], reasonDetails: [], reasonStatus: "not_applicable" };
+    }
+    return { status: "unknown", basis: [], reasons: [], reasonDetails: [], reasonStatus: "not_applicable" };
+}

package/dist/src/response-reviews.d.ts

@@ -0,0 +1,27 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { ResponseResult } from "./response-store.js";
+export declare const RESPONSE_REVIEW_POLICY = "response-review-v2";
+export type ResponseReviewStatus = "pending" | "resolved" | "dismissed" | "deferred";
+/** Operator-only tasks, intentionally not exposed as memory-curation agent tools. */
+export declare class ResponseReviews {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    sync(cohort: string, episodeId: string, inputHash: string, result: ResponseResult, now: number): void;
+    refresh(cohort: string, since: number): number;
+    reconcile(cohort: string): void;
+    list(cohort: string, id?: string): {
+        id: string;
+        episodeId: string;
+        family: string;
+        status: string;
+        evidenceStatus: string;
+        reviewerKind: import("node:sqlite").SQLOutputValue;
+        resolutionNote: import("node:sqlite").SQLOutputValue;
+        createdAt: import("node:sqlite").SQLOutputValue;
+        updatedAt: import("node:sqlite").SQLOutputValue;
+        evidence: unknown;
+    }[];
+    decide(cohort: string, id: string, status: ResponseReviewStatus, reviewer: "human" | "agent", note: string, now?: number): void;
+    annotate(occurredAt: number, kind: string, note: string): `${string}-${string}-${string}-${string}-${string}`;
+    annotations(since: number, until: number): Record<string, import("node:sqlite").SQLOutputValue>[];
+}

package/dist/src/response-reviews.js

@@ -0,0 +1,116 @@
+import { createHash, randomUUID } from "node:crypto";
+import { responseOutcome } from "./response-outcome.js";
+export const RESPONSE_REVIEW_POLICY = "response-review-v2";
+/** Operator-only tasks, intentionally not exposed as memory-curation agent tools. */
+export class ResponseReviews {
+    db;
+    constructor(db) {
+        this.db = db;
+        db.exec(`CREATE TABLE IF NOT EXISTS response_review_tasks (
+      id TEXT PRIMARY KEY, episode_id TEXT NOT NULL, family TEXT NOT NULL, human_key TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'pending',
+      reviewer_kind TEXT, resolution_note TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
+      UNIQUE(episode_id,family,human_key));
+      CREATE TABLE IF NOT EXISTS response_review_evidence (
+        task_id TEXT NOT NULL, cohort TEXT NOT NULL, input_hash TEXT NOT NULL, active INTEGER NOT NULL,
+        detail TEXT NOT NULL, PRIMARY KEY(task_id,cohort));
+      CREATE TABLE IF NOT EXISTS response_review_decisions (
+        id INTEGER PRIMARY KEY, task_id TEXT NOT NULL, status TEXT NOT NULL, reviewer_kind TEXT NOT NULL,
+        note TEXT NOT NULL, decided_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS response_review_versions (
+        cohort TEXT NOT NULL, episode_id TEXT NOT NULL, input_hash TEXT NOT NULL, policy TEXT NOT NULL,
+        PRIMARY KEY(cohort,episode_id));
+      CREATE TABLE IF NOT EXISTS response_annotations (
+        id TEXT PRIMARY KEY, occurred_at INTEGER NOT NULL, kind TEXT NOT NULL, note TEXT NOT NULL);`);
+    }
+    sync(cohort, episodeId, inputHash, result, now) {
+        this.db.prepare(`UPDATE response_review_evidence SET active=-1 WHERE cohort=? AND task_id IN
+      (SELECT id FROM response_review_tasks WHERE episode_id=?)`).run(cohort, episodeId);
+        const outcome = responseOutcome(result);
+        const f = result.feedback, intensity = f.dissatisfactionIntensity;
+        // Use probability of the relevant *group*, not the expected score or certainty
+        // of one fine-grained target. Ambiguity among agent-related targets is harmless.
+        const agentDirected = ["current_answer", "earlier_behavior", "delivery", "proactive_action", "mixed"];
+        const agentProbability = agentDirected.reduce((sum, key) => sum + f.target.probabilities[key], 0);
+        const signals = [
+            ...(outcome.status === "reported_shortfall" ? [{ family: "delivery_quality", detail: outcome }] : []),
+            ...(intensity && intensity.probabilities["2"] + intensity.probabilities["3"] >= 0.8 && agentProbability >= 0.8 &&
+                ((f.annoyance?.noul ?? 0) >= 0.8 || (f.frustration?.noul ?? 0) >= 0.8) ?
+                [{ family: "human_experience", detail: { target: f.target, sentiment: f.sentiment, annoyance: f.annoyance,
+                            frustration: f.frustration, intensity } }] : []),
+        ];
+        for (const s of signals) {
+            const humanKey = result.human?.key ?? "unknown";
+            const id = createHash("sha256").update(JSON.stringify([episodeId, s.family, humanKey])).digest("hex");
+            this.db.prepare(`INSERT INTO response_review_tasks(id,episode_id,family,human_key,created_at,updated_at) VALUES(?,?,?,?,?,?)
+        ON CONFLICT(id) DO UPDATE SET updated_at=excluded.updated_at`).run(id, episodeId, s.family, humanKey, now, now);
+            this.db.prepare(`INSERT INTO response_review_evidence VALUES(?,?,?,1,?) ON CONFLICT(task_id,cohort)
+        DO UPDATE SET input_hash=excluded.input_hash,active=1,detail=excluded.detail`)
+                .run(id, cohort, inputHash, JSON.stringify({ policy: RESPONSE_REVIEW_POLICY, signals: s.detail, human: result.human ?? null, references: result.references }));
+        }
+        this.db.prepare(`INSERT INTO response_review_versions VALUES(?,?,?,?) ON CONFLICT(cohort,episode_id)
+      DO UPDATE SET input_hash=excluded.input_hash,policy=excluded.policy`).run(cohort, episodeId, inputHash, RESPONSE_REVIEW_POLICY);
+    }
+    refresh(cohort, since) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const rows = this.db.prepare(`SELECT r.id,r.input_hash,r.result FROM response_results r
+        LEFT JOIN response_review_versions v ON v.cohort=r.cohort AND v.episode_id=r.id
+        WHERE r.cohort=? AND r.active=1 AND r.status='ok' AND r.episode_at>=?
+        AND (v.policy IS NULL OR v.policy!=? OR v.input_hash!=r.input_hash) ORDER BY r.id LIMIT 1000`)
+                .all(cohort, since, RESPONSE_REVIEW_POLICY);
+            for (const row of rows)
+                this.sync(cohort, String(row.id), String(row.input_hash), JSON.parse(String(row.result)), Date.now());
+            this.db.exec("COMMIT");
+            return rows.length;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    reconcile(cohort) {
+        this.db.prepare(`UPDATE response_review_evidence AS e SET active=CASE WHEN EXISTS (
+      SELECT 1 FROM response_review_tasks t JOIN response_results r ON r.id=t.episode_id
+      WHERE t.id=e.task_id AND r.cohort=e.cohort AND r.input_hash=e.input_hash AND r.active=1 AND r.status='ok')
+      THEN 1 ELSE 0 END WHERE cohort=? AND active>=0`).run(cohort);
+    }
+    list(cohort, id) {
+        return this.db.prepare(`SELECT t.*,e.input_hash,e.active,e.detail FROM response_review_tasks t
+      JOIN response_review_evidence e ON e.task_id=t.id WHERE e.cohort=? ${id ? "AND t.id=?" : ""}
+      ORDER BY t.updated_at DESC,t.id LIMIT 1001`).all(cohort, ...(id ? [id] : [])).map(row => ({
+            id: String(row.id), episodeId: String(row.episode_id), family: String(row.family), status: String(row.status),
+            evidenceStatus: row.active === 1 ? "current" : row.active === -1 ? "superseded" : "stale", reviewerKind: row.reviewer_kind,
+            resolutionNote: row.resolution_note, createdAt: row.created_at, updatedAt: row.updated_at,
+            evidence: JSON.parse(String(row.detail)),
+        }));
+    }
+    decide(cohort, id, status, reviewer, note, now = Date.now()) {
+        if (!["pending", "resolved", "dismissed", "deferred"].includes(status) || !["human", "agent"].includes(reviewer) ||
+            !note.trim() || note.length > 4000)
+            throw new Error("Invalid response review decision");
+        if (!this.list(cohort, id).length)
+            throw new Error("Unknown response review task in current cohort");
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            this.db.prepare("UPDATE response_review_tasks SET status=?,reviewer_kind=?,resolution_note=?,updated_at=? WHERE id=?")
+                .run(status, reviewer, note.trim(), now, id);
+            this.db.prepare("INSERT INTO response_review_decisions(task_id,status,reviewer_kind,note,decided_at) VALUES(?,?,?,?,?)")
+                .run(id, status, reviewer, note.trim(), now);
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    annotate(occurredAt, kind, note) {
+        if (!Number.isFinite(occurredAt) || !["model", "prompt", "deployment", "other"].includes(kind) || !note.trim() || note.length > 4000)
+            throw new Error("Invalid response annotation");
+        const id = randomUUID();
+        this.db.prepare("INSERT INTO response_annotations VALUES(?,?,?,?)").run(id, occurredAt, kind, note.trim());
+        return id;
+    }
+    annotations(since, until) {
+        return this.db.prepare("SELECT * FROM response_annotations WHERE occurred_at>=? AND occurred_at<? ORDER BY occurred_at,id").all(since, until);
+    }
+}

package/dist/src/response-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { UnblockMemoryConfig } from "./config.js";
+export declare function registerResponseAudit(api: OpenClawPluginApi, config: UnblockMemoryConfig): void;

package/dist/src/response-runtime.js

@@ -0,0 +1,150 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveAgentDir, resolveAgentWorkspaceDir, resolveStateDir } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
+import { listAgentIds } from "openclaw/plugin-sdk/agent-runtime";
+import { normalizeAgentIdStrict } from "openclaw/plugin-sdk/routing";
+import { resolveSources } from "./sources.js";
+import { auditResponses, responseCohort } from "./response-audit.js";
+import { ResponseAuditStore } from "./response-store.js";
+function dateOption(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 10) !== value) {
+        throw new Error("Dates must be valid YYYY-MM-DD UTC dates");
+    }
+    return Date.parse(value);
+}
+export function registerResponseAudit(api, config) {
+    const options = (cfg, id) => {
+        const normalized = normalizeAgentIdStrict(id);
+        if (!normalized.ok || !listAgentIds(cfg).includes(normalized.value))
+            throw new Error("Unknown response-audit agent");
+        const agentId = normalized.value;
+        const state = join(resolveStateDir(), "agents", agentId, "unblock-memory");
+        return { agentId, config, databasePath: join(resolveAgentDir(cfg, agentId), "openclaw-agent.sqlite"),
+            storePath: join(state, "response-audit.sqlite"), indexPath: join(state, "index.sqlite"),
+            peoplePath: join(state, "people.sqlite"),
+            sources: resolveSources(resolveAgentWorkspaceDir(cfg, agentId), config.corpora.filter(c => c.kind === "files")
+                .filter(c => config.responseAudit.memoryCorpora.includes(c.name))) };
+    };
+    api.registerCli(({ program, config: cfg }) => {
+        const root = program.command("memory-responses").description("Operator-only response quality audits and evidence-linked trend reports");
+        root.command("audit").option("--agent <id>", "Agent id", "main").option("--dry-run", "Preview bounded coverage without inference or audit writes")
+            .action(async (opts) => {
+            const result = await auditResponses({ ...options(cfg, opts.agent), dryRun: opts.dryRun });
+            console.log(JSON.stringify(result, null, 2));
+            if (result.status === "unavailable")
+                process.exitCode = 1;
+        });
+        root.command("report").option("--agent <id>", "Agent id", "main").option("--episode <id>", "Include one episode's judgments and source event references")
+            .option("--since <date>", "Inclusive UTC date YYYY-MM-DD").option("--until <date>", "Exclusive UTC date YYYY-MM-DD")
+            .option("--bucket <period>", "day or week", "week").option("--sender <id>", "Human sender ID; requires --account")
+            .option("--account <scope>", "Provider account scope; requires --sender").option("--person <id>", "Linked people-store person ID")
+            .option("--task-type <type>", "Task classification").option("--model <id>", "Agent model")
+            .action((opts) => {
+            if (!config.responseAudit.enabled) {
+                console.log(JSON.stringify({ status: "disabled" }));
+                return;
+            }
+            const { storePath } = options(cfg, opts.agent);
+            if (!existsSync(storePath)) {
+                console.log(JSON.stringify({ status: "not_run" }));
+                return;
+            }
+            const store = new ResponseAuditStore(storePath);
+            if (opts.bucket !== "day" && opts.bucket !== "week") {
+                store.close();
+                throw new Error("Bucket must be day or week");
+            }
+            try {
+                console.log(JSON.stringify(store.report(responseCohort(config.responseAudit), dateOption(opts.since, Date.now() - config.responseAudit.lookbackDays * 86400_000), opts.episode, { until: dateOption(opts.until, Number.MAX_SAFE_INTEGER), bucket: opts.bucket, senderId: opts.sender,
+                    accountScope: opts.account, personId: opts.person, taskType: opts.taskType, agentModel: opts.model }), null, 2));
+            }
+            finally {
+                store.close();
+            }
+        });
+        const withStore = (agent, fn) => {
+            if (!config.responseAudit.enabled)
+                throw new Error("Response audit is disabled");
+            const { storePath } = options(cfg, agent);
+            if (!existsSync(storePath))
+                throw new Error("Response audit has not run");
+            const store = new ResponseAuditStore(storePath);
+            try {
+                console.log(JSON.stringify(fn(store, responseCohort(config.responseAudit)), null, 2));
+            }
+            finally {
+                store.close();
+            }
+        };
+        root.command("tasks").description("Operator-only response reviews; never automatically writes memories or preferences")
+            .option("--agent <id>", "Agent id", "main").option("--id <id>", "One task with evidence")
+            .action((opts) => withStore(opts.agent, (store, cohort) => {
+            const tasks = store.reviews.list(cohort, opts.id);
+            return { tasks: tasks.slice(0, 1000), capped: tasks.length > 1000 };
+        }));
+        root.command("review").requiredOption("--id <id>", "Task ID").requiredOption("--status <status>", "pending, resolved, dismissed or deferred")
+            .requiredOption("--reviewer <kind>", "human or agent: provenance, not an authorization grant")
+            .requiredOption("--note <text>", "Evidence-based decision; no automatic whisperer write")
+            .option("--agent <id>", "Agent id", "main")
+            .action((opts) => withStore(opts.agent, (store, cohort) => {
+            store.reviews.decide(cohort, opts.id, opts.status, opts.reviewer, opts.note);
+            return store.reviews.list(cohort, opts.id);
+        }));
+        root.command("annotate").option("--agent <id>", "Agent id", "main").requiredOption("--date <date>", "UTC date YYYY-MM-DD")
+            .requiredOption("--kind <kind>", "model, prompt, deployment or other").requiredOption("--note <text>", "Known change; correlation is not causation")
+            .action((opts) => withStore(opts.agent, store => ({ id: store.reviews.annotate(dateOption(opts.date, NaN), opts.kind, opts.note) })));
+        root.command("retry-failed").description("Reset failed stage retries without discarding successful judgments; next audit performs the work")
+            .option("--agent <id>", "Agent id", "main")
+            .action((opts) => withStore(opts.agent, (store, cohort) => store.retryFailed(cohort)));
+    }, { descriptors: [{ name: "memory-responses", description: "Audit human-agent exchanges and report quality signals", hasSubcommands: true }] });
+    if (api.registrationMode === "cli-metadata" || !config.responseAudit.enabled || !config.typesafe.enabled || !config.responseAudit.intervalMinutes)
+        return;
+    let timer, running, lifetime = new AbortController();
+    const tick = () => {
+        if (running || lifetime.signal.aborted)
+            return;
+        running = (async () => {
+            for (const id of listAgentIds(api.config)) {
+                if (lifetime.signal.aborted)
+                    break;
+                try {
+                    const params = options(api.config, id);
+                    const store = new ResponseAuditStore(params.storePath);
+                    let due;
+                    try {
+                        due = store.claimScheduled(Date.now(), config.responseAudit.intervalMinutes * 60_000);
+                    }
+                    finally {
+                        store.close();
+                    }
+                    if (!due)
+                        continue;
+                    const result = await auditResponses({ ...params, signal: lifetime.signal });
+                    if (result.status === "unavailable")
+                        api.logger.warn("unblock-memory response audit unavailable; inspect operator report");
+                }
+                catch {
+                    api.logger.warn("unblock-memory response audit unavailable");
+                }
+            }
+        })().catch(() => { api.logger.warn("unblock-memory response audit unavailable"); }).finally(() => { running = undefined; });
+    };
+    api.on("gateway_start", () => {
+        if (timer)
+            clearInterval(timer);
+        lifetime = new AbortController();
+        // A minute poll honors durable due times without relying on process uptime.
+        timer = setInterval(tick, 60_000);
+        timer.unref();
+        tick(); // New schedules wait one interval; overdue schedules get one bounded attempt.
+    });
+    api.on("gateway_stop", async () => {
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+        lifetime.abort();
+        await running;
+    });
+}

package/dist/src/response-stages.d.ts

@@ -0,0 +1,184 @@
+import type { ResponseEpisode } from "./response-episodes.js";
+import type { ResponseAuditStore } from "./response-store.js";
+export declare function assessResponseStages(store: ResponseAuditStore, cohort: string, e: ResponseEpisode, params: {
+    apiKey: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+}, sentimentEnabled: boolean, usage: {
+    stageAttempts: number;
+    stageCacheHits: number;
+}): Promise<{
+    retrospective: {
+        status: ResponseEpisode["followup"]["status"];
+        judgment: import("typebox").Static<import("typebox").TObject<{
+            answers: import("typebox").TObject<{
+                correction: import("typebox").TObject<{
+                    type: import("typebox").TLiteral<"noul">;
+                    noul: import("typebox").TNumber;
+                }>;
+                deliveryAdmission: import("typebox").TObject<{
+                    type: import("typebox").TLiteral<"noul">;
+                    noul: import("typebox").TNumber;
+                }>;
+                regression: import("typebox").TObject<{
+                    type: import("typebox").TLiteral<"noul">;
+                    noul: import("typebox").TNumber;
+                }>;
+                scopeClarification: import("typebox").TObject<{
+                    type: import("typebox").TLiteral<"noul">;
+                    noul: import("typebox").TNumber;
+                }>;
+                outcome: import("typebox").TObject<{
+                    type: import("typebox").TLiteral<"choice">;
+                    choice: import("typebox").TEnum<("unknown" | "reported_shortfall" | "acknowledged_success")[]>;
+                    confidence: import("typebox").TNumber;
+                    probabilities: import("typebox").TObject<{
+                        [k: string]: import("typebox").TNumber;
+                    }>;
+                }>;
+                reason: import("typebox").TObject<{
+                    type: import("typebox").TLiteral<"choice">;
+                    choice: import("typebox").TEnum<("none_or_unclear" | "missing_requested_work" | "unnecessary_deferral" | "regression" | "incorrect_claim" | "wrong_scope" | "failed_delivery")[]>;
+                    confidence: import("typebox").TNumber;
+                    probabilities: import("typebox").TObject<{
+                        [k: string]: import("typebox").TNumber;
+                    }>;
+                }>;
+            }>;
+        }>>["answers"] | null;
+    };
+    quality: {
+        taskType: {
+            type: "choice";
+            choice: "action" | "question" | "artifact" | "discussion" | "other";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+        assessability: {
+            type: "choice";
+            choice: "assessable" | "not_assessable";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+        fitAssessability: {
+            type: "choice";
+            choice: "assessable" | "not_assessable";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+        underdelivery: {
+            type: "noul";
+            noul: number;
+        };
+        failureReason: {
+            type: "choice";
+            choice: "none_or_unclear" | "missing_requested_work" | "wrong_deliverable" | "missed_constraint" | "insufficient_answer_depth" | "unnecessary_deferral";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+        fulfillment: {
+            type: "score";
+            confidence: number;
+            probabilities: {
+                "0": number;
+                "1": number;
+                "2": number;
+                "3": number;
+            };
+            score: number;
+        };
+        deliverableFit: {
+            type: "score";
+            confidence: number;
+            probabilities: {
+                "0": number;
+                "1": number;
+                "2": number;
+                "3": number;
+            };
+            score: number;
+        };
+        consistency: {
+            type: "choice";
+            choice: "not_assessable" | "consistent" | "contradicted";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+    };
+    feedback: {
+        feedbackType: {
+            type: "choice";
+            choice: "mixed" | "unrelated" | "unclear" | "acceptance" | "correction" | "continuation";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+        target: {
+            type: "choice";
+            choice: "delivery" | "mixed" | "unclear" | "current_answer" | "earlier_behavior" | "proactive_action" | "external" | "new_work";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+        avoidableRework: {
+            type: "noul";
+            noul: number;
+        };
+        repeatedConstraint: {
+            type: "noul";
+            noul: number;
+        };
+        memoryGap: {
+            type: "noul";
+            noul: number;
+        };
+    } & Partial<{
+        sentiment: {
+            type: "choice";
+            choice: "satisfied" | "dissatisfied" | "mixed" | "neutral" | "unrelated" | "unclear";
+            confidence: number;
+            probabilities: {
+                [x: string]: number;
+                [x: number]: number;
+            };
+        };
+        annoyance: {
+            type: "noul";
+            noul: number;
+        };
+        frustration: {
+            type: "noul";
+            noul: number;
+        };
+        dissatisfactionIntensity: {
+            type: "score";
+            confidence: number;
+            probabilities: {
+                "0": number;
+                "1": number;
+                "2": number;
+                "3": number;
+            };
+            score: number;
+        };
+    }>;
+}>;

package/dist/src/response-stages.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { RESPONSE_EXTRACTOR_VERSION } from "./response-episodes.js";
+import { judgeResponse, judgeResponseFollowup, RESPONSE_STAGE_VERSIONS } from "./response-judge.js";
+import { TYPESAFE_REVIEW_MODEL } from "./typesafe-review.js";
+export async function assessResponseStages(store, cohort, e, params, sentimentEnabled, usage) {
+    const original = { before: e.before, request: e.request, answer: e.answer, contextLimited: e.contextLimited };
+    const feedback = { ...original, feedback: e.feedback };
+    const evidence = { quality: original, feedback, sentiment: feedback, retrospective: { ...feedback, followup: e.followup } };
+    const keys = Object.fromEntries(Object.keys(evidence).map(stage => [stage,
+        createHash("sha256").update(JSON.stringify([RESPONSE_EXTRACTOR_VERSION, TYPESAFE_REVIEW_MODEL, RESPONSE_STAGE_VERSIONS[stage],
+            e.id, e.session, e.senderId, e.thread, evidence[stage]])).digest("hex"),
+    ]));
+    const cache = {
+        quality: store.stage(cohort, e, "quality", keys.quality),
+        feedback: store.stage(cohort, e, "feedback", keys.feedback),
+        sentiment: sentimentEnabled ? store.stage(cohort, e, "sentiment", keys.sentiment) : undefined,
+        begin(stages) {
+            params.signal.throwIfAborted();
+            store.stageBegin(stages.map(stage => keys[stage]), Date.now());
+            usage.stageAttempts += stages.length;
+        },
+        save(stage, result) {
+            params.signal.throwIfAborted();
+            store.stageSave(keys[stage], result, Date.now());
+        },
+    };
+    usage.stageCacheHits += Number(!!cache.quality) + Number(!!cache.feedback) + Number(!!cache.sentiment);
+    const judgment = await judgeResponse(e, params, sentimentEnabled, cache);
+    let retrospective = store.stage(cohort, e, "retrospective", keys.retrospective);
+    if (retrospective)
+        usage.stageCacheHits++;
+    if (!retrospective) {
+        cache.begin(["retrospective"]);
+        retrospective = await judgeResponseFollowup(e, params);
+        cache.save("retrospective", retrospective);
+    }
+    return { ...judgment, retrospective };
+}