@loopingai/core 0.1.0 → 0.1.2

package/README.md

@@ -207,6 +207,77 @@ its cause.
 The contract is **additive-only within a major**: new capabilities arrive as optional
 fields on `AgentPlugin`.
 
+### Plugin-owned tables
+
+A plugin owns its tables outright, through `store: PluginStore` — but it must stay out of
+core's migration journal. `drizzle-orm/durable-sqlite/migrator` keeps one flat integer
+journal and one global `__drizzle_migrations` table, and two independently-versioned
+packages cannot share that index space.
+
+That is a prohibition on exactly **one import**, not on drizzle. The query builder holds
+no journal and no connection state, so a plugin declares its tables with `sqliteTable`,
+writes idempotent DDL in `ensureTables`, and queries through its own handle:
+
+```ts
+export const scrapes = sqliteTable("scraper_scrapes", { url: text("url").primaryKey() });
+
+store: {
+  plugin: "scraper",
+  version: 1,
+  // Re-run on every hibernation wake-up, so it must be idempotent.
+  ensureTables: (sql) => sql.exec(`CREATE TABLE IF NOT EXISTS scraper_scrapes (…)`)
+}
+
+// …and anywhere the plugin queries:
+const db = drizzle(storage, { schema: { scrapes } });
+```
+
+Core records each store's version in a `plugin_migrations` row, so `ensureTables` receives
+the version last seen on disk and an upgrade path can branch on it.
+
+### Session hooks
+
+`onMessagesDisplaced` hands over the raw messages a compaction is about to fold into a
+summary. Core performs the compaction, so core announces the loss; it neither stores the
+messages nor knows who wants them. An episodic-memory plugin, an audit log, and a
+cold-storage dump all want exactly this callback, and each gets it:
+
+```ts
+// in your DO, wiring the runtime's fan-out into the session
+buildAgentSession(this, model, {
+  …,
+  onMessagesDisplaced: this.runtime.onMessagesDisplaced
+});
+```
+
+Best-effort in both directions — a listener that throws never aborts compaction (history
+must still shorten when a side store is down), and the fan-out is `Promise.allSettled`, so
+one plugin's outage cannot cost another its notification.
+
+`shouldHandleTurn` is the other side of the session: a gate that decides whether a turn
+runs at all, before the loop builds or calls anything. An agent that sees every message in
+its channels is mostly seeing messages that are not for it, and asking a model already
+trying to be helpful to stay quiet degrades _invisibly_ — failing to call a decline-tool
+looks identical to deciding not to. Every declaring plugin is consulted and the answers are
+AND-ed, so any one gate may decline.
+
+```ts
+if (!(await this.runtime.shouldHandleTurn({ history }))) return; // declined
+```
+
+It **fails open**: a gate that throws is counted as `true`. The two mistakes are not
+symmetric — a wrong reply is noise the user can see and ignore, while a wrong silence is
+invisible to the person who needed an answer.
+
+### The workspace backend
+
+Core declares the `WorkspaceBacking` shape and enforces the caps, but ships no backend —
+the predecessor's was `@cloudflare/shell`, which is experimental, and an agent that never
+delegates file work should not carry it. A plugin supplies one via `workspaceBacking`; at
+most one may, and an agent that installs none gets `memoryWorkspaceBacking`. So
+`runtime.workspaceBacking` is always defined and your `SubagentRuntime` never needs a null
+check.
+
 ---
 
 ## Testing
