@snoai/memory 0.0.0-stage → 1.0.0

package/dist/_types-CUKHSRkS.d.ts

@@ -0,0 +1,103 @@
+//#region src/engine/i18n/res/_types.d.ts
+type TemporalIntervalAnchor = "today" | "yesterday" | "tomorrow" | "day_after_tomorrow" | "this_week" | "next_week" | "last_week" | "this_month" | "next_month" | "tonight" | "this_morning" | "recent";
+interface TemporalPhraseRule {
+  patterns: ReadonlyArray<RegExp>;
+  anchor: TemporalIntervalAnchor;
+}
+interface CategoryRoutingNs {
+  identity: ReadonlyArray<RegExp>;
+  preference: ReadonlyArray<RegExp>;
+  entity: ReadonlyArray<RegExp>;
+  event: ReadonlyArray<RegExp>;
+  lesson: ReadonlyArray<RegExp>;
+}
+interface CaptureTriggersNs {
+  categoryRouting: CategoryRoutingNs;
+  identityPattern: RegExp;
+  preferencePattern: RegExp;
+  entityPattern: RegExp;
+  eventPattern: RegExp;
+  lessonPattern: RegExp;
+  temporalPhrases?: ReadonlyArray<TemporalPhraseRule>;
+  /**
+   * Matches a clock time stated in this locale's own words, e.g. Korean "오후 3시" or "세 시".
+   *
+   * `temporalPhrases` only knows day-sized anchors. A sentence that names a day AND an hour is
+   * therefore only partly readable from the table, and the hour is the part a model has to read.
+   * Declaring the marker here — beside the phrases it qualifies — keeps the natural language in
+   * the locale resource, where a reader of that language can check it, rather than inline in the
+   * resolver.
+   */
+  temporalClockTimePattern?: RegExp;
+  weekStartDay: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /**
+   * Native imperative patterns the user issues to explicitly persist a memory
+   * (e.g. English "Remember X", Chinese "记住 X"). Used by the parser's
+   * deterministic fallback when LLM extraction misses an explicit teach.
+   * Each pattern must encode its own gating — bare "save" / "store" variants
+   * are intentionally excluded.
+   */
+  explicitMemoryCommandPositivePatterns: ReadonlyArray<RegExp>;
+  /**
+   * Native question forms that ask the system to recall a prior memory
+   * (e.g. English "do you remember", Chinese "你还记得...吗"). Must NOT
+   * be treated as a store-imperative.
+   */
+  explicitMemoryCommandRecallQuestionPatterns: ReadonlyArray<RegExp>;
+  /**
+   * Native verbs that ask the system to drop or clear a memory
+   * (e.g. English "forget", Chinese "忘记"). Must NOT be treated as
+   * a store-imperative.
+   */
+  explicitMemoryCommandManagementPatterns: ReadonlyArray<RegExp>;
+}
+interface NoiseNs {
+  denialPatterns: ReadonlyArray<RegExp>;
+  correctionSignals: ReadonlyArray<RegExp>;
+  metaQuestionPatterns: ReadonlyArray<RegExp>;
+  /** User frustration aimed at the memory system ("you never remember", "why is my memory broken"). */
+  metaFrustrationPatterns: ReadonlyArray<RegExp>;
+  ackTokens: ReadonlyArray<RegExp>;
+  memoryIntent: ReadonlyArray<RegExp>;
+}
+interface ToolDescriptionsNs {
+  memoryRecall: string;
+  memoryStore: string;
+  memoryForget: string;
+  memoryUpdate: string;
+  memoryStats: string;
+  memoryList: string;
+}
+interface ExtractionPromptsNs {
+  buildDateResolutionPrompt(): string;
+  buildExtractionPrompt(conversationText: string, user: string, sessionDateTime?: string, sessionTimezone?: string, activeProfileSectionNames?: readonly string[]): string;
+  buildDedupPrompt(candidateAbstract: string, candidateOverview: string, candidateContent: string, existingMemories: string): string;
+}
+interface ReflectionErrorSignalLike {
+  toolName: string;
+  summary: string;
+  signatureHash: string;
+}
+interface ReflectionPromptsNs {
+  buildReflectionPrompt(conversation: string, maxInputChars: number, toolErrorSignals?: ReadonlyArray<ReflectionErrorSignalLike>): string;
+  buildReflectionFallbackText(): string;
+}
+interface ReflectionSliceClassifiersNs {
+  invariantSignals: ReadonlyArray<RegExp>;
+  derivedSignals: ReadonlyArray<RegExp>;
+  openLoopSignals: ReadonlyArray<RegExp>;
+  invariantLegacySignals: ReadonlyArray<RegExp>;
+  derivedLegacySignals: ReadonlyArray<RegExp>;
+}
+interface LocaleResources {
+  captureTriggers: CaptureTriggersNs;
+  noise: NoiseNs;
+  toolDescriptions: ToolDescriptionsNs;
+  extractionPrompts: ExtractionPromptsNs;
+  reflectionPrompts: ReflectionPromptsNs;
+  reflectionSliceClassifiers: ReflectionSliceClassifiersNs;
+}
+type Namespace = keyof LocaleResources;
+declare const ALL_NAMESPACES: ReadonlyArray<Namespace>;
+//#endregion
+export { LocaleResources as a, ReflectionErrorSignalLike as c, TemporalIntervalAnchor as d, TemporalPhraseRule as f, ExtractionPromptsNs as i, ReflectionPromptsNs as l, CaptureTriggersNs as n, Namespace as o, ToolDescriptionsNs as p, CategoryRoutingNs as r, NoiseNs as s, ALL_NAMESPACES as t, ReflectionSliceClassifiersNs as u };

