@agent-native/core 0.52.0 → 0.54.0

package/dist/agent/observational-memory/config.js

@@ -0,0 +1,48 @@
+/**
+ * Tunable thresholds for Observational Memory compaction.
+ *
+ * Defaults are conservative and overridable per call. Deploy-level
+ * AGENT_NATIVE_* env overrides let an operator dial compaction without a
+ * redeploy; an invalid/missing value always falls back to the named default.
+ */
+/**
+ * Once a thread's UNOBSERVED messages exceed this many tokens, the Observer
+ * compacts them into a single dense, dated observation entry.
+ */
+export const DEFAULT_OBSERVATION_TOKEN_THRESHOLD = 30_000;
+/**
+ * Once the persisted observation log itself exceeds this many tokens, the
+ * Reflector condenses the observations into a higher-level reflection.
+ */
+export const DEFAULT_REFLECTION_TOKEN_THRESHOLD = 40_000;
+/**
+ * How many of the most-recent thread messages to always keep verbatim in the
+ * read-side context (the "recent raw messages" tier). These are never folded
+ * into an observation, so the agent always sees the latest turns in full.
+ */
+export const DEFAULT_RECENT_RAW_MESSAGE_COUNT = 12;
+/** Cap on the Observer's output so one observation can't itself blow the budget. */
+export const DEFAULT_OBSERVATION_MAX_OUTPUT_TOKENS = 4_000;
+/** Cap on the Reflector's output. */
+export const DEFAULT_REFLECTION_MAX_OUTPUT_TOKENS = 2_000;
+function readEnvInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function resolveObservationalMemoryConfig(overrides = {}) {
+    return {
+        observationTokenThreshold: overrides.observationTokenThreshold ??
+            readEnvInt(process.env.AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD, DEFAULT_OBSERVATION_TOKEN_THRESHOLD),
+        reflectionTokenThreshold: overrides.reflectionTokenThreshold ??
+            readEnvInt(process.env.AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD, DEFAULT_REFLECTION_TOKEN_THRESHOLD),
+        recentRawMessageCount: overrides.recentRawMessageCount ??
+            readEnvInt(process.env.AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT, DEFAULT_RECENT_RAW_MESSAGE_COUNT),
+        observationMaxOutputTokens: overrides.observationMaxOutputTokens ??
+            DEFAULT_OBSERVATION_MAX_OUTPUT_TOKENS,
+        reflectionMaxOutputTokens: overrides.reflectionMaxOutputTokens ??
+            DEFAULT_REFLECTION_MAX_OUTPUT_TOKENS,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/agent/observational-memory/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAM,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,MAAM,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,EAAE,CAAC;AAEnD,oFAAoF;AACpF,MAAM,CAAC,MAAM,qCAAqC,GAAG,KAAK,CAAC;AAE3D,qCAAqC;AACrC,MAAM,CAAC,MAAM,oCAAoC,GAAG,KAAK,CAAC;AAE1D,SAAS,UAAU,CAAC,GAAuB,EAAE,QAAgB;IAC3D,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AACnE,CAAC;AAWD,MAAM,UAAU,gCAAgC,CAC9C,YAAgD,EAAE;IAElD,OAAO;QACL,yBAAyB,EACvB,SAAS,CAAC,yBAAyB;YACnC,UAAU,CACR,OAAO,CAAC,GAAG,CAAC,2CAA2C,EACvD,mCAAmC,CACpC;QACH,wBAAwB,EACtB,SAAS,CAAC,wBAAwB;YAClC,UAAU,CACR,OAAO,CAAC,GAAG,CAAC,0CAA0C,EACtD,kCAAkC,CACnC;QACH,qBAAqB,EACnB,SAAS,CAAC,qBAAqB;YAC/B,UAAU,CACR,OAAO,CAAC,GAAG,CAAC,wCAAwC,EACpD,gCAAgC,CACjC;QACH,0BAA0B,EACxB,SAAS,CAAC,0BAA0B;YACpC,qCAAqC;QACvC,yBAAyB,EACvB,SAAS,CAAC,yBAAyB;YACnC,oCAAoC;KACvC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Tunable thresholds for Observational Memory compaction.\n *\n * Defaults are conservative and overridable per call. Deploy-level\n * AGENT_NATIVE_* env overrides let an operator dial compaction without a\n * redeploy; an invalid/missing value always falls back to the named default.\n */\n\n/**\n * Once a thread's UNOBSERVED messages exceed this many tokens, the Observer\n * compacts them into a single dense, dated observation entry.\n */\nexport const DEFAULT_OBSERVATION_TOKEN_THRESHOLD = 30_000;\n\n/**\n * Once the persisted observation log itself exceeds this many tokens, the\n * Reflector condenses the observations into a higher-level reflection.\n */\nexport const DEFAULT_REFLECTION_TOKEN_THRESHOLD = 40_000;\n\n/**\n * How many of the most-recent thread messages to always keep verbatim in the\n * read-side context (the \"recent raw messages\" tier). These are never folded\n * into an observation, so the agent always sees the latest turns in full.\n */\nexport const DEFAULT_RECENT_RAW_MESSAGE_COUNT = 12;\n\n/** Cap on the Observer's output so one observation can't itself blow the budget. */\nexport const DEFAULT_OBSERVATION_MAX_OUTPUT_TOKENS = 4_000;\n\n/** Cap on the Reflector's output. */\nexport const DEFAULT_REFLECTION_MAX_OUTPUT_TOKENS = 2_000;\n\nfunction readEnvInt(raw: string | undefined, fallback: number): number {\n  if (!raw) return fallback;\n  const parsed = Number.parseInt(raw, 10);\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;\n}\n\n/** Resolved thresholds, applying env overrides over the named defaults. */\nexport interface ObservationalMemoryConfig {\n  observationTokenThreshold: number;\n  reflectionTokenThreshold: number;\n  recentRawMessageCount: number;\n  observationMaxOutputTokens: number;\n  reflectionMaxOutputTokens: number;\n}\n\nexport function resolveObservationalMemoryConfig(\n  overrides: Partial<ObservationalMemoryConfig> = {},\n): ObservationalMemoryConfig {\n  return {\n    observationTokenThreshold:\n      overrides.observationTokenThreshold ??\n      readEnvInt(\n        process.env.AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD,\n        DEFAULT_OBSERVATION_TOKEN_THRESHOLD,\n      ),\n    reflectionTokenThreshold:\n      overrides.reflectionTokenThreshold ??\n      readEnvInt(\n        process.env.AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD,\n        DEFAULT_REFLECTION_TOKEN_THRESHOLD,\n      ),\n    recentRawMessageCount:\n      overrides.recentRawMessageCount ??\n      readEnvInt(\n        process.env.AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT,\n        DEFAULT_RECENT_RAW_MESSAGE_COUNT,\n      ),\n    observationMaxOutputTokens:\n      overrides.observationMaxOutputTokens ??\n      DEFAULT_OBSERVATION_MAX_OUTPUT_TOKENS,\n    reflectionMaxOutputTokens:\n      overrides.reflectionMaxOutputTokens ??\n      DEFAULT_REFLECTION_MAX_OUTPUT_TOKENS,\n  };\n}\n"]}

package/dist/agent/observational-memory/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Observational Memory (OM) — background compaction of a long agent thread into
+ * a dated, three-tier context (recent raw messages → dense observations →
+ * higher-level reflections) so long-running threads cost far fewer tokens and
+ * stay prompt-cache stable.
+ *
+ * Public surface:
+ * - `buildObservationalContext` — read API returning the three tiers, injected
+ *   into the turn's prompt assembly by the agent loop for long threads.
+ * - `maybeCompactThread` — decoupled compactor the agent loop calls after a
+ *   turn; runs the Observer then the Reflector.
+ * - `runObserver` / `runReflector` — the individual compaction passes.
+ * - store helpers + the migration plugin factory (registered as a default
+ *   framework plugin so the table is created on startup).
+ */
+export { resolveObservationalMemoryConfig, DEFAULT_OBSERVATION_TOKEN_THRESHOLD, DEFAULT_REFLECTION_TOKEN_THRESHOLD, DEFAULT_RECENT_RAW_MESSAGE_COUNT, DEFAULT_OBSERVATION_MAX_OUTPUT_TOKENS, DEFAULT_REFLECTION_MAX_OUTPUT_TOKENS, type ObservationalMemoryConfig, } from "./config.js";
+export { insertObservationalMemory, listObservationalMemory, getObservedThroughIndex, getObservationLogTokens, __resetObservationalMemoryTableCache, type InsertObservationalMemoryInput, type ListObservationalMemoryOptions, } from "./store.js";
+export { runInternalAgentCall, type InternalAgentRunOptions, type InternalAgentRunFn, } from "./internal-run.js";
+export { runObserver, type RunObserverOptions, type RunObserverResult, } from "./observer.js";
+export { runReflector, type RunReflectorOptions, type RunReflectorResult, } from "./reflector.js";
+export { maybeCompactThread, type MaybeCompactThreadOptions, type MaybeCompactThreadResult, } from "./compactor.js";
+export { buildObservationalContext, hasObservationalMemory, serializeObservationalMemoryBlock, type BuildObservationalContextOptions, } from "./read.js";
+export { createObservationalMemoryPlugin, defaultObservationalMemoryPlugin, } from "./plugin.js";
+export { OBSERVATIONAL_MEMORY_MIGRATIONS } from "./migrations.js";
+export type { ObservationalMemoryTier, ObservationalMemoryEntry, ObservationalMemoryOwner, ObservationalContext, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/observational-memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,gCAAgC,EAChC,mCAAmC,EACnC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,EACrC,oCAAoC,EACpC,KAAK,yBAAyB,GAC/B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,oCAAoC,EACpC,KAAK,8BAA8B,EACnC,KAAK,8BAA8B,GACpC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,iCAAiC,EACjC,KAAK,gCAAgC,GACtC,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,GACjC,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAElE,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/agent/observational-memory/index.js

@@ -0,0 +1,25 @@
+/**
+ * Observational Memory (OM) — background compaction of a long agent thread into
+ * a dated, three-tier context (recent raw messages → dense observations →
+ * higher-level reflections) so long-running threads cost far fewer tokens and
+ * stay prompt-cache stable.
+ *
+ * Public surface:
+ * - `buildObservationalContext` — read API returning the three tiers, injected
+ *   into the turn's prompt assembly by the agent loop for long threads.
+ * - `maybeCompactThread` — decoupled compactor the agent loop calls after a
+ *   turn; runs the Observer then the Reflector.
+ * - `runObserver` / `runReflector` — the individual compaction passes.
+ * - store helpers + the migration plugin factory (registered as a default
+ *   framework plugin so the table is created on startup).
+ */
+export { resolveObservationalMemoryConfig, DEFAULT_OBSERVATION_TOKEN_THRESHOLD, DEFAULT_REFLECTION_TOKEN_THRESHOLD, DEFAULT_RECENT_RAW_MESSAGE_COUNT, DEFAULT_OBSERVATION_MAX_OUTPUT_TOKENS, DEFAULT_REFLECTION_MAX_OUTPUT_TOKENS, } from "./config.js";
+export { insertObservationalMemory, listObservationalMemory, getObservedThroughIndex, getObservationLogTokens, __resetObservationalMemoryTableCache, } from "./store.js";
+export { runInternalAgentCall, } from "./internal-run.js";
+export { runObserver, } from "./observer.js";
+export { runReflector, } from "./reflector.js";
+export { maybeCompactThread, } from "./compactor.js";
+export { buildObservationalContext, hasObservationalMemory, serializeObservationalMemoryBlock, } from "./read.js";
+export { createObservationalMemoryPlugin, defaultObservationalMemoryPlugin, } from "./plugin.js";
+export { OBSERVATIONAL_MEMORY_MIGRATIONS } from "./migrations.js";
+//# sourceMappingURL=index.js.map

package/dist/agent/observational-memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,gCAAgC,EAChC,mCAAmC,EACnC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,EACrC,oCAAoC,GAErC,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,oCAAoC,GAGrC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,GAGrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,GAGZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,GAGb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,kBAAkB,GAGnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,iCAAiC,GAElC,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,+BAA+B,EAC/B,gCAAgC,GACjC,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["/**\n * Observational Memory (OM) — background compaction of a long agent thread into\n * a dated, three-tier context (recent raw messages → dense observations →\n * higher-level reflections) so long-running threads cost far fewer tokens and\n * stay prompt-cache stable.\n *\n * Public surface:\n * - `buildObservationalContext` — read API returning the three tiers, injected\n *   into the turn's prompt assembly by the agent loop for long threads.\n * - `maybeCompactThread` — decoupled compactor the agent loop calls after a\n *   turn; runs the Observer then the Reflector.\n * - `runObserver` / `runReflector` — the individual compaction passes.\n * - store helpers + the migration plugin factory (registered as a default\n *   framework plugin so the table is created on startup).\n */\n\nexport {\n  resolveObservationalMemoryConfig,\n  DEFAULT_OBSERVATION_TOKEN_THRESHOLD,\n  DEFAULT_REFLECTION_TOKEN_THRESHOLD,\n  DEFAULT_RECENT_RAW_MESSAGE_COUNT,\n  DEFAULT_OBSERVATION_MAX_OUTPUT_TOKENS,\n  DEFAULT_REFLECTION_MAX_OUTPUT_TOKENS,\n  type ObservationalMemoryConfig,\n} from \"./config.js\";\n\nexport {\n  insertObservationalMemory,\n  listObservationalMemory,\n  getObservedThroughIndex,\n  getObservationLogTokens,\n  __resetObservationalMemoryTableCache,\n  type InsertObservationalMemoryInput,\n  type ListObservationalMemoryOptions,\n} from \"./store.js\";\n\nexport {\n  runInternalAgentCall,\n  type InternalAgentRunOptions,\n  type InternalAgentRunFn,\n} from \"./internal-run.js\";\n\nexport {\n  runObserver,\n  type RunObserverOptions,\n  type RunObserverResult,\n} from \"./observer.js\";\nexport {\n  runReflector,\n  type RunReflectorOptions,\n  type RunReflectorResult,\n} from \"./reflector.js\";\n\nexport {\n  maybeCompactThread,\n  type MaybeCompactThreadOptions,\n  type MaybeCompactThreadResult,\n} from \"./compactor.js\";\n\nexport {\n  buildObservationalContext,\n  hasObservationalMemory,\n  serializeObservationalMemoryBlock,\n  type BuildObservationalContextOptions,\n} from \"./read.js\";\n\nexport {\n  createObservationalMemoryPlugin,\n  defaultObservationalMemoryPlugin,\n} from \"./plugin.js\";\n\nexport { OBSERVATIONAL_MEMORY_MIGRATIONS } from \"./migrations.js\";\n\nexport type {\n  ObservationalMemoryTier,\n  ObservationalMemoryEntry,\n  ObservationalMemoryOwner,\n  ObservationalContext,\n} from \"./types.js\";\n"]}

package/dist/agent/observational-memory/internal-run.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tiny headless internal-agent-call seam for Observational Memory.
+ *
+ * The Observer and Reflector each need a single, tool-less LLM round-trip:
+ * "here is some text, compress it". Rather than touch `production-agent.ts`,
+ * this reuses the SAME pattern the evals lane built — resolve a provider-
+ * agnostic engine + model from the registry (NEVER hardcode a model) and drive
+ * one `engine.stream()` to completion, collecting the text. It mirrors the
+ * `analyzeContext().judge` helper in `eval/agent-runner.ts`.
+ *
+ * Everything is injectable so tests can supply a fake engine and assert no real
+ * model is ever called.
+ */
+import type { AgentEngine } from "../engine/types.js";
+export interface InternalAgentRunOptions {
+    systemPrompt: string;
+    prompt: string;
+    maxOutputTokens?: number;
+    /** Pre-resolved engine; resolved from the registry when omitted. */
+    engine?: AgentEngine;
+    /** Pre-resolved model; resolved from the engine's stored/default when omitted. */
+    model?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Run one tool-less internal agent call and return the collected text.
+ *
+ * Resolution goes through `resolveEngine` / `getStoredModelForEngine` /
+ * `normalizeModelForEngine` — identical to the eval runner — so the compactor
+ * uses whatever provider/model the app is configured for. No model is ever
+ * hardcoded here.
+ */
+export declare function runInternalAgentCall(options: InternalAgentRunOptions): Promise<string>;
+/** The shape the Observer/Reflector depend on — injectable for tests. */
+export type InternalAgentRunFn = (options: InternalAgentRunOptions) => Promise<string>;
+//# sourceMappingURL=internal-run.d.ts.map

package/dist/agent/observational-memory/internal-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-run.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/internal-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAStD,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAED,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC,MAAM,CAAC,CAAC"}

package/dist/agent/observational-memory/internal-run.js

@@ -0,0 +1,59 @@
+/**
+ * Tiny headless internal-agent-call seam for Observational Memory.
+ *
+ * The Observer and Reflector each need a single, tool-less LLM round-trip:
+ * "here is some text, compress it". Rather than touch `production-agent.ts`,
+ * this reuses the SAME pattern the evals lane built — resolve a provider-
+ * agnostic engine + model from the registry (NEVER hardcode a model) and drive
+ * one `engine.stream()` to completion, collecting the text. It mirrors the
+ * `analyzeContext().judge` helper in `eval/agent-runner.ts`.
+ *
+ * Everything is injectable so tests can supply a fake engine and assert no real
+ * model is ever called.
+ */
+import { resolveEngine, getStoredModelForEngine, normalizeModelForEngine, } from "../engine/index.js";
+const DEFAULT_INTERNAL_RUN_TIMEOUT_MS = 60_000;
+/**
+ * Run one tool-less internal agent call and return the collected text.
+ *
+ * Resolution goes through `resolveEngine` / `getStoredModelForEngine` /
+ * `normalizeModelForEngine` — identical to the eval runner — so the compactor
+ * uses whatever provider/model the app is configured for. No model is ever
+ * hardcoded here.
+ */
+export async function runInternalAgentCall(options) {
+    const engine = options.engine ?? (await resolveEngine({ engineOption: undefined }));
+    const modelCandidate = options.model ??
+        (await getStoredModelForEngine(engine)) ??
+        engine.defaultModel;
+    const model = normalizeModelForEngine(engine, modelCandidate);
+    const controller = new AbortController();
+    const signal = options.signal ?? controller.signal;
+    const timer = options.signal
+        ? undefined
+        : setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_INTERNAL_RUN_TIMEOUT_MS);
+    let out = "";
+    try {
+        const stream = engine.stream({
+            model,
+            systemPrompt: options.systemPrompt,
+            messages: [
+                { role: "user", content: [{ type: "text", text: options.prompt }] },
+            ],
+            tools: [],
+            abortSignal: signal,
+            maxOutputTokens: options.maxOutputTokens ?? 4_000,
+            temperature: 0,
+        });
+        for await (const event of stream) {
+            if (event.type === "text-delta")
+                out += event.text;
+        }
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+    return out.trim();
+}
+//# sourceMappingURL=internal-run.js.map

package/dist/agent/observational-memory/internal-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-run.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/internal-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,+BAA+B,GAAG,MAAM,CAAC;AAc/C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAgC;IAEhC,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,aAAa,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IACvE,MAAM,cAAc,GAClB,OAAO,CAAC,KAAK;QACb,CAAC,MAAM,uBAAuB,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,CAAC,YAAY,CAAC;IACtB,MAAM,KAAK,GAAG,uBAAuB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE9D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM;QAC1B,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,UAAU,CACR,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EACxB,OAAO,CAAC,SAAS,IAAI,+BAA+B,CACrD,CAAC;IAEN,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YAC3B,KAAK;YACL,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE;aACpE;YACD,KAAK,EAAE,EAAE;YACT,WAAW,EAAE,MAAM;YACnB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,KAAK;YACjD,WAAW,EAAE,CAAC;SACf,CAAC,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACjC,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY;gBAAE,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC;QACrD,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC","sourcesContent":["/**\n * Tiny headless internal-agent-call seam for Observational Memory.\n *\n * The Observer and Reflector each need a single, tool-less LLM round-trip:\n * \"here is some text, compress it\". Rather than touch `production-agent.ts`,\n * this reuses the SAME pattern the evals lane built — resolve a provider-\n * agnostic engine + model from the registry (NEVER hardcode a model) and drive\n * one `engine.stream()` to completion, collecting the text. It mirrors the\n * `analyzeContext().judge` helper in `eval/agent-runner.ts`.\n *\n * Everything is injectable so tests can supply a fake engine and assert no real\n * model is ever called.\n */\n\nimport type { AgentEngine } from \"../engine/types.js\";\nimport {\n  resolveEngine,\n  getStoredModelForEngine,\n  normalizeModelForEngine,\n} from \"../engine/index.js\";\n\nconst DEFAULT_INTERNAL_RUN_TIMEOUT_MS = 60_000;\n\nexport interface InternalAgentRunOptions {\n  systemPrompt: string;\n  prompt: string;\n  maxOutputTokens?: number;\n  /** Pre-resolved engine; resolved from the registry when omitted. */\n  engine?: AgentEngine;\n  /** Pre-resolved model; resolved from the engine's stored/default when omitted. */\n  model?: string;\n  timeoutMs?: number;\n  signal?: AbortSignal;\n}\n\n/**\n * Run one tool-less internal agent call and return the collected text.\n *\n * Resolution goes through `resolveEngine` / `getStoredModelForEngine` /\n * `normalizeModelForEngine` — identical to the eval runner — so the compactor\n * uses whatever provider/model the app is configured for. No model is ever\n * hardcoded here.\n */\nexport async function runInternalAgentCall(\n  options: InternalAgentRunOptions,\n): Promise<string> {\n  const engine =\n    options.engine ?? (await resolveEngine({ engineOption: undefined }));\n  const modelCandidate =\n    options.model ??\n    (await getStoredModelForEngine(engine)) ??\n    engine.defaultModel;\n  const model = normalizeModelForEngine(engine, modelCandidate);\n\n  const controller = new AbortController();\n  const signal = options.signal ?? controller.signal;\n  const timer = options.signal\n    ? undefined\n    : setTimeout(\n        () => controller.abort(),\n        options.timeoutMs ?? DEFAULT_INTERNAL_RUN_TIMEOUT_MS,\n      );\n\n  let out = \"\";\n  try {\n    const stream = engine.stream({\n      model,\n      systemPrompt: options.systemPrompt,\n      messages: [\n        { role: \"user\", content: [{ type: \"text\", text: options.prompt }] },\n      ],\n      tools: [],\n      abortSignal: signal,\n      maxOutputTokens: options.maxOutputTokens ?? 4_000,\n      temperature: 0,\n    });\n    for await (const event of stream) {\n      if (event.type === \"text-delta\") out += event.text;\n    }\n  } finally {\n    if (timer) clearTimeout(timer);\n  }\n  return out.trim();\n}\n\n/** The shape the Observer/Reflector depend on — injectable for tests. */\nexport type InternalAgentRunFn = (\n  options: InternalAgentRunOptions,\n) => Promise<string>;\n"]}

package/dist/agent/observational-memory/message-text.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Render engine messages to a compact plain-text transcript for the compactor
+ * window, and account their tokens. Reuses the existing context-xray token
+ * accounting so OM thresholds match what the rest of the framework counts.
+ */
+import type { EngineMessage } from "../engine/types.js";
+/** Flatten one engine message to a single labeled line block. */
+export declare function messageToText(message: EngineMessage): string;
+/** Render a contiguous window of messages to one text blob. */
+export declare function windowToText(messages: EngineMessage[]): string;
+/** Token count for a window of messages (reuses framework tokenizer). */
+export declare function countWindowTokens(messages: EngineMessage[]): Promise<number>;
+//# sourceMappingURL=message-text.d.ts.map

package/dist/agent/observational-memory/message-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-text.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/message-text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAc5D;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,CAK9D;AAED,yEAAyE;AACzE,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,aAAa,EAAE,GACxB,OAAO,CAAC,MAAM,CAAC,CAGjB"}

package/dist/agent/observational-memory/message-text.js

@@ -0,0 +1,46 @@
+/**
+ * Render engine messages to a compact plain-text transcript for the compactor
+ * window, and account their tokens. Reuses the existing context-xray token
+ * accounting so OM thresholds match what the rest of the framework counts.
+ */
+import { countMessageTokens } from "../context-xray/tokenize.js";
+/** Flatten one engine message to a single labeled line block. */
+export function messageToText(message) {
+    const parts = [];
+    for (const part of message.content) {
+        if (part.type === "text" || part.type === "thinking") {
+            if (part.text.trim())
+                parts.push(part.text);
+        }
+        else if (part.type === "tool-call") {
+            parts.push(`[tool:${part.name}] ${safeJson(part.input)}`.trim());
+        }
+        else if (part.type === "tool-result") {
+            parts.push(`[tool-result] ${part.content}`.trim());
+        }
+        // image/file parts are intentionally omitted from the text window.
+    }
+    const body = parts.join("\n");
+    return body ? `${message.role}: ${body}` : "";
+}
+/** Render a contiguous window of messages to one text blob. */
+export function windowToText(messages) {
+    return messages
+        .map(messageToText)
+        .filter((line) => line.length > 0)
+        .join("\n\n");
+}
+/** Token count for a window of messages (reuses framework tokenizer). */
+export async function countWindowTokens(messages) {
+    const { tokens } = await countMessageTokens(messages);
+    return tokens;
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=message-text.js.map

package/dist/agent/observational-memory/message-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-text.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/message-text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,OAAsB;IAClD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACrD,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,mEAAmE;IACrE,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,QAAyB;IACpD,OAAO,QAAQ;SACZ,GAAG,CAAC,aAAa,CAAC;SAClB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;SACjC,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAyB;IAEzB,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC","sourcesContent":["/**\n * Render engine messages to a compact plain-text transcript for the compactor\n * window, and account their tokens. Reuses the existing context-xray token\n * accounting so OM thresholds match what the rest of the framework counts.\n */\n\nimport type { EngineMessage } from \"../engine/types.js\";\nimport { countMessageTokens } from \"../context-xray/tokenize.js\";\n\n/** Flatten one engine message to a single labeled line block. */\nexport function messageToText(message: EngineMessage): string {\n  const parts: string[] = [];\n  for (const part of message.content) {\n    if (part.type === \"text\" || part.type === \"thinking\") {\n      if (part.text.trim()) parts.push(part.text);\n    } else if (part.type === \"tool-call\") {\n      parts.push(`[tool:${part.name}] ${safeJson(part.input)}`.trim());\n    } else if (part.type === \"tool-result\") {\n      parts.push(`[tool-result] ${part.content}`.trim());\n    }\n    // image/file parts are intentionally omitted from the text window.\n  }\n  const body = parts.join(\"\\n\");\n  return body ? `${message.role}: ${body}` : \"\";\n}\n\n/** Render a contiguous window of messages to one text blob. */\nexport function windowToText(messages: EngineMessage[]): string {\n  return messages\n    .map(messageToText)\n    .filter((line) => line.length > 0)\n    .join(\"\\n\\n\");\n}\n\n/** Token count for a window of messages (reuses framework tokenizer). */\nexport async function countWindowTokens(\n  messages: EngineMessage[],\n): Promise<number> {\n  const { tokens } = await countMessageTokens(messages);\n  return tokens;\n}\n\nfunction safeJson(value: unknown): string {\n  try {\n    return JSON.stringify(value) ?? \"\";\n  } catch {\n    return \"\";\n  }\n}\n"]}

