@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/long-term-memory/events.js

@@ -0,0 +1,15 @@
+export const LONG_TERM_MEMORY_EVENTS = Object.freeze({
+    RETRIEVAL_STARTED: "memory.retrieval.started",
+    RETRIEVAL_COMPLETED: "memory.retrieval.completed",
+    RETRIEVAL_FAILED: "memory.retrieval.failed",
+    SAVE_QUEUED: "memory.save.queued",
+});
+export function emitLongTermMemoryEvent(params) {
+    if (!params.enabled || !params.context.onEvent) {
+        return;
+    }
+    params.context.onEvent(params.name, {
+        stage: "long_term_memory",
+        ...params.details,
+    });
+}

package/dist/src/runtime/long-term-memory/finalization.d.ts

@@ -0,0 +1,8 @@
+import type { LongTermMemoryService, MemoryCandidate } from "./contracts.js";
+export declare function scheduleFinalResponseMemory(params: {
+    service?: LongTermMemoryService;
+    candidates?: readonly MemoryCandidate[];
+    requestId: string;
+    sessionId: string;
+    onEvent?: (name: string, extra?: Record<string, unknown>) => void;
+}): void;

package/dist/src/runtime/long-term-memory/finalization.js

@@ -0,0 +1,24 @@
+import { classifyMemoryFailure } from "./diagnostics.js";
+import { traceDebug } from "../observability/debug-logger.js";
+export function scheduleFinalResponseMemory(params) {
+    if (!params.service?.enabled || !params.candidates?.length) {
+        return;
+    }
+    try {
+        params.service.scheduleCandidates({
+            candidates: params.candidates,
+            context: {
+                requestId: params.requestId,
+                sessionId: params.sessionId,
+                ...(params.onEvent ? { onEvent: params.onEvent } : {}),
+            },
+        });
+    }
+    catch (error) {
+        traceDebug("runtime.long_term_memory", "save.scheduling_isolated", {
+            requestId: params.requestId,
+            reason: classifyMemoryFailure(error),
+            candidateCount: params.candidates.length,
+        });
+    }
+}

package/dist/src/runtime/long-term-memory/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./contracts.js";
+export { createLongTermMemoryService } from "./service.js";
+export { isLongTermMemoryManagementError, LongTermMemoryManagementError, } from "./management/errors.js";
+export * from "./onboarding/contracts.js";
+export { createLongTermMemoryOnboardingService } from "./onboarding/service.js";
+export { LONG_TERM_MEMORY_MESSAGE_KIND, projectLongTermMemoryMessage, } from "./projection.js";

package/dist/src/runtime/long-term-memory/index.js

@@ -0,0 +1,6 @@
+export * from "./contracts.js";
+export { createLongTermMemoryService } from "./service.js";
+export { isLongTermMemoryManagementError, LongTermMemoryManagementError, } from "./management/errors.js";
+export * from "./onboarding/contracts.js";
+export { createLongTermMemoryOnboardingService } from "./onboarding/service.js";
+export { LONG_TERM_MEMORY_MESSAGE_KIND, projectLongTermMemoryMessage, } from "./projection.js";

package/dist/src/runtime/long-term-memory/management/contracts.d.ts

