@agent-native/core 0.52.0 → 0.54.0

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

@@ -0,0 +1,48 @@
+import { table, text, integer, ownableColumns } from "../../db/schema.js";
+/**
+ * Observational Memory (OM) entries.
+ *
+ * A long-running agent thread is compacted in the background into a dated,
+ * three-tier context so it costs far fewer tokens and stays prompt-cache
+ * stable:
+ *
+ *   recent raw messages  →  dense "observations"  →  higher-level "reflections"
+ *
+ * Each row is ONE compaction artifact for a thread:
+ *
+ * - `tier = "observation"` — a dense, dated digest of a contiguous range of
+ *   thread messages (task status, names, dates, decisions preserved). Produced
+ *   by the Observer once a thread's unobserved messages exceed a token
+ *   threshold.
+ * - `tier = "reflection"` — a higher-level condensation OVER observations,
+ *   produced by the Reflector once the observation log itself grows past its
+ *   own threshold.
+ *
+ * The table is ownable (scoped reads/writes via `accessFilter`/`assertAccess`
+ * per the `security` skill) and dialect-agnostic (Drizzle helpers from
+ * `db/schema`, never raw SQLite types). The companion migrations live in
+ * `./migrations.ts` and are additive-only.
+ */
+export const observationalMemory = table("observational_memory", {
+    id: text("id").primaryKey(),
+    threadId: text("thread_id").notNull(),
+    /** Which tier this entry belongs to. */
+    tier: text("tier", { enum: ["observation", "reflection"] }).notNull(),
+    /** The dated, compacted text content of this entry. */
+    text: text("text").notNull(),
+    /** Estimated token count of `text` (used for the reflection threshold). */
+    tokenEstimate: integer("token_estimate").notNull().default(0),
+    /**
+     * Inclusive index range of the source thread messages this entry summarizes.
+     * For observations these are indices into the flattened thread-message array;
+     * for reflections they span the observation indices that were folded.
+     */
+    sourceStartIndex: integer("source_start_index"),
+    sourceEndIndex: integer("source_end_index"),
+    /** How many source messages/observations this entry covers. */
+    sourceMessageCount: integer("source_message_count").notNull().default(0),
+    createdAt: integer("created_at").notNull(),
+    updatedAt: integer("updated_at").notNull(),
+    ...ownableColumns(),
+});
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC,sBAAsB,EAAE;IAC/D,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE;IACrC,wCAAwC;IACxC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,aAAa,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE;IACrE,uDAAuD;IACvD,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,2EAA2E;IAC3E,aAAa,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7D;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC,oBAAoB,CAAC;IAC/C,cAAc,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAC3C,+DAA+D;IAC/D,kBAAkB,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IAC1C,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IAC1C,GAAG,cAAc,EAAE;CACpB,CAAC,CAAC","sourcesContent":["import { table, text, integer, ownableColumns } from \"../../db/schema.js\";\n\n/**\n * Observational Memory (OM) entries.\n *\n * A long-running agent thread is compacted in the background into a dated,\n * three-tier context so it costs far fewer tokens and stays prompt-cache\n * stable:\n *\n *   recent raw messages  →  dense \"observations\"  →  higher-level \"reflections\"\n *\n * Each row is ONE compaction artifact for a thread:\n *\n * - `tier = \"observation\"` — a dense, dated digest of a contiguous range of\n *   thread messages (task status, names, dates, decisions preserved). Produced\n *   by the Observer once a thread's unobserved messages exceed a token\n *   threshold.\n * - `tier = \"reflection\"` — a higher-level condensation OVER observations,\n *   produced by the Reflector once the observation log itself grows past its\n *   own threshold.\n *\n * The table is ownable (scoped reads/writes via `accessFilter`/`assertAccess`\n * per the `security` skill) and dialect-agnostic (Drizzle helpers from\n * `db/schema`, never raw SQLite types). The companion migrations live in\n * `./migrations.ts` and are additive-only.\n */\nexport const observationalMemory = table(\"observational_memory\", {\n  id: text(\"id\").primaryKey(),\n  threadId: text(\"thread_id\").notNull(),\n  /** Which tier this entry belongs to. */\n  tier: text(\"tier\", { enum: [\"observation\", \"reflection\"] }).notNull(),\n  /** The dated, compacted text content of this entry. */\n  text: text(\"text\").notNull(),\n  /** Estimated token count of `text` (used for the reflection threshold). */\n  tokenEstimate: integer(\"token_estimate\").notNull().default(0),\n  /**\n   * Inclusive index range of the source thread messages this entry summarizes.\n   * For observations these are indices into the flattened thread-message array;\n   * for reflections they span the observation indices that were folded.\n   */\n  sourceStartIndex: integer(\"source_start_index\"),\n  sourceEndIndex: integer(\"source_end_index\"),\n  /** How many source messages/observations this entry covers. */\n  sourceMessageCount: integer(\"source_message_count\").notNull().default(0),\n  createdAt: integer(\"created_at\").notNull(),\n  updatedAt: integer(\"updated_at\").notNull(),\n  ...ownableColumns(),\n});\n"]}

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

