@unblocklabs/unblock-memory 0.3.15 → 0.3.16

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 };
+}

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

@@ -0,0 +1,180 @@
+import type { ResponseEpisode } from "./response-episodes.js";
+import type { ResponseJudgment, ResponseStages, judgeMemoryOpportunity, judgeResponseFollowup } from "./response-judge.js";
+import { responseOutcome } from "./response-outcome.js";
+import type { ResponseHuman } from "./response-identity.js";
+import { ResponseReviews } from "./response-reviews.js";
+export type ResponseResult = ResponseJudgment & {
+    references: {
+        sessionId: string;
+        request: number[];
+        answer: number[];
+        feedback: number[];
+        followup: number[];
+        inputHash: string;
+    };
+    retrospective: Awaited<ReturnType<typeof judgeResponseFollowup>>;
+    agentModel: string;
+    human?: ResponseHuman;
+    contextLimited: boolean;
+    memorySearchCalls: number;
+    memory: {
+        status: "not_requested" | "unavailable" | "checked";
+        candidates: Awaited<ReturnType<typeof judgeMemoryOpportunity>>;
+    };
+};
+export type ResponseReportOptions = {
+    until?: number;
+    bucket?: "day" | "week";
+    senderId?: string;
+    accountScope?: string;
+    personId?: string;
+    taskType?: string;
+    agentModel?: string;
+};
+/** Separate operator-only database: not a memory corpus and never injected into agent prompts. */
+export declare class ResponseAuditStore {
+    #private;
+    readonly reviews: ResponseReviews;
+    constructor(path: string);
+    /** Claim one bounded scheduled attempt, never replay every missed interval. */
+    claimScheduled(now: number, intervalMs: number): boolean;
+    acquire(now: number): string | undefined;
+    release(token: string): void;
+    activeSessions(cohort: string, since: number): string[];
+    observe(cohort: string, sessionId: string, episodes: readonly ResponseEpisode[]): void;
+    needsJudgment(cohort: string, e: ResponseEpisode, now: number): boolean;
+    attempted(cohort: string, e: ResponseEpisode, now: number): void;
+    stale(cohort: string, e: ResponseEpisode): void;
+    save(cohort: string, e: ResponseEpisode, result: ResponseResult, now: number): void;
+    cursor(cohort: string): string;
+    advance(cohort: string, cursor: string): void;
+    checkpoint(cohort: string, session: string): {
+        revision: string;
+        coverage: ReturnType<typeof import("./response-episodes.js").responseEpisodes>["coverage"];
+    } | undefined;
+    checkpointSave(cohort: string, session: string, revision: string, coverage: object): void;
+    checkpointForget(cohort: string, session: string): void;
+    sessionWork(cohort: string, session: string, since: number, now: number): {
+        total: number;
+        due: number;
+    };
+    pendingWork(cohort: string, since: number, now: number): number;
+    stage<K extends keyof ResponseStages>(cohort: string, e: ResponseEpisode, stage: K, key: string): ResponseStages[K] | undefined;
+    stageBegin(keys: string[], now: number): void;
+    stageSave<K extends keyof ResponseStages>(key: string, result: ResponseStages[K], now: number): void;
+    retryFailed(cohort: string): {
+        stages: number | bigint;
+        episodes: number | bigint;
+    };
+    scan(cohort: string, coverage: object, now: number): void;
+    report(cohort: string, since: number, id?: string, options?: ResponseReportOptions): {
+        limitations: string[];
+        episode?: {
+            result: any;
+        } | null | undefined;
+        cohort: string;
+        reportVersion: string;
+        reviewPolicy: string;
+        bucket: "day" | "week";
+        since: number;
+        until: number;
+        annotations: Record<string, import("node:sqlite").SQLOutputValue>[];
+        stages: Record<string, import("node:sqlite").SQLOutputValue>[];
+        stageCountsScope: string;
+        rubricScope: string;
+        coverage: any;
+        stored: number;
+        reportCapped: boolean;
+        failedOrPending: number;
+        groups: {
+            periodStart: string;
+            fulfillmentMean: number | null;
+            deliverableFitMean: number | null;
+            sentimentNotAssessed: number;
+            sentimentUnknown: number;
+            sentimentCoverage: number;
+            dissatisfactionRate: number | null;
+            sentimentUnknownRate: number | null;
+            annoyanceRate: number | null;
+            frustrationRate: number | null;
+            dissatisfactionIntensityMean: number | null;
+            observedSuccessRate: number | null;
+            observedSuccessRate95Interval: number[] | null;
+            outcomeUnknown: number;
+            outcomeCoverage: number;
+            acknowledgedRate: number;
+            reportedShortfallRate: number;
+            unknownRate: number;
+            underdeliveryRate: number | null;
+            underdeliveryRate95Interval: number[] | null;
+            reworkRate: number | null;
+            reworkRate95Interval: number[] | null;
+            smallSample: boolean;
+            week: string;
+            human: ResponseHuman | null;
+            taskType: string;
+            agentModel: string;
+            evaluated: number;
+            assessable: number;
+            fitAssessable: number;
+            fulfillmentScored: number;
+            deliverableFitScored: number;
+            feedbackCertain: number;
+            accepted: number;
+            reworkCertain: number;
+            rework: number;
+            memoryGap: number;
+            dissatisfied: number;
+            sentimentAssessed: number;
+            sentimentCertain: number;
+            emotionAssessed: number;
+            annoyed: number;
+            frustrated: number;
+            annoyanceUncertain: number;
+            frustrationUncertain: number;
+            dissatisfactionIntensityScored: number;
+            underdeliveryCertain: number;
+            underdelivery: number;
+            failureReasons: Record<string, number>;
+            feedbackTargets: Record<string, number>;
+            retrospectiveAssessed: number;
+            laterCorrections: number;
+            deliveryAdmissions: number;
+            outcomeKnown: number;
+            acknowledgedSuccess: number;
+            reportedShortfall: number;
+            outcomeReasons: Record<string, number>;
+        }[];
+        trends: {
+            fromWeek: string;
+            toWeek: string;
+            taskType: string;
+            agentModel: string;
+            fromPeriod: string;
+            toPeriod: string;
+            human: ResponseHuman | null;
+            dimension: "fulfillment" | "deliverableFit" | "dissatisfactionIntensity" | "acknowledgedRate" | "reportedShortfallRate" | "unknownRate" | "dissatisfactionRate" | "sentimentUnknownRate" | "annoyanceRate" | "frustrationRate";
+            beforeN: number;
+            afterN: number;
+            status: string;
+            before: number | null;
+            after: number | null;
+            beforeEvaluated: number;
+            afterEvaluated: number;
+            beforeCoverage: number;
+            afterCoverage: number;
+            coverageChanged: boolean;
+            denominator: string;
+            scale: string;
+            delta: number | null;
+        }[];
+        examples: {
+            id: string;
+            episodeAt: number;
+            assessedAt: number;
+            signals: string[];
+            outcome: ReturnType<typeof responseOutcome>;
+        }[];
+    };
+    close(): void;
+}