@unblocklabs/unblock-memory 0.3.14 → 0.3.16

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

@@ -0,0 +1,87 @@
+import type { UnblockMemoryConfig } from "./config.js";
+import type { ResolvedSource } from "./sources.js";
+export declare function responseCohort(config: UnblockMemoryConfig["responseAudit"]): string;
+export type ResponseAuditOptions = {
+    agentId: string;
+    databasePath: string;
+    storePath: string;
+    indexPath: string;
+    config: UnblockMemoryConfig;
+    sources: readonly ResolvedSource[];
+    signal?: AbortSignal;
+    dryRun?: boolean;
+    peoplePath?: string;
+};
+/** All inference is outside memory's mutation queue and outside transcript DB transactions. */
+export declare function auditResponses(options: ResponseAuditOptions): Promise<{
+    status: "disabled";
+    reason?: undefined;
+    cohort?: undefined;
+    coverage?: undefined;
+} | {
+    status: "unavailable";
+    reason: string;
+    cohort?: undefined;
+    coverage?: undefined;
+} | {
+    status: "already_running";
+    reason?: undefined;
+    cohort?: undefined;
+    coverage?: undefined;
+} | {
+    status: "ok" | "dry_run";
+    cohort: string;
+    coverage: {
+        sessions: number;
+        sessionLimitReached: boolean;
+        sessionsOverBudget: number;
+        completedResponses: number;
+        reconciledSessions: number;
+        reconciliationDeferred: number;
+        extractedSessions: number;
+        unchangedSessions: number;
+        stageAttempts: number;
+        stageCacheHits: number;
+        eligible: number;
+        noFeedback: number;
+        pendingFeedback: number;
+        oversized: number;
+        filteredEvents: number;
+        outsideLookback: number;
+        attempted: number;
+        evaluated: number;
+        cachedOrBackoff: number;
+        deferredByLimit: number;
+        failed: number;
+        stale: number;
+    };
+    reason?: undefined;
+} | {
+    status: "unavailable";
+    reason: string;
+    cohort: string;
+    coverage: {
+        sessions: number;
+        sessionLimitReached: boolean;
+        sessionsOverBudget: number;
+        completedResponses: number;
+        reconciledSessions: number;
+        reconciliationDeferred: number;
+        extractedSessions: number;
+        unchangedSessions: number;
+        stageAttempts: number;
+        stageCacheHits: number;
+        eligible: number;
+        noFeedback: number;
+        pendingFeedback: number;
+        oversized: number;
+        filteredEvents: number;
+        outsideLookback: number;
+        attempted: number;
+        evaluated: number;
+        cachedOrBackoff: number;
+        deferredByLimit: number;
+        failed: number;
+        stale: number;
+    };
+}>;

