@snoai/memory 0.0.0-stage → 1.0.0

package/dist/internal/engine/observability/observable-retriever.js

@@ -0,0 +1,95 @@
+import { l as runWithMemoryAudit } from "../../../runtime-audit-log-BCeujlEp.js";
+import { getSnoStationMemStateDir } from "../../contract/profile.js";
+import { n as countManyEmbeddingTokens, t as countEmbeddingTokens } from "../../../token-counter-BD1f48Km.js";
+import { a as DEFAULT_RETRIEVAL_CONFIG, n as MemoryRetriever } from "../../../retriever-CygHBazG.js";
+//#region src/engine/observability/observable-retriever.ts
+var ObservableMemoryRetriever = class extends MemoryRetriever {
+	observability;
+	sessionUuidProvider;
+	embeddingConfig;
+	constructor(store, embedder, logger, config = DEFAULT_RETRIEVAL_CONFIG, observability, sessionUuidProvider, embeddingConfig) {
+		super(store, embedder, logger, config);
+		this.observability = observability;
+		this.sessionUuidProvider = sessionUuidProvider;
+		this.embeddingConfig = embeddingConfig;
+	}
+	async retrieve(context) {
+		return this.observeRead(context, "retrieve", () => super.retrieve(context));
+	}
+	async retrieveWithTrace(context) {
+		const started = Date.now();
+		try {
+			const result = await auditRetrieval("retrieveWithTrace", context, () => super.retrieveWithTrace(context));
+			const sessionUuid = this.sessionUuidProvider();
+			this.observability.trackBestEffort("memory.read", () => this.emitRead(context, result.results, started, sessionUuid));
+			return result;
+		} catch (error) {
+			await this.observability.emitError("memory.read:throw", error, this.sessionUuidProvider());
+			throw error;
+		}
+	}
+	async observeRead(context, operationName, operation) {
+		const started = Date.now();
+		try {
+			const results = await auditRetrieval(operationName, context, operation);
+			const sessionUuid = this.sessionUuidProvider();
+			this.observability.trackBestEffort("memory.read", () => this.emitRead(context, results, started, sessionUuid));
+			return results;
+		} catch (error) {
+			await this.observability.emitError("memory.read:throw", error, this.sessionUuidProvider());
+			throw error;
+		}
+	}
+	async emitRead(context, results, started, sessionUuid) {
+		const queryHash = this.observability.hashText(context.query);
+		if (!queryHash) return;
+		const queryTokens = await countEmbeddingTokens(context.query, this.embeddingConfig);
+		const resultTokens = await countManyEmbeddingTokens(results.map((result) => result.entry.text), this.embeddingConfig);
+		await this.observability.emit({
+			eventType: "memory.read",
+			sessionUuid,
+			payload: {
+				query_hash: queryHash,
+				query_tokens: queryTokens.count,
+				k: context.limit,
+				hit_count: results.length,
+				result_tokens: resultTokens.count,
+				latency_ms: Math.max(0, Math.round(Date.now() - started)),
+				tokens_method: queryTokens.method
+			}
+		});
+	}
+};
+function auditRetrieval(operation, context, run) {
+	const scopes = context.scopeFilter ?? [];
+	const scope = scopes.length === 1 ? scopes[0] ?? "all" : scopes.length > 1 ? "multiple" : "all";
+	return runWithMemoryAudit({
+		stateDir: getSnoStationMemStateDir(),
+		event: "memory_searched",
+		operation,
+		scope,
+		startedDetails: {
+			scope: scopes,
+			query_kind: context.source ?? "unknown",
+			requested_count: context.limit
+		},
+		run,
+		completedDetails: (result) => {
+			const results = retrievalResults(result);
+			return {
+				scope: scopes,
+				query_kind: context.source ?? "unknown",
+				requested_count: context.limit,
+				result_count: results.length,
+				memory_ids: results.map((entry) => entry.entry.id)
+			};
+		}
+	});
+}
+function retrievalResults(result) {
+	if (Array.isArray(result)) return result;
+	if (typeof result === "object" && result !== null && "results" in result && Array.isArray(result.results)) return result.results;
+	return [];
+}
+//#endregion
+export { ObservableMemoryRetriever };

