import type { TranslateFn } from "@/i18n/i18n-context"; import { newId } from "@/lib/random-id"; /** * `managed-file` is a console capability label for the current * messages -> [file] contract. It is never sent as the legacy storageMode * wire field. */ export type StorageMode = "ots" | "managed-file" | "file+ots" | "filemem"; export type MemoryInputType = "short-term" | "file"; export type MemoryStorageStructure = "structured" | "file"; export type MemoryDetailSegment = | "scope" | "units" | "search" | "messages" | "tasks" | "requests" | "dream" | "wiki" | "settings"; export type MemoryCardShortcut = "longTerm" | "shortTerm" | "extract" | "consolidate" | "files"; export type MemoryCardAction = "units" | "search" | "settings"; export interface MemoryStorageSelection { inputType: MemoryInputType; storageStructures: MemoryStorageStructure[]; } export interface MemoryStoreTypeContract { inputType: "messages" | "file"; outputTypes: MemoryStorageStructure[]; } export interface MemoryStoreTypeSource { inputType?: "messages" | "file"; outputTypes?: MemoryStorageStructure[]; storageMode?: string | null; } export const FILEMEM_DEFAULT_RUN_ID = "__default__"; function createRandomRunId(): string { return newId("run"); } export function normalizeMemoryRunId( storageMode: StorageMode | undefined, runId: string, createRunId: () => string = createRandomRunId, ): string { if (storageMode === "filemem") return FILEMEM_DEFAULT_RUN_ID; return !runId || runId === FILEMEM_DEFAULT_RUN_ID ? createRunId() : runId; } export const STORAGE_MODE_VALUES = [ "ots", "managed-file", "file+ots", "filemem", ] as const satisfies readonly StorageMode[]; export function isKnownStorageMode(value: unknown): value is StorageMode { return ( typeof value === "string" && (STORAGE_MODE_VALUES as readonly string[]).includes(value) ); } const STRUCTURED_DETAIL_SEGMENTS: MemoryDetailSegment[] = [ "scope", "units", "search", "messages", "tasks", "requests", "dream", "wiki", "settings", ]; const FILE_DETAIL_SEGMENTS: MemoryDetailSegment[] = [ "scope", "units", "wiki", "settings", ]; const MANAGED_FILE_DETAIL_SEGMENTS: MemoryDetailSegment[] = [ "scope", "units", "search", "messages", "tasks", "requests", "wiki", "settings", ]; const STRUCTURED_CARD_SHORTCUTS: MemoryCardShortcut[] = [ "longTerm", "shortTerm", "extract", "consolidate", ]; const FILE_CARD_SHORTCUTS: MemoryCardShortcut[] = ["files"]; const SEARCHABLE_CARD_ACTIONS: MemoryCardAction[] = [ "units", "search", "settings", ]; const FILE_CARD_ACTIONS: MemoryCardAction[] = ["units", "settings"]; export function normalizeStorageMode( value: string | undefined | null, ): StorageMode { return parseKnownStorageMode(value) ?? "ots"; } export function parseKnownStorageMode( value: string | undefined | null, ): StorageMode | null { if (value === "ots") return "ots"; if (value === "managed-file") return "managed-file"; if (value === "file+ots" || value === "oss+ots") return "file+ots"; if (value === "filemem") return "filemem"; return null; } export function memoryStorageSelectionForInput( inputType: MemoryInputType, ): MemoryStorageSelection { return inputType === "file" ? { inputType, storageStructures: ["file"] } : { inputType, storageStructures: ["structured"] }; } export function toggleMemoryFileStorage( selection: MemoryStorageSelection, ): MemoryStorageSelection { if (selection.inputType === "file") { return memoryStorageSelectionForInput("file"); } return selection.storageStructures.includes("file") ? memoryStorageSelectionForInput("short-term") : { inputType: "short-term", storageStructures: ["structured", "file"], }; } export function toggleMemoryStructuredStorage( selection: MemoryStorageSelection, ): MemoryStorageSelection { if (selection.inputType === "file") { return memoryStorageSelectionForInput("file"); } if (selection.storageStructures.includes("structured")) { return selection.storageStructures.includes("file") ? { inputType: "short-term", storageStructures: ["file"] } : selection; } return { inputType: "short-term", storageStructures: ["structured", "file"], }; } export function storageSelectionToMode( selection: MemoryStorageSelection, ): StorageMode { const structures = new Set(selection.storageStructures); const hasDuplicates = structures.size !== selection.storageStructures.length; if ( !hasDuplicates && selection.inputType === "file" && structures.size === 1 && structures.has("file") ) { return "filemem"; } if ( !hasDuplicates && selection.inputType === "short-term" && structures.size > 0 ) { if (structures.size === 1 && structures.has("structured")) return "ots"; if (structures.size === 1 && structures.has("file")) return "managed-file"; if (structures.size === 2 && structures.has("file")) return "file+ots"; } throw new Error("Invalid memory input and storage structure combination"); } /** * Convert the console selection to the current server contract. New stores * must use inputType/outputTypes instead of the legacy storageMode alias so a * messages -> file-only store is not collapsed into one of the old modes. */ export function storageSelectionToStoreType( selection: MemoryStorageSelection, ): MemoryStoreTypeContract { // Reuse the strict combination validation above before translating labels. storageSelectionToMode(selection); return { inputType: selection.inputType === "short-term" ? "messages" : "file", outputTypes: [...selection.storageStructures], }; } export function storageModeToSelection( value: string | undefined | null, ): MemoryStorageSelection { const mode = normalizeStorageMode(value); if (mode === "filemem") return memoryStorageSelectionForInput("file"); if (mode === "managed-file") { return { inputType: "short-term", storageStructures: ["file"] }; } if (mode === "file+ots") { return { inputType: "short-term", storageStructures: ["structured", "file"], }; } return memoryStorageSelectionForInput("short-term"); } export function resolveMemoryStoreTypeContract( store: MemoryStoreTypeSource, ): MemoryStoreTypeContract { const fallback = storageSelectionToStoreType( storageModeToSelection(store.storageMode), ); return { inputType: store.inputType ?? fallback.inputType, outputTypes: store.outputTypes && store.outputTypes.length > 0 ? [...store.outputTypes] : fallback.outputTypes, }; } export function storageModeCapabilities(value: string | undefined | null) { const mode = normalizeStorageMode(value); const structured = mode === "ots" || mode === "file+ots"; const acceptsMessages = mode !== "filemem"; let detailSegments = FILE_DETAIL_SEGMENTS; if (mode === "managed-file") { detailSegments = MANAGED_FILE_DETAIL_SEGMENTS; } else if (structured) { detailSegments = STRUCTURED_DETAIL_SEGMENTS; } return { mode, files: mode === "managed-file" || mode === "file+ots" || mode === "filemem", structured, writableFiles: mode === "filemem", forceLocalRetrieval: mode === "filemem", structuredAutoSave: structured, supportsExtraction: structured, acceptsMessages, discoverableScopes: acceptsMessages, detailSegments: [...detailSegments], cardShortcuts: [ ...(structured ? STRUCTURED_CARD_SHORTCUTS : FILE_CARD_SHORTCUTS), ], cardActions: [ ...(mode === "filemem" ? FILE_CARD_ACTIONS : SEARCHABLE_CARD_ACTIONS), ], } as const; } export function resolveMemoryDetailSegment( value: string | undefined | null, requested: string, ): MemoryDetailSegment { const { detailSegments } = storageModeCapabilities(value); return detailSegments.includes(requested as MemoryDetailSegment) ? (requested as MemoryDetailSegment) : "units"; } export function isFileMemory(value: string | undefined | null): boolean { return storageModeCapabilities(value).files; } export function isWritableFileMemory( value: string | undefined | null, ): boolean { return storageModeCapabilities(value).writableFiles; } export function storageModeLabel( value: string | undefined | null, t?: TranslateFn, ): string { const mode = normalizeStorageMode(value); if (t) { if (mode === "filemem") { return t("memory.storageMode.writableFileLabel"); } if (mode === "managed-file") { return t("memory.storageMode.managedFileLabel"); } if (mode === "file+ots") { return t("memory.storageMode.projectedFileLabel"); } return t("memory.storageMode.apiOnlyLabel"); } if (mode === "filemem") return "Writable File Memory"; if (mode === "managed-file") return "Managed File Memory"; if (mode === "file+ots") return "Read-only File Projection"; return "API-only Memory"; } export function resolveRetrievalMode( mode: "search" | "local" | undefined, storageMode: string | boolean | undefined | null, ): "search" | "local" { let resolvedStorage: StorageMode; if (typeof storageMode === "boolean") { resolvedStorage = storageMode ? "file+ots" : "ots"; } else { resolvedStorage = normalizeStorageMode(storageMode); } if (resolvedStorage === "filemem") return "local"; if (resolvedStorage === "ots" || resolvedStorage === "managed-file") { return "search"; } return mode === "local" ? "local" : "search"; } export function storageModeDescription( value: string | undefined | null, t?: TranslateFn, ): string { const mode = normalizeStorageMode(value); if (t) { if (mode === "filemem") { return t("memory.storageMode.writableFileDescription"); } if (mode === "managed-file") { return t("memory.storageMode.managedFileDescription"); } if (mode === "file+ots") { return t("memory.storageMode.projectedFileDescription"); } return t("memory.storageMode.apiOnlyDescription"); } if (mode === "filemem") { return "Writable file memory with JSON API CRUD, version history, and local lexical retrieval."; } if (mode === "managed-file") { return "Short-term messages are consolidated into a managed, read-only file tree."; } if (mode === "file+ots") { return "Read-only file projection browsed through the JSON file API."; } return "Tablestore semantic memory without a file workspace."; }