package/dist/src/response-audit.js

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { abortable } from "./abortable.js";
+import { resolveTypeSafeApiKey } from "./typesafe.js";
+import { RESPONSE_EXTRACTOR_VERSION, ResponseTranscriptReader } from "./response-episodes.js";
+import { RESPONSE_RUBRIC_VERSION, RESPONSE_STAGE_VERSIONS, judgeMemoryOpportunity } from "./response-judge.js";
+import { ResponseAuditStore } from "./response-store.js";
+import { responseMemoryCandidates } from "./response-memory.js";
+import { assessResponseStages } from "./response-stages.js";
+import { ResponsePeople } from "./response-identity.js";
+import { TYPESAFE_REVIEW_MODEL } from "./typesafe-review.js";
+export function responseCohort(config) {
+    return RESPONSE_RUBRIC_VERSION + ":" + createHash("sha256").update(JSON.stringify({
+        extractor: RESPONSE_EXTRACTOR_VERSION, historyMessages: config.historyMessages,
+        stages: RESPONSE_STAGE_VERSIONS,
+        sentimentEnabled: config.sentimentEnabled,
+        senderIds: [...config.senderIds].sort(), chatTypes: [...config.chatTypes].sort(), memoryCorpora: [...config.memoryCorpora].sort(),
+    })).digest("hex").slice(0, 16);
+}
+/** All inference is outside memory's mutation queue and outside transcript DB transactions. */
+export async function auditResponses(options) {
+    const { config, agentId } = options;
+    if (!config.responseAudit.enabled || !config.typesafe.enabled)
+        return { status: "disabled" };
+    const signal = AbortSignal.any([AbortSignal.timeout(120_000), ...(options.signal ? [options.signal] : [])]);
+    const cohort = responseCohort(config.responseAudit);
+    let key;
+    if (!options.dryRun) {
+        try {
+            key = await abortable(resolveTypeSafeApiKey(config.typesafe), signal);
+        }
+        catch {
+            return { status: "unavailable", reason: "Credentials unavailable or audit cancelled" };
+        }
+        if (!key)
+            return { status: "unavailable", reason: "TypeSafe API key not configured" };
+    }
+    let reader, store, lease;
+    const people = new ResponsePeople(options.peoplePath);
+    const now = Date.now();
+    const coverage = { sessions: 0, sessionLimitReached: false, sessionsOverBudget: 0, completedResponses: 0,
+        reconciledSessions: 0, reconciliationDeferred: 0,
+        extractedSessions: 0, unchangedSessions: 0,
+        stageAttempts: 0, stageCacheHits: 0,
+        eligible: 0, noFeedback: 0, pendingFeedback: 0, oversized: 0, filteredEvents: 0, outsideLookback: 0,
+        attempted: 0, evaluated: 0, cachedOrBackoff: 0, deferredByLimit: 0, failed: 0, stale: 0 };
+    try {
+        signal.throwIfAborted();
+        if (!options.dryRun) {
+            store = new ResponseAuditStore(options.storePath);
+            lease = store.acquire(now);
+            if (!lease)
+                return { status: "already_running" };
+        }
+        reader = new ResponseTranscriptReader(options.databasePath, agentId);
+        const since = now - config.responseAudit.lookbackDays * 86400_000;
+        store?.reviews.refresh(cohort, since);
+        const cursor = store?.cursor(cohort) ?? "";
+        const tracked = new Set(store?.activeSessions(cohort, since) ?? []);
+        const sessions = [...new Set([...reader.sessions(config.responseAudit, now, cursor).map(s => s.sessionId),
+                ...[...tracked].filter(id => id > cursor)])].sort();
+        coverage.sessionLimitReached = sessions.length > 100;
+        let stoppedForBudget = false;
+        for (const session of sessions.slice(0, 100)) {
+            await new Promise(resolve => setImmediate(resolve));
+            signal.throwIfAborted();
+            coverage.sessions++;
+            const checkpoint = store?.checkpoint(cohort, session);
+            const work = store?.sessionWork(cohort, session, since, now);
+            const snapshot = reader.read(session, config.responseAudit, work?.due ? undefined : checkpoint?.revision);
+            if (snapshot === undefined) {
+                coverage.sessionsOverBudget++;
+                coverage.reconciliationDeferred++;
+                store?.advance(cohort, session);
+                continue;
+            }
+            if (snapshot === null) {
+                store?.observe(cohort, session, []);
+                store?.checkpointForget(cohort, session);
+                coverage.reconciledSessions++;
+                store?.advance(cohort, session);
+                continue;
+            }
+            if ("unchanged" in snapshot) {
+                coverage.unchangedSessions++;
+                coverage.cachedOrBackoff += work?.total ?? 0;
+                if (checkpoint)
+                    for (const key of Object.keys(checkpoint.coverage))
+                        coverage[key] += checkpoint.coverage[key];
+                store?.advance(cohort, session);
+                continue;
+            }
+            coverage.extractedSessions++;
+            if (tracked.has(session))
+                coverage.reconciledSessions++;
+            for (const key of Object.keys(snapshot.coverage))
+                coverage[key] += snapshot.coverage[key];
+            const episodes = snapshot.episodes.filter(e => e.timestamp >= now - config.responseAudit.lookbackDays * 86400_000);
+            coverage.outsideLookback += snapshot.episodes.length - episodes.length;
+            store?.observe(cohort, session, snapshot.episodes);
+            store?.checkpointSave(cohort, session, snapshot.revision, snapshot.coverage);
+            // Oldest first within a session; new data cannot forever starve its existing backlog.
+            for (const e of episodes) {
+                signal.throwIfAborted();
+                if (options.dryRun)
+                    continue;
+                if (!store.needsJudgment(cohort, e, Date.now())) {
+                    coverage.cachedOrBackoff++;
+                    continue;
+                }
+                if (coverage.attempted >= config.responseAudit.maxEpisodes) {
+                    coverage.deferredByLimit++;
+                    continue;
+                }
+                coverage.attempted++;
+                store.attempted(cohort, e, Date.now());
+                try {
+                    const params = { apiKey: key, timeoutMs: config.typesafe.timeoutMs, signal };
+                    const judgment = await abortable(assessResponseStages(store, cohort, e, params, config.responseAudit.sentimentEnabled, coverage), signal);
+                    let memory = { status: "not_requested", candidates: [] };
+                    if (judgment.feedback.memoryGap.noul >= 0.8 && config.responseAudit.memoryCorpora.length) {
+                        try {
+                            const approved = options.sources.filter(s => config.responseAudit.memoryCorpora.includes(s.corpus));
+                            const candidates = responseMemoryCandidates(options.indexPath, approved, e);
+                            const memoryKey = createHash("sha256").update(JSON.stringify([TYPESAFE_REVIEW_MODEL, RESPONSE_STAGE_VERSIONS.memory,
+                                e.id, e.session, e.senderId, e.request, e.answer, e.feedback, candidates,
+                                [...config.responseAudit.memoryCorpora].sort()])).digest("hex");
+                            let judged = store.stage(cohort, e, "memory", memoryKey);
+                            if (judged)
+                                coverage.stageCacheHits++;
+                            else {
+                                store.stageBegin([memoryKey], Date.now());
+                                coverage.stageAttempts++;
+                                judged = await abortable(judgeMemoryOpportunity(e, candidates, params), signal);
+                                store.stageSave(memoryKey, judged, Date.now());
+                            }
+                            memory = { status: "checked", candidates: judged };
+                        }
+                        catch {
+                            memory = { status: "unavailable", candidates: [] };
+                        }
+                    }
+                    signal.throwIfAborted();
+                    const fresh = reader.read(session, config.responseAudit);
+                    if (!fresh?.episodes.some(candidate => candidate.id === e.id && candidate.inputHash === e.inputHash)) {
+                        coverage.stale++;
+                        store.stale(cohort, e);
+                        if (fresh !== undefined) {
+                            store.observe(cohort, session, fresh?.episodes ?? []);
+                            store.checkpointForget(cohort, session);
+                        }
+                        break;
+                    }
+                    store.save(cohort, e, { ...judgment, human: people.resolve(e), references: references(e), agentModel: e.model,
+                        contextLimited: e.contextLimited, memorySearchCalls: e.memorySearchCalls, memory }, Date.now());
+                    coverage.evaluated++;
+                }
+                catch {
+                    coverage.failed++;
+                    if (signal.aborted)
+                        throw new Error("Audit cancelled");
+                }
+            }
+            // Let stop/cancellation handlers run between bounded synchronous session reads.
+            await new Promise(resolve => setImmediate(resolve));
+            store?.advance(cohort, session);
+            if (coverage.attempted >= config.responseAudit.maxEpisodes && session !== sessions.at(-1)) {
+                stoppedForBudget = true;
+                coverage.deferredByLimit++; // At least one unvisited session; precise episode count is not yet known.
+                break;
+            }
+        }
+        if (!coverage.sessionLimitReached && !stoppedForBudget)
+            store?.advance(cohort, "");
+        coverage.deferredByLimit = Math.max(coverage.deferredByLimit, store?.pendingWork(cohort, since, Date.now()) ?? 0);
+        store?.scan(cohort, coverage, Date.now());
+        return { status: options.dryRun ? "dry_run" : "ok", cohort, coverage };
+    }
+    catch {
+        store?.scan(cohort, { ...coverage, interrupted: true }, Date.now());
+        return { status: "unavailable", reason: "Response audit failed or was cancelled", cohort, coverage };
+    }
+    finally {
+        reader?.close();
+        if (lease)
+            store?.release(lease);
+        store?.close();
+        people.close();
+    }
+}
+function references(e) {
+    return { sessionId: e.session.sessionId, request: e.request.map(m => m.seq), answer: e.answer.map(m => m.seq),
+        feedback: e.feedback.map(m => m.seq), followup: e.followup.messages.map(m => m.seq), inputHash: e.inputHash };
+}

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