@@ -0,0 +1,54 @@
+import type { LongTermMemoryRecord, LongTermMemoryStatus } from "../contracts.js";
+export type LongTermMemoryManagementErrorCode = "long_term_memory_disabled" | "long_term_memory_management_conflict" | "long_term_memory_management_duplicate" | "long_term_memory_management_input_invalid" | "long_term_memory_management_not_found" | "long_term_memory_management_sensitive_data" | "long_term_memory_unavailable";
+export type MemoryManagementSource = "web_ui" | "management_api";
+export type LongTermMemoryManagementContext = Readonly<{
+    abortSignal: AbortSignal;
+    debugRequestId?: string;
+}>;
+export type MemoryListInput = Readonly<{
+    limit?: number;
+    offset?: number;
+}>;
+export type MemoryListResult = Readonly<{
+    items: readonly LongTermMemoryRecord[];
+    total: number;
+}>;
+export type MemorySearchInput = MemoryListInput & Readonly<{
+    query: string;
+    context: LongTermMemoryManagementContext;
+}>;
+export type MemorySearchResult = MemoryListResult;
+export type MemoryCreateInput = Readonly<{
+    content: string;
+    tags: readonly string[];
+    source: MemoryManagementSource;
+    context: LongTermMemoryManagementContext;
+}>;
+export type MemoryCreateResult = Readonly<{
+    record: LongTermMemoryRecord;
+}>;
+export type MemoryUpdateInput = Readonly<{
+    id: string;
+    expectedUpdatedAt: string;
+    content: string;
+    tags: readonly string[];
+    context: LongTermMemoryManagementContext;
+}>;
+export type MemoryUpdateResult = Readonly<{
+    record: LongTermMemoryRecord;
+    updated: boolean;
+}>;
+export type MemoryDeleteInput = Readonly<{
+    id: string;
+}>;
+export type MemoryDeleteResult = Readonly<{
+    deleted: boolean;
+}>;
+export type LongTermMemoryManagementService = Readonly<{
+    status(): Promise<LongTermMemoryStatus>;
+    list(input?: MemoryListInput): Promise<MemoryListResult>;
+    search(input: MemorySearchInput): Promise<MemorySearchResult>;
+    create(input: MemoryCreateInput): Promise<MemoryCreateResult>;
+    update(input: MemoryUpdateInput): Promise<MemoryUpdateResult>;
+    delete(input: MemoryDeleteInput): Promise<MemoryDeleteResult>;
+}>;

package/dist/src/runtime/long-term-memory/management/contracts.js

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

package/dist/src/runtime/long-term-memory/management/errors.d.ts

@@ -0,0 +1,10 @@
+import type { LongTermMemoryManagementErrorCode } from "./contracts.js";
+export declare class LongTermMemoryManagementError extends Error {
+    readonly code: LongTermMemoryManagementErrorCode;
+    readonly memoryId?: string;
+    constructor(code: LongTermMemoryManagementErrorCode, options?: Readonly<{
+        cause?: unknown;
+        memoryId?: string;
+    }>);
+}
+export declare function isLongTermMemoryManagementError(error: unknown): error is LongTermMemoryManagementError;

package/dist/src/runtime/long-term-memory/management/errors.js

@@ -0,0 +1,13 @@
+export class LongTermMemoryManagementError extends Error {
+    code;
+    memoryId;
+    constructor(code, options = {}) {
+        super(code, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "LongTermMemoryManagementError";
+        this.code = code;
+        this.memoryId = options.memoryId;
+    }
+}
+export function isLongTermMemoryManagementError(error) {
+    return error instanceof LongTermMemoryManagementError;
+}

package/dist/src/runtime/long-term-memory/management/mutations.d.ts

@@ -0,0 +1,17 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository, MemoryClearResult } from "../contracts.js";
+import type { MemoryCreateInput, MemoryCreateResult, MemoryDeleteInput, MemoryDeleteResult, MemoryUpdateInput, MemoryUpdateResult } from "./contracts.js";
+export declare function createManagedMemory(params: {
+    repository: LongTermMemoryRepository;
+    embeddings: LongTermMemoryEmbeddingClient;
+    input: MemoryCreateInput;
+    now?: () => Date;
+    createId?: () => string;
+}): Promise<MemoryCreateResult>;
+export declare function updateManagedMemory(params: {
+    repository: LongTermMemoryRepository;
+    embeddings: LongTermMemoryEmbeddingClient;
+    input: MemoryUpdateInput;
+    now?: () => Date;
+}): Promise<MemoryUpdateResult>;
+export declare function deleteManagedMemory(repository: LongTermMemoryRepository, input: MemoryDeleteInput): Promise<MemoryDeleteResult>;
+export declare function clearManagedMemories(repository: LongTermMemoryRepository): Promise<MemoryClearResult>;

