@unblocklabs/unblock-memory 0.3.15 → 0.3.16

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

@@ -0,0 +1,68 @@
+import type { ResponseAuditConfig } from "./response-config.js";
+export declare const RESPONSE_EXTRACTOR_VERSION = 5;
+type Row = {
+    seq: number;
+    eventJson: string;
+    createdAt: number;
+};
+export type ResponseSession = {
+    sessionId: string;
+    accountId: string;
+    chatType: string;
+    conversationId: string;
+};
+type Text = {
+    seq: number;
+    role: "user" | "assistant";
+    text: string;
+};
+export type ResponseEpisode = {
+    id: string;
+    inputHash: string;
+    session: ResponseSession;
+    senderId: string;
+    thread: string;
+    timestamp: number;
+    model: string;
+    before: Text[];
+    request: Text[];
+    answer: Text[];
+    feedback: Text[];
+    followup: {
+        status: "pending" | "complete" | "partial" | "unavailable" | "oversized";
+        messages: Text[];
+    };
+    memorySearchCalls: number;
+    contextLimited: boolean;
+};
+type ResponseCoverage = {
+    completedResponses: number;
+    eligible: number;
+    noFeedback: number;
+    pendingFeedback: number;
+    oversized: number;
+    filteredEvents: number;
+};
+/** Never deduce human identity from text or the user role alone. */
+export declare function responseEpisodes(session: ResponseSession, rows: readonly Row[], config: ResponseAuditConfig): {
+    episodes: ResponseEpisode[];
+    coverage: ResponseCoverage;
+};
+/** Bounded, read-only active transcript snapshot; archived/deleted branches are excluded. */
+export declare class ResponseTranscriptReader {
+    #private;
+    constructor(path: string, agentId: string);
+    sessions(config: ResponseAuditConfig, now: number, after?: string): ResponseSession[];
+    /** null = confirmed absent/ineligible; undefined = over budget, not evidence of deletion. */
+    read(input: ResponseSession | string, config: ResponseAuditConfig): (ReturnType<typeof responseEpisodes> & {
+        revision: string;
+    }) | null | undefined;
+    read(input: ResponseSession | string, config: ResponseAuditConfig, previousRevision: string | undefined): (ReturnType<typeof responseEpisodes> & {
+        revision: string;
+    }) | {
+        unchanged: true;
+        revision: string;
+    } | null | undefined;
+    close(): void;
+}
+export {};

package/dist/src/response-episodes.js