package/dist/access-tracker-CSc21GtV.d.ts

@@ -0,0 +1,110 @@
+import { v as MemoryMetadata } from "./types-DxKqU60b.js";
+import { sn as RecallLifecycleConfig } from "./index-DL8AVj0Z.js";
+import { C as MemoryStore } from "./memory-store-base-XRA4S9Xl.js";
+import "./store-2pM0-dZg.js";
+//#region src/engine/retrieval/access-tracker.d.ts
+interface AccessMetadata {
+  readonly accessCount: number;
+  readonly lastAccessedAt: number;
+}
+interface AccessTrackerOptions {
+  readonly store: MemoryStore;
+  readonly debounceMs?: number;
+  readonly recallLifecycle?: RecallLifecycleConfig;
+}
+/**
+ * Parse access-related fields from a metadata JSON string.
+ *
+ * Handles: undefined, empty string, malformed JSON, negative numbers,
+ * numbers exceeding 10000. Always returns a valid AccessMetadata.
+ */
+declare function parseAccessMetadata(metadata: string | undefined): AccessMetadata & Partial<MemoryMetadata>;
+/**
+ * Merge an access-count increment into existing metadata JSON.
+ *
+ * Preserves ALL existing fields in the metadata object — only overwrites
+ * `accessCount` and `lastAccessedAt`. Returns a new JSON string.
+ */
+declare function buildUpdatedMetadata(existingMetadata: string | undefined, accessDelta: number, ceiling?: number): string;
+/**
+ * Compute the effective half-life for a memory based on its access history.
+ *
+ * The access count itself decays over time (30-day half-life for access
+ * freshness), so stale accesses contribute less reinforcement. The extension
+ * uses a logarithmic curve (`Math.log1p`) to provide diminishing returns.
+ *
+ * @param baseHalfLife        - Base half-life in days (e.g. 30)
+ * @param accessCount         - Raw number of times the memory was accessed
+ * @param lastAccessedAt      - Timestamp (ms) of last access
+ * @param reinforcementFactor - Scaling factor for reinforcement (0 = disabled)
+ * @param maxMultiplier       - Hard cap: result <= baseHalfLife * maxMultiplier
+ * @returns Effective half-life in days
+ */
+declare function computeEffectiveHalfLife(baseHalfLife: number, accessCount: number, lastAccessedAt: number, reinforcementFactor: number, maxMultiplier: number, now?: number): number;
+/**
+ * Debounced write-back tracker for memory access events.
+ *
+ * `recordAccess()` is synchronous (Map update only, no I/O). Pending deltas
+ * accumulate until `flush()` is called (or after debounceMs timeout).
+ * On flush, each pending entry is read via `store.getById()`, its metadata
+ * is merged with the accumulated access delta, and written back via
+ * `store.update()`.
+ */
+declare class AccessTracker {
+  private readonly pending;
+  private debounceTimer;
+  private flushPromise;
+  private readonly debounceMs;
+  private readonly store;
+  private retryDelayMs;
+  private readonly writeFailures;
+  private destroying;
+  private readonly recallLifecycle;
+  private readonly clampedOnce;
+  /**
+   * Initializes access reinforcement metadata collaborators while keeping runtime work in
+   * explicit methods.
+   */
+  constructor(options: AccessTrackerOptions);
+  /**
+   * Record one access for each of the given memory IDs.
+   * Synchronous — only updates the in-memory pending map.
+   */
+  recordAccess(ids: readonly string[]): void;
+  /** Return a snapshot of all pending (id -> delta) entries. */
+  getPendingUpdates(): Map<string, number>;
+  /**
+   * Flush pending access deltas to the store.
+   *
+   * If a flush is already in progress, awaits the current flush to complete.
+   * If new pending data accumulated during the in-flight flush, a follow-up
+   * flush is automatically triggered.
+   */
+  flush(): Promise<void>;
+  /** Tear down the tracker with one final best-effort flush. */
+  destroy(): Promise<void>;
+  /**
+   * Flushes all pending deltas in ONE store call (one mutex acquisition + one
+   * transaction), instead of the historical per-id mutex+transaction+full
+   * update() round trip. Policy (rate-limit window, ceiling clamp) stays here,
+   * delivered through per-id delta callbacks; the store only merges and writes.
+   */
+  private doFlush;
+  /**
+   * Per-id policy transform executed inside the store's batch transaction.
+   * Returns undefined to skip the write (rate-limited). Both metadata key
+   * styles are written — see the cross-subsystem naming note on
+   * buildUpdatedMetadata.
+   */
+  private buildAccessDelta;
+  /** Implements reset timer as the local access reinforcement metadata operation. */
+  private resetTimer;
+  /** Implements schedule retry as the local access reinforcement metadata operation. */
+  private scheduleRetry;
+  /** Implements reset timer with delay as the local access reinforcement metadata operation. */
+  private resetTimerWithDelay;
+  /** Removes timer while preserving access reinforcement metadata invariants. */
+  private clearTimer;
+}
+//#endregion
+export { computeEffectiveHalfLife as a, buildUpdatedMetadata as i, AccessTracker as n, parseAccessMetadata as o, AccessTrackerOptions as r, AccessMetadata as t };