package/dist/src/runtime/long-term-memory/management/mutations.js

@@ -0,0 +1,178 @@
+import { randomUUID } from "node:crypto";
+import { LongTermMemoryManagementError } from "./errors.js";
+import { clearMemoryRecords } from "./queries.js";
+import { findExactMemoryDuplicate, normalizeMemoryId, prepareCreatedMemory, prepareUpdatedMemory, } from "./validation.js";
+export async function createManagedMemory(params) {
+    const prepared = prepareCreatedMemory(params.input);
+    const initial = await params.repository.read();
+    const initialDuplicate = findExactMemoryDuplicate(initial.records, prepared.candidate.content);
+    if (initialDuplicate) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_duplicate", { memoryId: initialDuplicate.id });
+    }
+    const embedded = await embedContent({
+        embeddings: params.embeddings,
+        content: prepared.candidate.content,
+        context: params.input.context,
+    });
+    const timestamp = readTimestamp(params.now);
+    const id = normalizeMemoryId((params.createId ?? randomUUID)());
+    const record = freezeMemoryRecord({
+        id,
+        content: prepared.candidate.content,
+        tags: prepared.candidate.tags,
+        provenance: Object.freeze({
+            kind: "manual",
+            source: prepared.source,
+        }),
+        createdAt: timestamp,
+        updatedAt: timestamp,
+    });
+    await params.repository.update((current) => {
+        params.input.context.abortSignal.throwIfAborted();
+        const duplicate = findExactMemoryDuplicate(current.records, record.content);
+        if (duplicate) {
+            throw new LongTermMemoryManagementError("long_term_memory_management_duplicate", { memoryId: duplicate.id });
+        }
+        if (current.records.some((existing) => existing.id === record.id)) {
+            throw new LongTermMemoryManagementError("long_term_memory_management_conflict", { memoryId: record.id });
+        }
+        return {
+            records: Object.freeze([...current.records, record]),
+            vectors: Object.freeze([
+                ...current.vectors,
+                createVectorEntry(record.id, embedded),
+            ]),
+        };
+    });
+    return Object.freeze({ record });
+}
+export async function updateManagedMemory(params) {
+    const prepared = prepareUpdatedMemory(params.input);
+    const initial = await findUpdateTarget(params.repository, prepared);
+    if (matchesCandidate(initial, prepared.candidate)) {
+        return Object.freeze({ record: initial, updated: false });
+    }
+    const contentChanged = initial.content !== prepared.candidate.content;
+    const embedded = contentChanged
+        ? await embedContent({
+            embeddings: params.embeddings,
+            content: prepared.candidate.content,
+            context: params.input.context,
+        })
+        : undefined;
+    let updatedRecord;
+    await params.repository.update((current) => {
+        params.input.context.abortSignal.throwIfAborted();
+        const target = requireCurrentUpdateTarget(current.records, prepared);
+        const duplicate = findExactMemoryDuplicate(current.records, prepared.candidate.content, target.id);
+        if (duplicate) {
+            throw new LongTermMemoryManagementError("long_term_memory_management_duplicate", { memoryId: duplicate.id });
+        }
+        updatedRecord = freezeMemoryRecord({
+            ...target,
+            content: prepared.candidate.content,
+            tags: prepared.candidate.tags,
+            updatedAt: nextTimestamp(target.updatedAt, params.now),
+        });
+        return {
+            records: Object.freeze(current.records.map((record) => record.id === target.id ? updatedRecord : record)),
+            vectors: embedded
+                ? replaceMemoryVector(current.vectors, createVectorEntry(target.id, embedded))
+                : current.vectors,
+        };
+    });
+    return Object.freeze({ record: updatedRecord, updated: true });
+}
+export async function deleteManagedMemory(repository, input) {
+    const id = normalizeMemoryId(input.id);
+    const current = await repository.read();
+    if (!current.records.some((record) => record.id === id)) {
+        return Object.freeze({ deleted: false });
+    }
+    let deleted = false;
+    await repository.update((snapshot) => {
+        const containsTarget = snapshot.records.some((record) => record.id === id);
+        if (!containsTarget) {
+            return { records: snapshot.records, vectors: snapshot.vectors };
+        }
+        deleted = true;
+        return {
+            records: Object.freeze(snapshot.records.filter((record) => record.id !== id)),
+            vectors: Object.freeze(snapshot.vectors.filter((entry) => entry.memoryId !== id)),
+        };
+    });
+    return Object.freeze({ deleted });
+}
+export function clearManagedMemories(repository) {
+    return clearMemoryRecords(repository);
+}
+async function findUpdateTarget(repository, prepared) {
+    const snapshot = await repository.read();
+    return requireCurrentUpdateTarget(snapshot.records, prepared);
+}
+function requireCurrentUpdateTarget(records, prepared) {
+    const target = records.find((record) => record.id === prepared.id);
+    if (!target) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_not_found", { memoryId: prepared.id });
+    }
+    if (target.updatedAt !== prepared.expectedUpdatedAt) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_conflict", { memoryId: prepared.id });
+    }
+    return target;
+}
+function matchesCandidate(record, candidate) {
+    return (record.content === candidate.content &&
+        record.tags.length === candidate.tags.length &&
+        record.tags.every((tag, index) => tag === candidate.tags[index]));
+}
+async function embedContent(params) {
+    params.context.abortSignal.throwIfAborted();
+    const embedded = await params.embeddings.embed({
+        texts: [params.content],
+        abortSignal: params.context.abortSignal,
+        ...(params.context.debugRequestId
+            ? { debugRequestId: params.context.debugRequestId }
+            : {}),
+    });
+    params.context.abortSignal.throwIfAborted();
+    const vector = embedded.vectors[0];
+    const validVector = embedded.vectors.length === 1 &&
+        embedded.dimensions > 0 &&
+        vector?.length === embedded.dimensions &&
+        vector.every(Number.isFinite);
+    if (!validVector || !embedded.modelFingerprint.trim()) {
+        throw new Error("long_term_memory_embedding_response_invalid");
+    }
+    return embedded;
+}
+function createVectorEntry(memoryId, embedded) {
+    return Object.freeze({
+        memoryId,
+        modelFingerprint: embedded.modelFingerprint,
+        dimensions: embedded.dimensions,
+        vector: Object.freeze([...embedded.vectors[0]]),
+    });
+}
+function replaceMemoryVector(vectors, replacement) {
+    return Object.freeze([
+        ...vectors.filter((entry) => entry.memoryId !== replacement.memoryId),
+        replacement,
+    ]);
+}
+function readTimestamp(now) {
+    return (now ?? (() => new Date()))().toISOString();
+}
+function nextTimestamp(previous, now) {
+    const current = readTimestamp(now);
+    if (Date.parse(current) > Date.parse(previous)) {
+        return current;
+    }
+    return new Date(Date.parse(previous) + 1).toISOString();
+}
+function freezeMemoryRecord(record) {
+    return Object.freeze({
+        ...record,
+        tags: Object.freeze([...record.tags]),
+        provenance: Object.freeze({ ...record.provenance }),
+    });
+}