@@ -246,7 +317,9 @@ await withDb("accepts a turn once", async (db) => {
 - The main agent's soul. Core ships no prompt copy.
 - Config _values_ — model ids, budgets, limits. Core ships the shapes and safe
   defaults, and `resolveConfig` validates your overrides.
-- Vectorize recall, browser tools, shell. All optional → plugins.
+- Vectorize recall, browser tools, shell. All optional → plugins. Core contains no
+  embedding code at all: it ships the `onMessagesDisplaced` hook and nothing about what
+  a listener does with the messages — no embedding model, no index, no dimension.
 
 ---
 

package/dist/agent/history.d.ts

@@ -7,9 +7,9 @@ import type { SessionMessage } from "agents/experimental/memory/session";
  * A2A adapter} has already reduced the inbound message to a plain string.
  *
  * The gateway inlines a `<turn from="…" id="…" channel="…" at="…">…</turn>` tag
- * into the message text in multi-actor channels so the model (and, in later
- * phases, recall) can attribute "who said what". This agent only *parses* that
- * wrapper — it never authors one.
+ * into the message text in multi-actor channels so the model — and anything
+ * downstream that needs per-message provenance — can attribute "who said what".
+ * This agent only *parses* that wrapper; it never authors one.
  *
  * We persist only the user turn and the assistant's final text: intra-turn tool
  * steps stay inside the single `generateText` call, so stored history is plain

package/dist/agent/index.d.ts

@@ -8,8 +8,8 @@
  * turns "the model called something that ends the round" into a checked value.
  */
 export { newTurnBudget, stepAllowance, type TurnBudget } from "./budget.js";
-export { createModelRuntime, type Embed, type GatewayMetadata, type ModelOverrides, type ModelPair, type ModelRuntime, type ModelRuntimeDeps } from "./model.js";
-export { appendOnce, archivingCompaction, buildAgentSession, type AgentSessionOptions, type SessionHost, type SessionLike } from "./session.js";
+export { createModelRuntime, type GatewayMetadata, type ModelOverrides, type ModelPair, type ModelRuntime, type ModelRuntimeDeps } from "./model.js";
+export { appendOnce, buildAgentSession, notifyingCompaction, type AgentSessionOptions, type SessionHost, type SessionLike } from "./session.js";
 export { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, parseTurn, roundAckMessageId, sessionText, taskUserMessageId, toModelMessages, type ParsedTurn } from "./history.js";
 export { buildIntermediateContentHandler, isTransientAiError, type OnContent } from "./inference.js";
 export { ControlCallError, controlTools, controlToolSet, type ControlTool, type TurnDecision } from "./control.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAClB,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,sBAAsB,EACtB,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,+BAA+B,EAC/B,kBAAkB,EAClB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACf,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,sBAAsB,EACtB,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,+BAA+B,EAC/B,kBAAkB,EAClB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACf,MAAM,kBAAkB,CAAC"}

package/dist/agent/index.js

@@ -9,7 +9,7 @@
  */
 export { newTurnBudget, stepAllowance } from "./budget.js";
 export { createModelRuntime } from "./model.js";
-export { appendOnce, archivingCompaction, buildAgentSession } from "./session.js";
+export { appendOnce, buildAgentSession, notifyingCompaction } from "./session.js";
 export { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, parseTurn, roundAckMessageId, sessionText, taskUserMessageId, toModelMessages } from "./history.js";
 export { buildIntermediateContentHandler, isTransientAiError } from "./inference.js";
 export { ControlCallError, controlTools, controlToolSet } from "./control.js";

package/dist/agent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAOnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,iBAAiB,EAIlB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,sBAAsB,EACtB,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,eAAe,EAEhB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,+BAA+B,EAC/B,kBAAkB,EAEnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,EAGf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACf,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAMnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EAIpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,sBAAsB,EACtB,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,eAAe,EAEhB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,+BAA+B,EAC/B,kBAAkB,EAEnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,EAGf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACf,MAAM,kBAAkB,CAAC"}

package/dist/agent/model.d.ts

@@ -8,12 +8,6 @@ import type { ModelConfig } from "../config.js";
  * Workers, and a module constant cannot be overridden by a consumer. So this is
  * a factory over an injected binding and an injected {@link ModelConfig}.
  */
-/**
- * Embed a batch of texts for episodic recall. Uses the same Workers-AI + AI
- * Gateway path as the chat models so embeddings get the same gateway
- * observability/caching. The output dimension must match the Vectorize index.
- */
-export type Embed = (texts: string[]) => Promise<number[][]>;
 /**
  * Custom metadata attached to the AI Gateway log for every call a pair makes.
  * The gateway's own `metadata` is otherwise `null`, so a model call can only be
@@ -55,7 +49,6 @@ export interface ModelRuntime {
      * `validateRecipe` is the single validation owner for recipe-supplied ids.
      */
     createModelPair(overrides?: ModelOverrides): ModelPair;
