@illuma-ai/agents 1.1.28 → 1.3.1

package/dist/types/memory/factory.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Factory for building a memory backend from environment variables.
+ *
+ * Called once at startup by host's singleton (`api/server/services/memoryStore.js`).
+ * Returns `null` — never throws — when required env vars are missing, so
+ * agents with `memory_enabled=true` still run, just without memory. Host
+ * logs a single warning on boot instead of crashing.
+ */
+import { Pool } from 'pg';
+import { type RecallTracker } from './recallTracking';
+import type { MemoryBackend } from './types';
+export interface BuildMemoryBackendResult {
+    backend: MemoryBackend;
+    pool: Pool;
+    /** Phase 2 — shared recall tracker bound to the same pool/migration. */
+    recallTracker: RecallTracker;
+}
+/**
+ * Try to build a configured memory backend. Returns null when the required
+ * env vars are absent — caller should log a single "memory disabled" warning
+ * and continue. Never throws on missing config.
+ */
+export declare function buildMemoryBackendFromEnv(): Promise<BuildMemoryBackendResult | null>;

package/dist/types/memory/index.d.ts

@@ -0,0 +1,21 @@
+/** Public entry point for the memory package. */
+export * from './types';
+export * from './constants';
+export * from './paths';
+export { PgvectorMemoryStore } from './pgvectorStore';
+export type { PgvectorStoreOptions } from './pgvectorStore';
+export { CompositeMemoryBackend } from './compositeBackend';
+export { getMemoryEmbedder, resetMemoryEmbedder } from './embeddings';
+export type { EmbeddingProvider, EmbeddingProviderKind } from './embeddings';
+export { runMemoryMigration } from './migrate';
+export type { MigrationOptions } from './migrate';
+export { buildMemoryBackendFromEnv } from './factory';
+export type { BuildMemoryBackendResult } from './factory';
+export { mmrRerank, applyMMRToMemoryHits, DEFAULT_MMR_CONFIG, tokenize, jaccardSimilarity, textSimilarity, computeMMRScore, } from './mmr';
+export type { MMRConfig, MMRItem } from './mmr';
+export { applyTemporalDecayToHits, applyTemporalDecayToScore, calculateTemporalDecayMultiplier, parseMemoryDateFromPath, isEvergreenMemoryPath, DEFAULT_TEMPORAL_DECAY_CONFIG, } from './temporalDecay';
+export type { TemporalDecayConfig, DecayCandidate } from './temporalDecay';
+export { decorateCitations, resolveMemoryCitationsMode, shouldIncludeCitations, } from './citations';
+export type { MemoryCitationsMode, CitationCandidate } from './citations';
+export { PgvectorRecallTracker, NullRecallTracker, RECALL_TABLE, } from './recallTracking';
+export type { RecallTracker, RecallRecordParams } from './recallTracking';

package/dist/types/memory/migrate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Idempotent schema install + vector-dimension safety check.
+ *
+ * Called once at agents-library startup by host's `memoryStore.js` singleton
+ * factory. Safe to call multiple times — every statement is `IF NOT EXISTS`.
+ */
+import type { Pool } from 'pg';
+export interface MigrationOptions {
+    pool: Pool;
+    table?: string;
+    /** If true, skip the live embedder probe (tests). */
+    skipEmbedderProbe?: boolean;
+}
+export declare function runMemoryMigration(opts: MigrationOptions): Promise<void>;