package/dist/src/runtime/long-term-memory/management/queries.d.ts

@@ -0,0 +1,8 @@
+import type { LongTermMemoryRepository, LongTermMemoryStatus, MemoryClearResult } from "../contracts.js";
+import type { MemoryListInput, MemoryListResult } from "./contracts.js";
+export declare function readMemoryStatus(params: {
+    repository: LongTermMemoryRepository;
+    enabled: boolean;
+}): Promise<LongTermMemoryStatus>;
+export declare function listMemoryRecords(repository: LongTermMemoryRepository, input?: MemoryListInput): Promise<MemoryListResult>;
+export declare function clearMemoryRecords(repository: LongTermMemoryRepository): Promise<MemoryClearResult>;

package/dist/src/runtime/long-term-memory/management/queries.js

@@ -0,0 +1,46 @@
+import { classifyMemoryFailure } from "../diagnostics.js";
+import { normalizeMemoryPage } from "./validation.js";
+export async function readMemoryStatus(params) {
+    try {
+        const snapshot = await params.repository.read();
+        return Object.freeze({
+            enabled: params.enabled,
+            available: true,
+            recordCount: snapshot.records.length,
+            indexedRecordCount: new Set(snapshot.vectors.map(({ memoryId }) => memoryId)).size,
+            ...(!params.enabled ? { reason: "disabled" } : {}),
+        });
+    }
+    catch (error) {
+        return Object.freeze({
+            enabled: params.enabled,
+            available: false,
+            recordCount: 0,
+            indexedRecordCount: 0,
+            reason: classifyMemoryFailure(error),
+        });
+    }
+}
+export async function listMemoryRecords(repository, input = {}) {
+    const snapshot = await repository.read();
+    const page = normalizeMemoryPage(input);
+    return Object.freeze({
+        items: Object.freeze(snapshot.records.slice(page.offset, page.offset + page.limit)),
+        total: snapshot.records.length,
+    });
+}
+export async function clearMemoryRecords(repository) {
+    const observed = await repository.read();
+    if (observed.records.length === 0 && observed.vectors.length === 0) {
+        return Object.freeze({ deletedCount: 0 });
+    }
+    let deletedCount = 0;
+    await repository.update((current) => {
+        deletedCount = current.records.length;
+        return {
+            records: Object.freeze([]),
+            vectors: Object.freeze([]),
+        };
+    });
+    return Object.freeze({ deletedCount });
+}

