@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/index.js

@@ -9,4 +9,5 @@ export * from "./adapters/in-memory-session-store.js";
 export * from "./adapters/multi-workspace-provider.js";
 export * from "./adapters/source-workspace-provider.js";
 export * from "./attachments/store.js";
+export * from "./long-term-memory/index.js";
 export * from "./observability/debug-logger.js";

package/dist/src/runtime/lifecycle/request-finalizer.d.ts

@@ -4,6 +4,7 @@ import type { EventSink } from "../ports.js";
 import { RequestLifecycle } from "../orchestration/lifecycle/request-lifecycle.js";
 import type { RequestObservation, RequestOutputTextMode } from "../request/result.js";
 import type { RequestSessionStore } from "../request/session-store.js";
+import type { LongTermMemoryService, MemoryCandidate } from "../long-term-memory/contracts.js";
 type RequestFinalizationResult = {
     status: "completed";
     output: string;
@@ -26,5 +27,7 @@ export declare function finalizeRequest(params: {
     agentMode: AgentMode;
     thinkingTrace?: SessionThinkingTraceEntry[];
     finalObservation?: RequestObservation;
+    memoryCandidates?: readonly MemoryCandidate[];
+    longTermMemory?: LongTermMemoryService;
 }): Promise<RequestFinalizationResult>;
 export {};

package/dist/src/runtime/lifecycle/request-finalizer.js

@@ -1,4 +1,5 @@
 import { finalizeResponse } from "../orchestration/final-response/finalization.js";
+import { scheduleFinalResponseMemory } from "../long-term-memory/finalization.js";
 export function failRequest(params) {
     params.events.event("thinking.completed");
     params.events.failed(params.error, params.details);
@@ -37,6 +38,13 @@ export async function finalizeRequest(params) {
                 observationContent: params.finalObservation.observationContent,
             }
             : {}),
+        afterPersist: () => scheduleFinalResponseMemory({
+            service: params.longTermMemory,
+            candidates: params.memoryCandidates,
+            requestId: params.requestId,
+            sessionId: params.sessionId,
+            onEvent: params.events.event.bind(params.events),
+        }),
     });
     return { status: "completed", output };
 }

package/dist/src/runtime/long-term-memory/background-save-queue.d.ts

@@ -0,0 +1,17 @@
+import type { LongTermMemoryRequestContext, MemoryCandidate, MemoryCandidateProcessingResult } from "./contracts.js";
+export type BackgroundMemorySave = Readonly<{
+    candidates: readonly MemoryCandidate[];
+    requestId: string;
+    sessionId: string;
+}>;
+export type LongTermMemorySaveQueue = Readonly<{
+    enqueue(save: BackgroundMemorySave): void;
+    drain(): Promise<void>;
+}>;
+export declare function createLongTermMemorySaveQueue(params: {
+    process(input: Readonly<{
+        candidates: readonly MemoryCandidate[];
+        context: LongTermMemoryRequestContext;
+    }>): Promise<MemoryCandidateProcessingResult>;
+    timeoutMs?: number;
+}): LongTermMemorySaveQueue;

package/dist/src/runtime/long-term-memory/background-save-queue.js

