@snoai/memory 0.0.0-stage → 1.0.0

package/dist/internal/engine/bindings/sno-station-mem-auto-recall-hook.js

@@ -0,0 +1,324 @@
+import "../../config/index.js";
+import { debugContentPreview } from "../shared/utils.js";
+import { pruneOldestEntries, setLruEntry, touchLruEntry } from "../shared/lru.js";
+import { normalizeQuery, shouldSkipRetrieval } from "../retrieval/retrieval-gate.js";
+import { c as formatRelevantMemoriesContext } from "../../../capture-policy-detector-DaMfy9CZ.js";
+import { t as appendAuditEntry } from "../../../runtime-audit-log-BCeujlEp.js";
+import { episodicEventDate, saidOnDate, sourceQuote } from "./memory-tool-formatting.js";
+import { r as retrieveForAutoRecall } from "../../../rem-consumer-retrieval-CRpvG8KS.js";
+import { isChatIdBasedAgentId, resolveHookAgentId } from "./sno-station-mem-runtime-mode.js";
+import { t as parseReflectionMetadata } from "../../../entry-metadata-parser-BIVSMCIk.js";
+import "../../../sno-station-mem-runtime-dependencies-DjLOhB45.js";
+import { resolveRuntimeSessionId } from "./sno-station-mem-session-state.js";
+import { createLogger, currentLogContext, withLogContext } from "@snoai/utils/logger";
+import { randomUUID } from "node:crypto";
+//#region src/engine/bindings/sno-station-mem-auto-recall-hook.ts
+const log = createLogger("sno-station-mem:auto-recall");
+const LOCOMO_BENCHMARK_PROMPT_RE = /^Question:\s*(?<question>[\s\S]*?)\n\s*\nYou are answering a benchmark question\b/;
+function extractAutoRecallQuery(prompt) {
+	const benchmarkQuestion = LOCOMO_BENCHMARK_PROMPT_RE.exec(prompt)?.groups?.question?.trim();
+	return benchmarkQuestion && benchmarkQuestion.length > 0 ? benchmarkQuestion : prompt;
+}
+/** Injects relevant memories into the next agent turn after scope and cache checks. */
+async function onBeforeAgentStart(api, config, retriever, _store, scopePolicy, recallHistory, turnCounter, event, ctx, stateDir, telemetryUsage, signal) {
+	const sessionId = resolveRuntimeSessionId(ctx);
+	const currentTurn = (touchLruEntry(turnCounter, sessionId) ?? 0) + 1;
+	setLruEntry(turnCounter, sessionId, currentTurn, 100);
+	const sessionKey = typeof ctx.sessionKey === "string" ? ctx.sessionKey : "";
+	return withLogContext({
+		operation_id: currentLogContext().operation_id ?? randomUUID(),
+		session_reference: sessionKey
+	}, async () => {
+		const started = performance.now();
+		let outcome = "skipped";
+		let served = [];
+		let repeatRemoved = 0;
+		const retrievalDiagnostics = {};
+		try {
+			if (sessionKey.includes(":subagent:")) {
+				appendAuditEntry(stateDir, {
+					event: "auto_recall",
+					hook: "before_prompt_build",
+					resultStatus: "skipped",
+					decision: "skipped_subagent",
+					details: { sessionKey }
+				});
+				return;
+			}
+			if (!config.autoRecall) return;
+			const resolvedAgentId = resolveHookAgentId(ctx.agentId, sessionKey).agentId ?? "openclaw";
+			if (isChatIdBasedAgentId(resolvedAgentId)) {
+				appendAuditEntry(stateDir, {
+					event: "auto_recall",
+					hook: "before_prompt_build",
+					resultStatus: "skipped",
+					decision: "rejected_chatid_agent_format",
+					details: { resolvedAgentId }
+				});
+				return;
+			}
+			if (config.autoRecallIncludeAgents.length > 0) {
+				if (!config.autoRecallIncludeAgents.includes(resolvedAgentId)) {
+					appendAuditEntry(stateDir, {
+						event: "auto_recall",
+						hook: "before_prompt_build",
+						resultStatus: "skipped",
+						decision: "skipped_agent_filter",
+						details: {
+							resolvedAgentId,
+							listKind: "include"
+						}
+					});
+					return;
+				}
+			} else if (config.autoRecallExcludeAgents.includes(resolvedAgentId)) {
+				appendAuditEntry(stateDir, {
+					event: "auto_recall",
+					hook: "before_prompt_build",
+					resultStatus: "skipped",
+					decision: "skipped_agent_filter",
+					details: {
+						resolvedAgentId,
+						listKind: "exclude"
+					}
+				});
+				return;
+			}
+			const incoming = event.prompt;
+			const recallInput = incoming ? extractAutoRecallQuery(incoming) : "";
+			const normalizedIncoming = recallInput ? normalizeQuery(recallInput) : "";
+			if (!normalizedIncoming || shouldSkipRetrieval(normalizedIncoming, config.autoRecallMinLength)) return;
+			const maxQueryLen = config.autoRecallMaxQueryLength;
+			let recallQuery = normalizedIncoming;
+			if (recallQuery.length > maxQueryLen) {
+				log.info("Auto recall query length limited", {
+					input_length: recallQuery.length,
+					limit: maxQueryLen
+				}, {
+					event_name: "memory.auto_recall.query.limited",
+					file: "packages/memory/src/engine/bindings/sno-station-mem-auto-recall-hook.ts",
+					function: "onBeforeAgentStart",
+					site_id: "memory.auto_recall.query.limited"
+				});
+				recallQuery = recallQuery.slice(0, maxQueryLen);
+			}
+			const scopeFilter = scopePolicy.resolveAgentScopes(resolvedAgentId);
+			let timeoutHandle;
+			try {
+				const timeoutMs = config.autoRecallTimeoutMs;
+				const recallController = new AbortController();
+				const timeoutPromise = new Promise((_, reject) => {
+					timeoutHandle = setTimeout(() => {
+						const timeoutError = /* @__PURE__ */ new Error("auto-recall timeout");
+						recallController.abort(timeoutError);
+						reject(timeoutError);
+					}, timeoutMs);
+					timeoutHandle.unref();
+				});
+				const recallLimit = config.retrieval.recallTopK;
+				const suppressionNow = Date.now();
+				const results = await Promise.race([retrieveForAutoRecall(retriever, {
+					diagnostics: retrievalDiagnostics,
+					query: recallQuery,
+					limit: recallLimit,
+					scopeFilter,
+					signal: signal ? AbortSignal.any([signal, recallController.signal]) : recallController.signal,
+					sessionId,
+					nowMs: suppressionNow
+				}), timeoutPromise]);
+				signal?.throwIfAborted();
+				if (results.length === 0) {
+					outcome = "empty_success";
+					appendAuditEntry(stateDir, {
+						event: "auto_recall",
+						hook: "before_prompt_build",
+						resultStatus: "ok",
+						decision: "executed_empty",
+						details: {
+							resolvedAgentId,
+							queryChars: recallQuery.length,
+							queryPreview: debugContentPreview(recallQuery, config.debugContent),
+							limit: recallLimit
+						}
+					});
+					return;
+				}
+				const minRepeated = config.autoRecallMinRepeated ?? 0;
+				let finalResults = results;
+				const sessionHistory = touchLruEntry(recallHistory, sessionId) ?? /* @__PURE__ */ new Map();
+				if (minRepeated > 0) {
+					const filtered = results.filter((r) => {
+						const lastTurn = sessionHistory.get(r.entry.id) ?? -999;
+						return currentTurn - lastTurn >= minRepeated;
+					});
+					repeatRemoved = results.length - filtered.length;
+					if (filtered.length === 0) {
+						outcome = "empty_success";
+						appendAuditEntry(stateDir, {
+							event: "auto_recall",
+							hook: "before_prompt_build",
+							resultStatus: "ok",
+							decision: "executed_filtered_empty",
+							details: {
+								resolvedAgentId,
+								queryChars: recallQuery.length,
+								queryPreview: debugContentPreview(recallQuery, config.debugContent),
+								retrievedCount: results.length,
+								minRepeated,
+								limit: recallLimit
+							}
+						});
+						return;
+					}
+					finalResults = filtered;
+				}
+				for (const r of finalResults) sessionHistory.set(r.entry.id, currentTurn);
+				pruneOldestEntries(sessionHistory, 200);
+				setLruEntry(recallHistory, sessionId, sessionHistory, 100);
+				appendAuditEntry(stateDir, {
+					event: "auto_recall",
+					hook: "before_prompt_build",
+					resultStatus: "ok",
+					decision: "executed",
+					details: {
+						resolvedAgentId,
+						queryChars: recallQuery.length,
+						queryPreview: debugContentPreview(recallQuery, config.debugContent),
+						injectedCount: finalResults.length,
+						limit: recallLimit,
+						topResultIds: finalResults.slice(0, 5).map((r) => r.entry.id),
+						topScores: finalResults.slice(0, 5).map((r) => Number(r.score.toFixed(4))),
+						topResultPreviews: config.debugContent ? finalResults.slice(0, 5).map((r) => debugContentPreview(r.snippet && r.snippet.length > 0 ? r.snippet : r.entry.text, config.debugContent)) : void 0
+					}
+				});
+				recordAutoRecallUsage({
+					api,
+					telemetryUsage,
+					results: finalResults,
+					resolvedAgentId,
+					sessionId,
+					currentTurn
+				});
+				served = finalResults.map((row) => row.entry.id);
+				outcome = "success";
+				return { prependContext: formatRelevantMemoriesContext(finalResults.map((result) => {
+					const eventDate = episodicEventDate(result.entry);
+					const quote = sourceQuote(result.entry);
+					return {
+						category: result.entry.category,
+						text: result.snippet && result.snippet.length > 0 ? result.snippet : result.entry.text,
+						lane: result.entry.lane,
+						...quote === void 0 ? {} : { quote },
+						eventDate,
+						saidOn: saidOnDate(result.entry)
+					};
+				})) };
+			} catch (error) {
+				if ((error instanceof Error ? error.message : String(error)) === "auto-recall timeout") outcome = "cancelled";
+				else {
+					outcome = "failed";
+					log.warn("Auto recall failed", { error }, {
+						event_name: "memory.auto_recall.failed",
+						file: "packages/memory/src/engine/bindings/sno-station-mem-auto-recall-hook.ts",
+						function: "onBeforeAgentStart",
+						site_id: "memory.auto_recall.failed"
+					});
+				}
+			} finally {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+			}
+		} finally {
+			log.info("Auto recall completed", {
+				outcome,
+				duration_ms: performance.now() - started,
+				served_ids: served.slice(0, 128),
+				served_count: served.length,
+				ids_truncated: served.length > 128,
+				repeat_removed_count: repeatRemoved,
+				token_budget_removed_count: 0,
+				retired_closed_removed_count: retrievalDiagnostics.retired_closed_removed_count ?? "unavailable",
+				sql_excluded_count: "unavailable",
+				sql_excluded_reason: "query_does_not_report_excluded_rows"
+			}, {
+				event_name: "memory.auto_recall.completed",
+				file: "packages/memory/src/engine/bindings/sno-station-mem-auto-recall-hook.ts",
+				function: "onBeforeAgentStart",
+				site_id: "memory.auto_recall.completed"
+			});
+		}
+	});
+}
+function recordAutoRecallUsage(params) {
+	if (!params.telemetryUsage) return;
+	for (const [index, result] of params.results.entries()) {
+		const factId = result.entry.factId;
+		if (!factId) {
+			log.warn("Recall telemetry lacks fact identity", { memory_id: result.entry.id }, {
+				event_name: "memory.auto_recall.telemetry.skipped",
+				file: "packages/memory/src/engine/bindings/sno-station-mem-auto-recall-hook.ts",
+				function: "recordAutoRecallUsage",
+				site_id: "memory.auto_recall.telemetry.skipped"
+			});
+			continue;
+		}
+		const retrievalRank = index + 1;
+		const retrievalScore = finiteNumberOrUndefined(result.score);
+		const base = {
+			factId,
+			memoryKind: result.entry.category,
+			projectId: result.entry.projectId,
+			agentId: params.resolvedAgentId,
+			sessionUuid: params.sessionId,
+			turnId: String(params.currentTurn),
+			retrievalRank,
+			retrievalScore
+		};
+		const recallAccepted = params.telemetryUsage.tryAcceptUsage({
+			eventType: "recall",
+			...base,
+			metadata: buildRecallUsageMetadata(result, retrievalRank, retrievalScore)
+		});
+		const writerAgentId = parseReflectionMetadata(result.entry.metadata).writer_agent_id;
+		const injectAccepted = params.telemetryUsage.tryAcceptUsage({
+			eventType: "inject",
+			...base,
+			metadata: {
+				injection_surface: "auto_recall_prepend_context",
+				...typeof writerAgentId === "string" && writerAgentId.trim() && writerAgentId !== params.resolvedAgentId ? { source_agent_id: writerAgentId } : {},
+				retrieval_rank: retrievalRank,
+				...retrievalScore !== void 0 && { retrieval_score: retrievalScore }
+			}
+		});
+		if (!recallAccepted || !injectAccepted) log.warn("Recall telemetry admission failed", {
+			fact_id: factId,
+			recall_accepted: recallAccepted,
+			inject_accepted: injectAccepted
+		}, {
+			event_name: "memory.auto_recall.telemetry.failed",
+			file: "packages/memory/src/engine/bindings/sno-station-mem-auto-recall-hook.ts",
+			function: "recordAutoRecallUsage",
+			site_id: "memory.auto_recall.telemetry.failed"
+		});
+	}
+}
+function buildRecallUsageMetadata(result, retrievalRank, retrievalScore) {
+	const metadata = {
+		retrieval_rank: retrievalRank,
+		...retrievalScore !== void 0 && { retrieval_score: retrievalScore }
+	};
+	addFiniteScore(metadata, "dense_score", result.denseScore);
+	addFiniteScore(metadata, "bm25_score", result.bm25Score);
+	addFiniteScore(metadata, "fused_score", result.fusedScore);
+	addFiniteScore(metadata, "rerank_score", result.rerankScore);
+	addFiniteScore(metadata, "mmr_score", result.mmrScore);
+	return metadata;
+}
+function addFiniteScore(metadata, key, value) {
+	const score = finiteNumberOrUndefined(value);
+	if (score !== void 0) metadata[key] = score;
+}
+function finiteNumberOrUndefined(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+//#endregion
+export { extractAutoRecallQuery, onBeforeAgentStart };

package/dist/internal/engine/bindings/sno-station-mem-hook-types.d.ts

@@ -0,0 +1,56 @@
+//#region src/engine/bindings/sno-station-mem-hook-types.d.ts
+/** @file sno-station-mem-hook-types.ts
+ * @purpose Names local SnoStationMem hook payload aliases that are not exported by the SDK.
+ * @boundary Type aliases only; hook behavior lives in dedicated hook modules.
+ */
+export type PluginHookAgentContext = {
+  agentId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  sessionTimezone?: string;
+  workspaceDir?: string;
+  messageProvider?: string;
+};
+export type PluginHookBeforeAgentStartEvent = {
+  prompt: string;
+  messages?: unknown[];
+};
+export type PluginHookBeforeAgentStartResult = {
+  systemPrompt?: string;
+  prependContext?: string;
+  modelOverride?: string;
+  providerOverride?: string;
+};
+export type PluginHookLlmOutputEvent = {
+  model?: unknown;
+  provider?: unknown;
+  sessionId?: unknown;
+  usage?: unknown;
+};
+export type PluginHookAgentEndEvent = {
+  messages: unknown[];
+  success: boolean;
+  error?: string;
+  durationMs?: number;
+};
+export type PluginHookBeforeResetEvent = {
+  sessionFile?: string;
+  messages?: unknown[];
+  reason?: string;
+};
+export type PluginHookSessionContext = {
+  agentId?: string;
+  sessionId: string;
+};
+export type PluginHookSessionEndEvent = {
+  sessionId: string;
+  messageCount: number;
+  durationMs?: number;
+};
+export type PluginHookGatewayStartEvent = {
+  port: number;
+};
+export type PluginHookGatewayContext = {
+  port?: number;
+};
+//#endregion

package/dist/internal/engine/bindings/sno-station-mem-hook-types.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/engine/bindings/sno-station-mem-insight-distill-factory.d.ts

@@ -0,0 +1,14 @@
+import { t as PluginConfig } from "../../../plugin-config-schema-C0UUbOmG.js";
+import { n as AgentLlmPort } from "../../../agent-llm-port-5oXgBpzJ.js";
+import { n as PluginObservability } from "../../../adapter-DMEmCTKo.js";
+import { t as Embedder } from "../../../embedding-provider-client-vynZMuit.js";
+import { C as MemoryStore } from "../../../memory-store-base-XRA4S9Xl.js";
+import { r as AtomicInsightDistiller } from "../../../atomic-memory-extraction-BpOUWPJM.js";
+import { t as SnoStationMemPluginApi } from "../../../sno-station-mem-runtime-dependencies-Bu-MiqPX.js";
+//#region src/engine/bindings/sno-station-mem-insight-distill-factory.d.ts
+/**
+ * Assembles Insight Distill from validated inputs for deterministic plugin lifecycle
+ * orchestration.
+ */
+export declare function buildInsightDistiller(api: SnoStationMemPluginApi, config: PluginConfig, store: MemoryStore, _embedder: Embedder, _observability: PluginObservability, _sessionUuidProvider: () => string | undefined, stateDir: string, agentPort?: AgentLlmPort): AtomicInsightDistiller | undefined;
+//#endregion

package/dist/internal/engine/bindings/sno-station-mem-insight-distill-factory.js

@@ -0,0 +1,119 @@
+import { pickLlmRoutingConfig, resolveLlmRoute } from "../../model/llm-mode-routing.js";
+import { t as appendAuditEntry } from "../../../runtime-audit-log-BCeujlEp.js";
+import { r as createSignedAtomicMemoryExtractionTransports, t as AtomicInsightDistiller } from "../../../atomic-memory-extraction-sdNf1-B1.js";
+import "../../../sno-station-mem-runtime-dependencies-DjLOhB45.js";
+import { createLogger } from "@snoai/utils/logger";
+//#region src/engine/bindings/sno-station-mem-insight-distill-factory.ts
+/** @file sno-station-mem-insight-distill-factory.ts
+* @purpose Builds the optional Insight Distill LLM extractor from validated plugin runtime config.
+* @boundary Extractor construction only; capture execution lives in the Ambient Learning hook.
+*/
+const diagnosticLog = createLogger("sno-station-mem:sno-station-mem-insight-distill-factory");
+/**
+* Assembles Insight Distill from validated inputs for deterministic plugin lifecycle
+* orchestration.
+*/
+function buildInsightDistiller(api, config, store, _embedder, _observability, _sessionUuidProvider, stateDir, agentPort) {
+	const routing = pickLlmRoutingConfig(config);
+	const extractRoute = resolveLlmRoute({
+		callId: "E1",
+		config: routing
+	});
+	if ("off" in extractRoute) {
+		diagnosticLog.info("Memory extraction disabled", {
+			outcome: "skipped",
+			reason_code: extractRoute.reason
+		}, {
+			event_name: "memory.sno-station-mem_insight_distill_factory.memory.extraction.disabled",
+			file: "packages/memory/src/engine/bindings/sno-station-mem-insight-distill-factory.ts",
+			function: "buildInsightDistiller",
+			site_id: "plugin.sno-station-mem-insight-distill-factory.buildInsightDistiller.8b084be5ca"
+		});
+		return;
+	}
+	if (extractRoute.transport !== "chat-completions" && extractRoute.transport !== "agent-host-seam") {
+		diagnosticLog.info("Memory extraction transport unavailable", {
+			outcome: "skipped",
+			transport: extractRoute.transport
+		}, {
+			event_name: "memory.sno-station-mem_insight_distill_factory.memory.extraction.transport.unavailable",
+			file: "packages/memory/src/engine/bindings/sno-station-mem-insight-distill-factory.ts",
+			function: "buildInsightDistiller",
+			site_id: "plugin.sno-station-mem-insight-distill-factory.buildInsightDistiller.6cdc733c64"
+		});
+		return;
+	}
+	if (extractRoute.transport === "agent-host-seam" && !agentPort) {
+		diagnosticLog.info("sno-station-mem insight-distill disabled (host agent binding unavailable)", void 0, {
+			event_name: "sno_station_mem.sno-station-mem-insight-distill-factory.sno.station.mem.insight.distill.disabled.host.agent.binding.unavailable",
+			file: "packages/memory/src/engine/bindings/sno-station-mem-insight-distill-factory.ts",
+			function: "buildInsightDistiller",
+			site_id: "sno-station-mem-insight-distill-factory.buildInsightDistiller.847c5ab779"
+		});
+		return;
+	}
+	if ("off" in extractRoute) return void 0;
+	const llmCfg = config.extraction.llm;
+	if (!llmCfg) throw new Error(`sno-station-mem mode "${config.mode}" requires extraction.llm.preset`);
+	try {
+		const transports = createSignedAtomicMemoryExtractionTransports({
+			preset: llmCfg.preset,
+			...llmCfg.apiKey ? { apiKey: llmCfg.apiKey } : {},
+			...llmCfg.baseURL ? { baseURL: llmCfg.baseURL } : {},
+			timeoutMs: llmCfg.timeoutMs,
+			routing,
+			...agentPort ? { agentPort } : {},
+			onTransportAttempt: ({ callId, destination, transport }) => {
+				appendAuditEntry(stateDir, {
+					event: "ambient_learning",
+					hook: "agent_end",
+					resultStatus: "ok",
+					decision: "llm_distill_attempted",
+					details: {
+						mode: config.mode,
+						callId,
+						destination,
+						transport
+					}
+				});
+			},
+			onProviderResponse: ({ callId, destination, provider, requestId, model, usage }) => {
+				appendAuditEntry(stateDir, {
+					event: "ambient_learning",
+					hook: "agent_end",
+					resultStatus: "ok",
+					decision: "llm_distill_response",
+					details: {
+						mode: config.mode,
+						callId,
+						destination,
+						requestId: requestId ?? null,
+						provider,
+						model: model ?? null,
+						usage: usage ? {
+							...usage,
+							source: "provider-returned"
+						} : null
+					}
+				});
+			}
+		});
+		diagnosticLog.info("Memory extraction enabled", {
+			outcome: "success",
+			model: llmCfg.preset
+		}, {
+			event_name: "memory.sno-station-mem_insight_distill_factory.memory.extraction.enabled",
+			file: "packages/memory/src/engine/bindings/sno-station-mem-insight-distill-factory.ts",
+			function: "buildInsightDistiller",
+			site_id: "plugin.sno-station-mem-insight-distill-factory.buildInsightDistiller.888f96bfef"
+		});
+		return new AtomicInsightDistiller(store, transports, {
+			defaultScope: config.scopes.default,
+			locale: config.language
+		});
+	} catch (err) {
+		throw new Error(`sno-station-mem insight-distill init failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+//#endregion
+export { buildInsightDistiller };

package/dist/internal/engine/bindings/sno-station-mem-message-transcript.d.ts

@@ -0,0 +1,52 @@
+import { a as FIXED_PROTOCOL_VALUE_63 } from "../../../signed-registry-constants-Bv0fgZ8Q.js";
+//#region src/engine/bindings/sno-station-mem-message-transcript.d.ts
+/** Collects text chunks from SDK messages while ignoring unsupported content parts. */
+export declare function extractAllMessageTexts(record: Record<string, unknown>): string[];
+/**
+ * Marks a message this plugin injected into the host agent as its OWN model request.
+ *
+ * `sourceChannel` is the host's own message-origin field — optional, free-form, and part of the
+ * persisted transcript schema (`sno-station-mem/dist/transcript-*.d.ts`). It is what survives the gap
+ * that matters: the host records our turn, and ambient learning reads the session LATER, from an
+ * unrelated async chain and possibly a later process. Nothing scoped to the originating call, and
+ * nothing held in memory, is still observable there.
+ *
+ * Verified against a real recorded row on the E2E host, 2026-08-30: a persisted message is
+ * `{role, timestamp, sourceChannel, content}` — this field is carried, an unknown field has no
+ * such guarantee.
+ *
+ * This excludes text THIS PLUGIN authored and nothing else. A message without this origin is
+ * untouched, so no incoming user turn can be dropped by this path — including one whose wording
+ * happens to match ours.
+ */
+export declare const PLUGIN_OWNED_SOURCE_CHANNEL: typeof FIXED_PROTOCOL_VALUE_63;
+/** Whether a raw SDK message is one this plugin injected as its own model request. */
+export declare function isPluginOwnedMessage(message: unknown): boolean;
+/** Narrows raw SDK messages to user/assistant turns eligible for ambient-learning. */
+export declare function isAmbientLearningMessage(message: unknown): message is Record<string, unknown> & {
+  role: "user" | "assistant";
+};
+/**
+ * Normalizes message timestamp ms at the boundary before plugin lifecycle orchestration uses
+ * it.
+ */
+export declare function normalizeMessageTimestampMs(value: unknown): number | undefined;
+/**
+ * Derive a session anchor from the most recent conversational message so the
+ * insight distiller can resolve relative dates like "yesterday" or "last year".
+ */
+export declare function deriveSessionDateTime(messages: unknown[], captureAssistant?: boolean): string | undefined;
+/**
+ * The session date a transcript states about itself. A replayed or imported log carries the date
+ * it was actually spoken on; the gateway's message timestamps only say when it was replayed, and
+ * anchoring "yesterday" to the replay day files every relative date years off. An ISO
+ * `session_date_time:` line in a user message therefore outranks the message timestamps; a
+ * header that does not parse as ISO is ignored, not guessed at.
+ */
+export declare function transcriptSessionDateTime(messages: unknown[]): string | undefined;
+/** Builds the chronological transcript used by session summary and capture logic. */
+export declare function buildConversationText(messages: unknown[], captureAssistant: boolean): {
+  text: string;
+  latestUserMemorySourceText?: string;
+};
+//#endregion