@ixo/oracle-runtime-workers 0.22.0 → 0.24.0

package/src/memory/session-history-indexer.ts

@@ -16,7 +16,10 @@
  *  - Auth is the oracle's two-hop UCAN invocation minted from the user's
  *    delegation (`ixo:memory` / `memory/*`) — no delegation, no indexing.
  *  - Endpoint: `POST <MEMORY_ENGINE_URL>/messages` with `x-room-id`, as
- *    `@ixo/common`'s `MemoryEngineService.processConversationHistory`.
+ *    `@ixo/common`'s `MemoryEngineService.processConversationHistory`, plus
+ *    `x-oracle-entity-did`: the engine keys the user's space by the oracle's
+ *    domain entity (`ORACLE_ENTITY_DID`). Without one nothing is indexed
+ *    (one warning per indexer) and the watermark stays put.
  *  - A per-session lock prevents overlapping runs; a failed upload is
  *    retried 3× with a 10 s pause (Node's numbers).
  *
@@ -24,6 +27,7 @@
  * preferred name is set; here the fallback is the literal "Me" straight away.
  */
 import type { Logger } from '../plugin-api/types';
+import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
 
 export interface HistoryMessage {
   /** LangChain message type: `human` | `ai` | `tool` | `system`. */
@@ -53,6 +57,12 @@ export interface SpeakerLabels {
 export interface SessionHistoryIndexerDeps {
   /** `MEMORY_ENGINE_URL`; undefined disables indexing (memory plugin absent). */
   memoryEngineUrl: string | undefined;
+  /**
+   * The configured `ORACLE_ENTITY_DID` (a well-formed domain entity DID),
+   * sent as `x-oracle-entity-did`. Never the `ORACLE_DID` fallback:
+   * undefined → every session is `skipped`.
+   */
+  entityDid: string | undefined;
   getSession(sessionId: string): Promise<IndexableSession | undefined>;
   /** The session transcript, summarisation bookkeeping already removed. */
   listMessages(sessionId: string): Promise<HistoryMessage[]>;
@@ -153,6 +163,9 @@ export class SessionHistoryIndexer {
 
   private readonly requestTimeoutMs: number;
 
+  /** The missing-entity warning has been logged (it is logged once). */
+  private warnedNoEntity = false;
+
   constructor(private readonly deps: SessionHistoryIndexerDeps) {
     this.fetchImpl = deps.fetchImpl ?? fetch.bind(globalThis);
     this.sleep =
@@ -187,6 +200,16 @@ export class SessionHistoryIndexer {
       );
       return 'skipped';
     }
+    const entityDid = this.deps.entityDid;
+    if (!entityDid) {
+      if (!this.warnedNoEntity) {
+        this.warnedNoEntity = true;
+        logger.warn(
+          `[history-indexer] ORACLE_ENTITY_DID is not a domain entity DID (did:ixo:entity:<32 hex>); the memory engine keys every space by it, so session history is not indexed`,
+        );
+      }
+      return 'skipped';
+    }
     if (this.inFlight.has(sessionId)) {
       logger.log(
         `[history-indexer] session ${sessionId} is already being indexed, skipping`,
@@ -197,7 +220,7 @@ export class SessionHistoryIndexer {
     try {
       for (let attempt = 1; attempt <= this.maxRetries; attempt += 1) {
         try {
-          const outcome = await this.processOnce(sessionId);
+          const outcome = await this.processOnce(sessionId, entityDid);
           if (outcome === 'processed') {
             logger.log(
               `[history-indexer] indexed session ${sessionId} into the memory engine`,
@@ -223,7 +246,10 @@ export class SessionHistoryIndexer {
     }
   }
 
-  private async processOnce(sessionId: string): Promise<IndexOutcome> {
+  private async processOnce(
+    sessionId: string,
+    entityDid: string,
+  ): Promise<IndexOutcome> {
     const { deps } = this;
     const { logger } = deps;
     const memoryEngineUrl = deps.memoryEngineUrl!.replace(/\/+$/, '');
@@ -306,6 +332,7 @@ export class SessionHistoryIndexer {
         headers: {
           Authorization: `Bearer ${invocation}`,
           'X-Auth-Type': 'ucan',
+          [MEMORY_ENTITY_HEADER]: entityDid,
           'x-room-id': roomId,
           'Content-Type': 'application/json',
         },

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

@@ -9,7 +9,8 @@
  * memory-context block before the model's first call.
  *
  * Policy:
- *  - The result is a function of the room (and the oracle), not the session,
+ *  - The result is a function of the room (and the oracle's domain entity,
+ *    which keys every memory space on the engine), not the session,
  *    so the cache is keyed by room: a new session in the same room reuses it.
  *    Positive entries live `cacheTtlMs` (5 min) in an LRU of `maxCachedRooms`.
  *    A successful batch is cached even when every slot is empty — "no
@@ -25,7 +26,9 @@
  *    a memory write and after session history is indexed.
  *  - A missing signing key or a failed invocation mint is a skip, never a
  *    negative-cache entry: the user may delegate `ixo:memory` before the next
- *    turn.
+ *    turn. So is a missing domain entity (`ORACLE_ENTITY_DID`): the engine
+ *    refuses a request that names none, so none is sent; it is warned about
+ *    once per fetcher.
  *  - One gather per room at a time; a second caller joins it. The blocking
  *    `fetch` waits at most `blockingCapMs`; past the cap the gather keeps
  *    running and fills the cache for later turns (the caller keeps the
@@ -41,6 +44,7 @@
  */
 import type { MemoryContextSection } from '../core/prompt-composer';
 import type { Logger, UserContextData } from '../plugin-api/types';
+import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
 import type {
   ComparisonOperator,
   EntityType,
@@ -99,15 +103,17 @@ const RECENT_WINDOW_DAYS = 90;
  * brittle), `node_labels` only where it discriminates, and the `recent`
  * slot bounded to the last 90 days explicitly (the server's
  * `recent_memory` strategy injects the same lower bound and keeps an
- * existing one).
+ * existing one). `oracle_dids` names the oracle's domain entity.
  */
 export function buildUserContextQueries(
-  oracleDid: string,
+  entityDid: string,
   now: Date,
 ): UserContextQuery[] {
   const recentSince = new Date(now.getTime());
   recentSince.setUTCDate(recentSince.getUTCDate() - RECENT_WINDOW_DAYS);
-  const oracle_dids = [oracleDid];
+  // The wire name predates entity keying; the engine reads its entries as
+  // domain entity DIDs (the knowledge spaces the queries also search).
+  const oracle_dids = [entityDid];
   return [
     {
       oracle_dids,
@@ -471,8 +477,13 @@ function perSlot<T>(
 export interface UserContextFetcherDeps {
   /** `MEMORY_ENGINE_URL`; undefined → every call is `skipped`, no request. */
   memoryEngineUrl: string | undefined;
-  /** `ORACLE_DID` — the knowledge space the queries search (`oracle_dids`). */
-  oracleDid: string;
+  /**
+   * The configured `ORACLE_ENTITY_DID` (a well-formed domain entity DID) —
+   * sent as `x-oracle-entity-did` and as the queries' `oracle_dids`. Never
+   * the `ORACLE_DID` fallback: undefined → every call is `skipped`
+   * (`no-entity`), no request, one warning per fetcher.
+   */
+  entityDid: string | undefined;
   /** The user's UCAN surface, bound to the user's DID by the caller. */
   ucan: {
     hasSigningKey(): boolean;
@@ -515,6 +526,7 @@ const DEFAULT_MAX_CACHED_ROOMS = 64;
 
 export type UserContextSkipReason =
   | 'no-engine-url'
+  | 'no-entity'
   | 'no-signing-key'
   | 'no-invocation'
   | 'recently-failed'
@@ -616,6 +628,9 @@ export class UserContextFetcher {
 
   private readonly maxCachedRooms: number;
 
+  /** The missing-entity warning has been logged (it is logged once). */
+  private warnedNoEntity = false;
+
   constructor(
     private readonly deps: UserContextFetcherDeps,
     options: UserContextFetcherOptions = {},
@@ -773,6 +788,16 @@ export class UserContextFetcher {
       );
       return { kind: 'skipped', reason: 'no-engine-url' };
     }
+    const entityDid = this.deps.entityDid;
+    if (!entityDid) {
+      if (!this.warnedNoEntity) {
+        this.warnedNoEntity = true;
+        logger.warn(
+          `[user-context] skipped: ORACLE_ENTITY_DID is not a domain entity DID (did:ixo:entity:<32 hex>); the memory engine keys every space by it, so no first-turn context is gathered`,
+        );
+      }
+      return { kind: 'skipped', reason: 'no-entity' };
+    }
     if (!roomId) {
       logger.warn(`[user-context] skipped: no oracle room for this turn`);
       return { kind: 'skipped', reason: 'no-room' };
@@ -807,7 +832,7 @@ export class UserContextFetcher {
 
     const entry: InFlightGather = {
       startedAt: this.now(),
-      promise: this.gather(engineUrl, roomId).then(
+      promise: this.gather(engineUrl, entityDid, roomId).then(
         (result) => this.settle(roomId, entry, result),
         (err: unknown) =>
           this.settle(roomId, entry, {
@@ -870,6 +895,7 @@ export class UserContextFetcher {
   /** Mint the invocation, run the batch, map the slots. Never rejects. */
   private async gather(
     engineUrl: string,
+    entityDid: string,
     roomId: string,
   ): Promise<GatherResult> {
     const { logger, ucan } = this.deps;
@@ -905,14 +931,12 @@ export class UserContextFetcher {
         headers: {
           Authorization: `Bearer ${invocation}`,
           'X-Auth-Type': 'ucan',
+          [MEMORY_ENTITY_HEADER]: entityDid,
           'x-room-id': roomId,
           'Content-Type': 'application/json',
         },
         body: JSON.stringify({
-          queries: buildUserContextQueries(
-            this.deps.oracleDid,
-            new Date(this.now()),
-          ),
+          queries: buildUserContextQueries(entityDid, new Date(this.now())),
         }),
         signal: AbortSignal.timeout(this.requestTimeoutMs),
       });

package/src/plugin-api/types.ts

@@ -1,3 +1,12 @@
+import type {
+  TopicActionProposal,
+  TopicProposalSubject,
+} from '@ixo/ixo-transaction/topic-proposals';
+import type { TopicCandidate } from '../action-proposals/topic-prepare';
+import type {
+  ActionProposal,
+  ActionProposalSubject,
+} from '@ixo/ixo-transaction/action-proposals';
 import type { TaskExecutionProfile } from '../core/execution-profile';
 import type {
   DecisionDefinition,
@@ -10,6 +19,12 @@ import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import type { UserPreferences } from '../core/state';
 import type { AttachmentViewSurface } from '../attachments/view';
 import type { DeliveryConfig } from '../delivery/profile';
+import type {
+  ActionOperationV1,
+  ActionReferenceV1,
+  ActionOutcomeV1,
+  ActionCapabilitiesV1,
+} from '@ixo/action-protocol';
 
 /**
  * Route shape returned by `OraclePlugin.getAuthExcludedRoutes()`. Paths are
@@ -530,6 +545,13 @@ export interface RuntimeContext<TConfig = MergedConfig> {
     client: 'portal' | 'matrix' | 'slack' | 'channel';
     wsId?: string;
     requestId: string;
+    runId?: string;
+    /** Authenticated channel identity captured by the runtime for this turn. */
+    channel?: {
+      provider: string;
+      bindingId: string;
+      bindingRevision: number;
+    };
     roomId?: string;
     /**
      * Where the reply lands. `stream` is the Portal; `chat` is a chat app
@@ -723,6 +745,38 @@ export interface RuntimeContext<TConfig = MergedConfig> {
    * Bounded semantic decisions. A decision only returns structured judgment;
    * policy, authority checks, and side effects remain outside this primitive.
    */
+  actionProposals?: {
+    create(subject: ActionProposalSubject): Promise<ActionProposal>;
+    prepareTopic?(input: {
+      candidate: TopicCandidate;
+      origin: TopicProposalSubject['origin'];
+      evidenceRefs: string[];
+    }): Promise<TopicActionProposal>;
+  };
+
+  /** Host-owned action coordinator. It accepts only runtime-derived channel context. */
+  hubActions?: {
+    capabilities(): Promise<ActionCapabilitiesV1>;
+    options(input: {
+      ownerDid: string;
+      provider: string;
+      bindingId: string;
+      bindingRevision: number;
+    }): Promise<import('@ixo/action-protocol').HubActionOptionsV2>;
+    request(input: {
+      ownerDid: string;
+      sessionId: string;
+      runId: string;
+      requestId: string;
+      provider: string;
+      bindingId: string;
+      bindingRevision: number;
+      requestKey: string;
+      operation: ActionOperationV1;
+    }): Promise<ActionReferenceV1>;
+    status(ownerDid: string, actionId: string): Promise<ActionOutcomeV1 | null>;
+  };
+
   decisions: {
     evaluate<TSchema extends z.ZodType>(
       definition: DecisionDefinition<TSchema>,