@@ -0,0 +1,242 @@
+import { createHash } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { messageText } from "./whisperer-context.js";
+import { responseUserText } from "./response-text.js";
+export const RESPONSE_EXTRACTOR_VERSION = 5;
+const MAX_EVENTS = 2000, MAX_SESSION_BYTES = 2_000_000, MAX_EPISODE_CHARS = 24_000;
+function record(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+/** Never deduce human identity from text or the user role alone. */
+export function responseEpisodes(session, rows, config) {
+    const coverage = { completedResponses: 0, eligible: 0, noFeedback: 0,
+        pendingFeedback: 0, oversized: 0, filteredEvents: 0 };
+    const episodes = [];
+    let history = [], historyDropped = false;
+    let followupTarget;
+    const closeFollowup = (safe, partial = false) => {
+        if (!followupTarget)
+            return;
+        if (!safe || !current?.answer.length || (!partial && !current.final))
+            followupTarget.followup = { status: "unavailable", messages: [] };
+        else if (current.answer.length > 6 || JSON.stringify(current.answer).length > 12_000) {
+            followupTarget.followup = { status: "oversized", messages: [] };
+        }
+        else
+            followupTarget.followup = { status: partial ? "partial" : "complete", messages: [...current.answer] };
+        followupTarget = undefined;
+    };
+    let current;
+    let pending = [];
+    const finish = (closed) => {
+        if (!current?.final) {
+            current = undefined;
+            return;
+        }
+        coverage.completedResponses++;
+        if (!current.feedback.length)
+            coverage.noFeedback++;
+        else if (!closed)
+            coverage.pendingFeedback++;
+        else if (current.feedback.length > 6 || JSON.stringify(current).length > MAX_EPISODE_CHARS)
+            coverage.oversized++;
+        else {
+            const { final: _final, ...content } = current;
+            const id = hash([session.sessionId, current.answer.at(-1).seq]);
+            const episode = { id, inputHash: "", session, ...content, followup: { status: "pending", messages: [] } };
+            episodes.push(episode);
+            followupTarget = episode;
+            coverage.eligible++;
+        }
+        current = undefined;
+    };
+    const boundary = () => { closeFollowup(false); finish(false); history = []; historyDropped = false; pending = []; };
+    const remember = (text) => {
+        history.push(text);
+        if (history.length > config.historyMessages) {
+            history.shift();
+            historyDropped = true;
+        }
+    };
+    for (const row of rows) {
+        let e;
+        try {
+            e = record(JSON.parse(row.eventJson));
+        }
+        catch {
+            coverage.filteredEvents++;
+            boundary();
+            continue;
+        }
+        if (e?.type !== "message") {
+            // Compaction/context rewrites cannot silently join unrelated transcript segments.
+            if (e?.type === "compaction")
+                boundary();
+            continue;
+        }
+        const m = record(e.message), meta = record(m?.__openclaw);
+        if (!m) {
+            boundary();
+            continue;
+        }
+        if (m.role === "toolResult")
+            continue; // Tool bodies/thinking are never sent.
+        if (m.role === "user") {
+            const identity = record(meta?.senderIdentity), transport = record(meta?.transport);
+            const senderId = meta?.senderId;
+            const human = identity?.senderKind !== "bot" && (identity?.senderKind === "human" || meta?.senderIsOwner === true);
+            if (m.provenance !== undefined || !human ||
+                typeof senderId !== "string" || !config.senderIds.includes(senderId) ||
+                transport?.channel !== "slack" || transport.conversationRef !== session.conversationId) {
+                coverage.filteredEvents++;
+                boundary();
+                continue;
+            }
+            const raw = typeof meta?.upstreamUserText === "string" ? meta.upstreamUserText : messageText(m)?.text;
+            const visible = raw ? responseUserText(raw, senderId) : undefined;
+            if (!visible) {
+                coverage.filteredEvents++;
+                boundary();
+                continue;
+            }
+            const thread = typeof transport.threadId === "string" ? transport.threadId : "";
+            if ((current && (current.senderId !== senderId || current.thread !== thread)) ||
+                pending.some(p => p.senderId !== senderId || p.thread !== thread))
+                boundary();
+            closeFollowup(true);
+            if (visible.contextLimited)
+                historyDropped = true;
+            const text = { seq: row.seq, role: "user", text: visible.text };
+            if (current) {
+                if (!current.final)
+                    boundary();
+                else
+                    current.feedback.push(text);
+            }
+            pending.push({ text, senderId, thread });
+            continue;
+        }
+        if (m.role !== "assistant") {
+            coverage.filteredEvents++;
+            boundary();
+            continue;
+        }
+        if (m.provenance !== undefined || meta?.turnTainted === true) {
+            coverage.filteredEvents++;
+            boundary();
+            continue;
+        }
+        if (m.provider === "openclaw" && (m.model === "delivery-mirror" || m.model === "gateway-injected")) {
+            // Preserve only preceding clean assistant evidence, never the synthetic notice.
+            // This is not a completed response and cannot enter the original quality grade.
+            closeFollowup(true, true);
+            coverage.filteredEvents++;
+            boundary();
+            continue;
+        }
+        if (pending.length) {
+            const request = pending.map(p => p.text), identity = pending[0];
+            finish(true);
+            current = { request, before: [...history], answer: [], feedback: [], senderId: identity.senderId,
+                thread: identity.thread, final: false, timestamp: row.createdAt, model: "unknown",
+                memorySearchCalls: 0, contextLimited: historyDropped };
+            pending = [];
+            request.forEach(remember);
+        }
+        if (!current)
+            continue;
+        if (meta?.turnTainted === true || m.stopReason === "error" || m.stopReason === "aborted") {
+            boundary();
+            continue;
+        }
+        if (Array.isArray(m.content)) {
+            current.memorySearchCalls += m.content.filter(p => {
+                const block = record(p);
+                return block?.type === "toolCall" && (block.name === "memory_search" || block.name === "memory_get");
+            }).length;
+        }
+        const text = messageText(m)?.text;
+        if (!text || text === "NO_REPLY" || text === "HEARTBEAT_OK" || m.channel === "analysis")
+            continue;
+        const item = { seq: row.seq, role: "assistant", text };
+        current.answer.push(item);
+        remember(item);
+        current.model = typeof m.model === "string" ? m.model : "unknown";
+        current.timestamp = row.createdAt;
+        current.final = meta?.runTerminal === true || (m.stopReason === "stop" && m.channel !== "commentary");
+    }
+    if (current?.final)
+        closeFollowup(true);
+    finish(false); // No next assistant turn: the feedback block may still grow.
+    for (const episode of episodes) {
+        const { inputHash: _hash, session: s, ...content } = episode;
+        episode.inputHash = hash([RESPONSE_EXTRACTOR_VERSION, s.sessionId, s.accountId, s.chatType, s.conversationId, content]);
+    }
+    return { episodes, coverage };
+}
+/** Bounded, read-only active transcript snapshot; archived/deleted branches are excluded. */
+export class ResponseTranscriptReader {
+    #db;
+    constructor(path, agentId) {
+        this.#db = new DatabaseSync(path, { readOnly: true });
+        try {
+            this.#db.exec("PRAGMA query_only=ON; PRAGMA busy_timeout=1000");
+            const version = this.#db.prepare("PRAGMA user_version").get()?.user_version;
+            const meta = this.#db.prepare("SELECT role,agent_id,schema_version FROM schema_meta WHERE meta_key='primary'").get();
+            if (![17, 18, 19].includes(Number(version)) || meta?.role !== "agent" || meta.agent_id !== agentId || meta.schema_version !== version) {
+                throw new Error("Unsupported response-audit transcript schema or agent");
+            }
+        }
+        catch (error) {
+            this.#db.close();
+            throw error;
+        }
+    }
+    sessions(config, now, after = "") {
+        return this.#db.prepare(`SELECT w.session_id sessionId, COALESCE(w.account_id,c.account_id,'') accountId,
+      w.chat_type chatType, w.primary_conversation_id conversationId
+      FROM session_windows w JOIN conversations c ON c.conversation_id=w.primary_conversation_id
+      WHERE COALESCE(w.channel,c.channel)='slack' AND w.chat_type IN (${config.chatTypes.map(() => "?").join(",")})
+      AND w.session_id>?
+      AND EXISTS (SELECT 1 FROM transcript_events e JOIN session_transcript_active_events a
+        ON a.session_id=e.session_id AND a.event_seq=e.seq WHERE e.session_id=w.session_id AND e.created_at >= ?
+        AND json_extract(e.event_json,'$.message.role')='user'
+        AND json_extract(e.event_json,'$.message.__openclaw.senderId') IN (${config.senderIds.map(() => "?").join(",")}))
+      ORDER BY w.session_id LIMIT 101`)
+            .all(...config.chatTypes, after, now - config.lookbackDays * 86400_000, ...config.senderIds);
+    }
+    read(input, config, previousRevision) {
+        this.#db.exec("BEGIN");
+        try {
+            const sessionId = typeof input === "string" ? input : input.sessionId;
+            const window = this.#db.prepare(`SELECT w.chat_type chatType,COALESCE(w.channel,c.channel) provider,
+        COALESCE(w.account_id,c.account_id,'') accountId,w.primary_conversation_id conversationId
+        FROM session_windows w JOIN conversations c ON c.conversation_id=w.primary_conversation_id WHERE w.session_id=?`).get(sessionId);
+            if (!window || window.provider !== "slack" || !config.chatTypes.some(type => type === window.chatType) ||
+                (typeof input !== "string" && (window.accountId !== input.accountId ||
+                    window.conversationId !== input.conversationId || window.chatType !== input.chatType)))
+                return null;
+            const session = { sessionId, accountId: String(window.accountId),
+                conversationId: String(window.conversationId), chatType: String(window.chatType) };
+            const count = this.#db.prepare(`SELECT COUNT(*) n,COALESCE(SUM(length(e.event_json)),0) bytes
+        FROM session_transcript_active_events a JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq
+        WHERE a.session_id=?`).get(session.sessionId);
+            if (Number(count.n) > MAX_EVENTS || Number(count.bytes) > MAX_SESSION_BYTES)
+                return undefined;
+            const rows = this.#db.prepare(`SELECT e.seq,e.event_json eventJson,e.created_at createdAt
+        FROM session_transcript_active_events a JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq
+        WHERE a.session_id=? ORDER BY a.active_position`).all(session.sessionId);
+            // Exact active content catches in-place edits and branch changes even when writer
+            // watermarks are absent. Raw text is never retained in the checkpoint database.
+            const revision = hash([RESPONSE_EXTRACTOR_VERSION, session, config.historyMessages, [...config.senderIds].sort(), rows]);
+            if (revision === previousRevision)
+                return { unchanged: true, revision };
+            return { ...responseEpisodes(session, rows, config), revision };
+        }
+        finally {
+            this.#db.exec("COMMIT");
+        }
+    }
+    close() { this.#db.close(); }
+}

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

@@ -0,0 +1,15 @@
+import type { ResponseEpisode } from "./response-episodes.js";
+export type ResponseHuman = {
+    key: string;
+    provider: "slack";
+    accountScope: string;
+    senderId: string;
+    personId: string | null;
+};
+/** Identity is trusted metadata, never inferred from names or transcript text. */
+export declare class ResponsePeople {
+    #private;
+    constructor(path?: string);
+    resolve(e: ResponseEpisode): ResponseHuman;
+    close(): void;
+}

package/dist/src/response-identity.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+/** Identity is trusted metadata, never inferred from names or transcript text. */
+export class ResponsePeople {
+    #db;
+    constructor(path) {
+        if (!path || !existsSync(path))
+            return;
+        try {
+            this.#db = new DatabaseSync(path, { readOnly: true });
+            this.#db.exec("PRAGMA query_only=ON; PRAGMA busy_timeout=1000");
+        }
+        catch {
+            this.#db?.close();
+            this.#db = undefined;
+        }
+    }
+    resolve(e) {
+        const accountScope = e.session.accountId, senderId = e.senderId;
+        let personId = null;
+        if (accountScope) {
+            try {
+                const row = this.#db?.prepare(`SELECT p.id FROM people p JOIN person_identities i ON i.person_id=p.id
+          WHERE i.provider='slack' AND i.account_scope=? AND i.external_id=? AND p.status='active'`).get(accountScope, senderId);
+                if (typeof row?.id === "string")
+                    personId = row.id;
+            }
+            catch { /* Optional people-store compatibility must not break the audit. */ }
+        }
+        return { key: JSON.stringify(["slack", accountScope || `unknown-session:${e.session.sessionId}`, senderId]),
+            provider: "slack", accountScope, senderId, personId };
+    }
+    close() { this.#db?.close(); }
+}

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

@@ -0,0 +1,224 @@
+import { Type, type Static } from "typebox";
+import type { ResponseEpisode } from "./response-episodes.js";
+export declare const RESPONSE_RUBRIC_VERSION = "jev-1.13.0:response-v10";
+export declare const RESPONSE_STAGE_VERSIONS: {
+    readonly quality: "quality-v9";
+    readonly feedback: "feedback-v9";
+    readonly sentiment: "sentiment-v10";
+    readonly retrospective: "retrospective-v9";
+    readonly memory: "memory-v1";
+};
+declare const qualitySchema: Type.TObject<{
+    answers: Type.TObject<{
+        taskType: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("action" | "question" | "artifact" | "discussion" | "other")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+        assessability: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("assessable" | "not_assessable")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+        fitAssessability: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("assessable" | "not_assessable")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+        underdelivery: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+        failureReason: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("none_or_unclear" | "missing_requested_work" | "wrong_deliverable" | "missed_constraint" | "insufficient_answer_depth" | "unnecessary_deferral")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+        fulfillment: Type.TObject<{
+            type: Type.TLiteral<"score">;
+            score: Type.TNumber;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                "0": Type.TNumber;
+                "1": Type.TNumber;
+                "2": Type.TNumber;
+                "3": Type.TNumber;
+            }>;
+        }>;
+        deliverableFit: Type.TObject<{
+            type: Type.TLiteral<"score">;
+            score: Type.TNumber;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                "0": Type.TNumber;
+                "1": Type.TNumber;
+                "2": Type.TNumber;
+                "3": Type.TNumber;
+            }>;
+        }>;
+        consistency: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("not_assessable" | "consistent" | "contradicted")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+    }>;
+}>;
+declare const sentimentSchema: Type.TObject<{
+    sentiment: Type.TObject<{
+        type: Type.TLiteral<"choice">;
+        choice: Type.TEnum<("satisfied" | "dissatisfied" | "mixed" | "neutral" | "unrelated" | "unclear")[]>;
+        confidence: Type.TNumber;
+        probabilities: Type.TObject<{
+            [k: string]: Type.TNumber;
+        }>;
+    }>;
+    annoyance: Type.TObject<{
+        type: Type.TLiteral<"noul">;
+        noul: Type.TNumber;
+    }>;
+    frustration: Type.TObject<{
+        type: Type.TLiteral<"noul">;
+        noul: Type.TNumber;
+    }>;
+    dissatisfactionIntensity: Type.TObject<{
+        type: Type.TLiteral<"score">;
+        score: Type.TNumber;
+        confidence: Type.TNumber;
+        probabilities: Type.TObject<{
+            "0": Type.TNumber;
+            "1": Type.TNumber;
+            "2": Type.TNumber;
+            "3": Type.TNumber;
+        }>;
+    }>;
+}>;
+declare const feedbackSchema: Type.TObject<{
+    answers: Type.TObject<{
+        feedbackType: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("mixed" | "unrelated" | "unclear" | "acceptance" | "correction" | "continuation")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+        target: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("delivery" | "mixed" | "unclear" | "current_answer" | "earlier_behavior" | "proactive_action" | "external" | "new_work")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+        avoidableRework: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+        repeatedConstraint: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+        memoryGap: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+    }>;
+}>;
+type ResponseQuality = Static<typeof qualitySchema>["answers"];
+type ResponseFeedback = Static<typeof feedbackSchema>["answers"] & Partial<Static<typeof sentimentSchema>>;
+export type ResponseJudgment = {
+    quality: ResponseQuality;
+    feedback: ResponseFeedback;
+};
+export type ResponseStages = {
+    quality: ResponseQuality;
+    feedback: Static<typeof feedbackSchema>["answers"];
+    sentiment: Static<typeof sentimentSchema>;
+    retrospective: Awaited<ReturnType<typeof judgeResponseFollowup>>;
+    memory: Awaited<ReturnType<typeof judgeMemoryOpportunity>>;
+};
+type StageCache = Partial<ResponseStages> & {
+    begin: (stages: (keyof ResponseStages)[]) => void;
+    save: <K extends keyof ResponseStages>(stage: K, result: ResponseStages[K]) => void;
+};
+/** Separate requests are deliberate: later feedback must not leak into the original quality grade. */
+export declare function judgeResponse(episode: ResponseEpisode, params: {
+    apiKey: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+}, sentimentEnabled?: boolean, cache?: StageCache): Promise<ResponseJudgment>;
+declare const retrospectiveSchema: Type.TObject<{
+    answers: Type.TObject<{
+        correction: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+        deliveryAdmission: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+        regression: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+        scopeClarification: Type.TObject<{
+            type: Type.TLiteral<"noul">;
+            noul: Type.TNumber;
+        }>;
+        outcome: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("unknown" | "reported_shortfall" | "acknowledged_success")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+        reason: Type.TObject<{
+            type: Type.TLiteral<"choice">;
+            choice: Type.TEnum<("none_or_unclear" | "missing_requested_work" | "unnecessary_deferral" | "regression" | "incorrect_claim" | "wrong_scope" | "failed_delivery")[]>;
+            confidence: Type.TNumber;
+            probabilities: Type.TObject<{
+                [k: string]: Type.TNumber;
+            }>;
+        }>;
+    }>;
+}>;
+/** Later evidence is kept in a third request and never changes the original grade. */
+export declare function judgeResponseFollowup(episode: ResponseEpisode, params: {
+    apiKey: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+}): Promise<{
+    status: ResponseEpisode["followup"]["status"];
+    judgment: Static<typeof retrospectiveSchema>["answers"] | null;
+}>;
+export declare function judgeMemoryOpportunity(episode: ResponseEpisode, candidates: readonly {
+    path: string;
+    text: string;
+    hash: string;
+}[], params: {
+    apiKey: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+}): Promise<{
+    path: string;
+    hash: string;
+    usefulness: number;
+    basis: string;
+}[]>;
+export {};