@ixo/oracle-runtime-workers 0.22.0 → 0.24.0

package/src/plugins/hub-actions/hub-actions.plugin.ts

@@ -0,0 +1,244 @@
+import {
+  operationJsonSchema,
+  parseOperation,
+  type ActionReferenceV1,
+} from '@ixo/action-protocol';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+
+const configSchema = z.object({
+  HUB_ACTIONS_ENABLED: z.enum(['true', 'false']).default('false'),
+});
+
+const operationSchema = z.fromJSONSchema({
+  ...operationJsonSchema,
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+});
+const requestSchema = z.strictObject({ operation: operationSchema });
+const statusSchema = z.strictObject({
+  actionId: z.string().regex(/^[A-Za-z0-9_-]{32}$/),
+});
+const discoverSchema = z.strictObject({});
+
+export type HubActionRequestResult =
+  | { status: 'prepared'; actionReference: ActionReferenceV1; summary: string }
+  | {
+      status: 'unavailable' | 'expired';
+      reason: string;
+      /** The earlier action that blocks this one (an unconfirmed email). */
+      priorActionId?: string;
+    };
+
+/**
+ * The idempotency key the Hub sees: a fixed-length digest of the run and
+ * tool call (the Hub allows 120 characters; a run id alone is 72).
+ */
+async function hubRequestKey(runId: string, toolCallId: string) {
+  const bytes = new Uint8Array(
+    await crypto.subtle.digest(
+      'SHA-256',
+      new TextEncoder().encode(`${runId}:${toolCallId}`),
+    ),
+  );
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+async function requestHubAction(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<HubActionRequestResult> {
+  const parsed = requestSchema.safeParse(input);
+  if (!parsed.success)
+    return { status: 'unavailable', reason: 'An operation is required.' };
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return {
+      status: 'unavailable',
+      reason: 'Hub actions are not enabled for this oracle.',
+    };
+  const channel = ctx.session.channel;
+  if (
+    ctx.session.client !== 'channel' ||
+    !channel ||
+    !ctx.session.runId ||
+    !ctx.toolCallId
+  )
+    return {
+      status: 'unavailable',
+      reason: 'A verified channel turn is required.',
+    };
+  let operation;
+  try {
+    operation = parseOperation(parsed.data.operation);
+  } catch (error) {
+    // The protocol's own words ("Invalid fromAddress"): the model can fix
+    // the field instead of guessing.
+    return {
+      status: 'unavailable',
+      reason: `The requested operation is unsupported or incomplete${error instanceof Error && error.message ? ` (${error.message})` : ''}.`,
+    };
+  }
+  let reference: ActionReferenceV1;
+  try {
+    reference = await ctx.hubActions.request({
+      ownerDid: ctx.user.did,
+      sessionId: ctx.session.id,
+      runId: ctx.session.runId,
+      requestId: ctx.session.requestId,
+      provider: channel.provider,
+      bindingId: channel.bindingId,
+      bindingRevision: channel.bindingRevision,
+      requestKey: await hubRequestKey(ctx.session.runId, ctx.toolCallId),
+      operation,
+    });
+  } catch (error) {
+    // A cap reached, a request that expired, a run no user message
+    // started: the runtime's own words, so the model can tell the user.
+    // Anything else stays an error.
+    if (
+      error instanceof Error &&
+      error.name === 'HubActionRefused' &&
+      'kind' in error
+    )
+      return {
+        status: error.kind === 'expired' ? 'expired' : 'unavailable',
+        reason: error.message,
+        ...('priorActionId' in error && typeof error.priorActionId === 'string'
+          ? { priorActionId: error.priorActionId }
+          : {}),
+      };
+    throw error;
+  }
+  return {
+    status: 'prepared',
+    actionReference: reference,
+    summary: reference.title,
+  };
+}
+
+async function hubActionStatus(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<unknown> {
+  const parsed = statusSchema.safeParse(input);
+  if (
+    !parsed.success ||
+    !ctx.hubActions ||
+    ctx.config.HUB_ACTIONS_ENABLED !== 'true'
+  )
+    return { status: 'unavailable' };
+  return {
+    status: 'known',
+    outcome: await ctx.hubActions.status(ctx.user.did, parsed.data.actionId),
+  };
+}
+
+async function hubActionCapabilities(
+  _input: unknown,
+  ctx: RuntimeContext,
+): Promise<unknown> {
+  if (
+    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
+    ctx.session.client !== 'channel' ||
+    !ctx.session.channel ||
+    !ctx.hubActions
+  )
+    return { status: 'unavailable' };
+  return ctx.hubActions.capabilities();
+}
+
+async function hubActionOptions(
+  _input: unknown,
+  ctx: RuntimeContext,
+): Promise<unknown> {
+  const channel = ctx.session.channel;
+  if (
+    ctx.config.HUB_ACTIONS_ENABLED !== 'true' ||
+    ctx.session.client !== 'channel' ||
+    !channel ||
+    !ctx.hubActions
+  )
+    return { status: 'unavailable' };
+  return ctx.hubActions.options({
+    ownerDid: ctx.user.did,
+    provider: channel.provider,
+    bindingId: channel.bindingId,
+    bindingRevision: channel.bindingRevision,
+  });
+}
+
+const manifest: PluginManifest = {
+  title: 'Auth Hub action review',
+  summary:
+    'Prepare a registered operation for owner review and read its verified status.',
+  whenToUse: [
+    'The user requests a registered form submission or a transfer.',
+    'The user asks to review an exact private resource or to sign a statement.',
+    'The user asks to connect Gmail or Calendar, send a reviewed email or add an event.',
+    'The user asks for document access or to save a private note.',
+  ],
+  whenNotToUse: [
+    'Signing, executing, or treating a resource open as acceptance.',
+  ],
+  tags: ['actions', 'channels'],
+  category: 'integration',
+  visibility: 'on-demand',
+  stability: 'experimental',
+};
+
+export class HubActionsPlugin extends OraclePlugin {
+  readonly name = 'hub-actions';
+  readonly version = '0.1.0';
+  readonly manifest = manifest;
+  override readonly configSchema = configSchema;
+  /** The flag alone is not enough: the owner object needs the Hub's URL and this oracle's key. */
+  override autoDetect(env: Record<string, unknown>): boolean {
+    return (
+      env.HUB_ACTIONS_ENABLED === 'true' &&
+      typeof env.AUTH_HUB_URL === 'string' &&
+      env.AUTH_HUB_URL.length > 0 &&
+      typeof env.AUTH_HUB_CHANNEL_SERVICE_KEY === 'string' &&
+      env.AUTH_HUB_CHANNEL_SERVICE_KEY.length > 0
+    );
+  }
+  override getTools(): PluginTool[] {
+    return [
+      {
+        name: 'hub_action_capabilities',
+        description:
+          "Read this authenticated oracle account's enabled operation kinds and exact registered form field schema before proposing a Hub action.",
+        schema: discoverSchema,
+        effect: 'read',
+        handler: hubActionCapabilities,
+      },
+      {
+        name: 'hub_action_options',
+        description:
+          'Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents and action resources. Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending.',
+        schema: discoverSchema,
+        effect: 'read',
+        handler: hubActionOptions,
+      },
+      {
+        name: 'request_hub_action',
+        description:
+          'Prepare a supported operation for the authenticated channel owner to review in Auth Hub. Never approves, signs, or executes. For email, propose one plain-text message to one recipient using a confirmed Gmail send connection. Supply only the operation candidate; the runtime supplies identity and turn binding. Never prepare a replacement email after an unknown send without the user checking Gmail’s Sent folder and asking again.',
+        schema: requestSchema,
+        effect: 'write',
+        handler: requestHubAction,
+      },
+      {
+        name: 'hub_action_status',
+        description:
+          'Read the verified status of a Hub action already prepared for this owner. Never executes.',
+        schema: statusSchema,
+        effect: 'read',
+        handler: hubActionStatus,
+      },
+    ];
+  }
+}

package/src/plugins/index.ts

@@ -1,3 +1,7 @@
+import { ActionProposalsPlugin } from './action-proposals/action-proposals.plugin';
+import { HubActionsPlugin } from './hub-actions/hub-actions.plugin';
+export { ActionProposalsPlugin } from './action-proposals/action-proposals.plugin';
+export { HubActionsPlugin } from './hub-actions/hub-actions.plugin';
 /**
  * Bundled Workers-runtime plugins — ports of the Node runtime's MCP / fetch
  * plugins. Each is gated the same way as on Node: `autoDetect` on its env
@@ -66,6 +70,8 @@ export const tasksPlugin = TasksPlugin;
  * instances instead of using these singletons.
  */
 export const BUNDLED_WORKERS_PLUGINS = [
+  new ActionProposalsPlugin(),
+  new HubActionsPlugin(),
   memoryPlugin,
   sandboxPlugin,
   firecrawlPlugin,

package/src/plugins/memory/index.ts

@@ -12,6 +12,10 @@ export {
   type MemoryMcpFactory,
   type UpstreamMcpTool,
 } from './memory-tools';
+export {
+  MEMORY_ENTITY_HEADER,
+  ORACLE_ENTITY_DID_PATTERN,
+} from './memory-entity';
 export { buildMemoryHeaders } from './memory-ucan';
 export { MemoryPlugin, type MemoryPluginOptions } from './memory.plugin';
 export type * from './types';

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

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+/**
+ * The Memory Engine keys every memory space by the oracle's domain entity
+ * (`did:ixo:entity:<32 hex>`): the user's personal space is
+ * `sha256(<userDid>-<entityDid>)` and the shared knowledge spaces are the
+ * entity's. Every engine request names the entity in this header; the engine
+ * refuses a request without it and checks (on chain) that the entity lists
+ * the oracle's agent account as a Matrix admin.
+ */
+export const MEMORY_ENTITY_HEADER = 'x-oracle-entity-did';
+
+/** The shape the Memory Engine accepts for {@link MEMORY_ENTITY_HEADER}. */
+export const ORACLE_ENTITY_DID_PATTERN = /^did:ixo:entity:[0-9a-f]{32}$/;
+
+const ENTITY_REQUIRED_MESSAGE =
+  "ORACLE_ENTITY_DID is required by the memory plugin: set it to the oracle's domain entity DID (did:ixo:entity: followed by 32 lower-case hex characters). The Memory Engine keys every memory space by that entity and refuses requests without it.";
+
+const ENTITY_SHAPE_MESSAGE =
+  "ORACLE_ENTITY_DID must be the oracle's domain entity DID (did:ixo:entity: followed by 32 lower-case hex characters); the Memory Engine refuses any other value.";
+
+/**
+ * `ORACLE_ENTITY_DID` as the memory plugin requires it. The core schema keeps
+ * the variable optional (rooms and feedback fall back to `ORACLE_DID`); the
+ * memory plugin redeclares it so an oracle with `MEMORY_MCP_URL` and no
+ * entity fails at boot. The engine never receives the `ORACLE_DID` fallback.
+ */
+export const oracleEntityDidSchema = z
+  .string({
+    error: (issue) =>
+      issue.input === undefined
+        ? ENTITY_REQUIRED_MESSAGE
+        : ENTITY_SHAPE_MESSAGE,
+  })
+  .regex(ORACLE_ENTITY_DID_PATTERN, ENTITY_SHAPE_MESSAGE);
+
+/**
+ * The configured `ORACLE_ENTITY_DID` when it is a well-formed domain entity
+ * DID, else `undefined`. For the engine paths outside the plugin (first-turn
+ * prefetch, session-history indexing, the memory debug route): they read the
+ * merged env directly and run wherever `MEMORY_ENGINE_URL` survives
+ * validation, which another plugin than this one may declare, so the
+ * plugin's schema does not cover them.
+ */
+export function memoryEntityDid(value: unknown): string | undefined {
+  return typeof value === 'string' && ORACLE_ENTITY_DID_PATTERN.test(value)
+    ? value
+    : undefined;
+}

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

@@ -28,8 +28,9 @@ export const MEMORY_CLEAR_MCP_NAME = 'memory-engine__clear';
  * 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
+ * itself checks on chain that the caller is a member (controller, owner,
+ * Matrix admin or DAO member) of the oracle's domain entity 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.
@@ -370,7 +371,8 @@ function buildLazyUpstreamTools(
 
 /**
  * Default factory: authenticates with the per-request UCAN headers from
- * {@link buildMemoryHeaders}, then serves the upstream tool list.
+ * {@link buildMemoryHeaders} (which name the oracle's domain entity,
+ * `entityDid`), then serves the upstream tool list.
  *
  * The first request per isolate connects and lists tools exactly like the
  * old always-fetch path, then snapshots the definitions. Subsequent requests
@@ -384,9 +386,10 @@ function buildLazyUpstreamTools(
  */
 export function createDefaultMemoryMcpFactory(
   memoryMcpUrl: string,
+  entityDid: string,
 ): MemoryMcpFactory {
   return async (runCtx) => {
-    const headers = await buildMemoryHeaders(runCtx, memoryMcpUrl);
+    const headers = await buildMemoryHeaders(runCtx, memoryMcpUrl, entityDid);
     if (!headers) return null;
 
     const cached = toolDefsCache.get(memoryMcpUrl);

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

@@ -1,6 +1,7 @@
 import type { RuntimeContext } from '../../plugin-api/types';
 import { MEMORY_CAPABILITY } from '../delegated-capabilities';
 import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
+import { MEMORY_ENTITY_HEADER } from './memory-entity';
 
 /**
  * Build the headers needed to call the Memory Engine MCP server on behalf of
@@ -9,7 +10,13 @@ import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
  *   1. Resolve the memory service DID via `runCtx.ucan.resolveServiceDid`
  *      (delegates the did:web lookup + cache to the UCAN service).
  *   2. Mint an `ixo:memory` invocation using the user's signing key.
- *   3. Layer the resulting Bearer token plus the active `x-room-id`.
+ *   3. Layer the resulting Bearer token, the oracle's domain entity
+ *      (`x-oracle-entity-did`, which keys every memory space on the engine)
+ *      and the active `x-room-id`.
+ *
+ * `entityDid` is the configured `ORACLE_ENTITY_DID` (validated by the memory
+ * plugin's `configSchema`), passed in because `RuntimeContext` carries no
+ * oracle identity. It is never the core's `ORACLE_DID` fallback.
  *
  * UCAN-only — no Matrix-OpenID fallback. If resolution or minting fails for
  * any reason (no signing key, no cached delegation, did:web unresolved,
@@ -22,6 +29,7 @@ import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
 export async function buildMemoryHeaders(
   runCtx: RuntimeContext,
   memoryMcpUrl: string,
+  entityDid: string,
 ): Promise<Record<string, string> | null> {
   const memoryDid = await resolveServiceDidSafely(
     runCtx,
@@ -44,6 +52,7 @@ export async function buildMemoryHeaders(
     Authorization: `Bearer ${invocation}`,
     'X-Auth-Type': 'ucan',
     'User-Agent': 'LangChain-MCP-Client/1.0',
+    [MEMORY_ENTITY_HEADER]: entityDid,
   };
   if (runCtx.session.roomId) {
     headers['x-room-id'] = runCtx.session.roomId;

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

@@ -14,12 +14,16 @@ import {
   fetchMemoryTools,
   type MemoryMcpFactory,
 } from './memory-tools';
+import { oracleEntityDidSchema } from './memory-entity';
 
 const configSchema = z.object({
   MEMORY_MCP_URL: z.string().url('MEMORY_MCP_URL must be a valid HTTP(S) URL.'),
   MEMORY_ENGINE_URL: z
     .string()
     .url('MEMORY_ENGINE_URL must be a valid HTTP(S) URL.'),
+  // The Memory Engine keys every space by the oracle's domain entity; an
+  // oracle without one gets no memory at all, so it fails at boot instead.
+  ORACLE_ENTITY_DID: oracleEntityDidSchema,
 });
 
 const manifest: PluginManifest = {
@@ -51,9 +55,11 @@ const manifest: PluginManifest = {
 export interface MemoryPluginOptions {
   /**
    * Override the MCP-tools factory. Defaults to an HTTP MCP client against
-   * `MEMORY_MCP_URL` authenticated with a per-request UCAN invocation.
+   * `MEMORY_MCP_URL` authenticated with a per-request UCAN invocation and
+   * the oracle's domain entity (`ORACLE_ENTITY_DID`, the engine's
+   * `x-oracle-entity-did` header).
    */
-  mcpFactory?: (memoryMcpUrl: string) => MemoryMcpFactory;
+  mcpFactory?: (memoryMcpUrl: string, entityDid: string) => MemoryMcpFactory;
   /**
    * Filter the upstream tool surface. Defaults to {@link DEFAULT_MEMORY_TOOLS}
    * (search + add + add-oracle-knowledge + delete-episode + clear). Pass an
@@ -62,9 +68,15 @@ export interface MemoryPluginOptions {
   selectedTools?: readonly string[];
 }
 
-function resolveMemoryUrl(config: MergedConfig): string {
+function resolveMemoryConfig(config: MergedConfig): {
+  memoryMcpUrl: string;
+  entityDid: string;
+} {
   const parsed = configSchema.parse(config);
-  return parsed.MEMORY_MCP_URL;
+  return {
+    memoryMcpUrl: parsed.MEMORY_MCP_URL,
+    entityDid: parsed.ORACLE_ENTITY_DID,
+  };
 }
 
 /**
@@ -90,7 +102,10 @@ export class MemoryPlugin extends OraclePlugin {
 
   override readonly autoDetectHint = 'MEMORY_MCP_URL';
 
-  private readonly mcpFactory: (memoryMcpUrl: string) => MemoryMcpFactory;
+  private readonly mcpFactory: (
+    memoryMcpUrl: string,
+    entityDid: string,
+  ) => MemoryMcpFactory;
 
   private readonly selectedTools: readonly string[];
 
@@ -107,8 +122,8 @@ export class MemoryPlugin extends OraclePlugin {
   }
 
   override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
-    const memoryUrl = resolveMemoryUrl(rtCtx.config);
-    const factory = this.mcpFactory(memoryUrl);
+    const { memoryMcpUrl, entityDid } = resolveMemoryConfig(rtCtx.config);
+    const factory = this.mcpFactory(memoryMcpUrl, entityDid);
     return fetchMemoryTools(rtCtx, factory, this.selectedTools);
   }