@abot-ai/runtime 1.0.0 → 1.1.0

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;

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>;