@ixo/oracle-runtime-workers 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -58,9 +58,9 @@
     "wa-sqlite": "1.0.0",
     "yjs": "13.6.32",
     "zod": "^4.4.3",
-    "@ixo/common": "1.7.0",
+    "@ixo/ucan": "2.2.1",
     "@ixo/ixo-transaction": "0.1.0",
-    "@ixo/ucan": "2.2.1"
+    "@ixo/common": "1.7.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/do/user-oracle-do.ts

@@ -3253,6 +3253,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       keepGathering();
       return async (onSlow, signal) => {
         if (signal.aborted) return undefined;
+        const waitedFrom = Date.now();
         const timer = setTimeout(onSlow, USER_CONTEXT_PROGRESS_GRACE_MS);
         let onAbort: (() => void) | undefined;
         const aborted = new Promise<undefined>((resolve) => {
@@ -3261,6 +3262,12 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         });
         try {
           const outcome = await Promise.race([pending, aborted]);
+          // One line per first contact, at warn so it stands out when logs
+          // are read at warn and above: what the turn was given and how
+          // long it waited for it.
+          console.warn(
+            `[user-context] first contact room=${input.roomId} session=${input.sessionId} outcome=${outcome?.kind ?? 'aborted'} waited=${Date.now() - waitedFrom}ms`,
+          );
           return outcome?.kind === 'cached' || outcome?.kind === 'fresh'
             ? withEverySlot(outcome.context)
             : undefined;

package/src/memory/user-context-fetcher.ts

@@ -557,8 +557,18 @@ type GatherResult = Extract<
 
 interface InFlightGather {
   promise: Promise<GatherResult>;
+  /** `now()` when the gather started; a gather older than its request timeout plus grace is treated as lost. */
+  startedAt: number;
 }
 
+/**
+ * Grace past `requestTimeoutMs` before an unsettled gather is given up on.
+ * A gather settles within its request timeout; one that has not after this
+ * long never will (its request context is gone), and a room must not keep
+ * joining it.
+ */
+const STALE_GATHER_GRACE_MS = 5_000;
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
@@ -769,7 +779,18 @@ export class UserContextFetcher {
     }
 
     const existing = this.inFlight.get(roomId);
-    if (existing) return existing;
+    if (existing) {
+      const ageMs = this.now() - existing.startedAt;
+      if (ageMs <= this.requestTimeoutMs + STALE_GATHER_GRACE_MS) {
+        return existing;
+      }
+      // Lost: never settled within its own timeout. Detach it (a late
+      // settle must not repopulate the room) and gather again.
+      logger.warn(
+        `[user-context] gather for room=${roomId} unsettled after ${ageMs}ms; starting a new one`,
+      );
+      this.inFlight.delete(roomId);
+    }
 
     if (this.recentlyFailed(roomId)) {
       logger.log(
@@ -785,6 +806,7 @@ export class UserContextFetcher {
     }
 
     const entry: InFlightGather = {
+      startedAt: this.now(),
       promise: this.gather(engineUrl, roomId).then(
         (result) => this.settle(roomId, entry, result),
         (err: unknown) =>

package/src/plugins/memory/memory-tools.ts

@@ -23,14 +23,21 @@ export const MEMORY_DELETE_EDGE_MCP_NAME = 'memory-engine__delete_edge';
 export const MEMORY_CLEAR_MCP_NAME = 'memory-engine__clear';
 
 /**
- * Default selection: search, add, delete-episode, and clear — the user must
- * always be able to ask for a full memory wipe, so the destructive `clear`
- * stays in the default set. Forks that need org-owner knowledge writes (or
- * want to drop `clear`) pass an explicit list via plugin options.
+ * Default selection: search, add, add-oracle-knowledge, delete-episode, and
+ * clear. The user must always be able to ask for a full memory wipe, so the
+ * destructive `clear` stays in the default set. `add_oracle_knowledge` is in
+ * the set so the controllers and owners of any oracle can grow its shared
+ * knowledge from chat without a per-oracle code change: the Memory Engine
+ * itself checks on chain that the caller controls or owns an entity linked to
+ * the oracle and refuses everyone else, so listing the tool for every user
+ * costs one tool description and grants nothing. Forks that want a different
+ * surface (drop `clear`, add `delete_edge`) pass an explicit list via plugin
+ * options.
  */
 export const DEFAULT_MEMORY_TOOLS = [
   MEMORY_SEARCH_MCP_NAME,
   MEMORY_ADD_MCP_NAME,
+  MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME,
   MEMORY_DELETE_EPISODE_MCP_NAME,
   MEMORY_CLEAR_MCP_NAME,
 ] as const;
@@ -450,7 +457,7 @@ function adaptMcpTool(mcpTool: UpstreamMcpTool): PluginTool {
 /**
  * Fetch the upstream Memory Engine MCP tools for this request and return them
  * as `PluginTool[]`. Filtered by `selectedTools` so forks can scope the
- * surface (e.g. drop `clear`, add `add_oracle_knowledge` for org-owner mode).
+ * surface (e.g. drop `clear`, add `delete_edge`).
  *
  * Returns `[]` when the factory cannot mint auth — the agent then sees no
  * memory tools rather than getting a half-built request to upstream.

package/src/plugins/memory/memory.plugin.ts

@@ -32,12 +32,14 @@ const manifest: PluginManifest = {
     'You create an artifact for the user (file, document, edit, generated content): record what it is, what it is for, and the structural choices you made.',
     'The user expresses satisfaction or dissatisfaction with something you produced: capture what worked or what did not — tone, length, structure, style — against that artifact entry.',
     'The user references something they told you before, or something you made before.',
+    'A controller or owner of this oracle asks you to store something every user of the oracle should know (a policy, a procedure, reference material): tell them it will be shared with every user of the oracle (or, for the private space, with its controllers and owners only), get their confirmation, then store it as oracle knowledge rather than as a memory about them.',
   ],
   whenNotToUse: [
     'Ephemeral conversation-only state (use the current message thread).',
     'Behavioral preferences about how to respond (call the user-preferences tool instead).',
     'Public web facts that are not specific to this user (use a web-search capability).',
     'Anything the user asked you to forget or framed as temporary.',
+    'Oracle knowledge for something about one user: the shared knowledge is only for what every user of this oracle should know.',
   ],
   tags: ['memory', 'recall', 'artifacts', 'personalization'],
   category: 'memory',
@@ -54,8 +56,8 @@ export interface MemoryPluginOptions {
   mcpFactory?: (memoryMcpUrl: string) => MemoryMcpFactory;
   /**
    * Filter the upstream tool surface. Defaults to {@link DEFAULT_MEMORY_TOOLS}
-   * (search + add + delete-episode + clear). Pass an explicit list to expose
-   * `add_oracle_knowledge`, `delete_edge`, etc.
+   * (search + add + add-oracle-knowledge + delete-episode + clear). Pass an
+   * explicit list to drop one of them or to expose `delete_edge`.
    */
   selectedTools?: readonly string[];
 }