@@ -0,0 +1,52 @@
+/**
+ * Persistence for Observational Memory entries.
+ *
+ * Owner-scoped throughout: every read and write takes an `ownerEmail` and the
+ * SQL always filters by it, so the ownable table is never read or written
+ * cross-owner (per the `security` skill). Dialect-agnostic — only `getDbExec()`
+ * and parameterized SQL, never raw SQLite/Postgres types or string interpolation
+ * of user data.
+ *
+ * `ensureTable()` lazily creates the table on first use (the same belt-and-
+ * suspenders pattern as `chat-threads/store.ts`), so OM works in tests and at
+ * runtime even before the migration plugin is registered.
+ */
+import type { ObservationalMemoryEntry, ObservationalMemoryOwner, ObservationalMemoryTier } from "./types.js";
+/** Reset the cached ensureTable promise — test-only seam. */
+export declare function __resetObservationalMemoryTableCache(): void;
+export interface InsertObservationalMemoryInput extends ObservationalMemoryOwner {
+    threadId: string;
+    tier: ObservationalMemoryTier;
+    text: string;
+    tokenEstimate: number;
+    sourceStartIndex?: number | null;
+    sourceEndIndex?: number | null;
+    sourceMessageCount?: number;
+    visibility?: "private" | "org" | "public";
+}
+/** Insert one OM entry, returning the persisted row. */
+export declare function insertObservationalMemory(input: InsertObservationalMemoryInput): Promise<ObservationalMemoryEntry>;
+export interface ListObservationalMemoryOptions extends ObservationalMemoryOwner {
+    threadId: string;
+    /** When set, only entries of this tier are returned. */
+    tier?: ObservationalMemoryTier;
+}
+/**
+ * List a thread's OM entries for an owner, oldest → newest. Always
+ * owner-scoped; `org_id` is matched too when supplied so org-visible rows
+ * don't leak across orgs.
+ */
+export declare function listObservationalMemory(options: ListObservationalMemoryOptions): Promise<ObservationalMemoryEntry[]>;
+/**
+ * The highest source-message index already folded into an observation for this
+ * thread/owner, or -1 if none. The Observer uses this to know which messages
+ * are still unobserved.
+ */
+export declare function getObservedThroughIndex(options: ObservationalMemoryOwner & {
+    threadId: string;
+}): Promise<number>;
+/** Sum the token estimates of a thread's observation entries for an owner. */
+export declare function getObservationLogTokens(options: ObservationalMemoryOwner & {
+    threadId: string;
+}): Promise<number>;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AA0CpB,6DAA6D;AAC7D,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAqDD,MAAM,WAAW,8BAA+B,SAAQ,wBAAwB;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,uBAAuB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC;CAC3C;AAED,wDAAwD;AACxD,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,wBAAwB,CAAC,CAyCnC;AAED,MAAM,WAAW,8BAA+B,SAAQ,wBAAwB;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,IAAI,CAAC,EAAE,uBAAuB,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAiBrC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,wBAAwB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,8EAA8E;AAC9E,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,wBAAwB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,MAAM,CAAC,CAcjB"}

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