package/dist/types/memory/mmr.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Maximal Marginal Relevance (MMR) re-ranking — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/memory/mmr.ts` with
+ * minor adaptation for our `MemoryEntry` shape (content vs snippet, id vs
+ * path+startLine). Behavior is identical: normalize scores, iteratively
+ * pick the item that maximizes `λ * relevance - (1-λ) * max_similarity`
+ * using Jaccard on tokenized content.
+ *
+ * @see Carbonell & Goldstein, "The Use of MMR, Diversity-Based Reranking" (1998)
+ */
+export interface MMRConfig {
+    /** Opt-in. Upstream default is false. */
+    enabled: boolean;
+    /** 0 = max diversity, 1 = max relevance. Upstream default 0.7. */
+    lambda: number;
+}
+export declare const DEFAULT_MMR_CONFIG: MMRConfig;
+/**
+ * Tokenize content into a set for Jaccard similarity.
+ *
+ * ASCII: alphanumeric + underscore runs, lowercased.
+ * CJK: each char becomes a unigram; consecutive pairs become a bigram.
+ * Non-adjacent CJK chars (e.g. `我a好`) do NOT form a bigram.
+ */
+export declare function tokenize(text: string): Set<string>;
+export declare function jaccardSimilarity(a: Set<string>, b: Set<string>): number;
+export declare function textSimilarity(a: string, b: string): number;
+export declare function computeMMRScore(relevance: number, maxSimilarity: number, lambda: number): number;
+export interface MMRItem {
+    id: string;
+    score: number;
+    content: string;
+}
+/**
+ * Re-rank items using MMR. Returns a new array in MMR order.
+ */
+export declare function mmrRerank<T extends MMRItem>(items: T[], config?: Partial<MMRConfig>): T[];
+/**
+ * Adapter: apply MMR to an array of MemoryEntry-shaped hits.
+ *
+ * Uses (path|id|index) as the stable ID so two hits from the same file at
+ * different content still get distinct MMR identities.
+ */
+export declare function applyMMRToMemoryHits<T extends {
+    id: string;
+    path: string;
+    content: string;
+    score: number;
+}>(results: T[], config?: Partial<MMRConfig>): T[];

package/dist/types/memory/paths.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Autonomous memory — canonical path whitelist + tier utilities.
+ *
+ * Single source of truth for the 8 stable memory documents. Every write
+ * goes through {@link assertWritablePath}; every reader can ask
+ * {@link getTierForPath} what a row belongs to. Adding or removing a
+ * path means editing this file — and exactly this file.
+ *
+ * ## Why a whitelist?
+ *
+ * Earlier upstream-faithful designs used date-keyed files
+ * (`memory/YYYY-MM-DD.md`), which have three problems for a persistent
+ * multi-user agent:
+ *
+ * 1. **Unbounded growth** — one row per day per agent per user, forever.
+ * 2. **LLM routing ambiguity** — "which date file do I read?" has no
+ *    good answer, so the model reads (and ranks against) all of them.
+ * 3. **No natural deduplication** — the same fact written across three
+ *    days returns three near-identical hits.
+ *
+ * With 8 stable canonical documents the LLM knows *exactly* where to
+ * write ("is this a preference? → `memory/user/preferences.md`") and
+ * each row accumulates via UPSERT instead of piling up new rows.
+ *
+ * ## Two tiers
+ *
+ * - **Agent tier** (`memory/agent/*`) — operational knowledge that
+ *   every caller of the agent benefits from. Stored with `user_id = NULL`.
+ *   Shared across all users of a collaborative agent; the only tier that
+ *   exists for isolated/autonomous agents with no invoker.
+ *
+ * - **User tier** (`memory/user/*`) — per-invoker personalization.
+ *   Stored with `user_id = <caller>`. Read path filters so User A never
+ *   sees User B's rows, even for the same agent. Not writable unless the
+ *   flush scope carries a non-empty `userId`.
+ *
+ * The tier of a path is a function of its prefix (`memory/agent/` vs
+ * `memory/user/`), so adding a new document is one line here + the
+ * constant array entry; no store or route code has to change.
+ */
+import type { MemoryScope } from './types';
+/** Tier discriminator — the two kinds of memory a row can belong to. */
+export type MemoryTier = 'agent' | 'user';
+/** Every canonical document the flush phase is allowed to write. */
+export interface MemoryPathDescriptor {
+    /** Full path including the `memory/` prefix. */
+    path: string;
+    /** Which tier the path lives under. */
+    tier: MemoryTier;
+    /** Short label shown in UI tier badges and the flush prompt rubric. */
+    label: string;
+    /** One-line description — fed to the LLM to make routing unambiguous. */
+    description: string;
+}
+/** Agent-tier documents — shared across all users of the agent. */
+export declare const MEMORY_AGENT_PATHS: readonly MemoryPathDescriptor[];
+/** User-tier documents — per-invoker, never shared across users. */
+export declare const MEMORY_USER_PATHS: readonly MemoryPathDescriptor[];
+/** All 8 canonical documents in display order: agent tier first, user tier second. */
+export declare const MEMORY_ALL_PATHS: readonly MemoryPathDescriptor[];
+/** Set of all whitelisted paths — for `has()` lookups. */
+export declare const MEMORY_WRITABLE_PATHS: ReadonlySet<string>;
+/** Returns the descriptor for a canonical path, or `undefined` if not on the whitelist. */
+export declare function getPathDescriptor(path: string): MemoryPathDescriptor | undefined;
+/**
+ * Returns the tier a given path belongs to.
+ *
+ * For unknown paths (e.g. legacy date-keyed rows that predate this schema),
+ * falls back to inspecting the `memory/agent/` or `memory/user/` prefix.
+ * Anything that matches neither is classified as `agent` — it will surface
+ * in the admin UI under the agent-tier header and stay read-only there.
+ */
+export declare function getTierForPath(path: string): MemoryTier;
+/**
+ * Paths that are legal to write **for this caller's scope**.
+ *
+ * If `scope.userId` is absent (isolated/autonomous agent), the user-tier
+ * paths are dropped. This is the list the flush prompt renders into its
+ * rubric — the LLM never sees paths it cannot write to.
+ */
+export declare function getWritablePathsForScope(scope: Pick<MemoryScope, 'userId'>): readonly MemoryPathDescriptor[];
+/**
+ * Validates a write path against the whitelist AND the caller's scope.
+ *
+ * Throws with an actionable message when:
+ * - the path is missing the `memory/` prefix
+ * - the path is not on the 8-doc whitelist
+ * - the path is user-tier but `scope.userId` is missing
+ *
+ * The store's append() is the single call site; other callers should
+ * never hit this directly. Kept as a standalone function for testability.
+ */
+export declare function assertWritablePath(path: string, scope: Pick<MemoryScope, 'userId'>): MemoryPathDescriptor;
+/**
+ * Renders the whitelist as a compact bullet list, used inside the flush
+ * prompt so the LLM sees the authoritative rubric at inference time.
+ *
+ * Output shape:
+ *   - memory/agent/playbook.md [Playbook, shared] — <description>
+ *   - memory/agent/pitfalls.md [Pitfalls, shared] — <description>
+ *   ...
+ *
+ * The `[Label, shared|private]` tag tells the model whether the doc is
+ * visible to all users (agent tier) or only to the caller (user tier).
+ * Filtered to only the paths writable for the given scope.
+ */
+export declare function renderPathsRubric(scope: Pick<MemoryScope, 'userId'>): string;

