@agent-native/core 0.51.15 → 0.53.0

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":"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","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"}

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

@@ -0,0 +1,42 @@
+/**
+ * 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 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.
+
+Rules:
+- Output a chronological, bulleted log. Prefix entries with a date/time when one is present in the source.
+- 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.
+- Preserve unresolved questions, TODOs, and error states verbatim enough to act on later.
+- Drop pleasantries, restated context, and redundant tool chatter. Never invent facts.
+- Be terse. This is a memory record, not prose. No preamble, no summary-of-summary, just the log.`;
+export 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.
+
+Rules:
+- 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.
+- Keep dates on anything time-sensitive. Keep proper names and identifiers exact.
+- Do not lose any still-open task, blocker, or unresolved decision.
+- 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 function buildObserverPrompt(input) {
+    const prior = input.priorObservations?.trim()
+        ? `Existing observation log (for continuity — do NOT repeat it, only summarize the NEW messages below):\n${input.priorObservations.trim()}\n\n`
+        : "";
+    return `${prior}New raw messages to compress into the observation log (thread ${input.threadId}):\n\n${input.windowText}`;
+}
+/**
+ * Build the Reflector user prompt over the current observation log.
+ */
+export function buildReflectorPrompt(input) {
+    const prior = input.priorReflections?.trim()
+        ? `Existing reflections (for continuity — refine/extend, do not duplicate):\n${input.priorReflections.trim()}\n\n`
+        : "";
+    return `${prior}Observation log to condense into higher-level reflections (thread ${input.threadId}):\n\n${input.observationsText}`;
+}
+//# sourceMappingURL=prompts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;kGAO4D,CAAC;AAEnG,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;oFAM6C,CAAC;AAErF;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAInC;IACC,MAAM,KAAK,GAAG,KAAK,CAAC,iBAAiB,EAAE,IAAI,EAAE;QAC3C,CAAC,CAAC,yGAAyG,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM;QAC/I,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,GAAG,KAAK,iEAAiE,KAAK,CAAC,QAAQ,SAAS,KAAK,CAAC,UAAU,EAAE,CAAC;AAC5H,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAIpC;IACC,MAAM,KAAK,GAAG,KAAK,CAAC,gBAAgB,EAAE,IAAI,EAAE;QAC1C,CAAC,CAAC,6EAA6E,KAAK,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM;QAClH,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,GAAG,KAAK,qEAAqE,KAAK,CAAC,QAAQ,SAAS,KAAK,CAAC,gBAAgB,EAAE,CAAC;AACtI,CAAC","sourcesContent":["/**\n * System prompts for the Observer and Reflector compaction passes.\n *\n * Both prompts insist on DATED output and preservation of task status, names,\n * dates, and decisions — the facts a long autonomous run rots and loses. The\n * compacted text replaces raw turns in the prompt, so it must stay dense,\n * factual, and chronological rather than narrative.\n */\n\nexport 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.`;\n\nexport 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.`;\n\n/**\n * Build the Observer user prompt for a window of raw thread text.\n */\nexport function buildObserverPrompt(input: {\n  threadId: string;\n  windowText: string;\n  priorObservations?: string;\n}): string {\n  const prior = input.priorObservations?.trim()\n    ? `Existing observation log (for continuity — do NOT repeat it, only summarize the NEW messages below):\\n${input.priorObservations.trim()}\\n\\n`\n    : \"\";\n  return `${prior}New raw messages to compress into the observation log (thread ${input.threadId}):\\n\\n${input.windowText}`;\n}\n\n/**\n * Build the Reflector user prompt over the current observation log.\n */\nexport function buildReflectorPrompt(input: {\n  threadId: string;\n  observationsText: string;\n  priorReflections?: string;\n}): string {\n  const prior = input.priorReflections?.trim()\n    ? `Existing reflections (for continuity — refine/extend, do not duplicate):\\n${input.priorReflections.trim()}\\n\\n`\n    : \"\";\n  return `${prior}Observation log to condense into higher-level reflections (thread ${input.threadId}):\\n\\n${input.observationsText}`;\n}\n"]}

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

@@ -0,0 +1,47 @@
+/**
+ * Read API for Observational Memory.
+ *
+ * `buildObservationalContext` assembles the three tiers — reflections (highest
+ * level) + observations (dense) + the recent raw message tail — into a single
+ * structure ready to fold into a prompt. It is intentionally NOT wired into
+ * production-agent.ts here; see the exported seam note below and the package
+ * barrel export so the wire-up is one call later.
+ *
+ * Token-cheap by construction: a long thread is represented by its compacted
+ * tiers plus only the last N raw turns, instead of the entire transcript.
+ */
+import type { EngineMessage } from "../engine/types.js";
+import { type ObservationalMemoryConfig } from "./config.js";
+import type { ObservationalContext, ObservationalMemoryOwner } from "./types.js";
+export interface BuildObservationalContextOptions extends ObservationalMemoryOwner {
+    threadId: string;
+    /** The full, ordered thread messages — the recent tail is taken from here. */
+    messages: EngineMessage[];
+    config?: Partial<ObservationalMemoryConfig>;
+}
+/**
+ * SEAM (deferred wire-up): build the three-tier Observational Memory context
+ * for a thread. The returned tiers are ready to be injected into the turn's
+ * prompt assembly.
+ *
+ * TODO(charlie-merge): inject buildObservationalContext output into the turn
+ * context assembly in production-agent.ts once the lazy-skill context changes
+ * land. The intended shape: replace the older raw-message prefix (everything
+ * before `recentMessages`) with the `reflections` + `observations` text, keep
+ * `recentMessages` verbatim, and prepend a short "Observational Memory" system
+ * section. This module deliberately does not edit production-agent.ts.
+ */
+/** True when this thread has at least one persisted observation or reflection. */
+export declare function hasObservationalMemory(context: ObservationalContext): boolean;
+/**
+ * Serialize the reflections + observations tiers into a single, clearly
+ * delimited prompt block. The recent-raw-message tail is NOT serialized here —
+ * it stays as verbatim engine messages — so this block represents only the
+ * compacted older history that replaces the raw prefix.
+ *
+ * Returns an empty string when there is nothing compacted yet, so callers can
+ * cheaply skip injection for short threads.
+ */
+export declare function serializeObservationalMemoryBlock(context: ObservationalContext): string;
+export declare function buildObservationalContext(options: BuildObservationalContextOptions): Promise<ObservationalContext>;
+//# sourceMappingURL=read.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EACV,oBAAoB,EAEpB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gCAAiC,SAAQ,wBAAwB;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC7C;AAMD;;;;;;;;;;;GAWG;AACH,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAuBR;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAwC/B"}