@@ -0,0 +1,66 @@
+import { classifyMemoryFailure } from "./diagnostics.js";
+import { traceDebug } from "../observability/debug-logger.js";
+const DEFAULT_BACKGROUND_SAVE_TIMEOUT_MS = 60_000;
+export function createLongTermMemorySaveQueue(params) {
+    const timeoutMs = resolveTimeout(params.timeoutMs);
+    let pending = Promise.resolve();
+    return Object.freeze({
+        enqueue(save) {
+            const detached = detachSave(save);
+            pending = pending.then(() => runSave(params.process, detached, timeoutMs));
+        },
+        drain: () => pending,
+    });
+}
+async function runSave(process, save, timeoutMs) {
+    const controller = new AbortController();
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            const error = new Error("long_term_memory_background_save_timeout");
+            controller.abort(error);
+            reject(error);
+        }, timeoutMs);
+    });
+    try {
+        await Promise.race([
+            process({
+                candidates: save.candidates,
+                context: {
+                    requestId: save.requestId,
+                    sessionId: save.sessionId,
+                    abortSignal: controller.signal,
+                },
+            }),
+            deadline,
+        ]);
+    }
+    catch (error) {
+        traceDebug("runtime.long_term_memory", "save.background_failed", {
+            requestId: save.requestId,
+            reason: classifyMemoryFailure(error),
+            candidateCount: save.candidates.length,
+        });
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function detachSave(save) {
+    return Object.freeze({
+        candidates: Object.freeze(save.candidates.map((candidate) => Object.freeze({
+            content: candidate.content,
+            tags: Object.freeze([...candidate.tags]),
+        }))),
+        requestId: save.requestId,
+        sessionId: save.sessionId,
+    });
+}
+function resolveTimeout(configured) {
+    if (configured !== undefined &&
+        (!Number.isSafeInteger(configured) || configured <= 0)) {
+        throw new TypeError("long_term_memory_background_save_timeout_invalid");
+    }
+    return configured ?? DEFAULT_BACKGROUND_SAVE_TIMEOUT_MS;
+}

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

@@ -0,0 +1,16 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository, LongTermMemoryRequestContext, MemoryCandidate } from "./contracts.js";
+type EmbeddingBatch = Awaited<ReturnType<LongTermMemoryEmbeddingClient["embed"]>>;
+export type MemoryCandidatePersistenceResult = Readonly<{
+    acceptedCount: number;
+    duplicateCount: number;
+}>;
+export declare function persistMemoryCandidates(params: {
+    repository: LongTermMemoryRepository;
+    preparedCandidates: readonly MemoryCandidate[];
+    freshCandidates: readonly MemoryCandidate[];
+    embedded?: EmbeddingBatch;
+    context: LongTermMemoryRequestContext;
+    now?: () => Date;
+    createId?: () => string;
+}): Promise<MemoryCandidatePersistenceResult>;
+export {};

