@agent-assistant/proactive 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { RoutingHint, SuppressionReason, FollowUpAction, ReminderPolicy, EvidenceEntry, FollowUpEvaluationContext, FollowUpRule, FollowUpDecision, WatchAction, WatchEvaluationContext, WatchRule, WatchTrigger, WatchRuleStatus, WatchRuleLifecycleStatus, WakeUpContext, SchedulerBinding, FollowUpEvidenceSource, ProactiveEngineConfig, ProactiveEngine, } from './types.js';
+export { ProactiveError, RuleNotFoundError, SchedulerBindingError, } from './types.js';
+export { createProactiveEngine, InMemorySchedulerBinding } from './proactive.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ProactiveError, RuleNotFoundError, SchedulerBindingError, } from './types.js';
+export { createProactiveEngine, InMemorySchedulerBinding } from './proactive.js';

package/dist/proactive.d.ts

@@ -0,0 +1,15 @@
+import type { ProactiveEngine, ProactiveEngineConfig, SchedulerBinding, WakeUpContext } from './types.js';
+export declare class InMemorySchedulerBinding implements SchedulerBinding {
+    readonly pendingWakeUps: Map<string, {
+        at: Date;
+        context: WakeUpContext;
+    }>;
+    requestWakeUp(at: Date, context: WakeUpContext): Promise<string>;
+    cancelWakeUp(bindingId: string): Promise<void>;
+    /**
+     * Test helper: manually fire a pending wake-up.
+     * Returns the WakeUpContext and removes it from pending.
+     */
+    trigger(bindingId: string): Promise<WakeUpContext>;
+}
+export declare function createProactiveEngine(config: ProactiveEngineConfig): ProactiveEngine;

package/dist/proactive.js

