@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/passive-learning/batch-receipt.d.ts

@@ -0,0 +1,15 @@
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+import type { ObservationMemoryReceipt } from "../long-term-memory/observation-contracts.js";
+import type { LearningBatch } from "./contracts.js";
+import type { LearningActiveBatches } from "./active-batches.js";
+import type { LearningJournal } from "./journal.js";
+export declare function resolveReviewedBatchStatus(records: readonly string[], candidates: readonly string[]): LearningBatch["status"];
+/** Receipts are commit authority across both the current and legacy memory stores. */
+export declare function readLearningBatchReceipt(memory: LongTermMemoryService, batchId: string): Promise<ObservationMemoryReceipt | undefined>;
+/** Local bookkeeping must not depend on model budgets, windows, or app eligibility. */
+export declare function reconcileLearningBatchReceipts(options: {
+    journal: LearningJournal;
+    active: LearningActiveBatches;
+    memory: LongTermMemoryService;
+    generation(): string;
+}): Promise<void>;

package/dist/src/runtime/passive-learning/batch-receipt.js

@@ -0,0 +1,34 @@
+import { isPendingLearningBatch } from "./batch-lifecycle.js";
+import { traceDebug } from "../observability/debug-logger.js";
+export function resolveReviewedBatchStatus(records, candidates) {
+    if (records.length)
+        return "saved";
+    if (candidates.length)
+        return "reviewed";
+    return "discarded";
+}
+/** Receipts are commit authority across both the current and legacy memory stores. */
+export async function readLearningBatchReceipt(memory, batchId) {
+    return await memory.learning?.receipt(batchId) ?? await memory.observationBatchReceipt?.(batchId);
+}
+/** Local bookkeeping must not depend on model budgets, windows, or app eligibility. */
+export async function reconcileLearningBatchReceipts(options) {
+    const canReconcileBatch = (batch) => {
+        if (!isPendingLearningBatch(batch) || options.active.has(batch.id))
+            return false;
+        if (batch.generation !== options.generation())
+            return false;
+        return options.journal.items.includes(batch);
+    };
+    for (const batch of options.journal.items) {
+        if (!canReconcileBatch(batch))
+            continue;
+        const receipt = await readLearningBatchReceipt(options.memory, batch.id);
+        if (!receipt || !canReconcileBatch(batch))
+            continue;
+        await options.journal.replace({ ...batch, status: resolveReviewedBatchStatus(receipt.recordIds, receipt.candidateIds ?? []),
+            recordIds: receipt.recordIds, candidateIds: receipt.candidateIds ?? [], reason: undefined, completedAt: receipt.createdAt });
+        traceDebug("runtime.passive_learning", "batch.receipt_reconciled", { batchId: batch.id,
+            saved: receipt.recordIds.length, candidates: receipt.candidateIds?.length ?? 0 });
+    }
+}

package/dist/src/runtime/passive-learning/collection-source.d.ts

@@ -0,0 +1,24 @@
+import type { HostObservationEvent } from "../../shared/passive-observation.js";
+import type { PassiveLearningConnection } from "./contracts.js";
+/** A collection lease is independent from the lifetime of queued analysis. */
+export declare class LearningCollectionSource {
+    private readonly options;
+    private abort;
+    private connection;
+    private leaseId;
+    private reconnectTimer;
+    private reconnectDelay;
+    constructor(options: Readonly<{
+        ownerId: string;
+        connect?: PassiveLearningConnection;
+        enabled(): boolean;
+        excludedApplications(): readonly string[];
+        opening(): void;
+        event(event: HostObservationEvent): void;
+        failed(error: unknown): void;
+    }>);
+    open(): Promise<void>;
+    accepts(event: HostObservationEvent): boolean;
+    close(): void;
+    private reconnect;
+}