package/dist/src/runtime/long-term-memory/candidate-persistence.js

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import { mergeMemoryTags, normalizeMemoryIdentifier, normalizeMemoryText, } from "./policies/normalization.js";
+import { reconcileMemoryCandidate } from "./policies/reconciliation.js";
+export async function persistMemoryCandidates(params) {
+    const vectorByContent = buildVectorMap(params.freshCandidates, params.embedded);
+    const now = (params.now ?? (() => new Date()))().toISOString();
+    const createId = params.createId ?? randomUUID;
+    let result;
+    await params.repository.update((current) => {
+        params.context.abortSignal.throwIfAborted();
+        const records = [...current.records];
+        const vectors = [...current.vectors];
+        let acceptedCount = 0;
+        let duplicateCount = 0;
+        for (const candidate of params.preparedCandidates) {
+            const existingIndex = findRecordIndex(records, candidate);
+            if (existingIndex >= 0) {
+                duplicateCount += 1;
+                records[existingIndex] = mergeDuplicateRecord(records[existingIndex], candidate, now);
+                continue;
+            }
+            const vector = vectorByContent.get(normalizeMemoryText(candidate.content));
+            if (!vector || !params.embedded) {
+                throw new Error("long_term_memory_candidate_embedding_missing");
+            }
+            const id = createAvailableMemoryId(createId, records, vectors);
+            const record = createMemoryRecord({
+                candidate,
+                context: params.context,
+                now,
+                id,
+            });
+            reconcileMemoryCandidate({
+                candidate,
+                vector,
+                existingVectors: compatibleVectors(vectors, params.embedded),
+            });
+            records.push(record);
+            acceptedCount += 1;
+            vectors.push(Object.freeze({
+                memoryId: record.id,
+                modelFingerprint: params.embedded.modelFingerprint,
+                dimensions: params.embedded.dimensions,
+                vector,
+            }));
+        }
+        result = Object.freeze({ acceptedCount, duplicateCount });
+        return { records: Object.freeze(records), vectors: Object.freeze(vectors) };
+    });
+    if (!result) {
+        throw new Error("long_term_memory_candidate_persistence_outcome_missing");
+    }
+    return result;
+}
+function createAvailableMemoryId(createId, records, vectors) {
+    const id = normalizeMemoryIdentifier(createId());
+    if (!id) {
+        throw new Error("long_term_memory_candidate_id_invalid");
+    }
+    const idInUse = records.some((record) => record.id === id) ||
+        vectors.some((entry) => entry.memoryId === id);
+    if (idInUse) {
+        throw new Error("long_term_memory_candidate_id_conflict");
+    }
+    return id;
+}
+function buildVectorMap(candidates, embedded) {
+    const validCount = embedded?.vectors.length === candidates.length;
+    if (!validCount && candidates.length > 0) {
+        throw new Error("long_term_memory_embedding_vector_count_invalid");
+    }
+    if (!embedded) {
+        return new Map();
+    }
+    return new Map(candidates.map((candidate, index) => [
+        normalizeMemoryText(candidate.content),
+        embedded.vectors[index],
+    ]));
+}
+function findRecordIndex(records, candidate) {
+    const candidateKey = normalizeMemoryText(candidate.content);
+    return records.findIndex((record) => normalizeMemoryText(record.content) === candidateKey);
+}
+function compatibleVectors(vectors, embedded) {
+    return vectors
+        .filter((entry) => entry.modelFingerprint === embedded.modelFingerprint &&
+        entry.dimensions === embedded.dimensions)
+        .map((entry) => ({ memoryId: entry.memoryId, vector: entry.vector }));
+}
+function mergeDuplicateRecord(record, candidate, updatedAt) {
+    const tags = mergeMemoryTags(record.tags, candidate.tags);
+    return tags.length === record.tags.length
+        ? record
+        : Object.freeze({ ...record, tags, updatedAt });
+}
+function createMemoryRecord(params) {
+    return Object.freeze({
+        id: params.id,
+        content: params.candidate.content,
+        tags: params.candidate.tags,
+        provenance: Object.freeze({
+            kind: "passive_response",
+            sourceSessionId: params.context.sessionId,
+            sourceRequestId: params.context.requestId,
+        }),
+        createdAt: params.now,
+        updatedAt: params.now,
+    });
+}

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

@@ -0,0 +1,8 @@
+import type { LongTermMemoryRecord, MemoryCandidate } from "./contracts.js";
+export type PreparedMemoryCandidates = Readonly<{
+    candidates: readonly MemoryCandidate[];
+    rejectedCount: number;
+    duplicateCount: number;
+}>;
+export declare function prepareMemoryCandidates(candidates: readonly MemoryCandidate[]): PreparedMemoryCandidates;
+export declare function indexMemoryRecordsByContent(records: readonly LongTermMemoryRecord[]): ReadonlyMap<string, LongTermMemoryRecord>;

package/dist/src/runtime/long-term-memory/candidate-preparation.js

@@ -0,0 +1,36 @@
+import { mergeMemoryTags, normalizeMemoryCandidate, normalizeMemoryText, } from "./policies/normalization.js";
+import { containsSensitiveMemoryCandidateData } from "./policies/sensitive-data.js";
+export function prepareMemoryCandidates(candidates) {
+    const byContent = new Map();
+    let rejectedCount = 0;
+    let duplicateCount = 0;
+    for (const rawCandidate of candidates) {
+        const candidate = normalizeMemoryCandidate(rawCandidate);
+        if (shouldRejectCandidate(candidate)) {
+            rejectedCount += 1;
+            continue;
+        }
+        const key = normalizeMemoryText(candidate.content);
+        const duplicate = byContent.get(key);
+        if (!duplicate) {
+            byContent.set(key, candidate);
+            continue;
+        }
+        duplicateCount += 1;
+        byContent.set(key, Object.freeze({
+            content: duplicate.content,
+            tags: mergeMemoryTags(duplicate.tags, candidate.tags),
+        }));
+    }
+    return Object.freeze({
+        candidates: Object.freeze([...byContent.values()]),
+        rejectedCount,
+        duplicateCount,
+    });
+}
+export function indexMemoryRecordsByContent(records) {
+    return new Map(records.map((record) => [normalizeMemoryText(record.content), record]));
+}
+function shouldRejectCandidate(candidate) {
+    return !candidate || containsSensitiveMemoryCandidateData(candidate);
+}

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