-    embedTexts: Embed;
 }
 export interface ModelRuntimeDeps {
     /** The `AI` binding. Read lazily — see {@link createModelRuntime}. */

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

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/agent/model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,aAAa,CAAC;IAC7B,QAAQ,EAAE,MAAM,aAAa,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,eAAe,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACvD,UAAU,EAAE,KAAK,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,EAAE,EAAE,EAAE,CAAC;IACP,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAuDvE"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/agent/model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,aAAa,CAAC;IAC7B,QAAQ,EAAE,MAAM,aAAa,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,eAAe,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,EAAE,EAAE,EAAE,CAAC;IACP,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CA2CvE"}

package/dist/agent/model.js

@@ -1,5 +1,4 @@
 import { createWorkersAI } from "workers-ai-provider";
-import { embedMany } from "ai";
 /**
  * Build the model runtime for one agent instance.
  *
@@ -44,18 +43,6 @@ export function createModelRuntime(deps) {
                 primaryId: () => primaryId,
                 fallbackId: () => fallbackId
             };
-        },
-        async embedTexts(texts) {
-            if (texts.length === 0)
-                return [];
-            const { embeddings } = await embedMany({
-                model: workersai().embedding(config.embeddingModelId),
-                values: texts,
-                // Failures surface to the caller (best-effort archival swallows them);
-                // the SDK's retry/backoff would only add latency on a hard failure.
-                maxRetries: 0
-            });
-            return embeddings;
         }
     };
 }

package/dist/agent/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/agent/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAwE/B;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACvD,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,IAAI,QAAwD,CAAC;IAC7D,MAAM,SAAS,GAAG,GAAG,EAAE,CACrB,CAAC,QAAQ,KAAK,eAAe,CAAC;QAC5B,OAAO,EAAE,IAAI,CAAC,EAAE;QAChB,OAAO,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,WAAW,EAAE;KACpC,CAAC,CAAC,CAAC;IAEN;;;;;;;OAOG;IACH,MAAM,YAAY,GAAG,CAAC,QAA0B,EAAE,EAAE,CAAC,CAAC;QACpD,OAAO,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;QACtE,gBAAgB,EAAE,MAAM,CAAC,eAAe;KACzC,CAAC,CAAC;IAEH,OAAO;QACL,eAAe,CAAC,YAA4B,EAAE;YAC5C,MAAM,SAAS,GAAG,SAAS,CAAC,cAAc,IAAI,MAAM,CAAC,WAAW,CAAC;YACjE,MAAM,UAAU,GACd,SAAS,CAAC,eAAe,IAAI,MAAM,CAAC,mBAAmB,CAAC;YAC1D,IAAI,OAAkC,CAAC;YACvC,IAAI,QAAmC,CAAC;YACxC,MAAM,QAAQ,GAAG,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAClD,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE,CACZ,CAAC,OAAO,KAAK,SAAS,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;gBACnE,QAAQ,EAAE,GAAG,EAAE,CACb,CAAC,QAAQ;oBACP,SAAS,CAAC,aAAa;wBACvB,SAAS,CAAC,KAAK;wBACf,SAAS,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;gBACtC,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS;gBAC1B,UAAU,EAAE,GAAG,EAAE,CAAC,UAAU;aAC7B,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,KAAe;YAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;YAClC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,SAAS,CAAC;gBACrC,KAAK,EAAE,SAAS,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,gBAAgB,CAAC;gBACrD,MAAM,EAAE,KAAK;gBACb,uEAAuE;gBACvE,oEAAoE;gBACpE,UAAU,EAAE,CAAC;aACd,CAAC,CAAC;YACH,OAAO,UAAU,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/agent/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAiEtD;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACvD,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,IAAI,QAAwD,CAAC;IAC7D,MAAM,SAAS,GAAG,GAAG,EAAE,CACrB,CAAC,QAAQ,KAAK,eAAe,CAAC;QAC5B,OAAO,EAAE,IAAI,CAAC,EAAE;QAChB,OAAO,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,WAAW,EAAE;KACpC,CAAC,CAAC,CAAC;IAEN;;;;;;;OAOG;IACH,MAAM,YAAY,GAAG,CAAC,QAA0B,EAAE,EAAE,CAAC,CAAC;QACpD,OAAO,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;QACtE,gBAAgB,EAAE,MAAM,CAAC,eAAe;KACzC,CAAC,CAAC;IAEH,OAAO;QACL,eAAe,CAAC,YAA4B,EAAE;YAC5C,MAAM,SAAS,GAAG,SAAS,CAAC,cAAc,IAAI,MAAM,CAAC,WAAW,CAAC;YACjE,MAAM,UAAU,GACd,SAAS,CAAC,eAAe,IAAI,MAAM,CAAC,mBAAmB,CAAC;YAC1D,IAAI,OAAkC,CAAC;YACvC,IAAI,QAAmC,CAAC;YACxC,MAAM,QAAQ,GAAG,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAClD,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE,CACZ,CAAC,OAAO,KAAK,SAAS,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;gBACnE,QAAQ,EAAE,GAAG,EAAE,CACb,CAAC,QAAQ;oBACP,SAAS,CAAC,aAAa;wBACvB,SAAS,CAAC,KAAK;wBACf,SAAS,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;gBACtC,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS;gBAC1B,UAAU,EAAE,GAAG,EAAE,CAAC,UAAU;aAC7B,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agent/session.d.ts

@@ -5,8 +5,12 @@ import { createCompactFunction } from "agents/experimental/memory/utils";
 /**
  * The one continuous {@link Session} an agent Durable Object owns. Ported from
  * the looping-gateway admin agent's `shared/session.ts` (single Session per DO —
- * soul + memory + compaction). Recall (Vectorize) archival is Phase 3: the
- * `onArchive` seam is present but left unwired for now.
+ * soul + memory + compaction).
+ *
+ * Compaction is the one **lossy** thing this module does, so it is also the one
+ * thing it announces: `onMessagesDisplaced` hands over the raw messages a
+ * summary is about to replace. Core neither stores them nor knows who wants
+ * them — a host wires the seam to whatever does.
  */
 /**
  * The SQLite-backed host the Sessions API needs — satisfied by the Agents SDK
@@ -28,7 +32,7 @@ export interface SessionLike {
     getMessage(id: string): Promise<SessionMessage | null>;
     refreshSystemPrompt(): Promise<string>;
     tools(): Promise<ToolSet>;
-    /** Compaction overlays so far — non-empty ⇒ an episodic archive exists. */
+    /** Compaction overlays so far — non-empty ⇒ history has been displaced. */
     getCompactions(): Promise<unknown[]>;
 }
 /**
@@ -67,20 +71,26 @@ export interface AgentSessionOptions {
      */
     maxOutputTokens: number;
     /**
-     * Archive the raw messages displaced by each compaction (episodic recall).
-     * Best-effort: a throw here must never abort compaction. (Wired in Phase 3.)
+     * Hand over the raw messages each compaction displaces, before a summary
+     * replaces them. Best-effort: a throw here must never abort compaction.
+     *
+     * The seam, not a policy — pass `runtime.onMessagesDisplaced` to reach every
+     * installed plugin declaring the hook, or any function of your own.
      */