package/dist/src/runtime/passive-learning/collection-source.js

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+function shouldReconnectCollectionSource(event) {
+    if (event.type !== "status")
+        return false;
+    if (event.state === "disconnected")
+        return true;
+    if (event.state === "failed")
+        return true;
+    if (event.state !== "unavailable")
+        return false;
+    if (event.reason === "collector_stopped")
+        return true;
+    return event.reason === "collector_start_failed";
+}
+function hasHealthyCollectionEvent(event) {
+    if (event.type === "observation")
+        return true;
+    return event.state === "collecting" || event.state === "partial";
+}
+/** A collection lease is independent from the lifetime of queued analysis. */
+export class LearningCollectionSource {
+    options;
+    abort;
+    connection;
+    leaseId = "";
+    reconnectTimer;
+    reconnectDelay = 5_000;
+    constructor(options) {
+        this.options = options;
+    }
+    async open() {
+        this.close();
+        if (!this.options.enabled())
+            return;
+        this.leaseId = randomUUID();
+        const abort = new AbortController();
+        this.abort = abort;
+        this.options.opening();
+        if (!this.options.connect) {
+            this.options.failed(new Error("learning_host_unavailable"));
+            return;
+        }
+        try {
+            const connection = await this.options.connect({
+                ownerId: this.options.ownerId,
+                leaseId: this.leaseId,
+                abortSignal: abort.signal,
+                excludedApplications: this.options.excludedApplications(),
+                onEvent: (event) => {
+                    if (this.abort !== abort || !this.accepts(event))
+                        return;
+                    if (shouldReconnectCollectionSource(event))
+                        this.reconnect();
+                    if (hasHealthyCollectionEvent(event))
+                        this.reconnectDelay = 5_000;
+                    this.options.event(event);
+                },
+            });
+            if (abort.signal.aborted) {
+                connection.close();
+                return;
+            }
+            this.connection = connection;
+        }
+        catch (error) {
+            if (abort.signal.aborted)
+                return;
+            this.options.failed(error);
+            this.reconnect();
+        }
+    }
+    accepts(event) {
+        if (!this.options.enabled() || !this.abort || this.abort.signal.aborted)
+            return false;
+        return (event.ownerId === this.options.ownerId && event.leaseId === this.leaseId);
+    }
+    close() {
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        this.abort?.abort();
+        this.connection?.close();
+        this.connection = undefined;
+        this.abort = undefined;
+    }
+    reconnect() {
+        if (!this.options.enabled() || this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            void this.open().catch(this.options.failed);
+        }, this.reconnectDelay);
+        this.reconnectDelay = Math.min(30_000, this.reconnectDelay * 2);
+        this.reconnectTimer.unref?.();
+    }
+}

package/dist/src/runtime/passive-learning/collection-window-clock.d.ts

@@ -0,0 +1,21 @@
+import type { LearningAnalysisWindow } from "./contracts.js";
+export declare function nextCollectionWindowBoundary(now: number, window?: LearningAnalysisWindow | null): number | undefined;
+/** A single native lease follows actual window transitions even without observations. */
+export declare class CollectionWindowClock {
+    private readonly options;
+    private timer;
+    private opened;
+    scheduledAt: number | undefined;
+    constructor(options: Readonly<{
+        enabled(): boolean;
+        window(): LearningAnalysisWindow | null | undefined;
+        now(): number;
+        open(): Promise<void>;
+        close(): void;
+        boundary(): void;
+    }>);
+    synchronize(forceReconnect?: boolean): Promise<void>;
+    stop(): void;
+    private close;
+    private clearTimer;
+}

package/dist/src/runtime/passive-learning/collection-window-clock.js