package/dist/types/memory/pgvectorStore.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Postgres + pgvector implementation of {@link MemoryBackend}.
+ *
+ * ## Scoping model (two-tier, layered)
+ *
+ * Every read query applies the layered filter
+ *
+ *   WHERE agent_id = $1 AND (user_id IS NULL OR user_id = $2)
+ *
+ * so the caller sees:
+ *   - agent-tier rows (`user_id IS NULL`) — shared operational knowledge,
+ *     visible to every user of the agent
+ *   - their own user-tier rows (`user_id = <caller>`) — private per-user
+ *     personalization
+ *
+ * Another user's user-tier rows are invisible — the privacy boundary is
+ * enforced in SQL, not just in the UI or route layer.
+ *
+ * ## Writes
+ *
+ * `append()` routes to a row based on the path's tier, resolved via
+ * {@link assertWritablePath}:
+ *
+ *   - `memory/agent/*` → stored with `user_id = NULL` regardless of
+ *     what scope the caller passed. Agent-tier content is inherently
+ *     shared; scoping it per-user would defeat the point.
+ *   - `memory/user/*`  → stored with `user_id = scope.userId`. A missing
+ *     `scope.userId` throws — user-tier paths cannot be written from
+ *     isolated/autonomous contexts.
+ *
+ * UPSERT key is `(agent_id, user_id, path)` with `NULLS NOT DISTINCT`,
+ * so each user gets their own `user/preferences.md` row and there is
+ * exactly one `agent/playbook.md` row shared across the whole user base.
+ * Content accumulates via `\n\n` concatenation on conflict, with the
+ * embedding regenerated over the merged content so search stays
+ * consistent.
+ */
+import type { Pool } from 'pg';
+import { type EmbeddingProvider } from './embeddings';
+import type { MemoryAppendInput, MemoryBackend, MemoryEntry, MemoryGetOptions, MemoryHealth, MemoryReadResult, MemoryScope, MemorySearchOptions } from './types';
+export interface PgvectorStoreOptions {
+    pool: Pool;
+    table?: string;
+    embedder?: EmbeddingProvider;
+}
+export declare class PgvectorMemoryStore implements MemoryBackend {
+    readonly kind: "vector";
+    private pool;
+    private table;
+    private embedder;
+    constructor(opts: PgvectorStoreOptions);
+    search(scope: MemoryScope, query: string, opts?: MemorySearchOptions): Promise<MemoryEntry[]>;
+    get(scope: MemoryScope, opts: MemoryGetOptions): Promise<MemoryReadResult | null>;
+    append(scope: MemoryScope, input: MemoryAppendInput): Promise<void>;
+    health(): Promise<MemoryHealth>;
+}