package/dist/agent/observational-memory/migrations.d.ts

@@ -0,0 +1,13 @@
+import type { MigrationEntry } from "../../db/migrations.js";
+/**
+ * Additive-only migrations for Observational Memory.
+ *
+ * These run under their OWN bookkeeping table (`_observational_memory_migrations`)
+ * so the version space is independent of core/org/context-xray — see
+ * `db/migrations.ts` for why each module owns its own version space.
+ *
+ * Strictly additive: a new table plus its hot-path indexes. Never drops,
+ * renames, or destructively alters anything.
+ */
+export declare const OBSERVATIONAL_MEMORY_MIGRATIONS: MigrationEntry[];
+//# sourceMappingURL=migrations.d.ts.map

package/dist/agent/observational-memory/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,cAAc,EA+B3D,CAAC"}

package/dist/agent/observational-memory/migrations.js

@@ -0,0 +1,43 @@
+/**
+ * Additive-only migrations for Observational Memory.
+ *
+ * These run under their OWN bookkeeping table (`_observational_memory_migrations`)
+ * so the version space is independent of core/org/context-xray — see
+ * `db/migrations.ts` for why each module owns its own version space.
+ *
+ * Strictly additive: a new table plus its hot-path indexes. Never drops,
+ * renames, or destructively alters anything.
+ */
+export const OBSERVATIONAL_MEMORY_MIGRATIONS = [
+    {
+        version: 1,
+        sql: `CREATE TABLE IF NOT EXISTS observational_memory (
+      id TEXT PRIMARY KEY,
+      thread_id TEXT NOT NULL,
+      tier TEXT NOT NULL,
+      text TEXT NOT NULL,
+      token_estimate INTEGER NOT NULL DEFAULT 0,
+      source_start_index INTEGER,
+      source_end_index INTEGER,
+      source_message_count INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private'
+    )`,
+    },
+    {
+        // Hot path: read a thread's entries of a given tier, ordered by recency.
+        version: 2,
+        sql: `CREATE INDEX IF NOT EXISTS observational_memory_thread_tier_idx
+      ON observational_memory(thread_id, tier, created_at)`,
+    },
+    {
+        // Hot path: owner-scoped reads for ownable-table access checks.
+        version: 3,
+        sql: `CREATE INDEX IF NOT EXISTS observational_memory_thread_owner_idx
+      ON observational_memory(thread_id, owner_email)`,
+    },
+];
+//# sourceMappingURL=migrations.js.map

