@snoai/memory 0.0.0-stage → 1.0.0

package/dist/index-DQ7VL6d3.d.ts

@@ -0,0 +1,350 @@
+import { p as LlmRoutingConfig, t as PluginConfig } from "./plugin-config-schema-C0UUbOmG.js";
+import { g as MemoryEntry, h as MemoryCategory, t as AGGREGATION_OPERATIONS, x as RetrievalResult } from "./types-DxKqU60b.js";
+import { r as SnoStationMemMemorySearchResult } from "./provider-runtime-types-DFhtdA6d.js";
+import { z } from "zod";
+//#region src/contract/error.d.ts
+declare const DEGRADED_REASONS: readonly ["sidecar-unreachable", "sidecar-unresponsive", "principal-mismatch", "store-mismatch", "no-agent-endpoint", "invalid-input", "timeout", "storage-unavailable", "engine-failed"];
+type DegradedReason = (typeof DEGRADED_REASONS)[number];
+declare class ContractError extends Error {
+  readonly reason: DegradedReason;
+  readonly degraded = true;
+  constructor(reason: DegradedReason, message?: string);
+}
+//#endregion
+//#region src/contract/inputs.d.ts
+type JsonValue = z.infer<ReturnType<typeof z.json>>;
+type HostContext = {
+  observeSessionUuid?: string;
+  agentId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  sessionTimezone?: string;
+  workspace?: string;
+  sessionFile?: string;
+  boundary?: "new" | "reset" | "session-end";
+  systemCaller?: boolean;
+  at?: number;
+};
+/** Every call reads `project` plus the shared global memory; writes land on `project`. */
+type ScopeCtx = {
+  principal: string;
+  project: string;
+  session: string;
+  host?: HostContext;
+};
+type Message = {
+  role: "system" | "developer" | "user" | "assistant" | "tool";
+  content: JsonValue;
+  at: number;
+};
+type Turn = {
+  turnId: string;
+  rewindEpoch: number;
+  messages: Message[];
+};
+type AgentModelRegistration = {
+  baseUrl: string;
+  credential: string;
+  model: string;
+};
+type Registration = {
+  skinId: string;
+  model?: AgentModelRegistration;
+};
+type InitRegistration = Registration;
+type RecallOptions = {
+  corpus?: "memory" | "wiki" | "all" | "sessions";
+  source?: "auto" | "manual" | "native";
+  injectionPhase?: "session-start" | "prompt" | "first-prompt";
+  maxChars?: number;
+  limit?: number;
+  minScore?: number;
+  category?: MemoryCategory;
+  includeMetadata?: boolean;
+  includeHistory?: boolean;
+  includeRefused?: boolean;
+  tokenBudget?: number;
+  externalReference?: string;
+  externalReferenceVisibility?: "public" | "private";
+  aggregation?: {
+    operation: (typeof AGGREGATION_OPERATIONS)[number];
+    terms: string[];
+  };
+};
+type Mutation = {
+  op: "correct";
+  id: string;
+  content: string;
+} | {
+  op: "store";
+  content: string;
+  category?: MemoryCategory;
+  importance?: number;
+  metadata?: Record<string, JsonValue>;
+} | {
+  op: "forget";
+  id?: string;
+  query?: string;
+  suppressKey?: {
+    subject: string;
+    attribute: string;
+  };
+  suppressContent?: string;
+  minScore?: number;
+  maxDelete?: number;
+  confirm?: boolean;
+} | {
+  op: "update";
+  id: string;
+  text?: string;
+  category?: MemoryCategory;
+  importance?: number;
+  metadata?: Record<string, JsonValue>;
+  timestamp?: number;
+} | {
+  op: "clear";
+  confirm: boolean;
+  all?: boolean;
+} | {
+  op: "resolveReflection";
+  memoryId?: string;
+  query?: string;
+  dryRun?: boolean;
+  note?: string;
+  limit?: number;
+};
+type Inspection = {
+  op: "storage";
+} | {
+  op: "stats";
+  scope?: string;
+} | {
+  op: "list";
+  category?: MemoryCategory;
+  limit?: number;
+  offset?: number;
+  importanceMin?: number;
+} | {
+  op: "get";
+  id?: string;
+  path?: string;
+  from?: number;
+  lines?: number;
+} | {
+  op: "listReflection";
+  limit?: number;
+  unresolvedOnly?: boolean;
+};
+type UsageSignal = {
+  event: "inject" | "used" | "rejected" | "tool-error";
+  memoryIds: string[];
+  toolName?: string;
+  text?: string;
+  error?: JsonValue;
+  result?: JsonValue;
+  at: number;
+};
+/** What the host agent did, for the skin's observe session: a prompt, a host model call, a tool call, or a permission decision. */
+type HostDecision = "allow" | "deny";
+type HostEvent = {
+  kind: "prompt";
+  prompt: string;
+} | {
+  kind: "llm";
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  latencyMs: number;
+} | {
+  kind: "tool";
+  toolName: string;
+  decision: HostDecision;
+  input: string;
+  output: string;
+  latencyMs: number;
+} | {
+  kind: "permission";
+  permissionKind: string;
+  decision: HostDecision;
+  target: string;
+};
+interface ContractInputs {
+  init: {
+    scope: ScopeCtx;
+    registration: InitRegistration;
+  };
+  hostEvent: {
+    scope: ScopeCtx;
+    event: HostEvent;
+  };
+  getRecall: {
+    query: string;
+    scope: ScopeCtx;
+    options: RecallOptions;
+  };
+  capture: {
+    turn: Turn;
+    scope: ScopeCtx;
+  };
+  mutate: {
+    op: Mutation;
+    scope: ScopeCtx;
+  };
+  inspect: {
+    op: Inspection;
+    scope: ScopeCtx;
+  };
+  recordUsage: {
+    recallId: string;
+    signal: UsageSignal;
+    scope: ScopeCtx;
+  };
+  onSessionEnd: {
+    messages: Message[];
+    scope: ScopeCtx;
+  };
+  staticBlock: {
+    scope: ScopeCtx;
+  };
+}
+declare const scopeSchema: z.ZodType<ScopeCtx, unknown>;
+declare const messageSchema: z.ZodType<Message, unknown>;
+declare const turnSchema: z.ZodType<Turn, unknown>;
+declare const registrationSchema: z.ZodType<Registration, unknown>;
+declare const initRegistrationSchema: z.ZodType<InitRegistration, unknown>;
+declare const recallOptionsSchema: z.ZodType<RecallOptions, unknown>;
+declare const mutationSchema: z.ZodType<Mutation, unknown>;
+declare const inspectionSchema: z.ZodType<Inspection, unknown>;
+declare const usageSignalSchema: z.ZodType<UsageSignal, unknown>;
+declare const hostEventSchema: z.ZodType<HostEvent, unknown>;
+declare const inputSchemas: { [K in keyof ContractInputs]: z.ZodType<ContractInputs[K], unknown>; };
+//#endregion
+//#region src/contract/results.d.ts
+type Result<T> = T & ({
+  degraded: false;
+} | {
+  degraded: true;
+  reason: DegradedReason;
+  error?: string;
+});
+type ToolResponse = {
+  isError?: boolean;
+  content: Array<{
+    type: "text";
+    text: string;
+  }>;
+  details: Record<string, JsonValue>;
+};
+type InspectData = {
+  op: "storage";
+  dimension: number | null;
+  failed: boolean;
+  reason?: string;
+} | {
+  op: "stats";
+  total: number;
+  projectBreakdown: Record<string, number>;
+  categoryBreakdown: Record<string, number>;
+} | {
+  op: "list" | "listReflection";
+  project: string;
+  entries: MemoryEntry[];
+} | {
+  op: "get";
+  entry: MemoryEntry | null;
+  file?: {
+    text: string;
+    path: string;
+    truncated?: boolean;
+    from?: number;
+    lines?: number;
+    nextFrom?: number;
+  };
+};
+interface ContractOutputs {
+  init: Result<{
+    principal: string;
+    skinId: string;
+  }>;
+  hostEvent: Result<{
+    accepted: boolean;
+  }>;
+  getRecall: Result<{
+    recallId: string;
+    contextText: string;
+    hits?: RetrievalResult[];
+    memoryIds?: string[];
+    toolResult?: ToolResponse;
+    nativeHits?: SnoStationMemMemorySearchResult[];
+    unavailable?: string;
+  }>;
+  capture: Result<{
+    turnId: string;
+    committed: boolean;
+    accepted?: boolean;
+    skipped?: true;
+    partial?: true;
+  }>;
+  mutate: Result<{
+    result: ToolResponse;
+  }>;
+  inspect: Result<{
+    result: InspectData;
+  }>;
+  recordUsage: Result<{
+    accepted: boolean;
+  }>;
+  onSessionEnd: Result<{
+    completed: boolean;
+  }>;
+  staticBlock: Result<{
+    contextText: string;
+  }>;
+}
+declare const memoryEntrySchema: z.ZodType<MemoryEntry, unknown>;
+declare const retrievalResultSchema: z.ZodType<RetrievalResult, unknown>;
+declare const toolResponseSchema: z.ZodType<ToolResponse, unknown>;
+declare const inspectDataSchema: z.ZodType<InspectData, unknown>;
+declare const outputSchemas: { [K in keyof ContractOutputs]: z.ZodType<ContractOutputs[K], unknown>; };
+//#endregion
+//#region src/contract/settings.d.ts
+type EngineSettings = Omit<PluginConfig, keyof LlmRoutingConfig | "remEnhanced">;
+declare const engineSettingsSchema: z.ZodType<EngineSettings, unknown>;
+//#endregion
+//#region src/contract/routes.d.ts
+declare const MEMORY_ROUTES: Readonly<Record<ContractMethod, {
+  path: string;
+  timeoutMs: number;
+}>>;
+declare const MEMORY_BODY_LIMIT_BYTES: number;
+declare const MEMORY_SKIN_HEADER = "x-sno-station-mem-skin";
+declare const MEMORY_HEALTH_TIMEOUT_MS = 5e3;
+declare const MEMORY_START_TIMEOUT_MS = 3e4;
+declare function memoryMethod(pathname: string): ContractMethod | undefined;
+declare const MEMORY_ERROR_STATUS: Readonly<Record<DegradedReason, number>>;
+declare const MEMORY_RECONNECT_INTERVAL_MS = 1e3;
+declare const MEMORY_DEFAULT_SKIN_ID = "default";
+//#endregion
+//#region src/contract/index.d.ts
+type ContractMethod = keyof ContractInputs;
+interface MemoryContract {
+  init(scope: ScopeCtx, registration: Registration): Promise<ContractOutputs["init"]>;
+  hostEvent(event: HostEvent, scope: ScopeCtx): Promise<ContractOutputs["hostEvent"]>;
+  getRecall(query: string, scope: ScopeCtx, options: RecallOptions): Promise<ContractOutputs["getRecall"]>;
+  capture(turn: Turn, scope: ScopeCtx): Promise<ContractOutputs["capture"]>;
+  mutate(op: Mutation, scope: ScopeCtx): Promise<ContractOutputs["mutate"]>;
+  inspect(op: Inspection, scope: ScopeCtx): Promise<ContractOutputs["inspect"]>;
+  recordUsage(recallId: string, signal: UsageSignal, scope: ScopeCtx): Promise<ContractOutputs["recordUsage"]>;
+  onSessionEnd(messages: Message[], scope: ScopeCtx): Promise<ContractOutputs["onSessionEnd"]>;
+  staticBlock(scope: ScopeCtx): Promise<ContractOutputs["staticBlock"]>;
+}
+declare function parseInput<K extends ContractMethod>(method: K, input: unknown): ContractInputs[K];
+declare function parseOutput<K extends ContractMethod>(method: K, output: unknown): ContractOutputs[K];
+declare function contractJsonSchemas(method: ContractMethod): {
+  input: z.core.JSONSchema.JSONSchema;
+  output: z.core.JSONSchema.JSONSchema;
+};
+//#endregion
+export { DEGRADED_REASONS as $, HostEvent as A, UsageSignal as B, outputSchemas as C, ContractInputs as D, AgentModelRegistration as E, Mutation as F, messageSchema as G, initRegistrationSchema as H, RecallOptions as I, registrationSchema as J, mutationSchema as K, Registration as L, Inspection as M, JsonValue as N, HostContext as O, Message as P, ContractError as Q, ScopeCtx as R, memoryEntrySchema as S, toolResponseSchema as T, inputSchemas as U, hostEventSchema as V, inspectionSchema as W, turnSchema as X, scopeSchema as Y, usageSignalSchema as Z, ContractOutputs as _, parseOutput as a, ToolResponse as b, MEMORY_ERROR_STATUS as c, MEMORY_ROUTES as d, DegradedReason as et, MEMORY_SKIN_HEADER as f, engineSettingsSchema as g, EngineSettings as h, parseInput as i, InitRegistration as j, HostDecision as k, MEMORY_HEALTH_TIMEOUT_MS as l, memoryMethod as m, MemoryContract as n, MEMORY_BODY_LIMIT_BYTES as o, MEMORY_START_TIMEOUT_MS as p, recallOptionsSchema as q, contractJsonSchemas as r, MEMORY_DEFAULT_SKIN_ID as s, ContractMethod as t, MEMORY_RECONNECT_INTERVAL_MS as u, InspectData as v, retrievalResultSchema as w, inspectDataSchema as x, Result as y, Turn as z };

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { t as PluginConfig, y as Settings } from "./plugin-config-schema-C0UUbOmG.js";
+import "./types-DxKqU60b.js";
+import { n as AgentLlmPort } from "./agent-llm-port-5oXgBpzJ.js";
+import { n as PluginObservability } from "./adapter-DMEmCTKo.js";
+import { $ as DEGRADED_REASONS, A as HostEvent, B as UsageSignal, C as outputSchemas, D as ContractInputs, E as AgentModelRegistration, F as Mutation, G as messageSchema, H as initRegistrationSchema, I as RecallOptions, J as registrationSchema, K as mutationSchema, L as Registration, M as Inspection, N as JsonValue, O as HostContext, P as Message, Q as ContractError, R as ScopeCtx, S as memoryEntrySchema, T as toolResponseSchema, U as inputSchemas, V as hostEventSchema, W as inspectionSchema, X as turnSchema, Y as scopeSchema, Z as usageSignalSchema, _ as ContractOutputs, a as parseOutput, b as ToolResponse, c as MEMORY_ERROR_STATUS, d as MEMORY_ROUTES, et as DegradedReason, f as MEMORY_SKIN_HEADER, g as engineSettingsSchema, h as EngineSettings, i as parseInput, j as InitRegistration, k as HostDecision, l as MEMORY_HEALTH_TIMEOUT_MS, m as memoryMethod, n as MemoryContract, o as MEMORY_BODY_LIMIT_BYTES, p as MEMORY_START_TIMEOUT_MS, q as recallOptionsSchema, r as contractJsonSchemas, s as MEMORY_DEFAULT_SKIN_ID, t as ContractMethod, u as MEMORY_RECONNECT_INTERVAL_MS, v as InspectData, w as retrievalResultSchema, x as inspectDataSchema, y as Result, z as Turn } from "./index-DQ7VL6d3.js";
+import { t as Embedder } from "./embedding-provider-client-vynZMuit.js";
+import { t as MemoryRetriever } from "./retriever-Ruk3zp7_.js";
+import { C as MemoryStore } from "./memory-store-base-XRA4S9Xl.js";
+import "./store-2pM0-dZg.js";
+import { n as AccessTracker } from "./access-tracker-CSc21GtV.js";
+import { r as MemoryTelemetryUsageOutbox } from "./memory-telemetry-outbox-ddTdImt7.js";
+import { t as ReflectionCommandParams } from "./reflection-command-hooks-C1Vxgb-O.js";
+import { createMemoryRuntime } from "./internal/engine/provider/provider-registration.js";
+//#region src/engine/contract-runtime.d.ts
+interface MemoryRuntimeServices {
+  config: PluginConfig;
+  store: MemoryStore;
+  embedder: Embedder;
+  retriever: MemoryRetriever;
+  accessTracker: AccessTracker;
+  observability: PluginObservability;
+  stateDir: string;
+  agentPort?: AgentLlmPort;
+  telemetryUsage?: MemoryTelemetryUsageOutbox;
+  logger: ReflectionCommandParams["logger"];
+  recallSettings?: Settings["recall"];
+}
+export declare class MemoryContractRuntime implements MemoryContract {
+  private readonly services;
+  private registration;
+  private readonly providers;
+  private readonly reflectionStates;
+  private recall;
+  constructor(services: MemoryRuntimeServices);
+  /** Takes over a replaced runtime's per-session recall turns, so a mid-turn re-registration keeps same-turn omission. */
+  adoptRecall(previous: MemoryContractRuntime): void;
+  close(): Promise<void>;
+  init(scope: ScopeCtx, registration: Registration): Promise<ContractOutputs["init"]>;
+  /** Host-side facts the skin reports for its observe session: a user prompt, or one host model call. */
+  hostEvent(hostEvent: HostEvent, scope: ScopeCtx): Promise<ContractOutputs["hostEvent"]>;
+  private configured;
+  /** Host identities are normalised the way the tools always did: blank or the literal "undefined" is missing. */
+  private agentId;
+  /** Every call writes to its project and reads that project plus the shared global memory. */
+  private scopePolicy;
+  private project;
+  private provider;
+  private hostContext;
+  private reflection;
+  private toolContext;
+  capture(turn: Turn, scope: ScopeCtx, signal?: AbortSignal): Promise<ContractOutputs["capture"]>;
+  getRecall(query: string, scope: ScopeCtx, options: RecallOptions, signal?: AbortSignal): Promise<ContractOutputs["getRecall"]>;
+  private injectionKey;
+  private recordRecalled;
+  private clearRecallSession;
+  private autoRecall;
+  mutate(op: Mutation, scope: ScopeCtx, signal?: AbortSignal): Promise<ContractOutputs["mutate"]>;
+  private correct;
+  inspect(op: Inspection, scope: ScopeCtx): Promise<ContractOutputs["inspect"]>;
+  recordUsage(recallId: string, signal: UsageSignal, scope: ScopeCtx): Promise<ContractOutputs["recordUsage"]>;
+  onSessionEnd(messages: Message[], scope: ScopeCtx, signal?: AbortSignal): Promise<ContractOutputs["onSessionEnd"]>;
+  staticBlock(scope: ScopeCtx): Promise<ContractOutputs["staticBlock"]>;
+}
+//#endregion
+export { AgentModelRegistration, ContractError, ContractInputs, ContractMethod, ContractOutputs, DEGRADED_REASONS, DegradedReason, EngineSettings, HostContext, HostDecision, HostEvent, InitRegistration, InspectData, Inspection, JsonValue, MEMORY_BODY_LIMIT_BYTES, MEMORY_DEFAULT_SKIN_ID, MEMORY_ERROR_STATUS, MEMORY_HEALTH_TIMEOUT_MS, MEMORY_RECONNECT_INTERVAL_MS, MEMORY_ROUTES, MEMORY_SKIN_HEADER, MEMORY_START_TIMEOUT_MS, MemoryContract, type MemoryRuntimeServices, Message, Mutation, RecallOptions, Registration, Result, ScopeCtx, ToolResponse, Turn, UsageSignal, contractJsonSchemas, createMemoryRuntime, engineSettingsSchema, hostEventSchema, initRegistrationSchema, inputSchemas, inspectDataSchema, inspectionSchema, memoryEntrySchema, memoryMethod, messageSchema, mutationSchema, outputSchemas, parseInput, parseOutput, recallOptionsSchema, registrationSchema, retrievalResultSchema, scopeSchema, toolResponseSchema, turnSchema, usageSignalSchema };