@@ -0,0 +1,285 @@
+import { nanoid } from 'nanoid';
+import { RuleNotFoundError, SchedulerBindingError, } from './types.js';
+// ─── Default policy ───────────────────────────────────────────────────────────
+const POLICY_DEFAULTS = {
+    maxReminders: 3,
+    cooldownMs: 3_600_000, // 1 hour
+    suppressWhenActive: true,
+};
+function mergePolicy(base, override) {
+    if (!override)
+        return base;
+    return {
+        maxReminders: override.maxReminders ?? base.maxReminders,
+        cooldownMs: override.cooldownMs ?? base.cooldownMs,
+        suppressWhenActive: override.suppressWhenActive ?? base.suppressWhenActive,
+    };
+}
+// ─── Suppression logic ────────────────────────────────────────────────────────
+function applySuppression(context, policy, state, now) {
+    // 1. user_active: user became active after the wake-up was scheduled
+    if (policy.suppressWhenActive &&
+        new Date(context.lastActivityAt) > new Date(context.scheduledAt)) {
+        return { suppressed: true, reason: 'user_active' };
+    }
+    // 2. max_reminders: reminder count for this (sessionId, ruleId) has reached maxReminders
+    if (state.reminderCount >= policy.maxReminders) {
+        return { suppressed: true, reason: 'max_reminders' };
+    }
+    // 3. cooldown: not enough time since last reminder
+    if (state.lastReminderSentAt !== null &&
+        now.getTime() - new Date(state.lastReminderSentAt).getTime() < policy.cooldownMs) {
+        return { suppressed: true, reason: 'cooldown' };
+    }
+    return { suppressed: false };
+}
+// ─── InMemorySchedulerBinding ─────────────────────────────────────────────────
+export class InMemorySchedulerBinding {
+    pendingWakeUps = new Map();
+    async requestWakeUp(at, context) {
+        const bindingId = nanoid();
+        this.pendingWakeUps.set(bindingId, { at, context });
+        return bindingId;
+    }
+    async cancelWakeUp(bindingId) {
+        this.pendingWakeUps.delete(bindingId);
+    }
+    /**
+     * Test helper: manually fire a pending wake-up.
+     * Returns the WakeUpContext and removes it from pending.
+     */
+    async trigger(bindingId) {
+        const entry = this.pendingWakeUps.get(bindingId);
+        if (!entry) {
+            throw new Error(`No pending wake-up for bindingId: ${bindingId}`);
+        }
+        this.pendingWakeUps.delete(bindingId);
+        return entry.context;
+    }
+}
+// ─── ProactiveEngine factory ──────────────────────────────────────────────────
+export function createProactiveEngine(config) {
+    const { schedulerBinding, evidenceSource } = config;
+    const defaultPolicy = mergePolicy(POLICY_DEFAULTS, config.defaultReminderPolicy);
+    // Follow-up state
+    const followUpRules = new Map();
+    const reminderStates = new Map();
+    // Watch rule state
+    const watchRuleRecords = new Map();
+    // ── Helpers ──────────────────────────────────────────────────────────────────
+    function reminderKey(sessionId, ruleId) {
+        return `${sessionId}:${ruleId}`;
+    }
+    function getReminderState(sessionId, ruleId) {
+        return (reminderStates.get(reminderKey(sessionId, ruleId)) ?? {
+            reminderCount: 0,
+            lastReminderSentAt: null,
+        });
+    }
+    async function scheduleWatchWakeUp(record, metadata) {
+        const nextAt = new Date(Date.now() + record.rule.intervalMs);
+        try {
+            const bindingId = await schedulerBinding.requestWakeUp(nextAt, {
+                sessionId: metadata?.['sessionId'] ?? '_watch',
+                ruleId: record.rule.id,
+                scheduledAt: nextAt.toISOString(),
+                metadata,
+            });
+            return bindingId;
+        }
+        catch (err) {
+            throw new SchedulerBindingError(`Failed to schedule wake-up for watch rule: ${record.rule.id}`, err);
+        }
+    }
+    // ── Follow-up rule methods ────────────────────────────────────────────────────
+    function registerFollowUpRule(rule) {
+        followUpRules.set(rule.id, rule);
+    }
+    function removeFollowUpRule(ruleId) {
+        if (!followUpRules.has(ruleId)) {
+            throw new RuleNotFoundError(ruleId, 'followUp');
+        }
+        followUpRules.delete(ruleId);
+        // Clear all reminder state for this ruleId across all sessions
+        for (const key of reminderStates.keys()) {
+            if (key.endsWith(`:${ruleId}`)) {
+                reminderStates.delete(key);
+            }
+        }
+    }
+    function listFollowUpRules() {
+        return Array.from(followUpRules.values());
+    }
+    async function evaluateFollowUp(context) {
+        // Fetch evidence once for this entire evaluation pass (Decision 3)
+        let evidence;
+        if (context.evidence !== undefined) {
+            evidence = context.evidence;
+        }
+        else if (evidenceSource) {
+            evidence = await evidenceSource.getRecentEntries(context.sessionId);
+        }
+        else {
+            evidence = [];
+        }
+        const now = new Date();
+        const decisions = [];
+        for (const rule of followUpRules.values()) {
+            const policy = mergePolicy(defaultPolicy, rule.policy);
+            const state = getReminderState(context.sessionId, rule.id);
+            const suppression = applySuppression(context, policy, state, now);
+            const routingHint = rule.routingHint ?? 'cheap';
+            if (suppression.suppressed) {
+                decisions.push({
+                    ruleId: rule.id,
+                    sessionId: context.sessionId,
+                    action: 'suppress',
+                    suppressionReason: suppression.reason,
+                    routingHint,
+                    messageTemplate: rule.messageTemplate,
+                });
+                continue;
+            }
+            // Evaluate condition
+            const conditionResult = await rule.condition(context, evidence);
+            if (!conditionResult) {
+                decisions.push({
+                    ruleId: rule.id,
+                    sessionId: context.sessionId,
+                    action: 'suppress',
+                    // No suppressionReason when condition returns false
+                    routingHint,
+                    messageTemplate: rule.messageTemplate,
+                });
+                continue;
+            }
+            // Fire: update reminder state
+            const key = reminderKey(context.sessionId, rule.id);
+            reminderStates.set(key, {
+                reminderCount: state.reminderCount + 1,
+                lastReminderSentAt: now.toISOString(),
+            });
+            decisions.push({
+                ruleId: rule.id,
+                sessionId: context.sessionId,
+                action: 'fire',
+                routingHint,
+                messageTemplate: rule.messageTemplate,
+            });
+        }
+        return decisions;
+    }
+    function resetReminderState(sessionId, ruleId) {
+        if (ruleId !== undefined) {
+            reminderStates.delete(reminderKey(sessionId, ruleId));
+        }
+        else {
+            // Clear all reminder state for the given session
+            const prefix = `${sessionId}:`;
+            for (const key of reminderStates.keys()) {
+                if (key.startsWith(prefix)) {
+                    reminderStates.delete(key);
+                }
+            }
+        }
+    }
+    // ── Watch rule methods ────────────────────────────────────────────────────────
+    async function registerWatchRule(rule) {
+        const record = {
+            rule,
+            status: 'active',
+            lastEvaluatedAt: null,
+            nextWakeUpBindingId: null,
+        };
+        watchRuleRecords.set(rule.id, record);
+        // Engine owns initial watch scheduling (Decision 5)
+        const bindingId = await scheduleWatchWakeUp(record);
+        record.nextWakeUpBindingId = bindingId;
+    }
+    function pauseWatchRule(ruleId) {
+        const record = watchRuleRecords.get(ruleId);
+        if (!record || record.status === 'cancelled') {
+            throw new RuleNotFoundError(ruleId, 'watch');
+        }
+        record.status = 'paused';
+    }
+    async function resumeWatchRule(ruleId) {
+        const record = watchRuleRecords.get(ruleId);
+        if (!record || record.status === 'cancelled') {
+            throw new RuleNotFoundError(ruleId, 'watch');
+        }
+        record.status = 'active';
+        // Engine schedules wake-up on resume (Decision 5)
+        const bindingId = await scheduleWatchWakeUp(record);
+        record.nextWakeUpBindingId = bindingId;
+    }
+    async function cancelWatchRule(ruleId) {
+        const record = watchRuleRecords.get(ruleId);
+        if (!record || record.status === 'cancelled') {
+            throw new RuleNotFoundError(ruleId, 'watch');
+        }
+        // Cancel any pending wake-up
+        if (record.nextWakeUpBindingId) {
+            await schedulerBinding.cancelWakeUp(record.nextWakeUpBindingId);
+            record.nextWakeUpBindingId = null;
+        }
+        record.status = 'cancelled';
+    }
+    function listWatchRules() {
+        return Array.from(watchRuleRecords.values()).map((r) => ({
+            rule: r.rule,
+            status: r.status,
+            lastEvaluatedAt: r.lastEvaluatedAt,
+            nextWakeUpBindingId: r.nextWakeUpBindingId,
+        }));
+    }
+    async function evaluateWatchRules(context) {
+        // Decision 6: evaluates only the rule identified by context.ruleId
+        const record = watchRuleRecords.get(context.ruleId);
+        if (!record || record.status === 'cancelled') {
+            throw new RuleNotFoundError(context.ruleId, 'watch');
+        }
+        // Paused rules are skipped (no error, just empty result)
+        if (record.status === 'paused') {
+            return [];
+        }
+        const now = new Date();
+        const triggers = [];
+        const ruleContext = {
+            ruleId: record.rule.id,
+            scheduledAt: context.scheduledAt,
+            metadata: context.metadata,
+        };
+        const conditionResult = await record.rule.condition(ruleContext);
+        record.lastEvaluatedAt = now.toISOString();
+        if (conditionResult) {
+            triggers.push({
+                ruleId: record.rule.id,
+                triggeredAt: now.toISOString(),
+                action: record.rule.action,
+                context: ruleContext,
+            });
+        }
+        // Re-schedule only the evaluated rule (Decision 6)
+        if (record.nextWakeUpBindingId) {
+            await schedulerBinding.cancelWakeUp(record.nextWakeUpBindingId);
+            record.nextWakeUpBindingId = null;
+        }
+        const newBindingId = await scheduleWatchWakeUp(record, context.metadata);
+        record.nextWakeUpBindingId = newBindingId;
+        return triggers;
+    }
+    return {
+        registerFollowUpRule,
+        removeFollowUpRule,
+        listFollowUpRules,
+        evaluateFollowUp,
+        resetReminderState,
+        registerWatchRule,
+        pauseWatchRule,
+        resumeWatchRule,
+        cancelWatchRule,
+        listWatchRules,
+        evaluateWatchRules,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,167 @@
+export type RoutingHint = 'cheap' | 'fast' | 'deep';
+export type SuppressionReason = 'user_active' | 'cooldown' | 'max_reminders';
+export type FollowUpAction = 'fire' | 'suppress';
+export interface ReminderPolicy {
+    /** Maximum number of reminders to send per (sessionId, ruleId). Default: 3. */
+    maxReminders?: number;
+    /**
+     * Minimum milliseconds between reminders for the same (sessionId, ruleId).
+     * Default: 3_600_000 (1 hour).
+     */
+    cooldownMs?: number;
+    /**
+     * If true, suppress when the user's last activity is after the wake-up's scheduledAt.
+     * Default: true.
+     */
+    suppressWhenActive?: boolean;
+}
+export interface EvidenceEntry {
+    id: string;
+    content: string;
+    tags: string[];
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface FollowUpEvaluationContext {
+    sessionId: string;
+    /** ISO-8601 — when the wake-up was originally scheduled. Used for suppression comparison. */
+    scheduledAt: string;
+    /** ISO-8601 — the session's last user activity timestamp. */
+    lastActivityAt: string;
+    /** Optional pre-fetched evidence entries from the evidence source. */
+    evidence?: EvidenceEntry[];
+}
+export interface FollowUpRule {
+    id: string;
+    /**
+     * Condition function. Receives the evaluation context and optional evidence.
+     * Returns true if the assistant should consider following up.
+     */
+    condition(ctx: FollowUpEvaluationContext, evidence: EvidenceEntry[]): boolean | Promise<boolean>;
+    /** Human-readable description for logging. */
+    description?: string;
+    /** ReminderPolicy governs suppression. If omitted, defaults are used. */
+    policy?: ReminderPolicy;
+    /** Routing hint passed through to the caller's routing logic. Defaults to 'cheap'. */
+    routingHint?: RoutingHint;
+    /** Free-form message template. The caller is responsible for final rendering. */
+    messageTemplate?: string;
+}
+export interface FollowUpDecision {
+    ruleId: string;
+    sessionId: string;
+    /** What the engine recommends the caller do. */
+    action: FollowUpAction;
+    /**
+     * suppressionReason is present when action === 'suppress' due to a policy check.
+     * - 'user_active': user became active after the wake-up was scheduled
+     * - 'cooldown': too soon after the previous reminder
+     * - 'max_reminders': rule's maxReminders count has been reached
+     * Not set when suppression is due to condition returning false.
+     */
+    suppressionReason?: SuppressionReason;
+    /** Routing hint from the rule. Callers should use this to select a model tier. */
+    routingHint: RoutingHint;
+    /** Message template from the rule, if provided. Caller renders the final message. */
+    messageTemplate?: string;
+}
+export interface WatchAction {
+    /** Short descriptor used by the caller to identify what to do. */
+    type: string;
+    /** Optional payload passed through to the caller unchanged. */
+    payload?: Record<string, unknown>;
+}
+export interface WatchEvaluationContext {
+    /** The specific rule to evaluate. Always required; wake-ups are per-rule. */
+    ruleId: string;
+    /** ISO-8601 — when this evaluation was scheduled. */
+    scheduledAt: string;
+    /** Product-supplied metadata from the original WakeUpContext. */
+    metadata?: Record<string, unknown>;
+}
+export interface WatchRule {
+    id: string;
+    /**
+     * Condition function evaluated on each scheduled check.
+     * Returns true if the watch rule should trigger an action.
+     */
+    condition(ctx: WatchEvaluationContext): boolean | Promise<boolean>;
+    /**
+     * Action descriptor. The engine does not execute actions — it returns WatchTrigger
+     * objects that the caller handles.
+     */
+    action: WatchAction;
+    /**
+     * Interval in milliseconds between condition checks.
+     * The engine requests a new wake-up after every evaluation regardless of trigger result.
+     */
+    intervalMs: number;
+    /** Optional description for logging and observability. */
+    description?: string;
+}
+export interface WatchTrigger {
+    ruleId: string;
+    triggeredAt: string;
+    action: WatchAction;
+    context: WatchEvaluationContext;
+}
+export type WatchRuleLifecycleStatus = 'active' | 'paused' | 'cancelled';
+export interface WatchRuleStatus {
+    rule: WatchRule;
+    status: WatchRuleLifecycleStatus;
+    lastEvaluatedAt: string | null;
+    nextWakeUpBindingId: string | null;
+}
+export interface WakeUpContext {
+    sessionId: string;
+    ruleId?: string;
+    scheduledAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SchedulerBinding {
+    /** Request a wake-up at the given time. Returns a bindingId the engine uses to cancel. */
+    requestWakeUp(at: Date, context: WakeUpContext): Promise<string>;
+    /** Cancel a previously requested wake-up by its bindingId. No-op if already fired or not found. */
+    cancelWakeUp(bindingId: string): Promise<void>;
+}
+export interface FollowUpEvidenceSource {
+    getRecentEntries(sessionId: string, options?: {
+        limit?: number;
+        tags?: string[];
+    }): Promise<EvidenceEntry[]>;
+}
+export interface ProactiveEngineConfig {
+    /** Required scheduler binding. Wire InMemorySchedulerBinding for tests. */
+    schedulerBinding: SchedulerBinding;
+    /** Optional evidence source wired to a memory store or other evidence backend. */
+    evidenceSource?: FollowUpEvidenceSource;
+    /** Default reminder policy applied when a rule does not specify its own policy. */
+    defaultReminderPolicy?: ReminderPolicy;
+}
+export interface ProactiveEngine {
+    registerFollowUpRule(rule: FollowUpRule): void;
+    removeFollowUpRule(ruleId: string): void;
+    listFollowUpRules(): FollowUpRule[];
+    evaluateFollowUp(context: FollowUpEvaluationContext): Promise<FollowUpDecision[]>;
+    resetReminderState(sessionId: string, ruleId?: string): void;
+    registerWatchRule(rule: WatchRule): Promise<void>;
+    pauseWatchRule(ruleId: string): void;
+    resumeWatchRule(ruleId: string): Promise<void>;
+    cancelWatchRule(ruleId: string): Promise<void>;
+    listWatchRules(): WatchRuleStatus[];
+    evaluateWatchRules(context: WatchEvaluationContext): Promise<WatchTrigger[]>;
+}
+export declare class ProactiveError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class RuleNotFoundError extends ProactiveError {
+    readonly ruleId: string;
+    readonly ruleType: 'followUp' | 'watch';
+    constructor(ruleId: string, ruleType: 'followUp' | 'watch');
+}
+export declare class SchedulerBindingError extends ProactiveError {
+    readonly bindingId?: string;
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown, bindingId?: string);
+}

package/dist/types.js

@@ -0,0 +1,33 @@
+// ─── Core scalar types ────────────────────────────────────────────────────────
+// ─── Error classes ────────────────────────────────────────────────────────────
+export class ProactiveError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'ProactiveError';
+        this.code = code;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class RuleNotFoundError extends ProactiveError {
+    ruleId;
+    ruleType;
+    constructor(ruleId, ruleType) {
+        super(`Rule not found: ${ruleId} (${ruleType})`, 'RULE_NOT_FOUND');
+        this.name = 'RuleNotFoundError';
+        this.ruleId = ruleId;
+        this.ruleType = ruleType;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class SchedulerBindingError extends ProactiveError {
+    bindingId;
+    cause;
+    constructor(message, cause, bindingId) {
+        super(message, 'SCHEDULER_BINDING_ERROR');
+        this.name = 'SchedulerBindingError';
+        this.cause = cause;
+        this.bindingId = bindingId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-assistant/proactive",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Proactive decision engine for Agent Assistant SDK",
   "type": "module",
   "main": "dist/index.js",