@psiclawops/hypermem 0.9.1 → 0.9.3

package/dist/tool-artifact-store.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Tool Artifact Store
+ *
+ * Durable, addressable storage for full tool result payloads. Schema v9.
+ *
+ * Why: the wave-guard at ingest time replaces oversized tool result payloads
+ * with a small stub for pressure relief. Before this store existed, the full
+ * payload was discarded. Now the stub in the transcript carries an
+ * `artifactId` pointing at the durable copy here, and hydration is an
+ * explicit decision, not an automatic transcript rewrite.
+ *
+ * Retention is deliberately independent of transcript eviction. Artifacts
+ * outlive the messages that referenced them, and GC is a separate concern
+ * (Phase 2).
+ *
+ * See: specs/TOOL_ARTIFACT_STORE.md
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface ToolArtifactRetentionPolicy {
+    /** TTL in ms for non-sensitive artifacts (e.g. 7 * 24 * 60 * 60 * 1000). */
+    standardTtlMs: number;
+    /** TTL in ms for sensitive artifacts. Should be <= standardTtlMs. */
+    sensitiveTtlMs: number;
+    /** Optional: max artifacts to keep per (agent_id, session_key). Excess removed oldest-first. */
+    maxPerSession?: number;
+}
+export interface ToolArtifactRecord {
+    id: string;
+    contentHash: string;
+    agentId: string;
+    sessionKey: string;
+    conversationId: number | null;
+    messageId: number | null;
+    turnId: string | null;
+    toolCallId: string | null;
+    toolName: string;
+    isError: boolean;
+    contentType: string;
+    sizeBytes: number;
+    tokenEstimate: number;
+    payload: string;
+    summary: string | null;
+    createdAt: string;
+    lastUsedAt: string;
+    refCount: number;
+    isSensitive: boolean;
+}
+export interface PutToolArtifactInput {
+    agentId: string;
+    sessionKey: string;
+    conversationId?: number;
+    messageId?: number;
+    turnId?: string;
+    toolCallId?: string;
+    toolName: string;
+    isError?: boolean;
+    contentType?: string;
+    payload: string;
+    summary?: string;
+    isSensitive?: boolean;
+}
+export declare class ToolArtifactStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Insert a new artifact, or dedupe against an existing one in the same
+     * (agentId, sessionKey) scope. Dedupe is scoped to a session so distinct
+     * sessions can't leak artifact ids across each other even when payload
+     * content is identical.
+     */
+    put(input: PutToolArtifactInput): ToolArtifactRecord;
+    /** Alias for get(id) — explicit name used by the compositor hydration pass. */
+    getById(id: string): ToolArtifactRecord | null;
+    get(id: string): ToolArtifactRecord | null;
+    getByHash(agentId: string, sessionKey: string, contentHash: string): ToolArtifactRecord | null;
+    listByTurn(sessionKey: string, turnId: string): ToolArtifactRecord[];
+    listByToolCall(toolCallId: string): ToolArtifactRecord[];
+    listRecent(agentId: string, sessionKey: string, limit?: number): ToolArtifactRecord[];
+    /** Update last_used_at — call this when hydration actually surfaces the payload. */
+    touch(id: string): void;
+    /**
+     * GC sweep: delete artifacts that exceed their TTL or per-session count cap.
+     * Returns total rows deleted.
+     *
+     * Sensitive artifacts use sensitiveTtlMs (shorter); standard artifacts use
+     * standardTtlMs. Optional maxPerSession bounds row count per (agent, session)
+     * using a ROW_NUMBER() window query — oldest last_used_at removed first.
+     */
+    sweep(policy: ToolArtifactRetentionPolicy): number;
+    /**
+     * Delete artifacts whose last_used_at is older than the ISO cutoff.
+     * Returns the number of rows deleted. Phase 1: manual invocation only.
+     */
+    deleteOlderThan(isoCutoff: string): number;
+    /** Debug / ops: row count across a session. */
+    count(agentId?: string, sessionKey?: string): number;
+}
+//# sourceMappingURL=tool-artifact-store.d.ts.map