@@ -0,0 +1,13 @@
+import type { ChatType, CorpusConfig } from "./config.js";
+export type ResponseAuditConfig = {
+    enabled: boolean;
+    sentimentEnabled: boolean;
+    senderIds: string[];
+    chatTypes: ChatType[];
+    historyMessages: number;
+    lookbackDays: number;
+    maxEpisodes: number;
+    intervalMinutes: number;
+    memoryCorpora: string[];
+};
+export declare function resolveResponseAudit(value: unknown, corpora: readonly CorpusConfig[]): ResponseAuditConfig;

package/dist/src/response-config.js

@@ -0,0 +1,43 @@
+export function resolveResponseAudit(value, corpora) {
+    const defaults = { enabled: false, sentimentEnabled: true, senderIds: [], chatTypes: ["direct"],
+        historyMessages: 6, lookbackDays: 30, maxEpisodes: 20, intervalMinutes: 60, memoryCorpora: [] };
+    if (value === undefined)
+        return defaults;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("responseAudit must be an object");
+    const v = value;
+    for (const key of Object.keys(v))
+        if (!Object.hasOwn(defaults, key))
+            throw new Error(`unknown responseAudit property: ${key}`);
+    const enabled = v.enabled ?? false;
+    if (typeof enabled !== "boolean")
+        throw new Error("responseAudit.enabled must be boolean");
+    const sentimentEnabled = v.sentimentEnabled === undefined ? true : v.sentimentEnabled;
+    if (typeof sentimentEnabled !== "boolean")
+        throw new Error("responseAudit.sentimentEnabled must be boolean");
+    const strings = (key) => {
+        const raw = v[key] ?? defaults[key];
+        if (!Array.isArray(raw) || raw.length > 50 || !raw.every((x) => typeof x === "string" && !!x.trim())) {
+            throw new Error(`responseAudit.${key} must be a bounded string array`);
+        }
+        return [...new Set(raw.map(x => x.trim()))];
+    };
+    const senderIds = strings("senderIds"), chatTypes = strings("chatTypes"), memoryCorpora = strings("memoryCorpora");
+    if (!chatTypes.length || !chatTypes.every((x) => ["direct", "group", "channel"].includes(x))) {
+        throw new Error("responseAudit.chatTypes must specify direct, group or channel");
+    }
+    if (enabled && !senderIds.length)
+        throw new Error("responseAudit requires explicit approved human senderIds");
+    if (memoryCorpora.some(name => !corpora.some(c => c.name === name && c.kind === "files"))) {
+        throw new Error("responseAudit.memoryCorpora must name configured file corpora");
+    }
+    const integer = (key, min, max) => {
+        const n = v[key] ?? defaults[key];
+        if (typeof n !== "number" || !Number.isInteger(n) || n < min || n > max)
+            throw new Error(`invalid responseAudit.${key}`);
+        return n;
+    };
+    return { enabled, sentimentEnabled, senderIds, chatTypes, memoryCorpora, historyMessages: integer("historyMessages", 0, 20),
+        lookbackDays: integer("lookbackDays", 1, 90), maxEpisodes: integer("maxEpisodes", 1, 100),
+        intervalMinutes: integer("intervalMinutes", 0, 1440) };
+}

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