-    onArchive?: (messages: SessionMessage[]) => Promise<void>;
+    onMessagesDisplaced?: (messages: SessionMessage[]) => Promise<void>;
 }
 type CompactFn = ReturnType<typeof createCompactFunction>;
 /**
  * Wrap a compaction function so the raw messages it folds into a summary are
- * also handed to `onArchive` (which embeds them for later recall). The displaced
- * range is `fromMessageId..toMessageId` of the result, sliced from the `history`
- * the compaction saw. Archival failure is swallowed — compaction must still
- * shorten history even if the recall store is briefly unavailable.
+ * also handed to `onMessagesDisplaced` before they stop being readable as
+ * history. The displaced range is `fromMessageId..toMessageId` of the result,
+ * sliced from the `history` the compaction saw.
+ *
+ * A listener's failure is swallowed — compaction must still shorten history
+ * when whatever is listening is briefly unavailable. The alternative is
+ * unbounded context because a side concern is down.
  */
-export declare function archivingCompaction(base: CompactFn, onArchive?: (messages: SessionMessage[]) => Promise<void>): CompactFn;
+export declare function notifyingCompaction(base: CompactFn, onMessagesDisplaced?: (messages: SessionMessage[]) => Promise<void>): CompactFn;
 /**
  * Build the one continuous `Session` an agent Durable Object owns: a read-only
  * `"soul"` identity block + a writable `"memory"` scratchpad, with history

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAGzE;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EACtD,OAAO,EAAE,oBAAoB,EAC7B,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,GAC9C,CAAC,EAAE,CAAC;CACR;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,aAAa,CACX,OAAO,EAAE,cAAc,EACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC9B,UAAU,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACxC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACvD,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,2EAA2E;IAC3E,cAAc,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,EACf,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GACxD,SAAS,CAiBX;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CA2BT"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAGzE;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EACtD,OAAO,EAAE,oBAAoB,EAC7B,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,GAC9C,CAAC,EAAE,CAAC;CACR;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,aAAa,CACX,OAAO,EAAE,cAAc,EACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC9B,UAAU,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACxC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACvD,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,2EAA2E;IAC3E,cAAc,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1D;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,EACf,mBAAmB,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAClE,SAAS,CAiBX;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CA2BT"}

package/dist/agent/session.js

@@ -22,13 +22,16 @@ export async function appendOnce(session, message) {
 }
 /**
  * Wrap a compaction function so the raw messages it folds into a summary are
- * also handed to `onArchive` (which embeds them for later recall). The displaced
- * range is `fromMessageId..toMessageId` of the result, sliced from the `history`
- * the compaction saw. Archival failure is swallowed — compaction must still
- * shorten history even if the recall store is briefly unavailable.
+ * also handed to `onMessagesDisplaced` before they stop being readable as
+ * history. The displaced range is `fromMessageId..toMessageId` of the result,
+ * sliced from the `history` the compaction saw.
+ *
+ * A listener's failure is swallowed — compaction must still shorten history
+ * when whatever is listening is briefly unavailable. The alternative is
+ * unbounded context because a side concern is down.
  */