package/dist/tool-artifact-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-artifact-store.d.ts","sourceRoot":"","sources":["../src/tool-artifact-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0BhD,MAAM,WAAW,2BAA2B;IAC1C,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA0BD,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,oBAAoB,GAAG,kBAAkB;IA+FpD,+EAA+E;IAC/E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAI9C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAO1C,SAAS,CACP,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,kBAAkB,GAAG,IAAI;IAY5B,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAWpE,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAWxD,UAAU,CACR,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAW,GACjB,kBAAkB,EAAE;IAYvB,oFAAoF;IACpF,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMvB;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,2BAA2B,GAAG,MAAM;IAsClD;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAO1C,+CAA+C;IAC/C,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAcrD"}

package/dist/tool-artifact-store.js

@@ -0,0 +1,244 @@
+/**
+ * Tool Artifact Store
+ *
+ * Durable, addressable storage for full tool result payloads. Schema v9.
+ *
+ * Why: the wave-guard at ingest time replaces oversized tool result payloads
+ * with a small stub for pressure relief. Before this store existed, the full
+ * payload was discarded. Now the stub in the transcript carries an
+ * `artifactId` pointing at the durable copy here, and hydration is an
+ * explicit decision, not an automatic transcript rewrite.
+ *
+ * Retention is deliberately independent of transcript eviction. Artifacts
+ * outlive the messages that referenced them, and GC is a separate concern
+ * (Phase 2).
+ *
+ * See: specs/TOOL_ARTIFACT_STORE.md
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Simple char/4 heuristic matching src/compositor.ts estimateTokens().
+ * Kept local to avoid a cyclic import and keep the store self-contained.
+ */
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function newArtifactId() {
+    // 24-char lowercase id. Deliberately NOT a UUID — shorter, fits the stub
+    // length cap in src/degradation.ts (DEGRADATION_LIMITS.artifactId = 64).
+    return 'art_' + randomBytes(10).toString('hex');
+}
+function sha256Hex(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        contentHash: row.content_hash,
+        agentId: row.agent_id,
+        sessionKey: row.session_key,
+        conversationId: row.conversation_id ?? null,
+        messageId: row.message_id ?? null,
+        turnId: row.turn_id ?? null,
+        toolCallId: row.tool_call_id ?? null,
+        toolName: row.tool_name,
+        isError: row.is_error === 1,
+        contentType: row.content_type,
+        sizeBytes: row.size_bytes,
+        tokenEstimate: row.token_estimate,
+        payload: row.payload,
+        summary: row.summary ?? null,
+        createdAt: row.created_at,
+        lastUsedAt: row.last_used_at,
+        refCount: row.ref_count,
+        isSensitive: row.is_sensitive === 1,
+    };
+}
+export class ToolArtifactStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Insert a new artifact, or dedupe against an existing one in the same
+     * (agentId, sessionKey) scope. Dedupe is scoped to a session so distinct
+     * sessions can't leak artifact ids across each other even when payload
+     * content is identical.
+     */
+    put(input) {
+        const payload = input.payload ?? '';
+        const contentHash = sha256Hex(payload);
+        const sizeBytes = Buffer.byteLength(payload, 'utf8');
+        const tokenEstimate = estimateTokens(payload);
+        const contentType = input.contentType ?? 'text/plain';
+        const isError = input.isError ? 1 : 0;
+        const isSensitive = input.isSensitive ? 1 : 0;
+        // Dedupe within (agentId, sessionKey) — same hash bumps ref_count and
+        // updates last_used_at, returning the existing record.
+        const existing = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE agent_id = ? AND session_key = ? AND content_hash = ?
+           LIMIT 1`)
+            .get(input.agentId, input.sessionKey, contentHash);
+        if (existing) {
+            const ts = nowIso();
+            this.db
+                .prepare(`UPDATE tool_artifacts
+             SET ref_count = ref_count + 1,
+                 last_used_at = ?
+             WHERE id = ?`)
+                .run(ts, existing.id);
+            return rowToRecord({ ...existing, ref_count: existing.ref_count + 1, last_used_at: ts, is_sensitive: existing.is_sensitive ?? 0 });
+        }
+        const id = newArtifactId();
+        const ts = nowIso();
+        this.db
+            .prepare(`INSERT INTO tool_artifacts (
+            id, content_hash, agent_id, session_key,
+            conversation_id, message_id, turn_id, tool_call_id,
+            tool_name, is_error, content_type,
+            size_bytes, token_estimate, payload, summary,
+            created_at, last_used_at, ref_count, is_sensitive
+          ) VALUES (?, ?, ?, ?,
+                    ?, ?, ?, ?,
+                    ?, ?, ?,
+                    ?, ?, ?, ?,
+                    ?, ?, 1, ?)`)
+            .run(id, contentHash, input.agentId, input.sessionKey, input.conversationId ?? null, input.messageId ?? null, input.turnId ?? null, input.toolCallId ?? null, input.toolName, isError, contentType, sizeBytes, tokenEstimate, payload, input.summary ?? null, ts, ts, isSensitive);
+        return {
+            id,
+            contentHash,
+            agentId: input.agentId,
+            sessionKey: input.sessionKey,
+            conversationId: input.conversationId ?? null,
+            messageId: input.messageId ?? null,
+            turnId: input.turnId ?? null,
+            toolCallId: input.toolCallId ?? null,
+            toolName: input.toolName,
+            isError: input.isError ?? false,
+            contentType,
+            sizeBytes,
+            tokenEstimate,
+            payload,
+            summary: input.summary ?? null,
+            createdAt: ts,
+            lastUsedAt: ts,
+            refCount: 1,
+            isSensitive: input.isSensitive ?? false,
+        };
+    }
+    /** Alias for get(id) — explicit name used by the compositor hydration pass. */
+    getById(id) {
+        return this.get(id);
+    }
+    get(id) {
+        const row = this.db
+            .prepare('SELECT * FROM tool_artifacts WHERE id = ? LIMIT 1')
+            .get(id);
+        return row ? rowToRecord(row) : null;
+    }
+    getByHash(agentId, sessionKey, contentHash) {
+        const row = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE agent_id = ? AND session_key = ? AND content_hash = ?
+           ORDER BY created_at DESC
+           LIMIT 1`)
+            .get(agentId, sessionKey, contentHash);
+        return row ? rowToRecord(row) : null;
+    }
+    listByTurn(sessionKey, turnId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE session_key = ? AND turn_id = ?
+           ORDER BY created_at ASC`)
+            .all(sessionKey, turnId);
+        return rows.map(rowToRecord);
+    }
+    listByToolCall(toolCallId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE tool_call_id = ?
+           ORDER BY created_at ASC`)
+            .all(toolCallId);
+        return rows.map(rowToRecord);
+    }
+    listRecent(agentId, sessionKey, limit = 20) {
+        const rows = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE agent_id = ? AND session_key = ?
+           ORDER BY created_at DESC
+           LIMIT ?`)
+            .all(agentId, sessionKey, limit);
+        return rows.map(rowToRecord);
+    }
+    /** Update last_used_at — call this when hydration actually surfaces the payload. */
+    touch(id) {
+        this.db
+            .prepare('UPDATE tool_artifacts SET last_used_at = ? WHERE id = ?')
+            .run(nowIso(), id);
+    }
+    /**
+     * GC sweep: delete artifacts that exceed their TTL or per-session count cap.
+     * Returns total rows deleted.
+     *
+     * Sensitive artifacts use sensitiveTtlMs (shorter); standard artifacts use
+     * standardTtlMs. Optional maxPerSession bounds row count per (agent, session)
+     * using a ROW_NUMBER() window query — oldest last_used_at removed first.
+     */
+    sweep(policy) {
+        const now = Date.now();
+        const standardCutoff = new Date(now - policy.standardTtlMs).toISOString();
+        const sensitiveCutoff = new Date(now - policy.sensitiveTtlMs).toISOString();
+        const ttlResult = this.db
+            .prepare(`DELETE FROM tool_artifacts
+           WHERE (is_sensitive = 0 AND last_used_at < ?)
+              OR (is_sensitive = 1 AND last_used_at < ?)`)
+            .run(standardCutoff, sensitiveCutoff);
+        let deleted = ttlResult.changes ?? 0;
+        if (policy.maxPerSession != null) {
+            const boundResult = this.db
+                .prepare(`DELETE FROM tool_artifacts
+             WHERE id IN (
+               SELECT id FROM (
+                 SELECT id,
+                        ROW_NUMBER() OVER (
+                          PARTITION BY agent_id, session_key
+                          ORDER BY last_used_at DESC
+                        ) AS rn
+                 FROM tool_artifacts
+               )
+               WHERE rn > ?
+             )`)
+                .run(policy.maxPerSession);
+            deleted += boundResult.changes ?? 0;
+        }
+        return deleted;
+    }
+    /**
+     * Delete artifacts whose last_used_at is older than the ISO cutoff.
+     * Returns the number of rows deleted. Phase 1: manual invocation only.
+     */
+    deleteOlderThan(isoCutoff) {
+        const result = this.db
+            .prepare('DELETE FROM tool_artifacts WHERE last_used_at < ?')
+            .run(isoCutoff);
+        return Number(result.changes ?? 0);
+    }
+    /** Debug / ops: row count across a session. */
+    count(agentId, sessionKey) {
+        if (agentId && sessionKey) {
+            const row = this.db
+                .prepare('SELECT COUNT(*) AS n FROM tool_artifacts WHERE agent_id = ? AND session_key = ?')
+                .get(agentId, sessionKey);
+            return row?.n ?? 0;
+        }
+        const row = this.db.prepare('SELECT COUNT(*) AS n FROM tool_artifacts').get();
+        return row?.n ?? 0;
+    }
+}
+//# sourceMappingURL=tool-artifact-store.js.map

package/dist/topic-detector.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Topic Detector (P3.1)
+ *
+ * Heuristic-based topic shift detection. No model calls.
+ * Uses explicit markers, entity shift, conversation gap, and continuation signals.
+ */
+import type { NeutralMessage } from './types.js';
+/**
+ * Strip inbound protocol metadata from message text before topic detection.
+ *
+ * Removes:
+ *   - "Sender (untrusted metadata):" header blocks through next blank line
+ *   - Pure timestamp lines: ISO 8601, bracket format, System YYYY-MM-DD
+ *   - JSON code blocks containing "\"schema\": \"openclaw" or "inbound_meta"
+ *   - Any ```json...``` block whose content contains those markers
+ *
+ * Called as the FIRST step in detectTopicShift() so that pattern matching
+ * operates on clean user content, not on injected transport headers.
+ */
+export declare function stripMessageMetadata(text: string): string;
+export interface TopicSignal {
+    topicId: string | null;
+    isNewTopic: boolean;
+    confidence: number;
+    topicName: string | null;
+}
+/**
+ * Detect whether the incoming message starts a new conversation topic.
+ *
+ * @param incomingMessage  The new user message to evaluate
+ * @param recentMessages   Last N messages for context (any role)
+ * @param currentTopicId   The active topic id, or null if none
+ */
+export declare function detectTopicShift(incomingMessage: NeutralMessage, recentMessages: NeutralMessage[], currentTopicId: string | null): TopicSignal;
+//# sourceMappingURL=topic-detector.d.ts.map

package/dist/topic-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-detector.d.ts","sourceRoot":"","sources":["../src/topic-detector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA6EzD;AAID,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AA6GD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,cAAc,EAC/B,cAAc,EAAE,cAAc,EAAE,EAChC,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,WAAW,CAkEb"}

package/dist/topic-detector.js

@@ -0,0 +1,249 @@
+/**
+ * Topic Detector (P3.1)
+ *
+ * Heuristic-based topic shift detection. No model calls.
+ * Uses explicit markers, entity shift, conversation gap, and continuation signals.
+ */
+// ─── Metadata Stripping ───────────────────────────────────────────────────────
+/**
+ * Strip inbound protocol metadata from message text before topic detection.
+ *
+ * Removes:
+ *   - "Sender (untrusted metadata):" header blocks through next blank line
+ *   - Pure timestamp lines: ISO 8601, bracket format, System YYYY-MM-DD
+ *   - JSON code blocks containing "\"schema\": \"openclaw" or "inbound_meta"
+ *   - Any ```json...``` block whose content contains those markers
+ *
+ * Called as the FIRST step in detectTopicShift() so that pattern matching
+ * operates on clean user content, not on injected transport headers.
+ */
+export function stripMessageMetadata(text) {
+    if (!text)
+        return text;
+    const lines = text.split('\n');
+    const result = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // ── ```json blocks containing openclaw markers ──────────────────────────
+        if (/^```json\s*$/i.test(line)) {
+            // Peek ahead to collect the block
+            const blockLines = [line];
+            let j = i + 1;
+            let closed = false;
+            while (j < lines.length) {
+                blockLines.push(lines[j]);
+                if (lines[j].trim() === '```') {
+                    closed = true;
+                    j++;
+                    break;
+                }
+                j++;
+            }
+            const blockContent = blockLines.join('\n');
+            if (blockContent.includes('"schema": "openclaw') ||
+                blockContent.includes('inbound_meta')) {
+                // Skip the whole block
+                i = j;
+                continue;
+            }
+            // Not an openclaw block — keep as-is
+            result.push(...blockLines.slice(0, closed ? blockLines.length : blockLines.length));
+            i = j;
+            continue;
+        }
+        // ── Sender (untrusted metadata): block ──────────────────────────────────
+        if (/^Sender \(untrusted metadata\):/i.test(line)) {
+            // Skip through next blank line or closing ```
+            i++;
+            while (i < lines.length) {
+                const l = lines[i];
+                if (l.trim() === '' || l.trim() === '```') {
+                    i++; // consume the blank/closing line too
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        // ── Pure timestamp lines ─────────────────────────────────────────────────
+        // ISO 8601: 2026-04-05T02:43:00Z  /  2026-04-05T02:43:00.000Z
+        if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?$/.test(line.trim())) {
+            i++;
+            continue;
+        }
+        // Bracket format: [Mon 2026-04-05 02:43 MST]
+        if (/^\[\w{3}\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}\s+\w+\]$/.test(line.trim())) {
+            i++;
+            continue;
+        }
+        // System YYYY-MM-DD
+        if (/^System\s+\d{4}-\d{2}-\d{2}$/.test(line.trim())) {
+            i++;
+            continue;
+        }
+        result.push(line);
+        i++;
+    }
+    return result.join('\n').trim();
+}
+// ─── Constants ────────────────────────────────────────────────────────────────
+const GAP_MS = 30 * 60 * 1000; // 30 minutes
+// Explicit topic-shift markers
+const SHIFT_PATTERNS = [
+    /^(?:let'?s?|can we)\s+(?:talk|discuss|chat)\s+about\s+(.+)/i,
+    /^switching\s+to\s+(.+)/i,
+    /^new\s+topic\s*[:—-]\s*(.+)/i,
+    /^regarding\s+(.+)/i,
+    /^on\s+(?:the\s+)?(?:topic\s+of\s+)?(.+)/i,
+    /^(?:i\s+want\s+to\s+)?(?:talk|ask)\s+about\s+(.+)/i,
+    /^(?:change\s+of\s+)?subject\s*[:—-]\s*(.+)/i,
+];
+// Continuation markers — if any match, this is almost certainly same topic
+const CONTINUATION_PATTERNS = [
+    /^\s*(?:also|and|additionally|furthermore|moreover|plus)\b/i,
+    /^\s*(?:what\s+about|how\s+about)\s+/i,
+    /^\s*(?:following\s+up|follow[- ]up|just\s+to\s+follow\s+up)\b/i,
+    /^\s*(?:actually|wait|oh)\s*[,—-]/i,
+    /^\s*(?:one\s+more\s+thing|another\s+thing|by\s+the\s+way)\b/i,
+];
+// Stop words for noun-phrase extraction
+const STOP_WORDS = new Set([
+    'a', 'an', 'the', 'this', 'that', 'these', 'those', 'i', 'you', 'we', 'they',
+    'it', 'he', 'she', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could', 'should',
+    'may', 'might', 'shall', 'can', 'to', 'of', 'in', 'on', 'at', 'for', 'with',
+    'by', 'from', 'up', 'about', 'into', 'through', 'and', 'or', 'but', 'not',
+    'so', 'yet', 'both', 'either', 'neither', 'nor', 'as', 'just', 'than',
+    'then', 'because', 'while', 'although', 'if', 'when', 'where', 'how', 'what',
+    'which', 'who', 'whom', 'whose',
+]);
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Extract a short heuristic topic name from message text (max 40 chars).
+ * Returns the first meaningful noun phrase or the first substantive clause.
+ */
+function extractTopicName(text) {
+    // First, check if any shift pattern captured a phrase
+    for (const pattern of SHIFT_PATTERNS) {
+        const m = text.match(pattern);
+        if (m?.[1]) {
+            const phrase = m[1].replace(/[?!.]+$/, '').trim();
+            return phrase.slice(0, 40);
+        }
+    }
+    // Fall back: split into words, skip stop words, take first 5 content words
+    const words = text
+        .replace(/[^\w\s'-]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length > 1 && !STOP_WORDS.has(w.toLowerCase()));
+    if (words.length === 0) {
+        // Last resort: first 40 chars
+        return text.slice(0, 40).trim();
+    }
+    return words.slice(0, 5).join(' ').slice(0, 40);
+}
+/**
+ * Naive named-entity heuristic: extract capitalized words (length ≥ 3) and
+ * quoted strings as "entities". Returns a Set<string> (lowercased).
+ */
+function extractEntities(text) {
+    const entities = new Set();
+    // Quoted strings
+    const quoted = text.match(/["']([^"']{2,30})["']/g);
+    if (quoted) {
+        for (const q of quoted)
+            entities.add(q.replace(/["']/g, '').toLowerCase());
+    }
+    // Capitalized words (simple NER proxy — excludes sentence-start)
+    const words = text.split(/\s+/);
+    for (let i = 1; i < words.length; i++) {
+        const w = words[i].replace(/[^a-zA-Z-]/g, '');
+        if (w.length >= 3 && /^[A-Z]/.test(w)) {
+            entities.add(w.toLowerCase());
+        }
+    }
+    return entities;
+}
+/**
+ * Jaccard similarity between two entity sets (0 = no overlap, 1 = identical).
+ */
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersect = 0;
+    for (const x of a) {
+        if (b.has(x))
+            intersect++;
+    }
+    const union = a.size + b.size - intersect;
+    return intersect / union;
+}
+// ─── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Detect whether the incoming message starts a new conversation topic.
+ *
+ * @param incomingMessage  The new user message to evaluate
+ * @param recentMessages   Last N messages for context (any role)
+ * @param currentTopicId   The active topic id, or null if none
+ */
+export function detectTopicShift(incomingMessage, recentMessages, currentTopicId) {
+    // Strip inbound protocol metadata FIRST — pattern matching must operate on
+    // clean user content, not on transport headers (timestamps, sender blocks, etc.)
+    const text = stripMessageMetadata(incomingMessage.textContent ?? '');
+    // Guard: if the message is entirely metadata with no real content, never
+    // create a new topic — there is nothing to name or classify.
+    if (!text) {
+        return { topicId: currentTopicId, isNewTopic: false, confidence: 0.9, topicName: null };
+    }
+    // ── 1. Continuation check (highest priority) ──────────────────────────────
+    for (const pat of CONTINUATION_PATTERNS) {
+        if (pat.test(text)) {
+            return { topicId: currentTopicId, isNewTopic: false, confidence: 0.85, topicName: null };
+        }
+    }
+    // ── 2. Explicit shift marker ───────────────────────────────────────────────
+    for (const pat of SHIFT_PATTERNS) {
+        if (pat.test(text)) {
+            const name = extractTopicName(text);
+            return { topicId: null, isNewTopic: true, confidence: 0.95, topicName: name };
+        }
+    }
+    // ── 3. Conversation gap (empty history or >30 min since last message) ──────
+    if (recentMessages.length === 0) {
+        const name = extractTopicName(text);
+        return { topicId: null, isNewTopic: true, confidence: 0.8, topicName: name };
+    }
+    // Find last message with a timestamp in metadata
+    const lastMsg = recentMessages[recentMessages.length - 1];
+    const lastTs = lastMsg.metadata?.createdAt
+        ? new Date(lastMsg.metadata.createdAt).getTime()
+        : null;
+    if (lastTs !== null && !isNaN(lastTs)) {
+        const now = Date.now();
+        if (now - lastTs > GAP_MS) {
+            const name = extractTopicName(text);
+            return { topicId: null, isNewTopic: true, confidence: 0.75, topicName: name };
+        }
+    }
+    // ── 4. Entity shift (compare incoming to last 3 messages) ─────────────────
+    const incomingEntities = extractEntities(text);
+    const contextWindow = recentMessages.slice(-3);
+    const contextText = contextWindow
+        .map(m => m.textContent ?? '')
+        .join(' ');
+    if (incomingEntities.size >= 2 && contextText.length > 0) {
+        const contextEntities = extractEntities(contextText);
+        const similarity = jaccardSimilarity(incomingEntities, contextEntities);
+        // Low similarity + no continuation marker → likely a new topic
+        if (similarity < 0.15) {
+            const name = extractTopicName(text);
+            return { topicId: null, isNewTopic: true, confidence: 0.6, topicName: name };
+        }
+    }
+    // ── 5. Default: continue current topic ────────────────────────────────────
+    return { topicId: currentTopicId, isNewTopic: false, confidence: 0.7, topicName: null };
+}
+//# sourceMappingURL=topic-detector.js.map