@@ -0,0 +1,55 @@
+import { nextSchedulerOccurrence } from "../scheduler/next-occurrence.js";
+import { isWithinAnalysisWindow } from "./analysis-schedule.js";
+export function nextCollectionWindowBoundary(now, window) {
+    if (!window || window.start === window.end)
+        return undefined;
+    const next = [window.start, window.end].flatMap((at) => {
+        const occurrence = nextSchedulerOccurrence({ kind: "daily", at }, window.timeZone, now);
+        return occurrence ? [Date.parse(occurrence)] : [];
+    });
+    return next.length ? Math.min(...next) : undefined;
+}
+/** A single native lease follows actual window transitions even without observations. */
+export class CollectionWindowClock {
+    options;
+    timer;
+    opened = false;
+    scheduledAt;
+    constructor(options) {
+        this.options = options;
+    }
+    async synchronize(forceReconnect = false) {
+        this.clearTimer();
+        if (!this.options.enabled()) {
+            this.close();
+            return;
+        }
+        const now = this.options.now();
+        const window = this.options.window();
+        this.scheduledAt = nextCollectionWindowBoundary(now, window);
+        if (this.scheduledAt !== undefined) {
+            this.timer = setTimeout(() => {
+                this.timer = undefined;
+                this.scheduledAt = undefined;
+                this.options.boundary();
+            }, Math.max(1, this.scheduledAt - now));
+            this.timer.unref?.();
+        }
+        if (!isWithinAnalysisWindow(now, window)) {
+            this.close();
+            return;
+        }
+        if (this.opened && !forceReconnect)
+            return;
+        this.opened = true;
+        await this.options.open();
+    }
+    stop() { this.clearTimer(); this.close(); }
+    close() { this.opened = false; this.options.close(); }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.scheduledAt = undefined;
+    }
+}

package/dist/src/runtime/passive-learning/contracts.d.ts