package/dist/agent/observational-memory/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/migrations.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAqB;IAC/D;QACE,OAAO,EAAE,CAAC;QACV,GAAG,EAAE;;;;;;;;;;;;;;MAcH;KACH;IACD;QACE,yEAAyE;QACzE,OAAO,EAAE,CAAC;QACV,GAAG,EAAE;2DACkD;KACxD;IACD;QACE,gEAAgE;QAChE,OAAO,EAAE,CAAC;QACV,GAAG,EAAE;sDAC6C;KACnD;CACF,CAAC","sourcesContent":["import type { MigrationEntry } from \"../../db/migrations.js\";\n\n/**\n * Additive-only migrations for Observational Memory.\n *\n * These run under their OWN bookkeeping table (`_observational_memory_migrations`)\n * so the version space is independent of core/org/context-xray — see\n * `db/migrations.ts` for why each module owns its own version space.\n *\n * Strictly additive: a new table plus its hot-path indexes. Never drops,\n * renames, or destructively alters anything.\n */\nexport const OBSERVATIONAL_MEMORY_MIGRATIONS: MigrationEntry[] = [\n  {\n    version: 1,\n    sql: `CREATE TABLE IF NOT EXISTS observational_memory (\n      id TEXT PRIMARY KEY,\n      thread_id TEXT NOT NULL,\n      tier TEXT NOT NULL,\n      text TEXT NOT NULL,\n      token_estimate INTEGER NOT NULL DEFAULT 0,\n      source_start_index INTEGER,\n      source_end_index INTEGER,\n      source_message_count INTEGER NOT NULL DEFAULT 0,\n      created_at INTEGER NOT NULL,\n      updated_at INTEGER NOT NULL,\n      owner_email TEXT NOT NULL DEFAULT 'local@localhost',\n      org_id TEXT,\n      visibility TEXT NOT NULL DEFAULT 'private'\n    )`,\n  },\n  {\n    // Hot path: read a thread's entries of a given tier, ordered by recency.\n    version: 2,\n    sql: `CREATE INDEX IF NOT EXISTS observational_memory_thread_tier_idx\n      ON observational_memory(thread_id, tier, created_at)`,\n  },\n  {\n    // Hot path: owner-scoped reads for ownable-table access checks.\n    version: 3,\n    sql: `CREATE INDEX IF NOT EXISTS observational_memory_thread_owner_idx\n      ON observational_memory(thread_id, owner_email)`,\n  },\n];\n"]}