package/dist/types/memory/recallTracking.d.ts

@@ -0,0 +1,30 @@
+import type { Pool } from 'pg';
+export interface RecallTracker {
+    /** Record that the given memory ids were surfaced to the model for a query. */
+    record(params: RecallRecordParams): Promise<void>;
+    /** Backend-specific schema migration. Idempotent. */
+    migrate(): Promise<void>;
+}
+export interface RecallRecordParams {
+    agentId: string;
+    query: string;
+    hits: Array<{
+        id: string;
+        path: string;
+        score: number;
+    }>;
+    nowMs?: number;
+}
+export declare const RECALL_TABLE = "agent_memory_recalls";
+export declare class PgvectorRecallTracker implements RecallTracker {
+    private readonly pool;
+    private readonly table;
+    constructor(pool: Pool, table?: string);
+    migrate(): Promise<void>;
+    record(params: RecallRecordParams): Promise<void>;
+}
+/** No-op tracker — used when recall tracking is disabled or the backend isn't pgvector. */
+export declare class NullRecallTracker implements RecallTracker {
+    record(): Promise<void>;
+    migrate(): Promise<void>;
+}

package/dist/types/memory/temporalDecay.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Temporal decay — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/memory/temporal-decay.ts`.
+ * Ages dated memory files (`memory/YYYY-MM-DD.md`) using exponential decay
+ * `multiplier = exp(-ln(2) / halfLifeDays * ageInDays)`. At half-life, the
+ * score is exactly halved.
+ *
+ * Evergreen files (MEMORY.md, memory/topics.md, any non-dated file inside
+ * memory/) do NOT decay — they represent durable knowledge and should stay
+ * hot regardless of age. This mirrors upstream's `isEvergreenMemoryPath`.
+ *
+ * Since our pgvector rows carry `createdAt`, we don't need filesystem stat
+ * fallback — the row timestamp is authoritative for any file without a
+ * date in the path.
+ */
+export interface TemporalDecayConfig {
+    enabled: boolean;
+    halfLifeDays: number;
+}
+export declare const DEFAULT_TEMPORAL_DECAY_CONFIG: TemporalDecayConfig;
+export declare function toDecayLambda(halfLifeDays: number): number;
+export declare function calculateTemporalDecayMultiplier(params: {
+    ageInDays: number;
+    halfLifeDays: number;
+}): number;
+export declare function applyTemporalDecayToScore(params: {
+    score: number;
+    ageInDays: number;
+    halfLifeDays: number;
+}): number;
+/** Parse a date out of `memory/YYYY-MM-DD.md` — returns null on non-match or invalid date. */
+export declare function parseMemoryDateFromPath(filePath: string): Date | null;
+/**
+ * Evergreen = durable knowledge file that should not decay.
+ * - `MEMORY.md` / `memory.md` at root
+ * - anything inside `memory/` that is NOT a dated `YYYY-MM-DD.md` file
+ */
+export declare function isEvergreenMemoryPath(filePath: string): boolean;
+export interface DecayCandidate {
+    path: string;
+    score: number;
+    createdAt?: Date;
+}
+/**
+ * Apply temporal decay to a list of memory hits.
+ *
+ * Priority for the effective timestamp:
+ *   1. Dated path (`memory/YYYY-MM-DD.md`) — use the date in the path
+ *   2. Otherwise, if the path is evergreen — NO decay
+ *   3. Otherwise, use the row's `createdAt`
+ */
+export declare function applyTemporalDecayToHits<T extends DecayCandidate>(hits: T[], config?: Partial<TemporalDecayConfig>, nowMs?: number): T[];

package/dist/types/memory/types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Autonomous memory — core types.
+ *
+ * Ported from upstream's memory-core pattern, adapted for Postgres + pgvector
+ * and shaped so a future graph-backend layer (Graphiti, Neo4j agent-memory, etc.)
+ * can be added alongside the vector store without changing the tool contracts.
+ *
+ * Architectural boundary: the LLM tools ({@link MemoryBackend}) never talk to
+ * Postgres directly — they go through an interface that a vector store,
+ * a graph store, or a composite of both can satisfy.
+ */
+/**
+ * Scope key for memory isolation.
+ *
+ * Two-tier model:
+ *   - Agent-tier rows (`memory/agent/*`) are stored with `user_id = NULL`
+ *     and are shared across every user of the agent.
+ *   - User-tier rows (`memory/user/*`) are stored with the caller's
+ *     `userId` and are private to that caller; other users of the same
+ *     agent never see them.
+ *
+ * Every read query applies `WHERE agent_id = $1 AND (user_id IS NULL OR
+ * user_id = $caller)`, so the caller sees shared rows plus their own.
+ * `userId` is therefore both the write target (for user-tier paths) AND
+ * the read filter. An absent `userId` is legal — it just means this
+ * scope is isolated/autonomous and the user tier is inert.
+ *
+ * Captured at tool construction time in a closure and NEVER exposed as
+ * tool parameters. The LLM cannot override either field.
+ */
+export interface MemoryScope {
+    agentId: string;
+    /**
+     * The caller's identity, used for user-tier writes AND the layered
+     * read filter. Undefined/null for isolated/autonomous agents — in
+     * that case only agent-tier rows are visible and writable.
+     */
+    userId?: string | null;
+}
+/**
+ * One retrieved memory record.
+ *
+ * `score` is a unit-interval hybrid score (0..1): 0.7 * cosine + 0.3 * text
+ * rank in the default pgvector backend. A graph backend is free to produce
+ * its own score as long as it stays within that range.
+ */
+export interface MemoryEntry {
+    id: string;
+    path: string;
+    content: string;
+    score: number;
+    createdAt: Date;
+    /**
+     * Which backend surfaced this entry. Lets a composite store tag results so
+     * downstream consumers (tests, telemetry, UI) can distinguish vector hits
+     * from graph hits without inspecting the ID format.
+     */
+    source?: MemoryBackendKind;
+    /**
+     * Which tier the row belongs to — derived from the path at read time.
+     * See `./paths.ts` for the whitelist. UI groups rows by this field
+     * so users can see which memories are shared (agent tier) vs private
+     * (user tier).
+     */
+    tier?: 'agent' | 'user';
+    /** Citation marker (Phase 2) — e.g. `memory/agent/playbook.md#L1-L8`. */
+    citation?: string;
+    /** 1-indexed start/end line range used to build the citation. */
+    startLine?: number;
+    endLine?: number;
+}
+export type MemoryBackendKind = 'vector' | 'graph' | 'composite';
+export interface MemorySearchOptions {
+    maxResults?: number;
+    minScore?: number;
+    /**
+     * Phase 2 toggles — when the backend supports them. Each is independently
+     * opt-in; all false = upstream Phase 1 behavior.
+     */
+    mmr?: {
+        enabled?: boolean;
+        lambda?: number;
+    };
+    temporalDecay?: {
+        enabled?: boolean;
+        halfLifeDays?: number;
+    };
+    /** Citation mode: 'on' decorates; 'off' strips; 'auto' = on for direct chat. */
+    citations?: 'on' | 'off' | 'auto';
+}
+export interface MemoryGetOptions {
+    path: string;
+    from?: number;
+    lines?: number;
+}
+export interface MemoryReadResult {
+    path: string;
+    text: string;
+}
+export interface MemoryAppendInput {
+    /** Must begin with "memory/". Enforced by the append tool wrapper. */
+    path: string;
+    content: string;
+}
+export interface MemoryHealth {
+    ok: boolean;
+    backend: MemoryBackendKind;
+    error?: string;
+}
+/**
+ * The contract every memory backend implements.
+ *
+ * A Phase 1 pgvector store satisfies this directly. A Phase 4 graph store
+ * (Graphiti / Neo4j agent-memory) will implement the same interface and plug
+ * into a {@link CompositeMemoryBackend} without touching the tools.
+ */
+export interface MemoryBackend {
+    readonly kind: MemoryBackendKind;
+    search(scope: MemoryScope, query: string, opts?: MemorySearchOptions): Promise<MemoryEntry[]>;
+    get(scope: MemoryScope, opts: MemoryGetOptions): Promise<MemoryReadResult | null>;
+    append(scope: MemoryScope, input: MemoryAppendInput): Promise<void>;
+    health(): Promise<MemoryHealth>;
+}
+/**
+ * Historical alias kept for one release so external consumers can still import
+ * the name used in the plan doc. New code should prefer {@link MemoryBackend}.
+ *
+ * @deprecated use {@link MemoryBackend}
+ */
+export type MemoryStore = MemoryBackend;
+/**
+ * Optional configuration bundle plumbed through `createAgentNode`.
+ * Missing config = memory fully disabled, no tools attached.
+ */
+export interface MemoryConfig {
+    backend: MemoryBackend;
+    scope: MemoryScope;
+    flush?: {
+        softThresholdTokens?: number;
+        reserveFloorTokens?: number;
+        windowTokens?: number;
+        enabled?: boolean;
+    };
+    search?: {
+        maxResults?: number;
+        maxInjectedChars?: number;
+        /** Phase 2 — enable MMR reranking (upstream-aligned defaults when true). */
+        mmr?: {
+            enabled?: boolean;
+            lambda?: number;
+        };
+        /** Phase 2 — enable temporal decay on dated memory files. */
+        temporalDecay?: {
+            enabled?: boolean;
+            halfLifeDays?: number;
+        };
+        /** Phase 2 — citation mode. Defaults to 'auto'. */
+        citations?: 'on' | 'off' | 'auto';
+    };
+    /**
+     * Phase 2 — optional recall tracker. When set, memory_search fires a
+     * best-effort recall record after each successful call. Failures are
+     * swallowed so recall tracking never blocks the tool result.
+     */
+    recallTracker?: {
+        record(params: {
+            agentId: string;
+            query: string;
+            hits: Array<{
+                id: string;
+                path: string;
+                score: number;
+            }>;
+        }): Promise<void>;
+    };
+    /**
+     * Phase state accessor. Returns the current phase so the append-tool wrapper
+     * can gate writes to the reflection phase. Supplied by the graph runtime.
+     */
+    getPhase?: () => MemoryPhase;
+}
+export type MemoryPhase = 'normal' | 'memory_flushing';