package/dist/adapter-DMEmCTKo.d.ts

@@ -0,0 +1,69 @@
+import { t as PluginConfig } from "./plugin-config-schema-C0UUbOmG.js";
+import "./types-DxKqU60b.js";
+import { t as ObserveLogger } from "./best-effort-BPZSzKk0.js";
+import { AgentId, EventType, JsonObject } from "@snoai/observability";
+//#region src/engine/observability/cost-aggregator.d.ts
+type CostSummaryPayload = JsonObject & {
+  session_uuid: string;
+  tokens_in: number;
+  tokens_out: number;
+  llm_calls: number;
+  memory_writes: number;
+  memory_reads: number;
+  tool_calls: number;
+  host_agent_prompt_tokens: number;
+  host_agent_completion_tokens: number;
+  plugin_internal_prompt_tokens: number;
+  plugin_internal_completion_tokens: number;
+  local_memory_input_tokens: number;
+  local_memory_output_tokens: number;
+};
+declare class CostAggregator {
+  private readonly sessions;
+  start(sessionUuid: string): void;
+  /** Takes over another aggregator's open sessions, so a re-registration keeps their tallies. */
+  adopt(other: CostAggregator): void;
+  record(eventType: EventType, sessionUuid: string | undefined, payload: JsonObject): void;
+  summary(sessionUuid: string): CostSummaryPayload;
+  delete(sessionUuid: string): void;
+  summaryAndDelete(sessionUuid: string): CostSummaryPayload;
+  clear(): void;
+}
+//#endregion
+//#region src/engine/observability/adapter.d.ts
+type EmitInput = {
+  eventType: EventType;
+  eventId?: string;
+  tsEdgeMs?: number;
+  scope?: JsonObject;
+  payload: JsonObject;
+  sessionUuid?: string;
+};
+type FlushOptions = {
+  force?: boolean;
+  timeoutMs?: number;
+};
+declare class PluginObservability {
+  private readonly runtime;
+  readonly logger: ObserveLogger | undefined;
+  private readonly pending;
+  readonly agentId: AgentId;
+  readonly enabled: boolean;
+  readonly aggregator: CostAggregator;
+  constructor(config: PluginConfig, cwd: string, logger?: ObserveLogger, options?: {
+    agentVersion?: string;
+  }, redactionRules?: readonly string[]);
+  hashText(input: string): string | undefined;
+  emit(input: EmitInput): Promise<void>;
+  tryEmit(input: EmitInput): Promise<boolean>;
+  private runEmitWithTimeout;
+  emitError(kind: string, error: unknown, sessionUuid?: string): Promise<void>;
+  trackBestEffort(label: string, task: () => void | Promise<void>): void;
+  private runBackgroundTask;
+  drain(options?: Pick<FlushOptions, "timeoutMs">): Promise<void>;
+  drainBuffer(options?: Pick<FlushOptions, "timeoutMs">): Promise<void>;
+  flush(options?: FlushOptions): Promise<void>;
+  shutdown(): Promise<void>;
+}
+//#endregion
+export { PluginObservability as n, EmitInput as t };