package/dist/agent/observational-memory/observer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Observer.
+ *
+ * When a thread's UNOBSERVED messages exceed the observation token threshold,
+ * the Observer runs ONE internal (tool-less) agent call to compress that window
+ * into a dense, dated observation log, persists it as a `tier: "observation"`
+ * entry, and marks those messages observed (recorded via the entry's
+ * `sourceEndIndex`, which `getObservedThroughIndex` reads back).
+ *
+ * It does NOT touch the agent loop — the internal call goes through the shared
+ * `runInternalAgentCall` seam (provider-agnostic, mockable).
+ */
+import type { EngineMessage } from "../engine/types.js";
+import { type ObservationalMemoryConfig } from "./config.js";
+import { type InternalAgentRunFn } from "./internal-run.js";
+import type { ObservationalMemoryEntry, ObservationalMemoryOwner } from "./types.js";
+export interface RunObserverOptions extends ObservationalMemoryOwner {
+    threadId: string;
+    /** The full, ordered thread messages. */
+    messages: EngineMessage[];
+    config?: Partial<ObservationalMemoryConfig>;
+    /** Internal-run seam — defaults to the real one; injected in tests. */
+    runInternal?: InternalAgentRunFn;
+}
+export interface RunObserverResult {
+    /** True when an observation was produced and persisted. */
+    observed: boolean;
+    entry?: ObservationalMemoryEntry;
+    /** Tokens in the unobserved window that was considered. */
+    unobservedTokens: number;
+}
+/**
+ * Compact a thread's unobserved tail into an observation IF it exceeds the
+ * token threshold; otherwise no-op.
+ */
+export declare function runObserver(options: RunObserverOptions): Promise<RunObserverResult>;
+//# sourceMappingURL=observer.d.ts.map