package/dist/src/runtime/long-term-memory/management/search.d.ts

@@ -0,0 +1,7 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository } from "../contracts.js";
+import type { MemorySearchInput, MemorySearchResult } from "./contracts.js";
+export declare function searchManagedMemories(params: {
+    repository: LongTermMemoryRepository;
+    embeddings: LongTermMemoryEmbeddingClient;
+    input: MemorySearchInput;
+}): Promise<MemorySearchResult>;

package/dist/src/runtime/long-term-memory/management/search.js

@@ -0,0 +1,18 @@
+import { searchRankedLongTermMemories } from "../ranked-search.js";
+import { normalizeMemoryPage, normalizeSearchQuery } from "./validation.js";
+export async function searchManagedMemories(params) {
+    const query = normalizeSearchQuery(params.input.query);
+    const page = normalizeMemoryPage(params.input);
+    const ranked = await searchRankedLongTermMemories({
+        repository: params.repository,
+        embeddings: params.embeddings,
+        query,
+        context: params.input.context,
+    });
+    return Object.freeze({
+        items: Object.freeze(ranked
+            .slice(page.offset, page.offset + page.limit)
+            .map(({ record }) => record)),
+        total: ranked.length,
+    });
+}

package/dist/src/runtime/long-term-memory/management/service.d.ts

@@ -0,0 +1,13 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository, MemoryClearResult } from "../contracts.js";
+import type { LongTermMemoryManagementService } from "./contracts.js";
+type LongTermMemoryManagementWithClear = LongTermMemoryManagementService & Readonly<{
+    clear(): Promise<MemoryClearResult>;
+}>;
+export declare function createLongTermMemoryManagement(params: {
+    repository: LongTermMemoryRepository;
+    enabled: boolean;
+    embeddings?: LongTermMemoryEmbeddingClient;
+    now?: () => Date;
+    createId?: () => string;
+}): LongTermMemoryManagementWithClear;
+export {};

package/dist/src/runtime/long-term-memory/management/service.js