@@ -0,0 +1,197 @@
+/**
+ * Persistence for Observational Memory entries.
+ *
+ * Owner-scoped throughout: every read and write takes an `ownerEmail` and the
+ * SQL always filters by it, so the ownable table is never read or written
+ * cross-owner (per the `security` skill). Dialect-agnostic — only `getDbExec()`
+ * and parameterized SQL, never raw SQLite/Postgres types or string interpolation
+ * of user data.
+ *
+ * `ensureTable()` lazily creates the table on first use (the same belt-and-
+ * suspenders pattern as `chat-threads/store.ts`), so OM works in tests and at
+ * runtime even before the migration plugin is registered.
+ */
+import { getDbExec } from "../../db/client.js";
+import { isPostgres } from "../../db/client.js";
+let tableReady = null;
+async function ensureTable() {
+    if (tableReady)
+        return tableReady;
+    tableReady = (async () => {
+        const client = getDbExec();
+        const intType = isPostgres() ? "BIGINT" : "INTEGER";
+        await client.execute(`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 ${intType} NOT NULL DEFAULT 0,
+        source_start_index ${intType},
+        source_end_index ${intType},
+        source_message_count ${intType} NOT NULL DEFAULT 0,
+        created_at ${intType} NOT NULL,
+        updated_at ${intType} NOT NULL,
+        owner_email TEXT NOT NULL,
+        org_id TEXT,
+        visibility TEXT NOT NULL DEFAULT 'private'
+      )`);
+        await client.execute(`CREATE INDEX IF NOT EXISTS observational_memory_thread_tier_idx
+        ON observational_memory(thread_id, tier, created_at)`);
+        await client.execute(`CREATE INDEX IF NOT EXISTS observational_memory_thread_owner_idx
+        ON observational_memory(thread_id, owner_email)`);
+    })().catch((err) => {
+        // Reset so a transient failure (e.g. SQLITE_BUSY on HMR) can retry.
+        tableReady = null;
+        throw err;
+    });
+    return tableReady;
+}
+/** Reset the cached ensureTable promise — test-only seam. */
+export function __resetObservationalMemoryTableCache() {
+    tableReady = null;
+}
+function entryId() {
+    return `om-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function numOrNull(value) {
+    if (value === null || value === undefined)
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+function rowToEntry(row) {
+    const ownerEmail = typeof row.owner_email === "string" && row.owner_email.trim()
+        ? row.owner_email
+        : null;
+    if (!ownerEmail) {
+        throw new Error("Observational memory row is missing owner_email.");
+    }
+    return {
+        id: String(row.id),
+        threadId: String(row.thread_id),
+        tier: row.tier,
+        text: typeof row.text === "string" ? row.text : "",
+        tokenEstimate: Number(row.token_estimate) || 0,
+        sourceStartIndex: numOrNull(row.source_start_index),
+        sourceEndIndex: numOrNull(row.source_end_index),
+        sourceMessageCount: Number(row.source_message_count) || 0,
+        createdAt: Number(row.created_at) || 0,
+        updatedAt: Number(row.updated_at) || 0,
+        ownerEmail,
+        orgId: typeof row.org_id === "string" ? row.org_id : null,
+        visibility: row.visibility ?? "private",
+    };
+}
+function addOwnerScope(clauses, args, owner) {
+    clauses.push("owner_email = ?");
+    args.push(owner.ownerEmail);
+    if (owner.orgId == null) {
+        clauses.push("org_id IS NULL");
+    }
+    else {
+        clauses.push("org_id = ?");
+        args.push(owner.orgId);
+    }
+}
+/** Insert one OM entry, returning the persisted row. */
+export async function insertObservationalMemory(input) {
+    await ensureTable();
+    const client = getDbExec();
+    const now = Date.now();
+    const id = entryId();
+    const entry = {
+        id,
+        threadId: input.threadId,
+        tier: input.tier,
+        text: input.text,
+        tokenEstimate: input.tokenEstimate,
+        sourceStartIndex: input.sourceStartIndex ?? null,
+        sourceEndIndex: input.sourceEndIndex ?? null,
+        sourceMessageCount: input.sourceMessageCount ?? 0,
+        createdAt: now,
+        updatedAt: now,
+        ownerEmail: input.ownerEmail,
+        orgId: input.orgId ?? null,
+        visibility: input.visibility ?? "private",
+    };
+    await client.execute({
+        sql: `INSERT INTO observational_memory
+      (id, thread_id, tier, text, token_estimate, source_start_index, source_end_index, source_message_count, created_at, updated_at, owner_email, org_id, visibility)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        args: [
+            entry.id,
+            entry.threadId,
+            entry.tier,
+            entry.text,
+            entry.tokenEstimate,
+            entry.sourceStartIndex,
+            entry.sourceEndIndex,
+            entry.sourceMessageCount,
+            entry.createdAt,
+            entry.updatedAt,
+            entry.ownerEmail,
+            entry.orgId,
+            entry.visibility,
+        ],
+    });
+    return entry;
+}
+/**
+ * List a thread's OM entries for an owner, oldest → newest. Always
+ * owner-scoped; `org_id` is matched too when supplied so org-visible rows
+ * don't leak across orgs.
+ */
+export async function listObservationalMemory(options) {
+    await ensureTable();
+    const client = getDbExec();
+    const clauses = ["thread_id = ?"];
+    const args = [options.threadId];
+    addOwnerScope(clauses, args, options);
+    if (options.tier) {
+        clauses.push("tier = ?");
+        args.push(options.tier);
+    }
+    const result = await client.execute({
+        sql: `SELECT * FROM observational_memory WHERE ${clauses.join(" AND ")} ORDER BY created_at ASC, id ASC`,
+        args,
+    });
+    return result.rows.map(rowToEntry);
+}
+/**
+ * The highest source-message index already folded into an observation for this
+ * thread/owner, or -1 if none. The Observer uses this to know which messages
+ * are still unobserved.
+ */
+export async function getObservedThroughIndex(options) {
+    await ensureTable();
+    const client = getDbExec();
+    const clauses = ["thread_id = ?", "tier = 'observation'"];
+    const args = [options.threadId];
+    addOwnerScope(clauses, args, options);
+    const result = await client.execute({
+        sql: `SELECT MAX(source_end_index) AS max_idx
+      FROM observational_memory
+      WHERE ${clauses.join(" AND ")}`,
+        args,
+    });
+    const row = result.rows[0];
+    const max = numOrNull(row?.max_idx);
+    return max == null ? -1 : max;
+}
+/** Sum the token estimates of a thread's observation entries for an owner. */
+export async function getObservationLogTokens(options) {
+    await ensureTable();
+    const client = getDbExec();
+    const clauses = ["thread_id = ?", "tier = 'observation'"];
+    const args = [options.threadId];
+    addOwnerScope(clauses, args, options);
+    const result = await client.execute({
+        sql: `SELECT COALESCE(SUM(token_estimate), 0) AS total
+      FROM observational_memory
+      WHERE ${clauses.join(" AND ")}`,
+        args,
+    });
+    const row = result.rows[0];
+    return Number(row?.total) || 0;
+}
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Persistence for Observational Memory entries.\n *\n * Owner-scoped throughout: every read and write takes an `ownerEmail` and the\n * SQL always filters by it, so the ownable table is never read or written\n * cross-owner (per the `security` skill). Dialect-agnostic — only `getDbExec()`\n * and parameterized SQL, never raw SQLite/Postgres types or string interpolation\n * of user data.\n *\n * `ensureTable()` lazily creates the table on first use (the same belt-and-\n * suspenders pattern as `chat-threads/store.ts`), so OM works in tests and at\n * runtime even before the migration plugin is registered.\n */\n\nimport { getDbExec } from \"../../db/client.js\";\nimport { isPostgres } from \"../../db/client.js\";\nimport type {\n  ObservationalMemoryEntry,\n  ObservationalMemoryOwner,\n  ObservationalMemoryTier,\n} from \"./types.js\";\n\nlet tableReady: Promise<void> | null = null;\n\nasync function ensureTable(): Promise<void> {\n  if (tableReady) return tableReady;\n  tableReady = (async () => {\n    const client = getDbExec();\n    const intType = isPostgres() ? \"BIGINT\" : \"INTEGER\";\n    await client.execute(\n      `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 ${intType} NOT NULL DEFAULT 0,\n        source_start_index ${intType},\n        source_end_index ${intType},\n        source_message_count ${intType} NOT NULL DEFAULT 0,\n        created_at ${intType} NOT NULL,\n        updated_at ${intType} NOT NULL,\n        owner_email TEXT NOT NULL,\n        org_id TEXT,\n        visibility TEXT NOT NULL DEFAULT 'private'\n      )`,\n    );\n    await client.execute(\n      `CREATE INDEX IF NOT EXISTS observational_memory_thread_tier_idx\n        ON observational_memory(thread_id, tier, created_at)`,\n    );\n    await client.execute(\n      `CREATE INDEX IF NOT EXISTS observational_memory_thread_owner_idx\n        ON observational_memory(thread_id, owner_email)`,\n    );\n  })().catch((err) => {\n    // Reset so a transient failure (e.g. SQLITE_BUSY on HMR) can retry.\n    tableReady = null;\n    throw err;\n  });\n  return tableReady;\n}\n\n/** Reset the cached ensureTable promise — test-only seam. */\nexport function __resetObservationalMemoryTableCache(): void {\n  tableReady = null;\n}\n\nfunction entryId(): string {\n  return `om-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;\n}\n\nfunction numOrNull(value: unknown): number | null {\n  if (value === null || value === undefined) return null;\n  const n = Number(value);\n  return Number.isFinite(n) ? n : null;\n}\n\nfunction rowToEntry(row: Record<string, unknown>): ObservationalMemoryEntry {\n  const ownerEmail =\n    typeof row.owner_email === \"string\" && row.owner_email.trim()\n      ? row.owner_email\n      : null;\n  if (!ownerEmail) {\n    throw new Error(\"Observational memory row is missing owner_email.\");\n  }\n  return {\n    id: String(row.id),\n    threadId: String(row.thread_id),\n    tier: row.tier as ObservationalMemoryTier,\n    text: typeof row.text === \"string\" ? row.text : \"\",\n    tokenEstimate: Number(row.token_estimate) || 0,\n    sourceStartIndex: numOrNull(row.source_start_index),\n    sourceEndIndex: numOrNull(row.source_end_index),\n    sourceMessageCount: Number(row.source_message_count) || 0,\n    createdAt: Number(row.created_at) || 0,\n    updatedAt: Number(row.updated_at) || 0,\n    ownerEmail,\n    orgId: typeof row.org_id === \"string\" ? row.org_id : null,\n    visibility:\n      (row.visibility as ObservationalMemoryEntry[\"visibility\"]) ?? \"private\",\n  };\n}\n\nfunction addOwnerScope(\n  clauses: string[],\n  args: unknown[],\n  owner: ObservationalMemoryOwner,\n): void {\n  clauses.push(\"owner_email = ?\");\n  args.push(owner.ownerEmail);\n  if (owner.orgId == null) {\n    clauses.push(\"org_id IS NULL\");\n  } else {\n    clauses.push(\"org_id = ?\");\n    args.push(owner.orgId);\n  }\n}\n\nexport interface InsertObservationalMemoryInput extends ObservationalMemoryOwner {\n  threadId: string;\n  tier: ObservationalMemoryTier;\n  text: string;\n  tokenEstimate: number;\n  sourceStartIndex?: number | null;\n  sourceEndIndex?: number | null;\n  sourceMessageCount?: number;\n  visibility?: \"private\" | \"org\" | \"public\";\n}\n\n/** Insert one OM entry, returning the persisted row. */\nexport async function insertObservationalMemory(\n  input: InsertObservationalMemoryInput,\n): Promise<ObservationalMemoryEntry> {\n  await ensureTable();\n  const client = getDbExec();\n  const now = Date.now();\n  const id = entryId();\n  const entry: ObservationalMemoryEntry = {\n    id,\n    threadId: input.threadId,\n    tier: input.tier,\n    text: input.text,\n    tokenEstimate: input.tokenEstimate,\n    sourceStartIndex: input.sourceStartIndex ?? null,\n    sourceEndIndex: input.sourceEndIndex ?? null,\n    sourceMessageCount: input.sourceMessageCount ?? 0,\n    createdAt: now,\n    updatedAt: now,\n    ownerEmail: input.ownerEmail,\n    orgId: input.orgId ?? null,\n    visibility: input.visibility ?? \"private\",\n  };\n  await client.execute({\n    sql: `INSERT INTO observational_memory\n      (id, thread_id, tier, text, token_estimate, source_start_index, source_end_index, source_message_count, created_at, updated_at, owner_email, org_id, visibility)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n    args: [\n      entry.id,\n      entry.threadId,\n      entry.tier,\n      entry.text,\n      entry.tokenEstimate,\n      entry.sourceStartIndex,\n      entry.sourceEndIndex,\n      entry.sourceMessageCount,\n      entry.createdAt,\n      entry.updatedAt,\n      entry.ownerEmail,\n      entry.orgId,\n      entry.visibility,\n    ],\n  });\n  return entry;\n}\n\nexport interface ListObservationalMemoryOptions extends ObservationalMemoryOwner {\n  threadId: string;\n  /** When set, only entries of this tier are returned. */\n  tier?: ObservationalMemoryTier;\n}\n\n/**\n * List a thread's OM entries for an owner, oldest → newest. Always\n * owner-scoped; `org_id` is matched too when supplied so org-visible rows\n * don't leak across orgs.\n */\nexport async function listObservationalMemory(\n  options: ListObservationalMemoryOptions,\n): Promise<ObservationalMemoryEntry[]> {\n  await ensureTable();\n  const client = getDbExec();\n  const clauses = [\"thread_id = ?\"];\n  const args: unknown[] = [options.threadId];\n  addOwnerScope(clauses, args, options);\n  if (options.tier) {\n    clauses.push(\"tier = ?\");\n    args.push(options.tier);\n  }\n  const result = await client.execute({\n    sql: `SELECT * FROM observational_memory WHERE ${clauses.join(\n      \" AND \",\n    )} ORDER BY created_at ASC, id ASC`,\n    args,\n  });\n  return (result.rows as Record<string, unknown>[]).map(rowToEntry);\n}\n\n/**\n * The highest source-message index already folded into an observation for this\n * thread/owner, or -1 if none. The Observer uses this to know which messages\n * are still unobserved.\n */\nexport async function getObservedThroughIndex(\n  options: ObservationalMemoryOwner & { threadId: string },\n): Promise<number> {\n  await ensureTable();\n  const client = getDbExec();\n  const clauses = [\"thread_id = ?\", \"tier = 'observation'\"];\n  const args: unknown[] = [options.threadId];\n  addOwnerScope(clauses, args, options);\n  const result = await client.execute({\n    sql: `SELECT MAX(source_end_index) AS max_idx\n      FROM observational_memory\n      WHERE ${clauses.join(\" AND \")}`,\n    args,\n  });\n  const row = (result.rows as Record<string, unknown>[])[0];\n  const max = numOrNull(row?.max_idx);\n  return max == null ? -1 : max;\n}\n\n/** Sum the token estimates of a thread's observation entries for an owner. */\nexport async function getObservationLogTokens(\n  options: ObservationalMemoryOwner & { threadId: string },\n): Promise<number> {\n  await ensureTable();\n  const client = getDbExec();\n  const clauses = [\"thread_id = ?\", \"tier = 'observation'\"];\n  const args: unknown[] = [options.threadId];\n  addOwnerScope(clauses, args, options);\n  const result = await client.execute({\n    sql: `SELECT COALESCE(SUM(token_estimate), 0) AS total\n      FROM observational_memory\n      WHERE ${clauses.join(\" AND \")}`,\n    args,\n  });\n  const row = (result.rows as Record<string, unknown>[])[0];\n  return Number(row?.total) || 0;\n}\n"]}

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