@@ -0,0 +1,9 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository, LongTermMemoryRequestContext, MemoryCandidate, MemoryCandidateProcessingResult } from "./contracts.js";
+export declare function processMemoryCandidates(params: {
+    repository: LongTermMemoryRepository;
+    embeddings: LongTermMemoryEmbeddingClient;
+    candidates: readonly MemoryCandidate[];
+    context: LongTermMemoryRequestContext;
+    now?: () => Date;
+    createId?: () => string;
+}): Promise<MemoryCandidateProcessingResult>;

package/dist/src/runtime/long-term-memory/candidate-processing.js

@@ -0,0 +1,79 @@
+import { classifyMemoryFailure, traceLongTermMemoryOperation, } from "./diagnostics.js";
+import { indexMemoryRecordsByContent, prepareMemoryCandidates, } from "./candidate-preparation.js";
+import { embedLongTermMemoryTexts } from "./embedding-batches.js";
+import { normalizeMemoryText } from "./policies/normalization.js";
+import { persistMemoryCandidates } from "./candidate-persistence.js";
+export async function processMemoryCandidates(params) {
+    const startedAt = Date.now();
+    try {
+        params.context.abortSignal.throwIfAborted();
+        const prepared = prepareMemoryCandidates(params.candidates);
+        if (prepared.candidates.length === 0) {
+            return completeCandidateProcessing(params, startedAt, {
+                proposedCount: params.candidates.length,
+                acceptedCount: 0,
+                rejectedCount: prepared.rejectedCount,
+                duplicateCount: prepared.duplicateCount,
+            });
+        }
+        const snapshot = await params.repository.read();
+        const existingByContent = indexMemoryRecordsByContent(snapshot.records);
+        const fresh = prepared.candidates.filter((candidate) => !existingByContent.has(normalizeMemoryText(candidate.content)));
+        const embedded = fresh.length
+            ? await embedLongTermMemoryTexts({
+                embeddings: params.embeddings,
+                texts: fresh.map(({ content }) => content),
+                abortSignal: params.context.abortSignal,
+                debugRequestId: params.context.requestId,
+            })
+            : undefined;
+        params.context.abortSignal.throwIfAborted();
+        const persisted = await persistMemoryCandidates({
+            ...params,
+            preparedCandidates: prepared.candidates,
+            freshCandidates: fresh,
+            embedded,
+        });
+        return completeCandidateProcessing(params, startedAt, {
+            proposedCount: params.candidates.length,
+            acceptedCount: persisted.acceptedCount,
+            rejectedCount: prepared.rejectedCount,
+            duplicateCount: prepared.duplicateCount + persisted.duplicateCount,
+        });
+    }
+    catch (error) {
+        if (params.context.abortSignal.aborted) {
+            throw error;
+        }
+        return failCandidateProcessing(params, startedAt, classifyMemoryFailure(error));
+    }
+}
+function completeCandidateProcessing(params, startedAt, counts) {
+    const durationMs = Date.now() - startedAt;
+    traceLongTermMemoryOperation({
+        operation: "save",
+        outcome: "completed",
+        requestId: params.context.requestId,
+        durationMs,
+        counts,
+    });
+    return Object.freeze({ available: true, ...counts });
+}
+function failCandidateProcessing(params, startedAt, reason) {
+    const durationMs = Date.now() - startedAt;
+    traceLongTermMemoryOperation({
+        operation: "save",
+        outcome: "failed",
+        requestId: params.context.requestId,
+        durationMs,
+        reason,
+    });
+    return Object.freeze({
+        available: false,
+        proposedCount: params.candidates.length,
+        acceptedCount: 0,
+        rejectedCount: params.candidates.length,
+        duplicateCount: 0,
+        reason,
+    });
+}

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