@@ -0,0 +1,168 @@
+import type { HostObservationEvent, PassiveObservation, PassiveCollectionState } from "../../shared/passive-observation.js";
+import type { ObservationMemoryProposal } from "../long-term-memory/observation-contracts.js";
+import type { LearningCandidateRecord, LearningKnowledgeContext, LearningMemoryDecision, LearningReviewCause, MaturationPolicy } from "../long-term-memory/maturation/contracts.js";
+import type { CoWorkerResourceLimits, CoWorkerResourceUsage } from "./resources/contracts.js";
+import type { ProactiveProposal } from "./proactive/contracts.js";
+import type { LearningApplicationSummary } from "./application-catalog.js";
+import type { CoWorkerReviewProgress, ReviewProgressPort } from "./review-progress.js";
+export type PassiveLearningPreferences = Readonly<{
+    /** Saved user authorization; activity switches below only control operation. */
+    activityPermissions?: Readonly<{
+        collection: boolean;
+        learning: boolean;
+        proactive: boolean;
+    }>;
+    enabled: boolean;
+    /** Collection and analysis are independently controlled. */
+    processingPaused?: boolean;
+    modelProfileId?: string;
+    excludedApplications: readonly string[];
+    /** Holds pending activity for these applications; collection is independent. */
+    processingExcludedApplications?: readonly string[];
+    analysisIntervalMinutes?: number;
+    analysisTrigger?: "interval" | "observations";
+    analysisObservationCount?: number;
+    analysisWindow?: LearningAnalysisWindow | null;
+    collectionWindow?: LearningAnalysisWindow | null;
+    proactiveEnabled?: boolean;
+    /** Absent inherits the learning model; null explicitly clears an override. */
+    proactiveModelProfileId?: string | null;
+    proactiveIntervalMinutes?: number;
+    proactiveWindow?: LearningAnalysisWindow | null;
+    proactiveMessagesPerDay?: number;
+    maxConcurrentBatches?: number;
+    maturation?: MaturationPolicy;
+    resourceLimits?: CoWorkerResourceLimits;
+}>;
+export type LearningAnalysisWindow = Readonly<{
+    start: string;
+    end: string;
+    timeZone: string;
+}>;
+export type LearningObservation = PassiveObservation & Readonly<{
+    deviceId: string;
+    revisit?: Readonly<{
+        firstObservedAt: string;
+        contentUnchanged: true;
+    }>;
+}>;
+export type LearningBatch = Readonly<{
+    id: string;
+    createdAt: string;
+    generation: string;
+    status: "pending" | "processing" | "saved" | "reviewed" | "discarded" | "failed" | "cancelled";
+    observations: readonly LearningObservation[];
+    recordIds: readonly string[];
+    candidateIds?: readonly string[];
+    reason?: string;
+    completedAt?: string;
+    reviewProgress?: CoWorkerReviewProgress;
+}>;
+export type LearningBatchSummary = Omit<LearningBatch, "observations" | "reviewProgress"> & Readonly<{
+    observationCount: number;
+}>;
+export type PassiveLearningStatus = Readonly<{
+    preferences: PassiveLearningPreferences;
+    state: "off" | PassiveCollectionState;
+    reason?: string;
+    /** Independent collection state; legacy state may also report processing failure. */
+    collectionState?: "off" | PassiveCollectionState;
+    collectionReason?: string;
+    processingReason?: string;
+    deviceId?: string;
+    pendingObservations: number;
+    reviewPassRemaining?: number;
+    /** Retained application-excluded evidence; deletable but not waiting for processing. */
+    blockedObservations?: number;
+    retentionHours?: number;
+    processing: boolean;
+    activeBatches?: number;
+    effectiveConcurrency?: number;
+    nextAnalysisAt?: string;
+    lastObservationAt?: string;
+    lastBatchAt?: string;
+    droppedObservations: number;
+    lastBatch?: LearningBatchSummary;
+    recentMemories: readonly Readonly<{
+        id: string;
+        content: string;
+        createdAt: string;
+    }>[];
+    resourceUsage?: CoWorkerResourceUsage & Readonly<{
+        activeCalls: number;
+    }>;
+    proactive?: ProactiveStatus;
+    nextCollectionAt?: string;
+    maintenanceReason?: string;
+    reassessment?: LearningReassessmentStatus;
+    applications?: readonly LearningApplicationSummary[];
+    applicationsOmitted?: number;
+}>;
+export type LearningReassessmentStatus = Readonly<{
+    state: "off" | "waiting" | "reviewing" | "budget_limited" | "failed";
+    nextReviewAt?: string;
+    reason?: string;
+}>;
+export type ProactiveStatus = Readonly<{
+    state: "off" | "waiting" | "reviewing" | "budget_limited" | "failed";
+    deliveredToday?: number;
+    nextReviewAt?: string;
+    reason?: string;
+    proposals: readonly ProactiveProposal[];
+}>;
+export type LearningChangedEvent = Readonly<{
+    type: "proposal_delivered";
+    proposalId: string;
+    sessionId: string;
+}>;
+export type PassiveLearningModel = Readonly<{
+    validateProfile(profileId: string): void;
+    supportsParallelBatches?(profileId: string): boolean;
+    review?(input: Readonly<{
+        batchId: string;
+        observations: readonly LearningObservation[];
+        modelProfileId: string;
+        signal: AbortSignal;
+        context: LearningKnowledgeContext;
+        promotionScore: number;
+        cause?: LearningReviewCause;
+        progress?: ReviewProgressPort;
+        expiresAt?: string;
+    }>): Promise<readonly LearningMemoryDecision[]>;
+    extract(input: Readonly<{
+        batchId: string;
+        observations: readonly LearningObservation[];
+        modelProfileId: string;
+        signal: AbortSignal;
+    }>): Promise<readonly ObservationMemoryProposal[]>;
+}>;
+export type PassiveLearningConnection = (input: Readonly<{
+    ownerId: string;
+    leaseId: string;
+    abortSignal: AbortSignal;
+    excludedApplications: readonly string[];
+    onEvent(event: HostObservationEvent): void;
+}>) => Promise<Readonly<{
+    close(): void;
+}>>;
+export type PassiveLearningService = Readonly<{
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    configure(input: Partial<PassiveLearningPreferences>): Promise<PassiveLearningStatus>;
+    status(): Promise<PassiveLearningStatus>;
+    clearPending(): Promise<PassiveLearningStatus>;
+    /** Recheck a permission-blocked collector without changing preferences or queued work. */
+    restartCollection?(): Promise<PassiveLearningStatus>;
+    batches(input?: Readonly<{
+        limit?: number;
+    }>): Promise<readonly LearningBatchSummary[]>;
+    batch(id: string): Promise<LearningBatch | undefined>;
+    accept(event: HostObservationEvent): void;
+    flush(): Promise<void>;
+    beginInteractive(): () => void;
+    subscribe(listener: (event?: LearningChangedEvent) => void): () => void;
+    dismissProposal?(id: string): Promise<void>;
+    sessionDeleted?(sessionId: string): Promise<void>;
+    notifyKnowledgeChanged?(): void;
+    candidates?(): Promise<readonly Omit<LearningCandidateRecord, "embedding">[]>;
+}>;