@@ -0,0 +1,61 @@
+/**
+ * Shared types for Observational Memory (OM).
+ *
+ * Kept in their own module (no DB / engine imports) so both the store and the
+ * compactor — and any future read-side consumer in production-agent — can
+ * depend on them without pulling in a runtime.
+ */
+import type { EngineMessage } from "../engine/types.js";
+/** The two compaction tiers. */
+export type ObservationalMemoryTier = "observation" | "reflection";
+/** One persisted OM entry (an observation or a reflection). */
+export interface ObservationalMemoryEntry {
+    id: string;
+    threadId: string;
+    tier: ObservationalMemoryTier;
+    /** Dated, compacted text. */
+    text: string;
+    /** Estimated tokens for `text`. */
+    tokenEstimate: number;
+    /** Inclusive source range this entry summarizes (null when unknown). */
+    sourceStartIndex: number | null;
+    sourceEndIndex: number | null;
+    /** Count of source messages/observations folded into this entry. */
+    sourceMessageCount: number;
+    createdAt: number;
+    updatedAt: number;
+    ownerEmail: string;
+    orgId: string | null;
+    visibility: "private" | "org" | "public";
+}
+/** Owner scoping common to every OM read/write. */
+export interface ObservationalMemoryOwner {
+    ownerEmail: string;
+    orgId?: string | null;
+}
+/**
+ * The three-tier context returned by `buildObservationalContext`, ready to be
+ * folded into a prompt:
+ *
+ *   reflections (highest level)  +  observations (dense)  +  recent raw messages
+ *
+ * The caller decides exactly how to serialize these into the system prompt /
+ * message list; OM only assembles the tiers and their token accounting.
+ */
+export interface ObservationalContext {
+    threadId: string;
+    /** Higher-level reflections, oldest → newest. */
+    reflections: ObservationalMemoryEntry[];
+    /** Dense observations, oldest → newest. */
+    observations: ObservationalMemoryEntry[];
+    /** The tail of raw thread messages kept verbatim (most recent turns). */
+    recentMessages: EngineMessage[];
+    /** Token accounting so the caller can reason about prompt budget. */
+    tokens: {
+        reflections: number;
+        observations: number;
+        recentMessages: number;
+        total: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agent/observational-memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,gCAAgC;AAChC,MAAM,MAAM,uBAAuB,GAAG,aAAa,GAAG,YAAY,CAAC;AAEnE,+DAA+D;AAC/D,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,uBAAuB,CAAC;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC;CAC1C;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,2CAA2C;IAC3C,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,yEAAyE;IACzE,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,qEAAqE;IACrE,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH"}

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

@@ -0,0 +1,9 @@
+/**
+ * Shared types for Observational Memory (OM).
+ *
+ * Kept in their own module (no DB / engine imports) so both the store and the
+ * compactor — and any future read-side consumer in production-agent — can
+ * depend on them without pulling in a runtime.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agent/observational-memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * Shared types for Observational Memory (OM).\n *\n * Kept in their own module (no DB / engine imports) so both the store and the\n * compactor — and any future read-side consumer in production-agent — can\n * depend on them without pulling in a runtime.\n */\n\nimport type { EngineMessage } from \"../engine/types.js\";\n\n/** The two compaction tiers. */\nexport type ObservationalMemoryTier = \"observation\" | \"reflection\";\n\n/** One persisted OM entry (an observation or a reflection). */\nexport interface ObservationalMemoryEntry {\n  id: string;\n  threadId: string;\n  tier: ObservationalMemoryTier;\n  /** Dated, compacted text. */\n  text: string;\n  /** Estimated tokens for `text`. */\n  tokenEstimate: number;\n  /** Inclusive source range this entry summarizes (null when unknown). */\n  sourceStartIndex: number | null;\n  sourceEndIndex: number | null;\n  /** Count of source messages/observations folded into this entry. */\n  sourceMessageCount: number;\n  createdAt: number;\n  updatedAt: number;\n  ownerEmail: string;\n  orgId: string | null;\n  visibility: \"private\" | \"org\" | \"public\";\n}\n\n/** Owner scoping common to every OM read/write. */\nexport interface ObservationalMemoryOwner {\n  ownerEmail: string;\n  orgId?: string | null;\n}\n\n/**\n * The three-tier context returned by `buildObservationalContext`, ready to be\n * folded into a prompt:\n *\n *   reflections (highest level)  +  observations (dense)  +  recent raw messages\n *\n * The caller decides exactly how to serialize these into the system prompt /\n * message list; OM only assembles the tiers and their token accounting.\n */\nexport interface ObservationalContext {\n  threadId: string;\n  /** Higher-level reflections, oldest → newest. */\n  reflections: ObservationalMemoryEntry[];\n  /** Dense observations, oldest → newest. */\n  observations: ObservationalMemoryEntry[];\n  /** The tail of raw thread messages kept verbatim (most recent turns). */\n  recentMessages: EngineMessage[];\n  /** Token accounting so the caller can reason about prompt budget. */\n  tokens: {\n    reflections: number;\n    observations: number;\n    recentMessages: number;\n    total: number;\n  };\n}\n"]}