package/dist/types/prompts/memoryFlushPrompt.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Memory-flush prompt resolver.
+ *
+ * The raw prompt strings live in `src/memory/constants.ts` and contain a
+ * single `{{MEMORY_PATHS_RUBRIC}}` placeholder. This module substitutes
+ * the caller-scoped rubric (produced by `renderPathsRubric()` in
+ * `src/memory/paths.ts`) into that placeholder at flush time, so:
+ *
+ *   - a collaborative agent with a real caller sees all 8 paths
+ *   - an isolated/autonomous agent sees only the 4 agent-tier paths
+ *     (user-tier rows are physically omitted from the rubric the LLM
+ *      sees, so it cannot route writes there even by mistake)
+ *
+ * ## Why this lives in prompts/ and not memory/constants.ts
+ *
+ * The constants file is pure strings — no imports, no runtime work.
+ * Injecting the rubric needs access to `renderPathsRubric()` which
+ * needs `MemoryScope`, so the substitution has to happen one layer up.
+ * Keeping the placeholder in constants and the substitution here means
+ * tests of the raw prompt (no scope) and tests of the rendered prompt
+ * (scope-aware) stay independent.
+ */
+import { DEFAULT_MEMORY_FLUSH_PROMPT, DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT } from '@/memory/constants';
+import type { MemoryScope } from '@/memory/types';
+export { DEFAULT_MEMORY_FLUSH_PROMPT, DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT };
+/** Back-compat alias so existing callers keep working. */
+export declare const MEMORY_FLUSH_SYSTEM_PROMPT: string;
+/** Minimum scope shape needed to render the rubric. */
+export interface ResolveFlushPromptsOptions {
+    /**
+     * The scope the memory tools were built with. Only `userId` matters
+     * for rubric rendering — if absent, the user-tier paths are filtered
+     * out of the rubric the LLM sees.
+     */
+    scope: Pick<MemoryScope, 'userId'>;
+}
+/**
+ * Result shape returned to `runMemoryFlush`. `prompt` goes in the
+ * HumanMessage, `systemPrompt` goes in the SystemMessage. Both already
+ * have the rubric substituted — the caller should pass them through
+ * verbatim.
+ */
+export interface ResolvedFlushPrompts {
+    prompt: string;
+    systemPrompt: string;
+}
+/**
+ * Substitutes the paths rubric into the raw prompts for a given scope.
+ *
+ * Idempotent (calling it twice on already-resolved strings is a no-op
+ * because the placeholder will have been replaced already). Safe to
+ * call per-flush; no caching needed — the string concat is microseconds.
+ */
+export declare function resolveFlushPrompts(options: ResolveFlushPromptsOptions): ResolvedFlushPrompts;