package/dist/src/runtime/passive-learning/contracts.js

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

package/dist/src/runtime/passive-learning/control-policy.d.ts

@@ -0,0 +1,9 @@
+import type { PassiveLearningPreferences } from "./contracts.js";
+import type { LearningBackgroundDependencies } from "./background-dependencies.js";
+import type { PassiveCollectionState } from "../../shared/passive-observation.js";
+export declare function canRestartPermissionBlockedCollection(collectionAllowed: boolean, state: "off" | PassiveCollectionState): boolean;
+export declare function requiresLearningAvailability(previous: PassiveLearningPreferences, next: PassiveLearningPreferences, availabilityFailed?: boolean, input?: Partial<PassiveLearningPreferences>): boolean;
+export declare function hasLearningMemoryWriter(background: LearningBackgroundDependencies): boolean;
+export declare function requiresCollectionConnection(previous: PassiveLearningPreferences, next: PassiveLearningPreferences): boolean;
+export declare function hasAnalysisScheduleChanged(previous: PassiveLearningPreferences, next: PassiveLearningPreferences): boolean;
+export declare function hasLearningProcessingConfigurationChanged(previous: PassiveLearningPreferences, next: PassiveLearningPreferences): boolean;

package/dist/src/runtime/passive-learning/control-policy.js

@@ -0,0 +1,52 @@
+export function canRestartPermissionBlockedCollection(collectionAllowed, state) {
+    if (!collectionAllowed)
+        return false;
+    return state === "permission_required";
+}
+export function requiresLearningAvailability(previous, next, availabilityFailed = false, input = {}) {
+    if (next.processingPaused)
+        return false;
+    if (!next.modelProfileId)
+        return false;
+    if (availabilityFailed && requestsLearningProcessingUpdate(input))
+        return true;
+    if (previous.processingPaused)
+        return true;
+    return next.modelProfileId !== previous.modelProfileId;
+}
+function requestsLearningProcessingUpdate(input) {
+    const keys = ["processingPaused", "modelProfileId", "analysisIntervalMinutes", "analysisWindow",
+        "analysisTrigger", "analysisObservationCount",
+        "maxConcurrentBatches", "processingExcludedApplications", "maturation", "resourceLimits"];
+    return keys.some((key) => input[key] !== undefined);
+}
+export function hasLearningMemoryWriter(background) {
+    if (background.memory.learning && background.model.review)
+        return true;
+    return typeof background.memory.saveObservationBatch === "function";
+}
+export function requiresCollectionConnection(previous, next) {
+    if (!next.enabled)
+        return false;
+    if (!previous.enabled)
+        return true;
+    return (JSON.stringify(previous.excludedApplications) !==
+        JSON.stringify(next.excludedApplications));
+}
+export function hasAnalysisScheduleChanged(previous, next) {
+    if (previous.analysisTrigger !== next.analysisTrigger)
+        return true;
+    if (previous.analysisObservationCount !== next.analysisObservationCount)
+        return true;
+    if (previous.analysisIntervalMinutes !== next.analysisIntervalMinutes)
+        return true;
+    return (JSON.stringify(previous.analysisWindow) !==
+        JSON.stringify(next.analysisWindow));
+}
+export function hasLearningProcessingConfigurationChanged(previous, next) {
+    if (hasAnalysisScheduleChanged(previous, next))
+        return true;
+    const keys = ["modelProfileId", "processingPaused", "maxConcurrentBatches",
+        "processingExcludedApplications", "resourceLimits", "maturation"];
+    return keys.some((key) => JSON.stringify(previous[key]) !== JSON.stringify(next[key]));
+}

package/dist/src/runtime/passive-learning/independent-preferences.d.ts

@@ -0,0 +1,2 @@
+import type { PassiveLearningPreferences } from "./contracts.js";
+export declare function normalizeIndependentLearningPreferences(input: Partial<PassiveLearningPreferences>, previous: PassiveLearningPreferences): Pick<PassiveLearningPreferences, "collectionWindow" | "proactiveEnabled" | "proactiveModelProfileId" | "proactiveIntervalMinutes" | "proactiveWindow" | "proactiveMessagesPerDay">;