package/dist/agent/processors.d.ts

@@ -0,0 +1,146 @@
+/**
+ * In-loop processor seam for the agent loop.
+ *
+ * A `Processor` is loop-internal *configuration* — not a tool, not an authoring
+ * DSL, not an action. It observes the model's streamed output and tool calls as
+ * the run progresses, may mutate its own per-processor `state`, and may `abort()`
+ * the run. This is the structural prerequisite for real-time guardrails and a
+ * proof-of-done / coverage gate: code that can watch the model mid-run and halt
+ * it (or surface a verdict) before a "done" is claimed.
+ *
+ * Borrowed from Mastra's output processors. The shape is intentionally minimal:
+ *
+ *   - `processOutputStream` fires per streamed chunk (text / thinking deltas,
+ *     etc.) while the model is generating, so a guardrail can react before the
+ *     full turn lands.
+ *   - `processOutputStep` fires once per model response, around tool execution,
+ *     with the tool calls the model just requested. A coverage gate can inspect
+ *     what the model is about to do and abort.
+ *   - `processOutputResult` fires once at run end with the final text.
+ *
+ * All hooks are OPTIONAL. When no processors are supplied to `runAgentLoop`, the
+ * loop must not run any of this code — the no-processors path is byte-for-byte
+ * unchanged and carries zero overhead (callers guard on a non-empty array).
+ *
+ * Each processor gets its own mutable `state` object that persists across every
+ * hook invocation for that processor within a single run, and is isolated from
+ * other processors' state.
+ */
+import type { EngineContentPart, EngineEvent } from "./engine/types.js";
+/**
+ * Thrown by a processor's `abort()` to halt the run gracefully. The loop catches
+ * it, emits a `tripwire` event, and stops. Carries the human-readable `reason`
+ * plus optional structured `meta` and the originating `processor` name.
+ *
+ * Lives here (not in production-agent) so any consumer can `instanceof` it
+ * without an import cycle.
+ */
+export declare class TripWire extends Error {
+    /** Optional structured metadata supplied at the abort site. */
+    readonly meta?: Record<string, unknown>;
+    /** Name of the processor that aborted, when known. */
+    readonly processor?: string;
+    constructor(reason: string, opts?: {
+        meta?: Record<string, unknown>;
+        processor?: string;
+    });
+}
+/**
+ * Per-processor mutable scratch space. Each processor sees the SAME object
+ * across all of its hook invocations within one run; processors never see each
+ * other's state.
+ */
+export type ProcessorState = Record<string, unknown>;
+/** Halts the run by throwing a {@link TripWire}. Never returns normally. */
+export type ProcessorAbort = (reason: string, meta?: Record<string, unknown>) => never;
+/** A single streamed chunk plus the running list of chunks seen so far. */
+export interface ProcessOutputStreamArgs {
+    /** The chunk that just streamed from the engine. */
+    part: EngineEvent;
+    /** Every chunk observed so far this turn, including `part`. */
+    streamParts: EngineEvent[];
+    /** This processor's mutable, isolated, run-scoped state. */
+    state: ProcessorState;
+    /** Halt the run; throws {@link TripWire}. */
+    abort: ProcessorAbort;
+}
+/** Context for a completed model response, fired around tool execution. */
+export interface ProcessOutputStepArgs {
+    /** Tool calls the model requested in this step (empty for a final answer). */
+    toolCalls: {
+        id: string;
+        name: string;
+        input: unknown;
+    }[];
+    /** Terminal stop reason for the step, when the engine reported one. */
+    finishReason?: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "error";
+    /** Cumulative token usage for the run so far, when available. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    /** This processor's mutable, isolated, run-scoped state. */
+    state: ProcessorState;
+    /** Halt the run; throws {@link TripWire}. */
+    abort: ProcessorAbort;
+}
+/** Context for the end of the whole run. */
+export interface ProcessOutputResultArgs {
+    /** The final assistant text for the run. */
+    text: string;
+    /** This processor's mutable, isolated, run-scoped state. */
+    state: ProcessorState;
+}
+/**
+ * A loop-internal observer/guardrail. All hooks are optional; implement only
+ * the ones a given guardrail needs. Hooks may be sync or async.
+ */
+export interface Processor {
+    /** Stable name, surfaced on `tripwire` events and in per-processor errors. */
+    name?: string;
+    /** Called per streamed chunk while the model generates. */
+    processOutputStream?(args: ProcessOutputStreamArgs): void | Promise<void>;
+    /** Called once per model response, around tool execution. */
+    processOutputStep?(args: ProcessOutputStepArgs): void | Promise<void>;
+    /** Called once at run end with the final text. */
+    processOutputResult?(args: ProcessOutputResultArgs): void | Promise<void>;
+}
+/**
+ * Runs a chain of processors over the loop's lifecycle. Created once per run;
+ * isolates each processor's `state`, runs hooks in registration order, and
+ * converts a processor's `abort()` (or any thrown `TripWire`) into a single
+ * halt signal the loop can act on.
+ *
+ * The executor is only constructed when at least one processor is supplied, so
+ * the no-processors path never touches any of this.
+ */
+export declare class ProcessorChain {
+    private readonly entries;
+    /** Accumulates every stream chunk so each `processOutputStream` call sees the running list. */
+    private readonly streamParts;
+    constructor(processors: Processor[]);
+    private makeAbort;
+    /** Fire `processOutputStream` for every processor that implements it. */
+    runStream(part: EngineEvent): Promise<void>;
+    /** Fire `processOutputStep` for every processor that implements it. */
+    runStep(args: {
+        toolCalls: {
+            id: string;
+            name: string;
+            input: unknown;
+        }[];
+        finishReason?: ProcessOutputStepArgs["finishReason"];
+        usage?: ProcessOutputStepArgs["usage"];
+    }): Promise<void>;
+    /** Fire `processOutputResult` for every processor that implements it. */
+    runResult(text: string): Promise<void>;
+}
+/** Engine content parts → the plain tool-call shape passed to `processOutputStep`. */
+export declare function toolCallsFromContent(parts: EngineContentPart[]): {
+    id: string;
+    name: string;
+    input: unknown;
+}[];
+//# sourceMappingURL=processors.d.ts.map

package/dist/agent/processors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors.d.ts","sourceRoot":"","sources":["../../src/agent/processors.ts"],"names":[],"mappings":"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"}