package/dist/agent/observational-memory/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,aAAa,CAAC;AAMrB,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAmB,SAAQ,wBAAwB;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAC5C,uEAAuE;IACvE,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,wBAAwB,CAAC;IACjC,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAqE5B"}

package/dist/agent/observational-memory/observer.js

@@ -0,0 +1,82 @@
+/**
+ * The Observer.
+ *
+ * When a thread's UNOBSERVED messages exceed the observation token threshold,
+ * the Observer runs ONE internal (tool-less) agent call to compress that window
+ * into a dense, dated observation log, persists it as a `tier: "observation"`
+ * entry, and marks those messages observed (recorded via the entry's
+ * `sourceEndIndex`, which `getObservedThroughIndex` reads back).
+ *
+ * It does NOT touch the agent loop — the internal call goes through the shared
+ * `runInternalAgentCall` seam (provider-agnostic, mockable).
+ */
+import { countTextTokens } from "../context-xray/tokenize.js";
+import { resolveObservationalMemoryConfig, } from "./config.js";
+import { getObservedThroughIndex, insertObservationalMemory, listObservationalMemory, } from "./store.js";
+import { runInternalAgentCall, } from "./internal-run.js";
+import { countWindowTokens, windowToText } from "./message-text.js";
+import { OBSERVER_SYSTEM_PROMPT, buildObserverPrompt } from "./prompts.js";
+/**
+ * Compact a thread's unobserved tail into an observation IF it exceeds the
+ * token threshold; otherwise no-op.
+ */
+export async function runObserver(options) {
+    const config = resolveObservationalMemoryConfig(options.config);
+    const owner = {
+        ownerEmail: options.ownerEmail,
+        orgId: options.orgId ?? null,
+    };
+    const observedThrough = await getObservedThroughIndex({
+        ...owner,
+        threadId: options.threadId,
+    });
+    const startIndex = observedThrough + 1;
+    const unobserved = options.messages.slice(startIndex);
+    if (unobserved.length === 0) {
+        return { observed: false, unobservedTokens: 0 };
+    }
+    const unobservedTokens = await countWindowTokens(unobserved);
+    if (unobservedTokens < config.observationTokenThreshold) {
+        return { observed: false, unobservedTokens };
+    }
+    const windowText = windowToText(unobserved);
+    if (!windowText.trim()) {
+        return { observed: false, unobservedTokens };
+    }
+    // Feed prior observations as continuity context so the new log doesn't repeat
+    // already-compacted history.
+    const priorObservations = (await listObservationalMemory({
+        ...owner,
+        threadId: options.threadId,
+        tier: "observation",
+    }))
+        .map((entry) => entry.text)
+        .join("\n\n");
+    const run = options.runInternal ?? runInternalAgentCall;
+    const observationText = await run({
+        systemPrompt: OBSERVER_SYSTEM_PROMPT,
+        prompt: buildObserverPrompt({
+            threadId: options.threadId,
+            windowText,
+            priorObservations,
+        }),
+        maxOutputTokens: config.observationMaxOutputTokens,
+    });
+    if (!observationText.trim()) {
+        return { observed: false, unobservedTokens };
+    }
+    const { tokens: tokenEstimate } = await countTextTokens(observationText);
+    const endIndex = options.messages.length - 1;
+    const entry = await insertObservationalMemory({
+        ...owner,
+        threadId: options.threadId,
+        tier: "observation",
+        text: observationText,
+        tokenEstimate,
+        sourceStartIndex: startIndex,
+        sourceEndIndex: endIndex,
+        sourceMessageCount: unobserved.length,
+    });
+    return { observed: true, entry, unobservedTokens };
+}
+//# sourceMappingURL=observer.js.map

