@ixo/oracle-runtime-workers 0.24.0 → 0.26.0

package/src/plugins/memory/document-source.ts

@@ -0,0 +1,229 @@
+/**
+ * Where the memory plugin's document tools get a document's text from: a chat
+ * attachment of the session (through the host's `AttachmentViewSurface`) or a
+ * file in the user's VFS. Both lanes return the document's own words — plain
+ * text decoded locally, a PDF's text layer parsed locally, anything else (a
+ * scan, an image, an Office file) transcribed by the helper model — never a
+ * stub or a `[Content of …]` wrapper.
+ *
+ * Every error thrown here carries a message meant for the person (the tools
+ * relay it as is).
+ */
+import { capText } from '../../attachments/extract';
+import { extractPdfText } from '../../attachments/pdf-text';
+import type { RuntimeContext } from '../../plugin-api/types';
+import type { VfsClient, VfsContentBytes } from '../vfs/vfs-client';
+import { mapVfsError, VfsAuthError, VfsHttpError } from '../vfs/vfs-errors';
+import {
+  isTextMime,
+  MAX_VISION_BYTES,
+  renderBinaryForIngestion,
+} from '../vfs/vfs-content';
+import { buildClient } from '../vfs/vfs-tools';
+import { resolveVfsConfig, type VfsConfig } from '../vfs/vfs.plugin';
+
+export type DocumentSource = { attachment_ref: string } | { vfs_path: string };
+
+export interface LoadedDocument {
+  text: string;
+  filename: string;
+  mimetype: string;
+  /** Size of the original file in bytes (of the text when the host did not report it). */
+  bytes: number;
+  method: 'text' | 'pdf' | 'model';
+  /** Page count, set when the text came from a PDF's text layer. */
+  pages?: number;
+  /** True when the text was cut at `maxChars`. */
+  truncated: boolean;
+}
+
+export interface DocumentSourceDeps {
+  /** Longest text returned (characters); more is cut and reported as `truncated`. */
+  maxChars: number;
+  /** Injected transport for the VFS client (tests). */
+  fetchImpl?: typeof fetch;
+  /** Retry backoff forwarded to the VFS client (tests pass `0`). */
+  retryDelayMs?: number;
+}
+
+const PDF_MIME = 'application/pdf';
+
+const LIBRARY_DISABLED = 'Library files are not enabled on this oracle.';
+
+function basename(path: string): string {
+  const i = path.lastIndexOf('/');
+  return i >= 0 ? path.slice(i + 1) : path;
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function requireText(loaded: LoadedDocument): LoadedDocument {
+  if (loaded.text.trim().length === 0) {
+    throw new Error(
+      `No text could be extracted from "${loaded.filename}" (${loaded.mimetype}).`,
+    );
+  }
+  return loaded;
+}
+
+export async function loadDocumentText(
+  ctx: RuntimeContext,
+  source: DocumentSource,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  return requireText(
+    'attachment_ref' in source
+      ? await loadAttachment(ctx, source.attachment_ref, deps)
+      : await loadVfsFile(ctx, source.vfs_path, deps),
+  );
+}
+
+async function loadAttachment(
+  ctx: RuntimeContext,
+  ref: string,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  if (!ctx.attachments) {
+    throw new Error(
+      'Chat attachments cannot be read from this session; use a file from the Library (vfs_path) instead.',
+    );
+  }
+  let extracted: Awaited<ReturnType<typeof ctx.attachments.extractText>>;
+  try {
+    extracted = await ctx.attachments.extractText(ref, {
+      maxChars: deps.maxChars,
+    });
+  } catch (error) {
+    throw new Error(`Could not read attachment ${ref}: ${describe(error)}`);
+  }
+  if (!extracted) {
+    throw new Error(
+      `No attachment ${ref} in this conversation; ask the person to attach the file again.`,
+    );
+  }
+  return extracted;
+}
+
+async function loadVfsFile(
+  ctx: RuntimeContext,
+  path: string,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  // Library files are the Files plugin's: an oracle that does not run it
+  // does not expose them through the memory tools either.
+  if (!ctx.availablePlugins.has('vfs')) throw new Error(LIBRARY_DISABLED);
+  if (!ctx.ucan.hasSigningKey()) {
+    throw new Error(
+      'The Library (files) is not available: this oracle has no UCAN signing key.',
+    );
+  }
+  let cfg: VfsConfig;
+  try {
+    cfg = resolveVfsConfig(ctx.config);
+  } catch {
+    throw new Error(LIBRARY_DISABLED);
+  }
+  const client = buildClient(ctx, {
+    cfg,
+    fetchImpl: deps.fetchImpl,
+    retryDelayMs: deps.retryDelayMs,
+  });
+  const oracleDid = oracleDidOf(ctx);
+  try {
+    return await readVfsFile(ctx, client, path, deps);
+  } catch (error) {
+    // Errors of the VFS family become the same sentences `vfs_read` gives;
+    // anything else already carries its own message.
+    if (error instanceof VfsAuthError || error instanceof VfsHttpError) {
+      throw new Error(mapVfsError(error, { path, oracleDid }));
+    }
+    throw error;
+  }
+}
+
+function oracleDidOf(ctx: RuntimeContext): string | undefined {
+  const did = (ctx.config as { ORACLE_DID?: unknown } | undefined)?.ORACLE_DID;
+  return typeof did === 'string' && did.length > 0 ? did : undefined;
+}
+
+async function readVfsFile(
+  ctx: RuntimeContext,
+  client: VfsClient,
+  path: string,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  const stat = await client.statByPath(path);
+  if (!stat) throw new Error(`No file at ${path} in your files.`);
+  const mimetype = stat.mimeType || 'application/octet-stream';
+  const filename = stat.name || basename(stat.path) || stat.id;
+  if (stat.size > MAX_VISION_BYTES) {
+    throw new Error(
+      `"${filename}" is ${stat.size} bytes, over the ${MAX_VISION_BYTES} byte limit for documents.`,
+    );
+  }
+
+  if (isTextMime(mimetype)) {
+    const { bytes } = await client.contentBytes(stat.id, MAX_VISION_BYTES);
+    // At most 3 UTF-8 bytes per UTF-16 unit: decoding past this adds nothing.
+    const head = new Uint8Array(bytes).subarray(0, deps.maxChars * 3 + 4);
+    const capped = capText(new TextDecoder().decode(head), deps.maxChars);
+    return {
+      ...capped,
+      filename,
+      mimetype,
+      bytes: bytes.byteLength,
+      method: 'text',
+    };
+  }
+
+  // Only a PDF is downloaded here (to try its text layer); any other type
+  // is downloaded by the render step itself, after its own type/size checks.
+  let downloaded: VfsContentBytes | undefined;
+  if (mimetype === PDF_MIME) {
+    downloaded = await client.contentBytes(stat.id, MAX_VISION_BYTES);
+    try {
+      const pdf = await extractPdfText(new Uint8Array(downloaded.bytes), {
+        maxChars: deps.maxChars,
+        signal: ctx.abortSignal,
+      });
+      if (pdf.kind === 'text') {
+        return {
+          text: pdf.text,
+          truncated: pdf.truncated,
+          filename,
+          mimetype,
+          bytes: downloaded.bytes.byteLength,
+          method: 'pdf',
+          pages: pdf.pages,
+        };
+      }
+      ctx.logger.log(
+        `[memory] document "${filename}": no text layer (${pdf.pages} page(s)), using the helper model`,
+      );
+    } catch (error) {
+      if (ctx.abortSignal.aborted) throw error;
+      ctx.logger.warn(
+        `[memory] document "${filename}": local PDF parse failed (${describe(error)}), using the helper model`,
+      );
+    }
+  }
+
+  // The bytes are already in hand: the render step does not download again.
+  const rendered = await renderBinaryForIngestion(
+    client,
+    ctx,
+    stat,
+    downloaded,
+  );
+  const capped = capText(rendered.text, deps.maxChars);
+  return {
+    text: capped.text,
+    truncated: capped.truncated || rendered.truncated,
+    filename,
+    mimetype,
+    bytes: stat.size,
+    method: 'model',
+  };
+}

package/src/plugins/memory/memory-engine-client.ts

@@ -0,0 +1,352 @@
+import { z } from 'zod';
+import type { RuntimeContext } from '../../plugin-api/types';
+import { MEMORY_CAPABILITY } from '../delegated-capabilities';
+import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
+import { memoryEntityDid } from './memory-entity';
+
+export type KnowledgeSpaceType = 'public' | 'private';
+
+export interface MemoryEngineClientDeps {
+  fetchImpl?: typeof fetch;
+  /** Per-request timeout (default 30 s). */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+let warnedMissingEntityDid = false;
+
+/** Forget that the missing-entity warning was logged (tests only). */
+export function resetMemoryEngineWarningsForTests(): void {
+  warnedMissingEntityDid = false;
+}
+
+/**
+ * The DID sent as `x-oracle-entity-did`: the configured `ORACLE_ENTITY_DID`
+ * when it is a well-formed domain entity DID, never the `ORACLE_DID` fallback
+ * (see the memory engine contract in docs/configuration.md). Logs once per
+ * isolate when there is none.
+ */
+export function entityDidOrWarn(ctx: RuntimeContext): string | undefined {
+  const did = memoryEntityDid(ctx.config.ORACLE_ENTITY_DID);
+  if (did === undefined && !warnedMissingEntityDid) {
+    warnedMissingEntityDid = true;
+    ctx.logger.warn(
+      "[memory] documents unavailable: set ORACLE_ENTITY_DID to the oracle's domain entity DID (did:ixo:entity:<32 hex digits>)",
+    );
+  }
+  return did;
+}
+
+/**
+ * An answer the Memory Engine refused (or a transport failure, `status` 0).
+ * `message` never carries the response body or the bearer; the engine's own
+ * `detail` is kept on the error so a tool can show it to the person, and is
+ * never logged.
+ */
+export class MemoryEngineError extends Error {
+  readonly status: number;
+
+  readonly code?: string;
+
+  readonly detail?: string;
+
+  readonly retryable: boolean;
+
+  readonly retryAfterSeconds?: number;
+
+  /** Parts the engine had queued before it failed (`PARTIAL_QUEUE`). */
+  readonly queued?: number;
+
+  constructor(init: {
+    status: number;
+    code?: string;
+    detail?: string;
+    retryable?: boolean;
+    retryAfterSeconds?: number;
+    queued?: number;
+  }) {
+    super(
+      `memory engine answered ${init.status}${init.code ? ` ${init.code}` : ''}`,
+    );
+    this.name = 'MemoryEngineError';
+    this.status = init.status;
+    if (init.code !== undefined) this.code = init.code;
+    if (init.detail !== undefined) this.detail = init.detail;
+    this.retryable = init.retryable ?? false;
+    if (init.retryAfterSeconds !== undefined) {
+      this.retryAfterSeconds = init.retryAfterSeconds;
+    }
+    if (init.queued !== undefined) this.queued = init.queued;
+  }
+}
+
+export interface DocumentChunkInput {
+  label?: string;
+  content: string;
+}
+
+export interface AddDocumentRequest {
+  knowledge_space_type: KnowledgeSpaceType;
+  confirmed_insertion_from_user: true;
+  /** Present for a grouped document, absent for loose knowledge. */
+  document?: { id?: string; title: string; source_description?: string };
+  if_exists?: 'replace' | 'fail';
+  chunks: DocumentChunkInput[];
+}
+
+const documentStatusSchema = z.enum([
+  'ingesting',
+  'ready',
+  'partial',
+  'deleting',
+  'delete_failed',
+]);
+
+const addDocumentResponseSchema = z.object({
+  success: z.boolean().optional(),
+  queued: z.number(),
+  document: z
+    .object({
+      id: z.string(),
+      generation: z.number(),
+      chunk_count: z.number(),
+      status: documentStatusSchema,
+      replaced: z.boolean(),
+      /** Chunks of the replaced generation still being removed. */
+      retiring_chunks: z.number().optional(),
+    })
+    .optional(),
+  chunk_ids: z.array(z.string()).optional(),
+});
+export type AddDocumentResponse = z.infer<typeof addDocumentResponseSchema>;
+
+const documentSummarySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  source_description: z.string().nullable().optional(),
+  generation: z.number(),
+  chunk_count: z.number(),
+  chunks_indexed: z.number(),
+  retiring_chunks: z.number().optional(),
+  status: documentStatusSchema,
+  /** Why the last deletion failed (status `delete_failed`). */
+  delete_error: z.string().nullable().optional(),
+  created_by: z.string().nullable().optional(),
+  updated_by: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+});
+export type DocumentSummary = z.infer<typeof documentSummarySchema>;
+
+const listDocumentsResponseSchema = z.object({
+  documents: z.array(documentSummarySchema),
+});
+export type ListDocumentsResponse = z.infer<typeof listDocumentsResponseSchema>;
+
+const documentViewSchema = documentSummarySchema.extend({
+  chunks: z.array(z.unknown()).optional(),
+});
+export type DocumentView = z.infer<typeof documentViewSchema>;
+
+const deleteDocumentResponseSchema = z.object({
+  success: z.boolean().optional(),
+  document: z.object({
+    id: z.string(),
+    status: documentStatusSchema,
+    chunks: z.number(),
+  }),
+});
+export type DeleteDocumentResponse = z.infer<
+  typeof deleteDocumentResponseSchema
+>;
+
+export interface MemoryEngineClient {
+  addDocument(body: AddDocumentRequest): Promise<AddDocumentResponse>;
+  listDocuments(space: KnowledgeSpaceType): Promise<ListDocumentsResponse>;
+  getDocument(id: string, space: KnowledgeSpaceType): Promise<DocumentView>;
+  /** Deletion runs in the background; the answer says it was scheduled. */
+  deleteDocument(
+    id: string,
+    space: KnowledgeSpaceType,
+  ): Promise<DeleteDocumentResponse['document']>;
+}
+
+const configSchema = z.object({
+  MEMORY_ENGINE_URL: z.string().url(),
+});
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function parseRetryAfter(res: Response): number | undefined {
+  const raw = res.headers.get('Retry-After');
+  if (!raw) return undefined;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+
+function detailText(detail: unknown): string | undefined {
+  if (typeof detail === 'string') return detail.slice(0, 500);
+  if (detail === undefined || detail === null) return undefined;
+  try {
+    return JSON.stringify(detail).slice(0, 500);
+  } catch {
+    return undefined;
+  }
+}
+
+const errorBodySchema = z.object({
+  code: z.string().optional(),
+  detail: z.unknown().optional(),
+  retryable: z.boolean().optional(),
+  queued: z.number().optional(),
+});
+
+async function toEngineError(res: Response): Promise<MemoryEngineError> {
+  let raw: unknown;
+  try {
+    raw = await res.json();
+  } catch {
+    raw = undefined;
+  }
+  const body = errorBodySchema.safeParse(raw);
+  const parsed = body.success ? body.data : {};
+  const detail = detailText(parsed.detail);
+  const retryAfterSeconds = parseRetryAfter(res);
+  return new MemoryEngineError({
+    status: res.status,
+    ...(parsed.code !== undefined ? { code: parsed.code } : {}),
+    ...(detail !== undefined ? { detail } : {}),
+    retryable: parsed.retryable === true,
+    ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+    ...(parsed.queued !== undefined ? { queued: parsed.queued } : {}),
+  });
+}
+
+/**
+ * A client for the Memory Engine's document routes, authenticated as the
+ * current user (UCAN invocation minted once per client) and as the oracle's
+ * entity (`x-oracle-entity-did`). Returns `null`, after logging why, when the
+ * engine URL, the entity DID or an invocation is unavailable; a tool then tells
+ * the model the engine is not reachable.
+ */
+export async function createMemoryEngineClient(
+  ctx: RuntimeContext,
+  deps: MemoryEngineClientDeps = {},
+): Promise<MemoryEngineClient | null> {
+  const config = configSchema.safeParse(ctx.config);
+  if (!config.success) {
+    ctx.logger.warn(
+      '[memory] documents unavailable: MEMORY_ENGINE_URL missing',
+    );
+    return null;
+  }
+  const engineUrl = config.data.MEMORY_ENGINE_URL.replace(/\/+$/, '');
+  const entityDid = entityDidOrWarn(ctx);
+  if (!entityDid) return null;
+
+  const serviceDid = await resolveServiceDidSafely(ctx, engineUrl, 'memory');
+  if (!serviceDid) return null;
+  const invocation = await mintInvocationSafely(
+    ctx,
+    { did: serviceDid, capability: MEMORY_CAPABILITY.resource },
+    'memory',
+    { can: MEMORY_CAPABILITY.action },
+  );
+  if (!invocation) return null;
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${invocation}`,
+    'X-Auth-Type': 'ucan',
+    'x-oracle-entity-did': entityDid,
+  };
+  if (ctx.session.roomId) headers['x-room-id'] = ctx.session.roomId;
+
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  async function request<T>(
+    method: 'GET' | 'POST' | 'DELETE',
+    path: string,
+    schema: z.ZodType<T>,
+    body?: unknown,
+  ): Promise<T> {
+    let res: Response;
+    try {
+      res = await fetchImpl(`${engineUrl}${path}`, {
+        method,
+        headers:
+          body === undefined
+            ? headers
+            : { ...headers, 'Content-Type': 'application/json' },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: AbortSignal.any([
+          ctx.abortSignal,
+          AbortSignal.timeout(timeoutMs),
+        ]),
+      });
+    } catch (error) {
+      // A cancelled turn is not an engine failure.
+      if (ctx.abortSignal.aborted) throw error;
+      const timedOut = error instanceof Error && error.name === 'TimeoutError';
+      throw new MemoryEngineError({
+        status: 0,
+        code: timedOut ? 'TIMEOUT' : 'NETWORK_ERROR',
+        detail: timedOut
+          ? `no answer within ${timeoutMs} ms`
+          : describe(error).slice(0, 200),
+        retryable: true,
+      });
+    }
+    if (!res.ok) throw await toEngineError(res);
+    let json: unknown;
+    try {
+      json = await res.json();
+    } catch {
+      throw new MemoryEngineError({
+        status: res.status,
+        code: 'MALFORMED_RESPONSE',
+        detail: 'the answer was not valid JSON',
+      });
+    }
+    const parsed = schema.safeParse(json);
+    if (!parsed.success) {
+      throw new MemoryEngineError({
+        status: res.status,
+        code: 'MALFORMED_RESPONSE',
+        detail: 'the answer did not have the expected shape',
+      });
+    }
+    return parsed.data;
+  }
+
+  const spaceQuery = (space: KnowledgeSpaceType): string =>
+    `knowledge_space_type=${space}`;
+
+  return {
+    addDocument: (body) =>
+      request('POST', '/knowledge/documents', addDocumentResponseSchema, body),
+    listDocuments: (space) =>
+      request(
+        'GET',
+        `/knowledge/documents?${spaceQuery(space)}`,
+        listDocumentsResponseSchema,
+      ),
+    getDocument: (id, space) =>
+      request(
+        'GET',
+        `/knowledge/documents/${encodeURIComponent(id)}?${spaceQuery(space)}`,
+        documentViewSchema,
+      ),
+    deleteDocument: async (id, space) => {
+      const out = await request(
+        'DELETE',
+        `/knowledge/documents/${encodeURIComponent(id)}?${spaceQuery(space)}`,
+        deleteDocumentResponseSchema,
+      );
+      return out.document;
+    },
+  };
+}

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

@@ -15,6 +15,7 @@ import {
   type MemoryMcpFactory,
 } from './memory-tools';
 import { oracleEntityDidSchema } from './memory-entity';
+import { createOracleDocumentTools } from './oracle-document-tools';
 
 const configSchema = z.object({
   MEMORY_MCP_URL: z.string().url('MEMORY_MCP_URL must be a valid HTTP(S) URL.'),
@@ -36,7 +37,8 @@ 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.',
+    'A controller or owner of this oracle TYPES into the chat 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 the members of the domain only: its controllers, owner, admins and DAO members), get their confirmation, then store it as oracle knowledge rather than as a memory about them. This line is only for knowledge typed in the chat.',
+    'A controller or owner of this oracle hands you a file (an attachment or a Library file) and asks you to store it as oracle knowledge: a file the person attached or a Library file ALWAYS goes to add_oracle_document, never to add_oracle_knowledge, even when its text is visible in the conversation. If the file is one coherent record (a board resolution, a contract, a report) group it as a document (group_as_document true); if it is a file where someone dumped many unrelated company facts to upload them easily, store it as loose facts (group_as_document false). When it is not obvious which, ask the person first, and always confirm the public or private space with them before writing. list_oracle_documents and delete_oracle_document show and remove grouped documents.',
   ],
   whenNotToUse: [
     'Ephemeral conversation-only state (use the current message thread).',
@@ -44,6 +46,7 @@ const manifest: PluginManifest = {
     '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.',
+    'Storing a file the person did not ask you to store as oracle knowledge, or choosing between a grouped document and loose facts without asking when the file could be either.',
   ],
   tags: ['memory', 'recall', 'artifacts', 'personalization'],
   category: 'memory',
@@ -66,6 +69,15 @@ export interface MemoryPluginOptions {
    * explicit list to drop one of them or to expose `delete_edge`.
    */
   selectedTools?: readonly string[];
+  /**
+   * Surface `add_oracle_document`, `list_oracle_documents` and
+   * `delete_oracle_document` next to the upstream tools (default true). They
+   * talk to `MEMORY_ENGINE_URL` directly and are not part of
+   * {@link selectedTools}, and appear only when the upstream tools do (a user
+   * without a memory delegation gets neither). Pass `false` to keep documents
+   * out of the oracle.
+   */
+  documentTools?: boolean;
 }
 
 function resolveMemoryConfig(config: MergedConfig): {
@@ -109,10 +121,13 @@ export class MemoryPlugin extends OraclePlugin {
 
   private readonly selectedTools: readonly string[];
 
+  private readonly documentTools: boolean;
+
   constructor(options: MemoryPluginOptions = {}) {
     super();
     this.mcpFactory = options.mcpFactory ?? createDefaultMemoryMcpFactory;
     this.selectedTools = options.selectedTools ?? DEFAULT_MEMORY_TOOLS;
+    this.documentTools = options.documentTools ?? true;
   }
 
   override autoDetect(env: PluginEnv): boolean {
@@ -124,7 +139,15 @@ export class MemoryPlugin extends OraclePlugin {
   override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
     const { memoryMcpUrl, entityDid } = resolveMemoryConfig(rtCtx.config);
     const factory = this.mcpFactory(memoryMcpUrl, entityDid);
-    return fetchMemoryTools(rtCtx, factory, this.selectedTools);
+    const mcpTools = await fetchMemoryTools(rtCtx, factory, this.selectedTools);
+    // The document tools come first so a file never lands on the upstream
+    // add_oracle_knowledge by position.
+    // No upstream tools means memory is unavailable for this user (no
+    // delegation, unresolved service DID): the document tools would only
+    // answer "not reachable", so they are left out too.
+    return this.documentTools && mcpTools.length > 0
+      ? [...createOracleDocumentTools(), ...mcpTools]
+      : mcpTools;
   }
 
   override getSharedState(): Record<