package/dist/types/run.d.ts

@@ -15,6 +15,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     Graph: StandardGraph | MultiAgentGraph | undefined;
     returnContent: boolean;
     private skipCleanup;
+    private _originalCallbacksSnapshot?;
     private constructor();
     private createLegacyGraph;
     private createMultiAgentGraph;

package/dist/types/tools/AskUser.d.ts

@@ -38,7 +38,7 @@ export declare const AskUserStepSchema: z.ZodObject<{
 export type AskUserStep = z.infer<typeof AskUserStepSchema>;
 /**
  * Represents a single step selection from the multi-step wizard UI.
- * Exported for use by both ranger web client and browser extension.
+ * Exported for use by both the host web client and browser extension.
  */
 export type StepSelection = {
     values: string[];

package/dist/types/tools/BrowserTools.d.ts

@@ -1,6 +1,6 @@
 import { DynamicStructuredTool } from '@langchain/core/tools';
 /**
- * Browser tool names - keep in sync with ranger-browser extension
+ * Browser tool names - keep in sync with the browser extension
  * These tools execute locally in the browser extension, NOT on the server
  */
 export declare const EBrowserTools: {
@@ -20,7 +20,7 @@ export declare const EBrowserTools: {
 export type BrowserToolName = (typeof EBrowserTools)[keyof typeof EBrowserTools];
 /**
  * Callback function type for waiting on browser action results
- * This allows the server (Ranger) to provide a callback that waits for the extension
+ * This allows the host server to provide a callback that waits for the extension
  * to POST results back to the server before returning to the LLM.
  *
  * @param action - The browser action (click, type, navigate, etc.)

package/dist/types/tools/approval/constants.d.ts

@@ -2,7 +2,7 @@
  * Shared HITL (Human-in-the-Loop) constants and enums.
  *
  * Single source of truth for approval-related values consumed by
- * the agents library, ranger backend, and browser extension.
+ * the agents library, host backend, and browser extension.
  *
  * @module approval/constants
  */
@@ -78,6 +78,6 @@ export declare enum ActionCategory {
  *
  * Example: `send_email_mcp_outlook` → tool = `send_email`, server = `outlook`
  *
- * Must match `Constants.mcp_delimiter` in `@ranger/data-provider`.
+ * Must match the host data-provider delimiter constant.
  */
 export declare const MCP_DELIMITER = "_mcp_";