package/dist/adapter-XaRHZWZ2.js

@@ -0,0 +1,333 @@
+import { bestEffort, bestEffortSync } from "./internal/engine/observability/best-effort.js";
+import { readInstalledPackageVersion, readSnoStationCoreWorkspaceVersion } from "./internal/engine/observability/version-metadata.js";
+import { createLogger } from "@snoai/utils/logger";
+import { createSnoObserve, laneForEventType } from "@snoai/observability";
+//#region src/engine/observability/cost-aggregator.ts
+function emptyCounters() {
+	return {
+		hostAgentPromptTokens: 0,
+		hostAgentCompletionTokens: 0,
+		pluginInternalPromptTokens: 0,
+		pluginInternalCompletionTokens: 0,
+		localMemoryInputTokens: 0,
+		localMemoryOutputTokens: 0,
+		llmCalls: 0,
+		memoryWrites: 0,
+		memoryReads: 0,
+		toolCalls: 0
+	};
+}
+function numberFromPayload(payload, key) {
+	const value = payload[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+var CostAggregator = class {
+	sessions = /* @__PURE__ */ new Map();
+	start(sessionUuid) {
+		if (!this.sessions.has(sessionUuid)) this.sessions.set(sessionUuid, emptyCounters());
+	}
+	/** Takes over another aggregator's open sessions, so a re-registration keeps their tallies. */
+	adopt(other) {
+		for (const [sessionUuid, counters] of other.sessions) if (!this.sessions.has(sessionUuid)) this.sessions.set(sessionUuid, counters);
+	}
+	record(eventType, sessionUuid, payload) {
+		if (!sessionUuid) return;
+		const counters = this.sessions.get(sessionUuid) ?? emptyCounters();
+		let changed = true;
+		if (eventType === "memory.write") {
+			counters.memoryWrites += 1;
+			counters.localMemoryInputTokens += numberFromPayload(payload, "content_tokens");
+		} else if (eventType === "memory.read") {
+			counters.memoryReads += 1;
+			counters.localMemoryInputTokens += numberFromPayload(payload, "query_tokens");
+			counters.localMemoryOutputTokens += numberFromPayload(payload, "result_tokens");
+		} else if (eventType === "llm.call") {
+			counters.llmCalls += 1;
+			if (payload.token_source === "plugin_internal_paid") {
+				counters.pluginInternalPromptTokens += numberFromPayload(payload, "prompt_tokens");
+				counters.pluginInternalCompletionTokens += numberFromPayload(payload, "completion_tokens");
+			} else {
+				counters.hostAgentPromptTokens += numberFromPayload(payload, "prompt_tokens");
+				counters.hostAgentCompletionTokens += numberFromPayload(payload, "completion_tokens");
+			}
+		} else if (eventType === "tool.call") counters.toolCalls += 1;
+		else changed = false;
+		if (changed) this.sessions.set(sessionUuid, counters);
+	}
+	summary(sessionUuid) {
+		const counters = this.sessions.get(sessionUuid) ?? emptyCounters();
+		return {
+			session_uuid: sessionUuid,
+			tokens_in: counters.hostAgentPromptTokens + counters.pluginInternalPromptTokens,
+			tokens_out: counters.hostAgentCompletionTokens + counters.pluginInternalCompletionTokens,
+			llm_calls: counters.llmCalls,
+			memory_writes: counters.memoryWrites,
+			memory_reads: counters.memoryReads,
+			tool_calls: counters.toolCalls,
+			host_agent_prompt_tokens: counters.hostAgentPromptTokens,
+			host_agent_completion_tokens: counters.hostAgentCompletionTokens,
+			plugin_internal_prompt_tokens: counters.pluginInternalPromptTokens,
+			plugin_internal_completion_tokens: counters.pluginInternalCompletionTokens,
+			local_memory_input_tokens: counters.localMemoryInputTokens,
+			local_memory_output_tokens: counters.localMemoryOutputTokens
+		};
+	}
+	delete(sessionUuid) {
+		this.sessions.delete(sessionUuid);
+	}
+	summaryAndDelete(sessionUuid) {
+		const summary = this.summary(sessionUuid);
+		this.delete(sessionUuid);
+		return summary;
+	}
+	clear() {
+		this.sessions.clear();
+	}
+};
+//#endregion
+//#region src/engine/observability/adapter.ts
+/** @file adapter.ts
+* @purpose Adapts plugin events to the public @snoai/observability SDK.
+* @boundary Plugin emits only public SDK events; the SDK owns buffering and HTTP delivery.
+*/
+const diagnosticLog = createLogger("sno-station-mem:adapter");
+const OBSERVE_EMIT_TIMEOUT_MS = 5e3;
+const OBSERVE_BACKGROUND_TIMEOUT_MS = 5e3;
+function formatErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	if (typeof error === "object" && error !== null) try {
+		return JSON.stringify(error);
+	} catch {
+		return "[unserializable]";
+	}
+	return String(error);
+}
+var PluginObservability = class {
+	runtime;
+	logger;
+	pending = /* @__PURE__ */ new Set();
+	agentId;
+	enabled;
+	aggregator = new CostAggregator();
+	constructor(config, cwd, logger, options = {}, redactionRules = []) {
+		this.enabled = config.observe.enabled;
+		this.agentId = config.observe.agentId;
+		this.logger = logger;
+		if (this.enabled) {
+			const pluginVersion = readSnoStationCoreWorkspaceVersion() ?? readInstalledPackageVersion();
+			this.runtime = createSnoObserve({
+				cwd,
+				baseUrl: config.observe.baseUrl,
+				redactionRules,
+				...pluginVersion ? {
+					cliVersion: pluginVersion,
+					pluginVersion
+				} : {},
+				...options.agentVersion ? { agentVersion: options.agentVersion } : {}
+			});
+		}
+	}
+	hashText(input) {
+		if (!this.runtime) return void 0;
+		return bestEffortSync("hashRedactedText", () => this.runtime?.hashRedactedText(input), this.logger);
+	}
+	async emit(input) {
+		await this.tryEmit(input);
+	}
+	async tryEmit(input) {
+		if (!this.runtime) return false;
+		const scope = input.sessionUuid ? {
+			...input.scope ?? {},
+			session_uuid: input.sessionUuid
+		} : input.scope;
+		const event = {
+			event_type: input.eventType,
+			...input.tsEdgeMs !== void 0 ? { ts_edge_ms: input.tsEdgeMs } : {},
+			...input.eventId ? { event_id: input.eventId } : {},
+			agent_id: this.agentId,
+			lane: laneForEventType(input.eventType),
+			...scope ? { scope } : {},
+			payload: input.payload
+		};
+		if (input.eventType !== "tool.call") bestEffortSync("costAggregator.record", () => this.aggregator.record(input.eventType, input.sessionUuid, input.payload), this.logger);
+		try {
+			return await this.runEmitWithTimeout(event, { timeoutMs: OBSERVE_EMIT_TIMEOUT_MS });
+		} catch (error) {
+			diagnosticLog.error("Cloud event emission failed", {
+				event_type: input.eventType,
+				error,
+				outcome: "failed"
+			}, {
+				event_name: "observability.emit.failed",
+				file: "packages/memory/src/engine/observability/adapter.ts",
+				function: "PluginObservability.tryEmit",
+				site_id: "observability.emit.failed"
+			});
+			return false;
+		}
+	}
+	async runEmitWithTimeout(event, options) {
+		let timeoutHandle;
+		const run = Promise.resolve().then(() => this.runtime?.emit(event)).then(() => true);
+		run.catch(() => void 0);
+		try {
+			return await Promise.race([run, new Promise((resolve) => {
+				timeoutHandle = setTimeout(() => {
+					diagnosticLog.error("sno-station-mem observability: emit timed out", { event_type: event.event_type }, {
+						event_name: "sno_station_mem.adapter.sno.station.mem.observability.emit.timed.out",
+						file: "packages/memory/src/engine/observability/adapter.ts",
+						function: "<anonymous callback>",
+						site_id: "adapter.<anonymous callback>.82f49c57a7"
+					});
+					resolve(false);
+				}, options.timeoutMs);
+				timeoutHandle.unref?.();
+			})]);
+		} finally {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+		}
+	}
+	async emitError(kind, error, sessionUuid) {
+		const messageHash = this.hashText(formatErrorMessage(error));
+		if (!messageHash) return;
+		await this.emit({
+			eventType: "error",
+			sessionUuid,
+			payload: {
+				kind,
+				component: {
+					"claude-code": "mem-claude",
+					codex: "mem-codex",
+					openclaw: "mem-claw",
+					hermes: "mem-hermes"
+				}[this.agentId],
+				context: kind.split(":", 1)[0] ?? kind,
+				message_hash: messageHash,
+				recoverable: false
+			}
+		});
+	}
+	trackBestEffort(label, task) {
+		const run = bestEffort(label, task, this.logger);
+		const tracked = this.runBackgroundTask(label, run).finally(() => {
+			this.pending.delete(tracked);
+		});
+		this.pending.add(tracked);
+	}
+	async runBackgroundTask(label, run) {
+		let timeoutHandle;
+		run.catch(() => void 0);
+		try {
+			await Promise.race([run, new Promise((resolve) => {
+				timeoutHandle = setTimeout(() => {
+					diagnosticLog.error("Background telemetry action timed out", {
+						action: label,
+						timeout_ms: OBSERVE_BACKGROUND_TIMEOUT_MS
+					}, {
+						event_name: "observability.background.timed_out",
+						file: "packages/memory/src/engine/observability/adapter.ts",
+						function: "PluginObservability.runBackgroundTask",
+						site_id: "observability.background.timed_out"
+					});
+					resolve();
+				}, OBSERVE_BACKGROUND_TIMEOUT_MS);
+				timeoutHandle.unref?.();
+			})]);
+		} finally {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+		}
+	}
+	async drain(options = {}) {
+		if (this.pending.size === 0) return;
+		const pending = Promise.allSettled([...this.pending]).then(() => void 0);
+		if (!options.timeoutMs) {
+			await bestEffort("drain", () => pending, this.logger);
+			return;
+		}
+		await bestEffort("drain", async () => {
+			let timeoutHandle;
+			try {
+				await Promise.race([pending, new Promise((resolve) => {
+					timeoutHandle = setTimeout(() => {
+						diagnosticLog.warn("sno observe drain timed out", void 0, {
+							event_name: "sno_station_mem.adapter.sno.observe.drain.timed.out",
+							file: "packages/memory/src/engine/observability/adapter.ts",
+							function: "<anonymous callback>",
+							site_id: "adapter.<anonymous callback>.f036514cb8"
+						});
+						resolve();
+					}, options.timeoutMs);
+					timeoutHandle.unref?.();
+				})]);
+			} finally {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+			}
+		}, this.logger);
+	}
+	async drainBuffer(options = {}) {
+		if (!this.runtime) return;
+		const run = this.runtime.drain().then(() => void 0);
+		run.catch(() => void 0);
+		if (!options.timeoutMs) {
+			await bestEffort("drainBuffer", () => run, this.logger);
+			return;
+		}
+		await bestEffort("drainBuffer", async () => {
+			let timeoutHandle;
+			try {
+				await Promise.race([run, new Promise((resolve) => {
+					timeoutHandle = setTimeout(() => {
+						diagnosticLog.warn("sno observe buffer drain timed out", void 0, {
+							event_name: "sno_station_mem.adapter.sno.observe.buffer.drain.timed.out",
+							file: "packages/memory/src/engine/observability/adapter.ts",
+							function: "<anonymous callback>",
+							site_id: "adapter.<anonymous callback>.9aedc01548"
+						});
+						resolve();
+					}, options.timeoutMs);
+					timeoutHandle.unref?.();
+				})]);
+			} finally {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+			}
+		}, this.logger);
+	}
+	async flush(options = {}) {
+		if (!this.runtime) return;
+		const force = options.force ?? true;
+		const run = this.runtime.flush({ force }).then(() => void 0);
+		run.catch(() => void 0);
+		if (!options.timeoutMs) {
+			await bestEffort("flush", () => run, this.logger);
+			return;
+		}
+		await bestEffort("flush", async () => {
+			let timeoutHandle;
+			try {
+				await Promise.race([run, new Promise((resolve) => {
+					timeoutHandle = setTimeout(() => {
+						diagnosticLog.warn("sno observe flush timed out", void 0, {
+							event_name: "sno_station_mem.adapter.sno.observe.flush.timed.out",
+							file: "packages/memory/src/engine/observability/adapter.ts",
+							function: "<anonymous callback>",
+							site_id: "adapter.<anonymous callback>.52f64c2607"
+						});
+						resolve();
+					}, options.timeoutMs);
+					timeoutHandle.unref?.();
+				})]);
+			} finally {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+			}
+		}, this.logger);
+	}
+	async shutdown() {
+		if (!this.runtime) return;
+		await bestEffort("shutdown", async () => {
+			await this.runtime?.shutdown();
+		}, this.logger);
+	}
+};
+//#endregion
+export { PluginObservability as t };

package/dist/agent-llm-port-5oXgBpzJ.d.ts

@@ -0,0 +1,53 @@
+//#region src/model/agent-llm-port.d.ts
+/** @file agent-llm-port.ts
+ * @purpose Universal call surface for borrowing the host agent's LLM (the agent-host-seam transport).
+ * @boundary Types and result contracts only; host bindings live in plugin/, dispatch in llm-client.ts.
+ */
+/**
+ * One completion request against the host agent's configured model. The
+ * binding absorbs its transport's limitations (OAuth, cancellation shape,
+ * unsupported knobs) — callers never branch on host specifics.
+ */
+type AgentLlmRequest = {
+  /** System prompt; the binding places it wherever its transport expects. */
+  system?: string;
+  /** User prompt content. */
+  prompt: string;
+  /** Best-effort output bound; stripped when the transport rejects it. */
+  maxTokens?: number;
+  /** Overrides the host binding's default-off reasoning mode for this request. */
+  enableThinking?: boolean;
+  /** Deadline; the binding MUST terminate the underlying request. */
+  timeoutMs?: number;
+  /** Cooperative cancellation; the binding MUST honor it. */
+  signal?: AbortSignal;
+};
+/**
+ * Typed completion result. Cancellation and errors are values, not thrown:
+ * a cancelled call must never be readable as "the model found nothing"
+ * (the SnoStationMem seam resolves aborted calls with a normal-shaped empty
+ * response, which is exactly the trap this shape exists to close).
+ */
+type AgentLlmCompletion = {
+  kind: "ok";
+  text: string;
+} | {
+  kind: "cancelled";
+  reason: string;
+} | {
+  kind: "error";
+  /**
+   * auth: generic credential rejection. credential-expired and
+   * credential-revoked preserve actionable OAuth states. exhausted:
+   * the subscription has reached a hard usage limit. throttle:
+   * transient rate limit. transport: the seam is unavailable.
+   * unknown: everything else.
+   */
+  category: "auth" | "credential-expired" | "credential-revoked" | "exhausted" | "throttle" | "transport" | "unknown";
+  message: string;
+};
+interface AgentLlmPort {
+  complete(request: AgentLlmRequest): Promise<AgentLlmCompletion>;
+}
+//#endregion
+export { AgentLlmPort as n, AgentLlmRequest as r, AgentLlmCompletion as t };