@@ -0,0 +1,61 @@
+import { LongTermMemoryManagementError, isLongTermMemoryManagementError, } from "./errors.js";
+import { clearManagedMemories, createManagedMemory, deleteManagedMemory, updateManagedMemory, } from "./mutations.js";
+import { listMemoryRecords, readMemoryStatus } from "./queries.js";
+import { searchManagedMemories } from "./search.js";
+export function createLongTermMemoryManagement(params) {
+    return Object.freeze({
+        status: () => readMemoryStatus(params),
+        list: (input) => runManagementOperation(() => listMemoryRecords(params.repository, input)),
+        search: (input) => runActiveManagementOperation(params, input.context, (embeddings) => searchManagedMemories({
+            repository: params.repository,
+            embeddings,
+            input,
+        })),
+        create: (input) => runActiveManagementOperation(params, input.context, (embeddings) => createManagedMemory({
+            repository: params.repository,
+            embeddings,
+            input,
+            ...(params.now ? { now: params.now } : {}),
+            ...(params.createId ? { createId: params.createId } : {}),
+        })),
+        update: (input) => runActiveManagementOperation(params, input.context, (embeddings) => updateManagedMemory({
+            repository: params.repository,
+            embeddings,
+            input,
+            ...(params.now ? { now: params.now } : {}),
+        })),
+        delete: (input) => runManagementOperation(() => deleteManagedMemory(params.repository, input)),
+        clear: () => runManagementOperation(() => clearManagedMemories(params.repository)),
+    });
+}
+async function runActiveManagementOperation(params, context, operation) {
+    const embeddings = params.embeddings;
+    if (!params.enabled || !embeddings) {
+        throw new LongTermMemoryManagementError("long_term_memory_disabled");
+    }
+    try {
+        context.abortSignal.throwIfAborted();
+        return await operation(embeddings);
+    }
+    catch (error) {
+        if (context.abortSignal.aborted || isLongTermMemoryManagementError(error)) {
+            throw error;
+        }
+        throw new LongTermMemoryManagementError("long_term_memory_unavailable", {
+            cause: error,
+        });
+    }
+}
+async function runManagementOperation(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (isLongTermMemoryManagementError(error)) {
+            throw error;
+        }
+        throw new LongTermMemoryManagementError("long_term_memory_unavailable", {
+            cause: error,
+        });
+    }
+}

package/dist/src/runtime/long-term-memory/management/validation.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryCandidate } from "../contracts.js";
+import type { MemoryCreateInput, MemoryListInput, MemoryManagementSource, MemoryUpdateInput } from "./contracts.js";
+export type MemoryPage = Readonly<{
+    limit: number;
+    offset: number;
+}>;
+export declare function prepareCreatedMemory(input: MemoryCreateInput): Readonly<{
+    candidate: MemoryCandidate;
+    source: MemoryManagementSource;
+}>;
+export declare function prepareUpdatedMemory(input: MemoryUpdateInput): Readonly<{
+    id: string;
+    expectedUpdatedAt: string;
+    candidate: MemoryCandidate;
+}>;
+export declare function normalizeMemoryId(value: string): string;
+export declare function normalizeSearchQuery(value: string): string;
+export declare function normalizeMemoryPage(input?: MemoryListInput): MemoryPage;
+export declare function findExactMemoryDuplicate(records: readonly Readonly<{
+    id: string;
+    content: string;
+}>[], content: string, excludedId?: string): Readonly<{
+    id: string;
+}> | undefined;

package/dist/src/runtime/long-term-memory/management/validation.js