@@ -0,0 +1,108 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { LongTermMemoryManagementService } from "./management/contracts.js";
+export type { LongTermMemoryManagementContext, LongTermMemoryManagementErrorCode, LongTermMemoryManagementService, MemoryCreateInput, MemoryCreateResult, MemoryDeleteInput, MemoryDeleteResult, MemoryListInput, MemoryListResult, MemoryManagementSource, MemorySearchInput, MemorySearchResult, MemoryUpdateInput, MemoryUpdateResult, } from "./management/contracts.js";
+export type MemoryCandidate = Readonly<{
+    content: string;
+    tags: readonly string[];
+}>;
+export type RootAuthoredResponse = Readonly<{
+    finalResponse: string;
+    memoryCandidates: readonly MemoryCandidate[];
+}>;
+export type LongTermMemoryProvenance = Readonly<{
+    kind: "passive_response";
+    sourceSessionId: string;
+    sourceRequestId: string;
+}> | Readonly<{
+    kind: "manual";
+    source: "web_ui" | "management_api";
+}>;
+export type LongTermMemoryRecord = Readonly<{
+    id: string;
+    content: string;
+    tags: readonly string[];
+    provenance: LongTermMemoryProvenance;
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type MemoryVectorIndexEntry = Readonly<{
+    memoryId: string;
+    modelFingerprint: string;
+    dimensions: number;
+    vector: readonly number[];
+}>;
+export type LongTermMemoryRepositorySnapshot = Readonly<{
+    schemaVersion: 1;
+    revision: number;
+    records: readonly LongTermMemoryRecord[];
+    vectors: readonly MemoryVectorIndexEntry[];
+}>;
+export type LongTermMemoryRepositoryState = Pick<LongTermMemoryRepositorySnapshot, "records" | "vectors">;
+export type LongTermMemoryRepository = Readonly<{
+    read(): Promise<LongTermMemoryRepositorySnapshot>;
+    update(mutate: (current: LongTermMemoryRepositorySnapshot) => LongTermMemoryRepositoryState): Promise<LongTermMemoryRepositorySnapshot>;
+}>;
+export type LongTermMemoryEmbeddingResult = Readonly<{
+    modelFingerprint: string;
+    dimensions: number;
+    vectors: readonly (readonly number[])[];
+}>;
+export type LongTermMemoryEmbeddingClient = Readonly<{
+    /** Provider-facing maximum for one embedding request. */
+    maxBatchSize?: number;
+    embed(input: Readonly<{
+        texts: readonly string[];
+        abortSignal: AbortSignal;
+        debugRequestId?: string;
+    }>): Promise<LongTermMemoryEmbeddingResult>;
+}>;
+export type LongTermMemoryStatus = Readonly<{
+    enabled: boolean;
+    available: boolean;
+    recordCount: number;
+    indexedRecordCount: number;
+    reason?: string;
+}>;
+export type MemoryClearResult = Readonly<{
+    deletedCount: number;
+}>;
+export type LongTermMemoryRetrieval = Readonly<{
+    available: boolean;
+    records: readonly LongTermMemoryRecord[];
+    message?: ChatMessage;
+    reason?: string;
+}>;
+export type MemoryCandidateProcessingResult = Readonly<{
+    available: boolean;
+    proposedCount: number;
+    acceptedCount: number;
+    rejectedCount: number;
+    duplicateCount: number;
+    reason?: string;
+}>;
+export type LongTermMemoryRequestContext = Readonly<{
+    requestId: string;
+    sessionId: string;
+    abortSignal: AbortSignal;
+    onEvent?: (name: string, extra?: Record<string, unknown>) => void;
+}>;
+export type LongTermMemoryService = Readonly<{
+    enabled: boolean;
+    retrieve(input: Readonly<{
+        query: string;
+        context: LongTermMemoryRequestContext;
+    }>): Promise<LongTermMemoryRetrieval>;
+    processCandidates(input: Readonly<{
+        candidates: readonly MemoryCandidate[];
+        context: LongTermMemoryRequestContext;
+    }>): Promise<MemoryCandidateProcessingResult>;
+    scheduleCandidates(input: Readonly<{
+        candidates: readonly MemoryCandidate[];
+        context: Readonly<{
+            requestId: string;
+            sessionId: string;
+            onEvent?: LongTermMemoryRequestContext["onEvent"];
+        }>;
+    }>): void;
+    clear(): Promise<MemoryClearResult>;
+}> & LongTermMemoryManagementService;

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

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

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

@@ -0,0 +1,9 @@
+export declare function traceLongTermMemoryOperation(params: {
+    operation: "retrieval" | "save";
+    outcome: "completed" | "failed" | "skipped";
+    requestId: string;
+    durationMs: number;
+    counts?: Record<string, number>;
+    reason?: string;
+}): void;
+export declare function classifyMemoryFailure(error: unknown): string;

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

@@ -0,0 +1,42 @@
+import { traceDebug } from "../observability/debug-logger.js";
+const SAFE_MEMORY_FAILURE_CODES = new Set([
+    "long_term_memory_embedding_binding_changed",
+    "long_term_memory_embedding_client_required",
+    "long_term_memory_embedding_gateway_unavailable",
+    "long_term_memory_embedding_profile_id_invalid",
+    "long_term_memory_embedding_profile_required",
+    "long_term_memory_embedding_vector_count_invalid",
+    "long_term_memory_model_policy_required",
+    "long_term_memory_store_corrupt",
+    "long_term_memory_store_lock_timeout",
+    "long_term_memory_store_schema_unsupported",
+    "long_term_memory_vector_corrupt",
+    "memory_store_unavailable",
+    "model_gateway_embedding_binding_invalid",
+    "model_gateway_embedding_dimensions_inconsistent",
+    "model_gateway_embedding_dimensions_invalid",
+    "model_gateway_embedding_profile_mismatch",
+    "model_gateway_embedding_request_invalid",
+    "model_gateway_embedding_response_invalid",
+    "model_gateway_embedding_vector_count_invalid",
+    "model_gateway_embedding_vector_empty",
+    "model_gateway_embedding_vector_invalid",
+    "model_gateway_embedding_vector_non_finite",
+]);
+const GENERIC_MEMORY_FAILURE_CODE = "long_term_memory_unavailable";
+export function traceLongTermMemoryOperation(params) {
+    traceDebug("runtime.long_term_memory", `${params.operation}.${params.outcome}`, {
+        requestId: params.requestId,
+        operation: params.operation,
+        outcome: params.outcome,
+        durationMs: params.durationMs,
+        ...(params.counts ?? {}),
+        ...(params.reason ? { reason: params.reason } : {}),
+    });
+}
+export function classifyMemoryFailure(error) {
+    const errorCode = error instanceof Error ? error.message : "";
+    return SAFE_MEMORY_FAILURE_CODES.has(errorCode)
+        ? errorCode
+        : GENERIC_MEMORY_FAILURE_CODE;
+}

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

@@ -0,0 +1,13 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryEmbeddingResult } from "./contracts.js";
+type ExpectedEmbeddingBinding = Readonly<{
+    modelFingerprint: string;
+    dimensions: number;
+}>;
+export declare function embedLongTermMemoryTexts(params: {
+    embeddings: LongTermMemoryEmbeddingClient;
+    texts: readonly string[];
+    abortSignal: AbortSignal;
+    debugRequestId?: string;
+    expectedBinding?: ExpectedEmbeddingBinding;
+}): Promise<LongTermMemoryEmbeddingResult>;
+export {};