package/dist/agent/observational-memory/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EACL,gCAAgC,GAEjC,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,GAErB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAuB3E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAA2B;IAE3B,MAAM,MAAM,GAAG,gCAAgC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,MAAM,KAAK,GAA6B;QACtC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI;KAC7B,CAAC;IAEF,MAAM,eAAe,GAAG,MAAM,uBAAuB,CAAC;QACpD,GAAG,KAAK;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,eAAe,GAAG,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACtD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC,EAAE,CAAC;IAClD,CAAC;IAED,MAAM,gBAAgB,GAAG,MAAM,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC7D,IAAI,gBAAgB,GAAG,MAAM,CAAC,yBAAyB,EAAE,CAAC;QACxD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;QACvB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC/C,CAAC;IAED,8EAA8E;IAC9E,6BAA6B;IAC7B,MAAM,iBAAiB,GAAG,CACxB,MAAM,uBAAuB,CAAC;QAC5B,GAAG,KAAK;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,aAAa;KACpB,CAAC,CACH;SACE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IACxD,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC;QAChC,YAAY,EAAE,sBAAsB;QACpC,MAAM,EAAE,mBAAmB,CAAC;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,UAAU;YACV,iBAAiB;SAClB,CAAC;QACF,eAAe,EAAE,MAAM,CAAC,0BAA0B;KACnD,CAAC,CAAC;IAEH,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,eAAe,CAAC,eAAe,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAE7C,MAAM,KAAK,GAAG,MAAM,yBAAyB,CAAC;QAC5C,GAAG,KAAK;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,eAAe;QACrB,aAAa;QACb,gBAAgB,EAAE,UAAU;QAC5B,cAAc,EAAE,QAAQ;QACxB,kBAAkB,EAAE,UAAU,CAAC,MAAM;KACtC,CAAC,CAAC;IAEH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;AACrD,CAAC","sourcesContent":["/**\n * The Observer.\n *\n * When a thread's UNOBSERVED messages exceed the observation token threshold,\n * the Observer runs ONE internal (tool-less) agent call to compress that window\n * into a dense, dated observation log, persists it as a `tier: \"observation\"`\n * entry, and marks those messages observed (recorded via the entry's\n * `sourceEndIndex`, which `getObservedThroughIndex` reads back).\n *\n * It does NOT touch the agent loop — the internal call goes through the shared\n * `runInternalAgentCall` seam (provider-agnostic, mockable).\n */\n\nimport type { EngineMessage } from \"../engine/types.js\";\nimport { countTextTokens } from \"../context-xray/tokenize.js\";\nimport {\n  resolveObservationalMemoryConfig,\n  type ObservationalMemoryConfig,\n} from \"./config.js\";\nimport {\n  getObservedThroughIndex,\n  insertObservationalMemory,\n  listObservationalMemory,\n} from \"./store.js\";\nimport {\n  runInternalAgentCall,\n  type InternalAgentRunFn,\n} from \"./internal-run.js\";\nimport { countWindowTokens, windowToText } from \"./message-text.js\";\nimport { OBSERVER_SYSTEM_PROMPT, buildObserverPrompt } from \"./prompts.js\";\nimport type {\n  ObservationalMemoryEntry,\n  ObservationalMemoryOwner,\n} from \"./types.js\";\n\nexport interface RunObserverOptions extends ObservationalMemoryOwner {\n  threadId: string;\n  /** The full, ordered thread messages. */\n  messages: EngineMessage[];\n  config?: Partial<ObservationalMemoryConfig>;\n  /** Internal-run seam — defaults to the real one; injected in tests. */\n  runInternal?: InternalAgentRunFn;\n}\n\nexport interface RunObserverResult {\n  /** True when an observation was produced and persisted. */\n  observed: boolean;\n  entry?: ObservationalMemoryEntry;\n  /** Tokens in the unobserved window that was considered. */\n  unobservedTokens: number;\n}\n\n/**\n * Compact a thread's unobserved tail into an observation IF it exceeds the\n * token threshold; otherwise no-op.\n */\nexport async function runObserver(\n  options: RunObserverOptions,\n): Promise<RunObserverResult> {\n  const config = resolveObservationalMemoryConfig(options.config);\n  const owner: ObservationalMemoryOwner = {\n    ownerEmail: options.ownerEmail,\n    orgId: options.orgId ?? null,\n  };\n\n  const observedThrough = await getObservedThroughIndex({\n    ...owner,\n    threadId: options.threadId,\n  });\n  const startIndex = observedThrough + 1;\n  const unobserved = options.messages.slice(startIndex);\n  if (unobserved.length === 0) {\n    return { observed: false, unobservedTokens: 0 };\n  }\n\n  const unobservedTokens = await countWindowTokens(unobserved);\n  if (unobservedTokens < config.observationTokenThreshold) {\n    return { observed: false, unobservedTokens };\n  }\n\n  const windowText = windowToText(unobserved);\n  if (!windowText.trim()) {\n    return { observed: false, unobservedTokens };\n  }\n\n  // Feed prior observations as continuity context so the new log doesn't repeat\n  // already-compacted history.\n  const priorObservations = (\n    await listObservationalMemory({\n      ...owner,\n      threadId: options.threadId,\n      tier: \"observation\",\n    })\n  )\n    .map((entry) => entry.text)\n    .join(\"\\n\\n\");\n\n  const run = options.runInternal ?? runInternalAgentCall;\n  const observationText = await run({\n    systemPrompt: OBSERVER_SYSTEM_PROMPT,\n    prompt: buildObserverPrompt({\n      threadId: options.threadId,\n      windowText,\n      priorObservations,\n    }),\n    maxOutputTokens: config.observationMaxOutputTokens,\n  });\n\n  if (!observationText.trim()) {\n    return { observed: false, unobservedTokens };\n  }\n\n  const { tokens: tokenEstimate } = await countTextTokens(observationText);\n  const endIndex = options.messages.length - 1;\n\n  const entry = await insertObservationalMemory({\n    ...owner,\n    threadId: options.threadId,\n    tier: \"observation\",\n    text: observationText,\n    tokenEstimate,\n    sourceStartIndex: startIndex,\n    sourceEndIndex: endIndex,\n    sourceMessageCount: unobserved.length,\n  });\n\n  return { observed: true, entry, unobservedTokens };\n}\n"]}