@@ -0,0 +1,77 @@
+import { isMemoryCandidateWithinLimits, normalizeMemoryCandidate, normalizeMemoryIdentifier, normalizeMemoryText, } from "../policies/normalization.js";
+import { containsSensitiveMemoryCandidateData } from "../policies/sensitive-data.js";
+import { LongTermMemoryManagementError } from "./errors.js";
+const DEFAULT_LIST_LIMIT = 100;
+const MAX_LIST_LIMIT = 500;
+const MAX_SEARCH_QUERY_CHARACTERS = 4_000;
+export function prepareCreatedMemory(input) {
+    const candidate = prepareManualCandidate(input.content, input.tags);
+    if (input.source !== "web_ui" && input.source !== "management_api") {
+        throw new LongTermMemoryManagementError("long_term_memory_management_input_invalid");
+    }
+    return Object.freeze({ candidate, source: input.source });
+}
+export function prepareUpdatedMemory(input) {
+    const id = normalizeMemoryId(input.id);
+    const expectedUpdatedAt = input.expectedUpdatedAt.trim();
+    if (!isTimestamp(expectedUpdatedAt)) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_input_invalid", { memoryId: id });
+    }
+    return Object.freeze({
+        id,
+        expectedUpdatedAt,
+        candidate: prepareManualCandidate(input.content, input.tags),
+    });
+}
+export function normalizeMemoryId(value) {
+    const id = normalizeMemoryIdentifier(value);
+    if (!id) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_input_invalid");
+    }
+    return id;
+}
+export function normalizeSearchQuery(value) {
+    const query = typeof value === "string" ? value.trim() : "";
+    if (!query || query.length > MAX_SEARCH_QUERY_CHARACTERS) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_input_invalid");
+    }
+    return query;
+}
+export function normalizeMemoryPage(input = {}) {
+    const offset = normalizeNonNegativeInteger(input.offset, 0);
+    const limit = Math.min(normalizePositiveInteger(input.limit, DEFAULT_LIST_LIMIT), MAX_LIST_LIMIT);
+    return Object.freeze({ limit, offset });
+}
+export function findExactMemoryDuplicate(records, content, excludedId) {
+    const key = normalizeMemoryText(content);
+    return records.find((record) => record.id !== excludedId && normalizeMemoryText(record.content) === key);
+}
+function prepareManualCandidate(content, tags) {
+    if (typeof content !== "string" || !Array.isArray(tags)) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_input_invalid");
+    }
+    if (!isMemoryCandidateWithinLimits({ content, tags })) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_input_invalid");
+    }
+    const candidate = normalizeMemoryCandidate({ content, tags });
+    if (!candidate) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_input_invalid");
+    }
+    if (containsSensitiveMemoryCandidateData(candidate)) {
+        throw new LongTermMemoryManagementError("long_term_memory_management_sensitive_data");
+    }
+    return candidate;
+}
+function isTimestamp(value) {
+    return value.length > 0 && Number.isFinite(Date.parse(value));
+}
+function normalizePositiveInteger(value, fallback) {
+    return Number.isSafeInteger(value) && Number(value) > 0
+        ? Number(value)
+        : fallback;
+}
+function normalizeNonNegativeInteger(value, fallback) {
+    return Number.isSafeInteger(value) && Number(value) >= 0
+        ? Number(value)
+        : fallback;
+}

package/dist/src/runtime/long-term-memory/onboarding/configuration.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeConfigFile } from "../../config/types.js";
+import type { LongTermMemoryOnboardingProvider, LongTermMemoryOnboardingStatus } from "./contracts.js";
+export declare const DEFAULT_MEMORY_EMBEDDING_PROFILE_ID = "memory-embedding";
+export declare function projectOnboardingStatus(config: RuntimeConfigFile): LongTermMemoryOnboardingStatus;
+export declare function buildEnabledMemoryConfig(params: {
+    config: RuntimeConfigFile;
+    providerId: string;
+    model: string;
+    profileId: string;
+    emitClientEvents: boolean;
+}): RuntimeConfigFile;
+export declare function buildDisabledMemoryConfig(config: RuntimeConfigFile): RuntimeConfigFile;
+export declare function listConfiguredProviders(config: RuntimeConfigFile): readonly LongTermMemoryOnboardingProvider[];
+export declare function requireConfiguredProvider(config: RuntimeConfigFile, providerId: string): void;