package/dist/internal/engine/observability/runtime-diagnostics.d.ts

@@ -0,0 +1,13 @@
+import { a as LlmPreset, m as LlmRoutingConfigInput, y as Settings } from "../../../plugin-config-schema-C0UUbOmG.js";
+//#region src/engine/observability/runtime-diagnostics.d.ts
+export interface RuntimeDiagnosticSnapshot {
+  runtimeMode: "plugin" | "sidecar";
+  routing: LlmRoutingConfigInput;
+  preset: LlmPreset;
+  baseURL?: string;
+  hostModel?: unknown;
+  logging: Settings["logging"];
+}
+export declare function initializeRuntimeDiagnostics(logging: Settings["logging"]): void;
+export declare function emitRuntimeStartSnapshot(input: RuntimeDiagnosticSnapshot): void;
+//#endregion

package/dist/internal/engine/observability/runtime-diagnostics.js

@@ -0,0 +1,96 @@
+import { t as MODEL_CALLS } from "../../../model-call-table-CspopkBg.js";
+import { pickLlmRoutingConfig, resolveLlmRoute } from "../../model/llm-mode-routing.js";
+import { n as ATOMIC_EXTRACTION_SKILL_HASH } from "../../../atomic-extraction-skill-CcXmuCqL.js";
+import { getStateDir } from "../../contract/profile.js";
+import { r as ATOMIC_EXTRACTION_RESPONSE_JSON_SCHEMA } from "../../../atomic-extraction-reply-BJ9XV_9s.js";
+import { r as attribute_dictionary_default } from "../../../relation-dictionary-Cev1kyLe.js";
+import { n as version, t as logSiteCatalog } from "../../../log-site-catalog.generated-B9WYdnAM.js";
+import { configureLogger, createLogger, effectiveLogLevel, loggerFileStatus } from "@snoai/utils/logger";
+import { createHash } from "node:crypto";
+//#region src/engine/observability/runtime-diagnostics.ts
+const APPLICATION_NAME = "sno-station-mem";
+const log = createLogger("sno-station-mem:runtime");
+let snapshotEmitted = false;
+function initializeRuntimeDiagnostics(logging) {
+	configureLogger({
+		app: APPLICATION_NAME,
+		serviceVersion: version,
+		buildId: logSiteCatalog.build_id,
+		catalog: logSiteCatalog,
+		level: logging.level,
+		file: logging.file,
+		home: getStateDir()
+	});
+}
+function contentHash(value) {
+	return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function configuredHostModel(value) {
+	if (typeof value === "string") return value;
+	if (value && typeof value === "object" && "primary" in value && typeof value.primary === "string") return value.primary;
+}
+function endpointWithoutCredentials(value) {
+	if (!value) return void 0;
+	try {
+		const endpoint = new URL(value);
+		endpoint.username = "";
+		endpoint.password = "";
+		endpoint.search = "";
+		endpoint.hash = "";
+		return endpoint.toString();
+	} catch {
+		return;
+	}
+}
+function emitRuntimeStartSnapshot(input) {
+	initializeRuntimeDiagnostics(input.logging);
+	if (snapshotEmitted) return;
+	snapshotEmitted = true;
+	const hostModel = configuredHostModel(input.hostModel);
+	const configuredRouting = pickLlmRoutingConfig(input.routing);
+	const endpoint = endpointWithoutCredentials(input.baseURL);
+	const isMemoryCall = (id) => !("calledBy" in MODEL_CALLS[id]);
+	const routing = Object.keys(MODEL_CALLS).filter(isMemoryCall).map((callId) => ({
+		call_id: callId,
+		...resolveLlmRoute({
+			callId,
+			config: configuredRouting
+		})
+	}));
+	log.info("Memory process started", {
+		runtime_mode: input.runtimeMode,
+		product_mode: input.routing.mode,
+		occasion_routing: routing,
+		tiers: {
+			snoRemMem: {
+				preset: input.preset,
+				model: "unavailable",
+				model_reason: "resolved_at_request",
+				...endpoint ? { endpoint } : { route_reason: "resolved_at_request" }
+			},
+			agent: {
+				model: hostModel ?? "unavailable",
+				model_reason: hostModel ? "host_configuration" : "host_owned_per_request",
+				transport: "agent-host-seam"
+			}
+		},
+		effective_level: effectiveLogLevel(),
+		file_sink: loggerFileStatus(),
+		extraction_skill_hash: ATOMIC_EXTRACTION_SKILL_HASH,
+		extraction_reply_schema_hash: contentHash(ATOMIC_EXTRACTION_RESPONSE_JSON_SCHEMA),
+		attribute_dictionary_hash: contentHash(attribute_dictionary_default),
+		config_hash: contentHash({
+			routing,
+			preset: input.preset,
+			endpoint,
+			hostModel
+		})
+	}, {
+		event_name: "memory.process.started",
+		file: "packages/memory/src/engine/observability/runtime-diagnostics.ts",
+		function: "emitRuntimeStartSnapshot",
+		site_id: "runtime.process.started"
+	});
+}
+//#endregion
+export { emitRuntimeStartSnapshot, initializeRuntimeDiagnostics };

package/dist/internal/engine/observability/session-registry.d.ts

@@ -0,0 +1,2 @@
+import { n as isUuidV7, t as ObserveSessionRegistry } from "../../../session-registry-DBoE7AvZ.js";
+export { ObserveSessionRegistry, isUuidV7 };

package/dist/internal/engine/observability/session-registry.js

@@ -0,0 +1,58 @@
+import { canonicalizeUUIDv7Input, createUUIDv7, isLowercaseCanonicalUUIDv7 } from "@snoai/common-core";
+//#region src/engine/observability/session-registry.ts
+/** @file session-registry.ts
+* @purpose Maps host session identifiers to UUID-v7 values for cloud events.
+* @boundary Observability identity only; local plugin session keys are unchanged.
+*/
+function isUuidV7(value) {
+	return isLowercaseCanonicalUUIDv7(value);
+}
+var ObserveSessionRegistry = class {
+	mapped = /* @__PURE__ */ new Map();
+	normalize(runtimeSessionId) {
+		const normalized = runtimeSessionId?.trim();
+		if (!normalized) return void 0;
+		return canonicalizeUUIDv7Input(normalized) ?? normalized;
+	}
+	resolve(runtimeSessionId) {
+		const normalized = this.normalize(runtimeSessionId);
+		if (!normalized) return createUUIDv7();
+		const existing = this.mapped.get(normalized);
+		if (existing) return existing;
+		if (isUuidV7(normalized)) return normalized;
+		const created = createUUIDv7();
+		this.mapped.set(normalized, created);
+		return created;
+	}
+	lookup(runtimeSessionId) {
+		const normalized = this.normalize(runtimeSessionId);
+		if (!normalized) return void 0;
+		const existing = this.mapped.get(normalized);
+		if (existing) return existing;
+		if (isUuidV7(normalized)) return normalized;
+	}
+	link(runtimeSessionId, sessionUuid) {
+		const normalized = this.normalize(runtimeSessionId);
+		if (!normalized) return;
+		if (normalized === sessionUuid) {
+			this.mapped.delete(normalized);
+			return;
+		}
+		this.mapped.set(normalized, sessionUuid);
+	}
+	create() {
+		return createUUIDv7();
+	}
+	delete(runtimeSessionId) {
+		const normalized = this.normalize(runtimeSessionId);
+		if (!normalized) return;
+		this.mapped.delete(normalized);
+	}
+	deleteSession(sessionUuid) {
+		const runtimeSessionIds = [];
+		for (const [runtimeSessionId, mappedSessionUuid] of this.mapped) if (mappedSessionUuid === sessionUuid) runtimeSessionIds.push(runtimeSessionId);
+		for (const runtimeSessionId of runtimeSessionIds) this.mapped.delete(runtimeSessionId);
+	}
+};
+//#endregion
+export { ObserveSessionRegistry, isUuidV7 };

package/dist/internal/engine/observability/version-metadata.d.ts

@@ -0,0 +1,7 @@
+//#region src/engine/observability/version-metadata.d.ts
+export declare function readSnoStationCoreWorkspaceVersion(env?: NodeJS.ProcessEnv): string | undefined;
+/** The nearest manifest above this module: the installed plugin's own package.json. */
+export declare function readInstalledPackageVersion(): string | undefined;
+/** The manifest named `expectedName` above `startDir`; a host reads its own version from its entry file. */
+export declare function readNamedPackageVersion(startDir: string, expectedName: string): string | undefined;
+//#endregion

package/dist/internal/engine/observability/version-metadata.js

@@ -0,0 +1,59 @@
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/engine/observability/version-metadata.ts
+/** @file version-metadata.ts
+* @purpose Resolves SNO Station Core workspace and sno-station-mem package version metadata.
+* @boundary Reads local version files/build-time env only; does not fetch release metadata.
+*/
+const VERSION_ENV_KEYS = ["SNO_STATION_MEM_VERSION", "SNO_STATION_MEM_VERSION"];
+const VERSION_LINE_RE = /^version:\s*["']?([^"'\s]+)["']?\s*$/m;
+function readSnoStationCoreWorkspaceVersion(env = process.env) {
+	for (const key of VERSION_ENV_KEYS) {
+		const value = env[key]?.trim();
+		if (value) return value;
+	}
+	for (const startDir of versionSearchRoots()) {
+		const version = readVersionYamlUpward(startDir);
+		if (version) return version;
+	}
+}
+/** The nearest manifest above this module: the installed plugin's own package.json. */
+function readInstalledPackageVersion() {
+	return readPackageVersionUpward(dirname(fileURLToPath(import.meta.url)));
+}
+/** The manifest named `expectedName` above `startDir`; a host reads its own version from its entry file. */
+function readNamedPackageVersion(startDir, expectedName) {
+	return readPackageVersionUpward(startDir, expectedName);
+}
+function versionSearchRoots() {
+	const moduleDir = dirname(fileURLToPath(import.meta.url));
+	return [process.cwd(), moduleDir];
+}
+function readVersionYamlUpward(startDir) {
+	let dir = startDir;
+	for (let depth = 0; depth < 10; depth += 1) {
+		const candidate = join(dir, "VERSION.yaml");
+		if (existsSync(candidate)) return VERSION_LINE_RE.exec(readFileSync(candidate, "utf8"))?.[1];
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+}
+function readPackageVersionUpward(startDir, expectedName) {
+	let dir = startDir;
+	for (let depth = 0; depth < 10; depth += 1) {
+		const candidate = join(dir, "package.json");
+		if (existsSync(candidate)) try {
+			const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+			if ((expectedName === void 0 || parsed.name === expectedName) && typeof parsed.version === "string" && parsed.version.trim()) return parsed.version.trim();
+		} catch {
+			return;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+}
+//#endregion
+export { readInstalledPackageVersion, readNamedPackageVersion, readSnoStationCoreWorkspaceVersion };

package/dist/internal/engine/operations/daily-spend-estimator.d.ts

@@ -0,0 +1,2 @@
+import { t as readEstimatedSpendToday } from "../../../daily-spend-estimator-DiwzBlo1.js";
+export { readEstimatedSpendToday };

package/dist/internal/engine/operations/daily-spend-estimator.js

@@ -0,0 +1,97 @@
+import { COST_ESTIMATE_CACHE_TTL_MS } from "../../config/index.js";
+import { s as getCostPath } from "../../../runtime-audit-log-BCeujlEp.js";
+import { createLogger } from "@snoai/utils/logger";
+import { stat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+//#region src/engine/operations/daily-spend-estimator.ts
+/** @file daily-spend-estimator.ts
+* @purpose Tracks extraction and LLM usage costs for capture and reflection flows.
+* @boundary LLM client accounting, extractor usage, and runtime diagnostics.
+* @see llm-client.ts, memory-extraction-pipeline.ts, daily-log-generator.ts.
+*/
+const diagnosticLog = createLogger("sno-station-mem:daily-spend-estimator");
+const spendCache = /* @__PURE__ */ new Map();
+/**
+* Reads estimated spend today and applies daily spend accounting fallback behavior for missing
+* data.
+*/
+async function readEstimatedSpendToday(stateDir) {
+	const filePath = getCostPath(stateDir);
+	let fileStat;
+	try {
+		fileStat = await stat(filePath);
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) diagnosticLog.warn("Recorded spend file unavailable", {
+			error,
+			outcome: "partial"
+		}, {
+			event_name: "memory.spend.read.failed",
+			file: "packages/memory/src/engine/operations/daily-spend-estimator.ts",
+			function: "readEstimatedSpendToday",
+			site_id: "memory.spend.stat.failed"
+		});
+		return 0;
+	}
+	const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const now = Date.now();
+	const cached = spendCache.get(filePath);
+	if (cached && cached.day === today && cached.size === fileStat.size && cached.mtimeMs === fileStat.mtimeMs && cached.expiresAt > now) return cached.total;
+	let total = 0;
+	let malformedCount = 0;
+	let startOffset = 0;
+	if (cached && cached.day === today && fileStat.size >= cached.size && fileStat.mtimeMs >= cached.mtimeMs) {
+		total = cached.total;
+		startOffset = cached.size;
+	}
+	try {
+		const stream = createReadStream(filePath, {
+			encoding: "utf-8",
+			...startOffset > 0 ? { start: startOffset } : {}
+		});
+		const lines = createInterface({
+			input: stream,
+			crlfDelay: Number.POSITIVE_INFINITY
+		});
+		for await (const line of lines) {
+			if (!line.trim()) continue;
+			try {
+				const parsed = JSON.parse(line);
+				if (!parsed.timestamp?.startsWith(today)) continue;
+				if (typeof parsed.estimatedCostUsd === "number") total += parsed.estimatedCostUsd;
+			} catch {
+				malformedCount += 1;
+			}
+		}
+	} catch (error) {
+		diagnosticLog.warn("Recorded spend read failed", {
+			error,
+			outcome: "partial"
+		}, {
+			event_name: "memory.spend.read.failed",
+			file: "packages/memory/src/engine/operations/daily-spend-estimator.ts",
+			function: "readEstimatedSpendToday",
+			site_id: "memory.spend.stream.failed"
+		});
+		return 0;
+	}
+	if (malformedCount > 0) diagnosticLog.warn("Recorded spend contains invalid rows", {
+		malformed_count: malformedCount,
+		outcome: "partial"
+	}, {
+		event_name: "memory.spend.rows.invalid",
+		file: "packages/memory/src/engine/operations/daily-spend-estimator.ts",
+		function: "readEstimatedSpendToday",
+		site_id: "memory.spend.rows.invalid"
+	});
+	spendCache.set(filePath, {
+		day: today,
+		size: fileStat.size,
+		mtimeMs: fileStat.mtimeMs,
+		expiresAt: now + COST_ESTIMATE_CACHE_TTL_MS,
+		total
+	});
+	return total;
+}
+//#endregion
+export { readEstimatedSpendToday };

package/dist/internal/engine/operations/learning-file-maintenance.d.ts

@@ -0,0 +1,2 @@
+import { a as appendSelfImprovementEntry, i as DEFAULT_LEARNINGS_TEMPLATE, n as DEFAULT_ERRORS_TEMPLATE, o as ensureSelfImprovementLearningFiles, r as DEFAULT_FEATURE_REQUESTS_TEMPLATE, t as AppendSelfImprovementEntryParams } from "../../../learning-file-maintenance-9b-Ut6Kv.js";
+export { AppendSelfImprovementEntryParams, DEFAULT_ERRORS_TEMPLATE, DEFAULT_FEATURE_REQUESTS_TEMPLATE, DEFAULT_LEARNINGS_TEMPLATE, appendSelfImprovementEntry, ensureSelfImprovementLearningFiles };