package/dist/agent/observational-memory/plugin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Nitro plugin that applies the Observational Memory migrations under its own
+ * bookkeeping table. Mirrors `context-xray/plugin.ts`.
+ *
+ * NOT YET registered in the default plugin set — registering it means editing
+ * shared bootstrap files (server/framework-request-handler.ts,
+ * deploy/route-discovery.ts), which is deferred to the same follow-up that
+ * wires `buildObservationalContext` into production-agent.ts. Until then the
+ * store's `ensureTable()` creates the table lazily on first use, so OM is fully
+ * functional without the plugin.
+ */
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+export declare function createObservationalMemoryPlugin(): NitroPluginDef;
+export declare const defaultObservationalMemoryPlugin: NitroPluginDef;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/agent/observational-memory/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,IAAI,cAAc,CAUhE;AAED,eAAO,MAAM,gCAAgC,EAAE,cACZ,CAAC"}

package/dist/agent/observational-memory/plugin.js

@@ -0,0 +1,26 @@
+/**
+ * Nitro plugin that applies the Observational Memory migrations under its own
+ * bookkeeping table. Mirrors `context-xray/plugin.ts`.
+ *
+ * NOT YET registered in the default plugin set — registering it means editing
+ * shared bootstrap files (server/framework-request-handler.ts,
+ * deploy/route-discovery.ts), which is deferred to the same follow-up that
+ * wires `buildObservationalContext` into production-agent.ts. Until then the
+ * store's `ensureTable()` creates the table lazily on first use, so OM is fully
+ * functional without the plugin.
+ */
+import { awaitBootstrap, markDefaultPluginProvided, } from "../../server/framework-request-handler.js";
+import { runMigrations } from "../../db/migrations.js";
+import { OBSERVATIONAL_MEMORY_MIGRATIONS } from "./migrations.js";
+export function createObservationalMemoryPlugin() {
+    const migrate = runMigrations(OBSERVATIONAL_MEMORY_MIGRATIONS, {
+        table: "_observational_memory_migrations",
+    });
+    return async (nitroApp) => {
+        markDefaultPluginProvided(nitroApp, "observational-memory");
+        await awaitBootstrap(nitroApp);
+        await migrate(nitroApp);
+    };
+}
+export const defaultObservationalMemoryPlugin = createObservationalMemoryPlugin();
+//# sourceMappingURL=plugin.js.map