package/dist/src/runtime/passive-learning/independent-preferences.js

@@ -0,0 +1,39 @@
+import { validateWindow } from "./analysis-schedule.js";
+export function normalizeIndependentLearningPreferences(input, previous) {
+    if (input.proactiveEnabled !== undefined && typeof input.proactiveEnabled !== "boolean")
+        throw new Error("invalid_learning_preferences");
+    const profile = input.proactiveModelProfileId === undefined ? previous.proactiveModelProfileId : input.proactiveModelProfileId;
+    if (profile != null && !isLearningProfileId(profile))
+        throw new Error("invalid_learning_model_profile");
+    const collectionWindow = input.collectionWindow === undefined ? previous.collectionWindow ?? null : input.collectionWindow;
+    const proactiveWindow = input.proactiveWindow === undefined ? previous.proactiveWindow ?? null : input.proactiveWindow;
+    validateWindow(collectionWindow);
+    validateWindow(proactiveWindow);
+    const proactiveIntervalMinutes = input.proactiveIntervalMinutes ?? previous.proactiveIntervalMinutes ?? 60;
+    const proactiveMessagesPerDay = input.proactiveMessagesPerDay ?? previous.proactiveMessagesPerDay ?? 2;
+    if (!isBoundedPositiveInteger(proactiveIntervalMinutes, 1440))
+        throw new Error("invalid_learning_preferences");
+    if (!isBoundedPositiveInteger(proactiveMessagesPerDay, 100))
+        throw new Error("invalid_learning_preferences");
+    return {
+        collectionWindow: collectionWindow ? Object.freeze({ ...collectionWindow }) : null,
+        proactiveWindow: proactiveWindow ? Object.freeze({ ...proactiveWindow }) : null,
+        proactiveEnabled: input.proactiveEnabled ?? previous.proactiveEnabled ?? false,
+        ...(profile ? { proactiveModelProfileId: profile.trim() } : {}),
+        proactiveIntervalMinutes, proactiveMessagesPerDay,
+    };
+}
+function isLearningProfileId(value) {
+    if (typeof value !== "string")
+        return false;
+    if (!value.trim())
+        return false;
+    return value.length <= 128;
+}
+function isBoundedPositiveInteger(value, maximum) {
+    if (typeof value !== "number")
+        return false;
+    if (!Number.isInteger(value))
+        return false;
+    return value >= 1 && value <= maximum;
+}

package/dist/src/runtime/passive-learning/journal.d.ts

@@ -0,0 +1,37 @@
+import type { LearningBatch, PassiveLearningPreferences } from "./contracts.js";
+import type { ObservationMemoryReceipt } from "../long-term-memory/observation-contracts.js";
+/** Bounded intake/debug journal; canonical learned records belong to long-term memory. */
+export declare class LearningJournal {
+    private readonly options;
+    private readonly store;
+    private committedPreferences;
+    private history;
+    observationReviewPass: readonly string[] | undefined;
+    private writes;
+    private expiryTimer;
+    private retryTimer;
+    private retryDelay;
+    private running;
+    storageAvailable: boolean;
+    constructor(options: Readonly<{
+        directory: string;
+        now(): number;
+        preferences(): PassiveLearningPreferences;
+        changed(): void;
+        failed(error: unknown): void;
+        receipt?(batchId: string): Promise<ObservationMemoryReceipt | undefined>;
+    }>);
+    get items(): readonly LearningBatch[];
+    load(generation?: string): Promise<PassiveLearningPreferences>;
+    start(): Promise<void>;
+    stop(): void;
+    replace(batch: LearningBatch): Promise<void>;
+    replaceMany(batches: readonly LearningBatch[]): Promise<void>;
+    partition(parts: readonly LearningBatch[]): Promise<boolean>;
+    clearPending(): Promise<void>;
+    persist(preferences?: PassiveLearningPreferences): Promise<void>;
+    private clearPersistenceRetry;
+    setObservationReviewPass(keys: readonly string[]): Promise<void>;
+    private retryPersistence;
+    private prune;
+}