package/dist/src/runtime/long-term-memory/embedding-batches.js

@@ -0,0 +1,87 @@
+export async function embedLongTermMemoryTexts(params) {
+    if (params.texts.length === 0) {
+        throw new Error("long_term_memory_embedding_input_empty");
+    }
+    const vectors = [];
+    let binding = params.expectedBinding
+        ? validateEmbeddingBinding(params.expectedBinding)
+        : undefined;
+    const batchSize = resolveEmbeddingBatchSize(params.embeddings.maxBatchSize, params.texts.length);
+    for (let offset = 0; offset < params.texts.length; offset += batchSize) {
+        params.abortSignal.throwIfAborted();
+        const texts = params.texts.slice(offset, offset + batchSize);
+        const embedded = validateEmbeddingResult(await params.embeddings.embed({
+            texts,
+            abortSignal: params.abortSignal,
+            ...(params.debugRequestId
+                ? { debugRequestId: params.debugRequestId }
+                : {}),
+        }), texts.length);
+        binding = bindEmbeddingResult(binding, embedded);
+        vectors.push(...embedded.vectors);
+    }
+    if (!binding) {
+        throw new Error("long_term_memory_embedding_input_empty");
+    }
+    return Object.freeze({
+        modelFingerprint: binding.modelFingerprint,
+        dimensions: binding.dimensions,
+        vectors: Object.freeze(vectors),
+    });
+}
+function resolveEmbeddingBatchSize(configuredLimit, textCount) {
+    const validLimit = Number.isSafeInteger(configuredLimit) && Number(configuredLimit) > 0;
+    return validLimit ? Math.min(Number(configuredLimit), textCount) : textCount;
+}
+function bindEmbeddingResult(expected, actual) {
+    if (!expected) {
+        return Object.freeze({
+            modelFingerprint: actual.modelFingerprint,
+            dimensions: actual.dimensions,
+        });
+    }
+    const bindingChanged = actual.modelFingerprint !== expected.modelFingerprint ||
+        actual.dimensions !== expected.dimensions;
+    if (bindingChanged) {
+        throw new Error("long_term_memory_embedding_binding_changed");
+    }
+    return expected;
+}
+function validateEmbeddingResult(result, expectedCount) {
+    const binding = validateEmbeddingBinding(result);
+    if (!Array.isArray(result.vectors) ||
+        result.vectors.length !== expectedCount) {
+        throw new Error("long_term_memory_embedding_vector_count_invalid");
+    }
+    const vectors = result.vectors.map((vector) => validateEmbeddingVector(vector, binding.dimensions));
+    return Object.freeze({
+        ...binding,
+        vectors: Object.freeze(vectors),
+    });
+}
+function validateEmbeddingBinding(result) {
+    const validFingerprint = typeof result.modelFingerprint === "string" &&
+        result.modelFingerprint.trim().length > 0;
+    const validDimensions = Number.isSafeInteger(result.dimensions) && result.dimensions > 0;
+    if (!validFingerprint || !validDimensions) {
+        throw new Error("long_term_memory_embedding_response_invalid");
+    }
+    return Object.freeze({
+        modelFingerprint: result.modelFingerprint,
+        dimensions: result.dimensions,
+    });
+}
+function validateEmbeddingVector(vector, expectedDimensions) {
+    if (!Array.isArray(vector) || vector.length !== expectedDimensions) {
+        throw new Error("long_term_memory_embedding_response_invalid");
+    }
+    const validated = [];
+    for (let index = 0; index < vector.length; index += 1) {
+        const component = vector[index];
+        if (typeof component !== "number" || !Number.isFinite(component)) {
+            throw new Error("long_term_memory_embedding_response_invalid");
+        }
+        validated.push(component);
+    }
+    return Object.freeze(validated);
+}

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

@@ -0,0 +1,13 @@
+import type { LongTermMemoryRequestContext } from "./contracts.js";
+export declare const LONG_TERM_MEMORY_EVENTS: Readonly<{
+    RETRIEVAL_STARTED: "memory.retrieval.started";
+    RETRIEVAL_COMPLETED: "memory.retrieval.completed";
+    RETRIEVAL_FAILED: "memory.retrieval.failed";
+    SAVE_QUEUED: "memory.save.queued";
+}>;
+export declare function emitLongTermMemoryEvent(params: {
+    enabled: boolean;
+    context: Pick<LongTermMemoryRequestContext, "onEvent">;
+    name: (typeof LONG_TERM_MEMORY_EVENTS)[keyof typeof LONG_TERM_MEMORY_EVENTS];
+    details?: Record<string, unknown>;
+}): void;