@ixo/oracle-runtime-workers 0.20.1 → 0.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "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,8 +58,8 @@
     "wa-sqlite": "1.0.0",
     "yjs": "13.6.32",
     "zod": "^4.4.3",
-    "@ixo/ixo-transaction": "0.1.0",
     "@ixo/common": "1.7.0",
+    "@ixo/ixo-transaction": "0.1.0",
     "@ixo/ucan": "2.2.1"
   },
   "devDependencies": {

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

@@ -3198,17 +3198,28 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       client: TurnRequest['client'];
       roomKind: TurnRequest['roomKind'];
     }): UserContextSettle | null {
-      // Task runs never get the user's memory (see `scheduleHistoryIndexing`).
-      if (!input.roomId || input.sessionId.startsWith(TASK_SESSION_PREFIX))
+      // A first contact that fetches nothing still prints the one
+      // first-contact line (see the settle step below), with its reason, so
+      // a warn-level reading of the logs accounts for every first turn.
+      const skipped = (reason: string): null => {
+        if (!hasUserContext(input.prior)) {
+          console.warn(
+            `[user-context] first contact room=${input.roomId ?? '-'} session=${input.sessionId} outcome=skipped reason=${reason} waited=0ms`,
+          );
+        }
         return null;
+      };
+      // Task runs never get the user's memory (see `scheduleHistoryIndexing`).
+      if (input.sessionId.startsWith(TASK_SESSION_PREFIX)) return null;
+      if (!input.roomId) return skipped('no-room');
       const settings = this.userContextSettings();
+      if (!settings) return skipped('disabled');
       const ambient = this.ambient;
-      if (!settings || !ambient) return null;
+      if (!ambient) return skipped('not-booted');
       // A group room's reply is posted to every member: one user's memory
       // must not be (as direct reads are not, see `admissionApplies`).
       if (input.client === 'matrix' && input.roomKind === 'group') {
-        console.log('[user-context] skipped: group room');
-        return null;
+        return skipped('group-room');
       }
       // Without a memory grant the gather could only fail at the mint: skip
       // it before any request (the engine's did.json included).
@@ -3219,10 +3230,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           MEMORY_CAPABILITY.action,
         )
       ) {
-        console.log(
-          `[user-context] skipped: the delegation grants no ${MEMORY_CAPABILITY.resource} ${MEMORY_CAPABILITY.action}`,
-        );
-        return null;
+        return skipped('no-memory-grant');
       }
       const fetcher = this.userContextFetcherFor(settings);
       const params: UserContextFetchParams = {
@@ -3265,8 +3273,12 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           // 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.
+          const reason =
+            outcome?.kind === 'skipped' || outcome?.kind === 'failed'
+              ? ` reason=${outcome.reason}`
+              : '';
           console.warn(
-            `[user-context] first contact room=${input.roomId} session=${input.sessionId} outcome=${outcome?.kind ?? 'aborted'} waited=${Date.now() - waitedFrom}ms`,
+            `[user-context] first contact room=${input.roomId} session=${input.sessionId} outcome=${outcome?.kind ?? 'aborted'}${reason} waited=${Date.now() - waitedFrom}ms`,
           );
           return outcome?.kind === 'cached' || outcome?.kind === 'fresh'
             ? withEverySlot(outcome.context)

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[];
 }