package/dist/agent/observational-memory/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,cAAc,EACd,yBAAyB,GAC1B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAIlE,MAAM,UAAU,+BAA+B;IAC7C,MAAM,OAAO,GAAG,aAAa,CAAC,+BAA+B,EAAE;QAC7D,KAAK,EAAE,kCAAkC;KAC1C,CAAC,CAAC;IAEH,OAAO,KAAK,EAAE,QAAa,EAAE,EAAE;QAC7B,yBAAyB,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC;QAC5D,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC/B,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,gCAAgC,GAC3C,+BAA+B,EAAE,CAAC","sourcesContent":["/**\n * Nitro plugin that applies the Observational Memory migrations under its own\n * bookkeeping table. Mirrors `context-xray/plugin.ts`.\n *\n * NOT YET registered in the default plugin set — registering it means editing\n * shared bootstrap files (server/framework-request-handler.ts,\n * deploy/route-discovery.ts), which is deferred to the same follow-up that\n * wires `buildObservationalContext` into production-agent.ts. Until then the\n * store's `ensureTable()` creates the table lazily on first use, so OM is fully\n * functional without the plugin.\n */\n\nimport {\n  awaitBootstrap,\n  markDefaultPluginProvided,\n} from \"../../server/framework-request-handler.js\";\nimport { runMigrations } from \"../../db/migrations.js\";\nimport { OBSERVATIONAL_MEMORY_MIGRATIONS } from \"./migrations.js\";\n\ntype NitroPluginDef = (nitroApp: any) => void | Promise<void>;\n\nexport function createObservationalMemoryPlugin(): NitroPluginDef {\n  const migrate = runMigrations(OBSERVATIONAL_MEMORY_MIGRATIONS, {\n    table: \"_observational_memory_migrations\",\n  });\n\n  return async (nitroApp: any) => {\n    markDefaultPluginProvided(nitroApp, \"observational-memory\");\n    await awaitBootstrap(nitroApp);\n    await migrate(nitroApp);\n  };\n}\n\nexport const defaultObservationalMemoryPlugin: NitroPluginDef =\n  createObservationalMemoryPlugin();\n"]}

package/dist/agent/observational-memory/prompts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * System prompts for the Observer and Reflector compaction passes.
+ *
+ * Both prompts insist on DATED output and preservation of task status, names,
+ * dates, and decisions — the facts a long autonomous run rots and loses. The
+ * compacted text replaces raw turns in the prompt, so it must stay dense,
+ * factual, and chronological rather than narrative.
+ */
+export declare const OBSERVER_SYSTEM_PROMPT = "You are the Observer for a long-running agent thread. You compress a span of raw conversation into a single DENSE, DATED observation log that will REPLACE those raw messages in future context.\n\nRules:\n- Output a chronological, bulleted log. Prefix entries with a date/time when one is present in the source.\n- Preserve precisely: task status (what is done / in progress / blocked / decided), proper names (people, files, functions, repos, branches, IDs), exact dates, numbers, and decisions with their rationale.\n- Preserve unresolved questions, TODOs, and error states verbatim enough to act on later.\n- Drop pleasantries, restated context, and redundant tool chatter. Never invent facts.\n- Be terse. This is a memory record, not prose. No preamble, no summary-of-summary, just the log.";
+export declare const REFLECTOR_SYSTEM_PROMPT = "You are the Reflector for a long-running agent thread. You condense an existing log of dated OBSERVATIONS into a smaller set of higher-level REFLECTIONS that will sit above the observations in future context.\n\nRules:\n- Roll many low-level observations up into durable, higher-level statements: overall goal and current status, key decisions and why, stable facts (names, identifiers, constraints), and open threads.\n- Keep dates on anything time-sensitive. Keep proper names and identifiers exact.\n- Do not lose any still-open task, blocker, or unresolved decision.\n- Be terse and factual. Output a chronological/thematic bulleted list. No preamble.";
+/**
+ * Build the Observer user prompt for a window of raw thread text.
+ */
+export declare function buildObserverPrompt(input: {
+    threadId: string;
+    windowText: string;
+    priorObservations?: string;
+}): string;
+/**
+ * Build the Reflector user prompt over the current observation log.
+ */
+export declare function buildReflectorPrompt(input: {
+    threadId: string;
+    observationsText: string;
+    priorReflections?: string;
+}): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/agent/observational-memory/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,sBAAsB,+xBAO+D,CAAC;AAEnG,eAAO,MAAM,uBAAuB,opBAMgD,CAAC;AAErF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,MAAM,CAKT;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAKT"}