-export function archivingCompaction(base, onArchive) {
-    if (!onArchive)
+export function notifyingCompaction(base, onMessagesDisplaced) {
+    if (!onMessagesDisplaced)
         return base;
     return async (history, options) => {
         const result = await base(history, options);
@@ -37,10 +40,10 @@ export function archivingCompaction(base, onArchive) {
             const to = history.findIndex((m) => m.id === result.toMessageId);
             if (from !== -1 && to !== -1) {
                 try {
-                    await onArchive(history.slice(from, to + 1));
+                    await onMessagesDisplaced(history.slice(from, to + 1));
                 }
                 catch (err) {
-                    console.error("[recall] archive on compaction failed", err);
+                    console.error("[session] displacement listener failed", err);
                 }
             }
         }
@@ -54,7 +57,7 @@ export function archivingCompaction(base, onArchive) {
  * or thread) accumulate into this single conversation.
  */
 export function buildAgentSession(agent, model, opts) {
-    const compact = archivingCompaction(createCompactFunction({
+    const compact = notifyingCompaction(createCompactFunction({
         // The one boundary worth owning. `protectHead` (3) and `minTailMessages`
         // (2) keep the SDK defaults: the head is the conversation's opening and is
         // cheap, and the tail floor is a safety net rather than a budget.
@@ -67,7 +70,7 @@ export function buildAgentSession(agent, model, opts) {
             prompt,
             maxOutputTokens: opts.maxOutputTokens
         }).then((r) => r.text)
-    }), opts.onArchive);
+    }), opts.onMessagesDisplaced);
     return Session.create(agent)
         .withContext("soul", { provider: { get: async () => opts.soul() } })
         .withContext("memory", {

package/dist/agent/session.js.map

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

package/dist/config.d.ts

@@ -31,11 +31,6 @@ export interface ModelConfig {
     maxOutputTokens: number;
     /** Reasoning budget forwarded on the binding's `inputs` by workers-ai-provider. */
     reasoningEffort: "low" | "medium" | "high";
-    /**
-     * Embedding model backing recall. Its dimension/metric must match the
-     * Vectorize index (1024-dim, cosine); changing it means recreating the index.
-     */
-    embeddingModelId: string;
 }
 /**
  * An execution budget, in the only two currencies that mean anything: **turns**
@@ -89,17 +84,6 @@ export interface SessionConfig {
     /** One-line description shown to the model for the writable `"memory"` block. */
     memoryDescription: string;
 }
-/** Episodic-recall (Vectorize) tuning. */
-export interface RecallConfig {
-    /** Default number of archived messages one `recall` query returns. */
-    topK: number;
-    /**
-     * Max chars of a message's text stored in its vector metadata. Keeps each
-     * vector under Vectorize's ~10 KiB/vector limit; recall returns this snippet
-     * plus provenance, not the full original message.
-     */
-    metadataTextMax: number;
-}
 export interface CoreConfig {
     model: ModelConfig;
     /** What bounds the MAIN agent across every round of one task. */
@@ -132,7 +116,6 @@ export interface CoreConfig {
      */
     maxSubtasks: number;
     session: SessionConfig;
-    recall: RecallConfig;
 }
 /**
  * A working baseline. Every value is overridable; none is a ceiling. These are

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,eAAe,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC3C;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;OAaG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,iEAAiE;IACjE,eAAe,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAsBjC,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG;KAC/B,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,SAAS,MAAM,GAClD,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GACtB,UAAU,CAAC,CAAC,CAAC;CAClB,CAAC;AAEF,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,GAAE,mBAAwB,GAAG,UAAU,CA4C7E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,eAAe,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;OAaG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,iEAAiE;IACjE,eAAe,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAoBjC,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG;KAC/B,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,SAAS,MAAM,GAClD,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GACtB,UAAU,CAAC,CAAC,CAAC;CAClB,CAAC;AAEF,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,GAAE,mBAAwB,GAAG,UAAU,CA2C7E"}

package/dist/config.js

@@ -22,8 +22,7 @@ export const DEFAULT_CORE_CONFIG = {
         fallbackChatModelId: "@cf/moonshotai/kimi-k2.7-code",
         aiGatewayId: "default",
         maxOutputTokens: 16_384,
-        reasoningEffort: "medium",
-        embeddingModelId: "@cf/baai/bge-m3"
+        reasoningEffort: "medium"
     },
     mainAgentLimits: { maxTurns: 20, maxWallMs: 60 * 60_000 },
     subagentLimits: { maxTurns: 20, maxWallMs: 30 * 60_000 },
@@ -35,8 +34,7 @@ export const DEFAULT_CORE_CONFIG = {
         compactTailTokens: 5_000,
         memoryDescription: "Durable facts worth remembering across all of this caller's conversations — " +
             "stable preferences, decisions, people, and context. Keep it concise."
-    },
-    recall: { topK: 5, metadataTextMax: 2000 }
+    }
 };
 export class ConfigError extends Error {
     constructor(message) {
@@ -65,8 +63,7 @@ export function resolveConfig(overrides = {}) {
         },
         toolOutputWindow: overrides.toolOutputWindow ?? DEFAULT_CORE_CONFIG.toolOutputWindow,
         maxSubtasks: overrides.maxSubtasks ?? DEFAULT_CORE_CONFIG.maxSubtasks,
-        session: { ...DEFAULT_CORE_CONFIG.session, ...overrides.session },
-        recall: { ...DEFAULT_CORE_CONFIG.recall, ...overrides.recall }
+        session: { ...DEFAULT_CORE_CONFIG.session, ...overrides.session }
     };
     const positive = (value, name) => {
         if (!Number.isFinite(value) || value <= 0) {

package/dist/config.js.map

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

package/dist/contract/index.d.ts

@@ -4,7 +4,7 @@
  * Re-exported from the package root as well, so a plugin author writes
  * `import { definePlugin } from "@loopingai/core"` and nothing else.
  */
-export { PLUGIN_CONTRACT_VERSION, definePlugin, type AgentPlugin, type EmitProgress, type EnrichResultContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext } from "./plugin.js";
+export { PLUGIN_CONTRACT_VERSION, definePlugin, type AgentPlugin, type EmitProgress, type EnrichResultContext, type MainAgentToolContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext, type TurnGateContext } from "./plugin.js";
 export type { DelegationNames, RecipeLimits, ResolvedRecipe, SubtaskParams, SubtaskParamsSchema, SubtaskParamsShape, SubtaskTypeSpec, ValidatedRecipe } from "./recipe.js";
 export { RecipeValidationError, resolveLimits, validateRecipe, type RecipePolicy } from "./validation.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/contract/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC"}

package/dist/contract/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,YAAY,EASb,MAAM,aAAa,CAAC;AAarB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EAEf,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,YAAY,EAWb,MAAM,aAAa,CAAC;AAarB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EAEf,MAAM,iBAAiB,CAAC"}

package/dist/contract/plugin.d.ts

@@ -1,6 +1,8 @@
 import type { ToolSet } from "ai";
+import type { SessionMessage } from "agents/experimental/memory/session";
+import type { SessionLike } from "../agent/session.js";
 import type { PluginStore } from "../db/db.js";
-import type { WorkspaceHandle } from "../subagent/workspace.js";
+import type { WorkspaceBacking, WorkspaceHandle } from "../subagent/workspace.js";
 import type { ProgressEvent, RecipeExecutionRequest, RecipeExecutionResult, SubtaskRuntime } from "../subtasks/types.js";
 import type { SubtaskParams, SubtaskTypeSpec } from "./recipe.js";
 /**
@@ -87,6 +89,34 @@ export interface EnrichResultContext<TRuntime = SubtaskRuntime> {
     request: RecipeExecutionRequest;
     runtime: TRuntime;
 }
+/**
+ * What a plugin knows when it builds the *main* agent's tools.
+ *
+ * Deliberately just the session, and deliberately not the caller's identity. A
+ * plugin that needs a per-caller value takes it as config at instantiation, like
+ * every other config value — the Durable Object is keyed 1:1 by the verified
+ * caller, so that value is constant for its life. Putting it here as well would
+ * give a plugin two ways to reach one fact, and the *other* hook that needs it
+ * ({@link AgentPlugin.onMessagesDisplaced}) has no context to read it from
+ * anyway.
+ *
+ * What the session gives that config cannot is **durable state the tool surface
+ * depends on** — whether history has ever been compacted, how many contexts are
+ * set. That is a question only the session can answer, and only at call time.
+ */
+export interface MainAgentToolContext {
+    session: SessionLike;
+}
+/** What a plugin knows when deciding whether a turn should run at all. */
+export interface TurnGateContext {
+    /**
+     * The conversation so far, **including the message being judged** — which is
+     * already appended when a gate runs, so the agent reads a message it declines.
+     * A bare message is frequently unclassifiable ("yes", "thanks", "and the
+     * second one?"), so the tail is what makes the judgement possible at all.
+     */
+    history: SessionMessage[];
+}
 /** Bindings and secrets a plugin needs the *host* to provide in `wrangler.jsonc`. */
 export interface PluginRequirements {
     /** Secret names, e.g. `["ARC_API_KEY"]`. */
@@ -114,11 +144,25 @@ export interface AgentPlugin<TRuntime = SubtaskRuntime> {
      * `validateRecipe`, so the legal set is exactly what is installed.
      */
     toolFamilies?: Record<string, ToolFamilyBuilder<TRuntime>>;
-    /** Tools offered to the *main* agent (e.g. a catalogue lookup before delegating). */
-    mainAgentTools?: () => ToolSet;
+    /**
+     * Tools offered to the *main* agent (e.g. a catalogue lookup before
+     * delegating).
+     *
+     * May return a promise, so a plugin can shape its tool surface from durable
+     * state — offering a search tool only once there is something to search, say.
+     * A tool that can only ever return "nothing here yet" costs the model a call to
+     * find that out, and costs every round the tokens to describe it.
+     */
+    mainAgentTools?: (ctx: MainAgentToolContext) => ToolSet | Promise<ToolSet>;
     /**
      * What the main agent is told it can do with this domain, rendered into its
      * soul alongside the other capability blocks.
+     *
+     * A plugin that declares a {@link subtaskType} should put its capability block
+     * on the *type* instead ({@link SubtaskTypeSpec.capability}) and leave this
+     * unset — the two are rendered by different call sites, so declaring both
+     * makes the main agent read the same advice twice per round. Which is the
+     * exact failure the type's own prompt fields were introduced to end.
      */
     capability?: string;
     /**
@@ -137,8 +181,66 @@ export interface AgentPlugin<TRuntime = SubtaskRuntime> {
     enrichResult?: (ctx: EnrichResultContext<TRuntime>, result: RecipeExecutionResult) => Promise<RecipeExecutionResult>;
     /** Release anything {@link resolveRuntime} acquired, when an execution is canceled. */
     onAbort?: (ctx: ResolveRuntimeContext) => Promise<void>;
+    /**
+     * Decide whether a turn should run at all, before the loop builds or calls
+     * anything.
+     *
+     * An agent that sees every message in its channels is mostly seeing messages
+     * that are not for it. Left to the main loop that judgement is made by a model
+     * simultaneously trying to be helpful, with history and half a dozen tools in
+     * view, and it degrades exactly there — *invisibly*, because failing to call a
+     * decline-tool looks identical to deciding not to. A gate moves the decision
+     * somewhere it cannot be skipped.
+     *
+     * **Fails open, and the asymmetry is the whole design.** A gate that throws is
+     * counted as `true`, so an outage degrades to the previous behaviour (run the
+     * turn) and never to a silent agent: a wrong reply is noise the user can see
+     * and ignore, while a wrong silence is invisible — the person who needed the
+     * agent simply never hears back. Failing *synchronously* is as safe as
+     * rejecting.
+     *
+     * Every declaring plugin is consulted and the results are AND-ed: any one gate
+     * may decline the turn. Returning `true` is always valid.
+     */
+    shouldHandleTurn?: (ctx: TurnGateContext) => Promise<boolean>;
+    /**
+     * The raw messages a compaction is about to fold into a summary, handed over
+     * before they stop being readable as history.
+     *
+     * This is core being honest about a **lossy operation it performs**, not a
+     * write path for any one plugin: compaction is destructive, core is what
+     * destroys, and anything that wants the originals — an archive, an audit log,
+     * a cold-storage dump — needs to be told at exactly this moment. What a plugin
+     * does with them is entirely its own business; core neither knows nor cares.
+     *
+     * Best-effort in both directions. A throw here never aborts compaction —
+     * history must still shorten when a side store is briefly unavailable — and
+     * the runtime fans out with `Promise.allSettled`, so one plugin's failure can
+     * neither abort another plugin's write nor leave it unawaited. Failing
+     * *synchronously* is as safe as rejecting: this need not be an `async`
+     * function, and the runtime handles either.
+     */
+    onMessagesDisplaced?: (messages: SessionMessage[]) => Promise<void>;
     /** Tables this plugin owns, outside core's migration journal. See {@link PluginStore}. */
     store?: PluginStore;
+    /**
+     * The durable file store a subagent execution's workspace is built over.
+     *
+     * Core declares the {@link WorkspaceBacking} shape and enforces the caps, but
+     * ships no backend: the predecessor's was `@cloudflare/shell`, which is
+     * experimental ("expect breaking changes"), and an agent that never delegates
+     * file work should not carry it. So the backend arrives here, from a plugin,
+     * and an agent that installs none falls back to an in-memory one.
+     *
+     * At most one installed plugin may declare this — two backends would mean two
+     * answers to "where did that file go", and the file would be in whichever the
+     * runtime happened to pick.
+     *
+     * `sql` is the executing facet's own SQLite, so isolation per execution is
+     * free and deleting the child wipes the workspace with it. `name` is lazy
+     * because a facet's name is set after construction.
+     */
+    workspaceBacking?: (sql: SqlStorage, name: () => string | undefined) => WorkspaceBacking;
     /**
      * Bindings and secrets the host must declare in `wrangler.jsonc`. A plugin
      * cannot add its own binding, so declaring them lets startup fail with a

package/dist/contract/plugin.d.ts.map

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

package/dist/contract/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/contract/plugin.ts"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAqJzC;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,MAEC;IAED,OAAO;QACL,GAAG,MAAM;QACT,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,uBAAuB;KACnE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/contract/plugin.ts"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAkQzC;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,MAEC;IAED,OAAO;QACL,GAAG,MAAM;QACT,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,uBAAuB;KACnE,CAAC;AACJ,CAAC"}