@ixo/oracle-runtime-workers 0.24.0 → 0.26.0

package/src/plugins/vfs/index.ts

@@ -1,4 +1,9 @@
-export { VfsPlugin, type VfsConfig, type VfsPluginOptions } from './vfs.plugin';
+export {
+  resolveVfsConfig,
+  VfsPlugin,
+  type VfsConfig,
+  type VfsPluginOptions,
+} from './vfs.plugin';
 export {
   buildClient,
   createVfsTools,
@@ -26,7 +31,11 @@ export {
   type VfsSearchResult,
   type VfsTreeEntry,
 } from './vfs-client';
-export { isTextMime, readForAgent } from './vfs-content';
+export {
+  isTextMime,
+  readForAgent,
+  renderBinaryForIngestion,
+} from './vfs-content';
 export {
   isAlreadyExistsConflict,
   isWriteConflict,

package/src/plugins/vfs/vfs-content.ts

@@ -1,12 +1,13 @@
 import { HumanMessage } from '@langchain/core/messages';
 import type { MessageContent } from '@langchain/core/messages';
+import { MAX_MODEL_LANE_BYTES, replyText } from '../../attachments/extract';
 import type { RuntimeContext } from '../../plugin-api/types';
 import { bytesToBase64 } from '../base64';
-import type { VfsClient, VfsFileStat } from './vfs-client';
+import type { VfsClient, VfsContentBytes, VfsFileStat } from './vfs-client';
 import { VfsContentTooLargeError, VfsHttpError } from './vfs-errors';
 
 /** Cap on the bytes we download and base64 into the vision model. */
-export const MAX_VISION_BYTES = 10 * 1024 * 1024;
+export const MAX_VISION_BYTES = MAX_MODEL_LANE_BYTES;
 
 /** MIME types that are text even though they don't start with `text/`. */
 const TEXT_MIME_EXACT = new Set<string>([
@@ -70,17 +71,37 @@ function isRenderableMime(mime: string): boolean {
 }
 
 /**
- * Read a non-text file for the agent. Returns a metadata stub without
- * downloading when the stored size or type already rules rendering out;
- * otherwise fetches at most {@link MAX_VISION_BYTES} and routes the bytes
- * through the vision model, returning its description/transcription. A vision
- * failure degrades to a metadata stub.
+ * What rendering a binary produced: the model's text (`truncated` when the
+ * provider stopped it at its output limit), or a metadata stub.
  */
-async function renderBinary(
+type BinaryRendering = { text: string; truncated: boolean } | { stub: string };
+
+/** True when the provider cut the reply at its output-token limit. */
+function stoppedAtLimit(metadata: unknown): boolean {
+  if (typeof metadata !== 'object' || metadata === null) return false;
+  const reason =
+    'finish_reason' in metadata
+      ? metadata.finish_reason
+      : 'stop_reason' in metadata
+        ? metadata.stop_reason
+        : undefined;
+  return reason === 'length' || reason === 'max_tokens';
+}
+
+/**
+ * Shared body of {@link renderBinary} and {@link renderBinaryForIngestion}.
+ * Returns a metadata stub without downloading when the stored size or type
+ * already rules rendering out; otherwise fetches at most
+ * {@link MAX_VISION_BYTES} and routes the bytes through the vision model. A
+ * vision failure is a stub too; the caller decides whether a stub is
+ * acceptable (`vfs_read`) or an error (ingestion).
+ */
+async function renderBinaryOrStub(
   client: VfsClient,
   rtCtx: RuntimeContext,
   stat: VfsFileStat,
-): Promise<string> {
+  preloaded?: VfsContentBytes,
+): Promise<BinaryRendering> {
   const name = basename(stat.path) || stat.id;
   const publicSuffix = stat.publicUrl
     ? ` — public link: ${stat.publicUrl}`
@@ -89,17 +110,23 @@ async function renderBinary(
     `[binary file "${name}" — ${mime}, ${size} bytes — too large to render (limit ${MAX_VISION_BYTES} bytes)${publicSuffix}]`;
   const storedMime = stat.mimeType || 'application/octet-stream';
 
-  if (stat.size > MAX_VISION_BYTES) return tooLarge(storedMime, stat.size);
+  if (stat.size > MAX_VISION_BYTES)
+    return { stub: tooLarge(storedMime, stat.size) };
   if (stat.mimeType && !isRenderableMime(stat.mimeType)) {
-    return `[binary file "${name}" — ${stat.mimeType}, ${stat.size} bytes — not rendered${publicSuffix}]`;
+    return {
+      stub: `[binary file "${name}" — ${stat.mimeType}, ${stat.size} bytes — not rendered${publicSuffix}]`,
+    };
   }
 
-  let downloaded: Awaited<ReturnType<VfsClient['contentBytes']>>;
+  let downloaded: VfsContentBytes;
   try {
-    downloaded = await client.contentBytes(stat.id, MAX_VISION_BYTES);
+    downloaded =
+      preloaded ?? (await client.contentBytes(stat.id, MAX_VISION_BYTES));
   } catch (err) {
     if (err instanceof VfsContentTooLargeError) {
-      return tooLarge(storedMime, `more than ${MAX_VISION_BYTES}`);
+      return {
+        stub: tooLarge(storedMime, `more than ${MAX_VISION_BYTES}`),
+      };
     }
     throw err;
   }
@@ -109,7 +136,9 @@ async function renderBinary(
   const isImage = mime.startsWith('image/');
   const isDoc = isDocMime(mime);
   if (!isImage && !isDoc) {
-    return `[binary file "${name}" — ${mime}, ${size} bytes — not rendered${publicSuffix}]`;
+    return {
+      stub: `[binary file "${name}" — ${mime}, ${size} bytes — not rendered${publicSuffix}]`,
+    };
   }
 
   const base64 = bytesToBase64(new Uint8Array(bytes));
@@ -138,20 +167,55 @@ async function renderBinary(
     const result = await model.invoke([new HumanMessage({ content })], {
       signal: rtCtx.abortSignal,
     });
-    const text =
-      typeof result.content === 'string'
-        ? result.content
-        : String(result.content);
-    if (text.trim().length > 0) return text;
-    return `[${isImage ? 'image' : 'document'} "${name}" — ${mime}, ${size} bytes — no description returned${publicSuffix}]`;
+    const text = replyText(result.content);
+    if (text.trim().length > 0) {
+      return { text, truncated: stoppedAtLimit(result.response_metadata) };
+    }
+    return {
+      stub: `[${isImage ? 'image' : 'document'} "${name}" — ${mime}, ${size} bytes — no description returned${publicSuffix}]`,
+    };
   } catch (err) {
     rtCtx.logger.warn(
       `[vfs] vision render failed for ${name}: ${err instanceof Error ? err.message : String(err)}`,
     );
-    return `[${isImage ? 'image' : 'document'} "${name}" — ${mime}, ${size} bytes — could not be rendered${publicSuffix}]`;
+    return {
+      stub: `[${isImage ? 'image' : 'document'} "${name}" — ${mime}, ${size} bytes — could not be rendered${publicSuffix}]`,
+    };
   }
 }
 
+/**
+ * Read a non-text file for the agent: the vision model's description or
+ * transcription, or a metadata stub when the file cannot be rendered.
+ */
+async function renderBinary(
+  client: VfsClient,
+  rtCtx: RuntimeContext,
+  stat: VfsFileStat,
+): Promise<string> {
+  const rendered = await renderBinaryOrStub(client, rtCtx, stat);
+  return 'text' in rendered ? rendered.text : rendered.stub;
+}
+
+/**
+ * Like {@link renderBinary} for callers that need the file's real text (the
+ * memory plugin's document ingestion): a file that is too large, not
+ * renderable or that the vision model fails on throws instead of returning a
+ * stub, so a stub is never mistaken for the document's content. Pass
+ * `preloaded` when the bytes are already in hand (no second download);
+ * `truncated` reports a reply the provider cut at its output limit.
+ */
+export async function renderBinaryForIngestion(
+  client: VfsClient,
+  rtCtx: RuntimeContext,
+  stat: VfsFileStat,
+  preloaded?: VfsContentBytes,
+): Promise<{ text: string; truncated: boolean }> {
+  const rendered = await renderBinaryOrStub(client, rtCtx, stat, preloaded);
+  if ('text' in rendered) return rendered;
+  throw new Error(rendered.stub);
+}
+
 /**
  * Resolve a path to a file and return content the agent can read: numbered
  * lines for text, a vision transcription for images/PDFs, or a metadata stub

package/src/plugins/vfs/vfs.plugin.ts

@@ -42,6 +42,33 @@ export interface VfsConfig {
   VFS_REQUEST_TIMEOUT_MS: number;
 }
 
+/**
+ * Assemble the {@link VfsConfig} from a runtime config: worker URLs derived
+ * from `NETWORK` (or the per-deployment overrides), tuning knobs defaulted
+ * when absent or invalid. Shared by the plugin and by code that talks to the
+ * VFS on its own (the memory plugin's document ingestion).
+ */
+export function resolveVfsConfig(config: unknown): VfsConfig {
+  const tuning = configSchema.safeParse(config);
+  const siblings = siblingEnvSchema.safeParse(config);
+  const network = (siblings.success && siblings.data.NETWORK) || 'mainnet';
+  return {
+    VFS_BASE_URL:
+      (siblings.success && siblings.data.VFS_BASE_URL) ||
+      VFS_DEFAULT_BASE_URLS[network] ||
+      // Unreachable: `network` is one of the three keys the map declares.
+      'https://vfs.ixo.earth',
+    UCAN_STORE_URL:
+      (siblings.success && siblings.data.UCAN_STORE_URL) ||
+      UCAN_STORE_DEFAULT_URLS[network] ||
+      'https://store.ucan.ixo.earth',
+    VFS_MAX_READ_LINES: tuning.success ? tuning.data.VFS_MAX_READ_LINES : 2000,
+    VFS_REQUEST_TIMEOUT_MS: tuning.success
+      ? tuning.data.VFS_REQUEST_TIMEOUT_MS
+      : 20000,
+  };
+}
+
 const manifest: PluginManifest = {
   title: 'Files',
   summary:
@@ -149,26 +176,8 @@ export class VfsPlugin extends OraclePlugin {
       return [];
     }
 
-    const tuning = configSchema.safeParse(rtCtx.config);
+    const cfg = resolveVfsConfig(rtCtx.config);
     const siblings = siblingEnvSchema.safeParse(rtCtx.config);
-    const network = (siblings.success && siblings.data.NETWORK) || 'mainnet';
-    const cfg: VfsConfig = {
-      VFS_BASE_URL:
-        (siblings.success && siblings.data.VFS_BASE_URL) ||
-        VFS_DEFAULT_BASE_URLS[network] ||
-        // Unreachable: `network` is one of the three keys the map declares.
-        'https://vfs.ixo.earth',
-      UCAN_STORE_URL:
-        (siblings.success && siblings.data.UCAN_STORE_URL) ||
-        UCAN_STORE_DEFAULT_URLS[network] ||
-        'https://store.ucan.ixo.earth',
-      VFS_MAX_READ_LINES: tuning.success
-        ? tuning.data.VFS_MAX_READ_LINES
-        : 2000,
-      VFS_REQUEST_TIMEOUT_MS: tuning.success
-        ? tuning.data.VFS_REQUEST_TIMEOUT_MS
-        : 20000,
-    };
 
     const tools = createVfsTools({
       cfg,

package/src/shell/app.ts

@@ -78,22 +78,7 @@ import {
 } from '../feedback/submit';
 import { z } from 'zod';
 import { parseOutcome } from '@ixo/action-protocol';
-
-async function equalOutcomeKeys(
-  provided: string | null,
-  expected: string | undefined,
-): Promise<boolean> {
-  if (!provided || !expected || expected.length < 32 || provided.length > 512)
-    return false;
-  const digest = async (value: string) =>
-    new Uint8Array(
-      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)),
-    );
-  const [a, b] = await Promise.all([digest(provided), digest(expected)]);
-  let difference = 0;
-  for (let i = 0; i < a.length; i++) difference |= (a[i] ?? 0) ^ (b[i] ?? 0);
-  return difference === 0;
-}
+import { verifyHubOutcomeCallback } from '../hub-actions/outcome-signature';
 
 const DebugEventBody = z.object({
   type: z
@@ -217,6 +202,22 @@ export const BYO_LLM_BODY_BYTES = 64 * 1024;
 export const DEBUG_BODY_BYTES = 64 * 1024;
 
 /** A body cap enforced before the body is buffered: over it, 413 and the handler never runs. */
+/**
+ * The audience a signed Hub outcome callback must be signed for: the origin
+ * of `ORACLE_PUBLIC_URL` when it is set, else the origin of the request URL.
+ * An unparsable public URL yields '' (which never verifies).
+ */
+export function callbackAudience(
+  publicUrl: string | undefined,
+  requestUrl: string,
+): string {
+  try {
+    return new URL(publicUrl || requestUrl).origin;
+  } catch {
+    return '';
+  }
+}
+
 function limitBody(maxSize: number) {
   return bodyLimit({
     maxSize,
@@ -455,17 +456,32 @@ export function createShell(
   });
 
   app.use('/api/internal/actions/outcomes', limitBody(64 * 1024));
+  // Auth Hub's signed outcome callbacks: on whenever Hub actions are
+  // configured. The signature is checked against the Hub's own did:web key
+  // (from AUTH_HUB_URL) for this oracle's origin, then the owner object
+  // confirms the outcome through Auth Hub's authenticated status API.
   app.post('/api/internal/actions/outcomes', async (c) => {
     if (
       c.env.HUB_ACTIONS_ENABLED !== 'true' ||
-      !(await equalOutcomeKeys(
-        c.req.header('x-auth-hub-outcome-key') ?? null,
-        c.env.AUTH_HUB_ACTION_OUTCOME_KEY,
-      ))
+      !c.env.AUTH_HUB_URL ||
+      !c.env.AUTH_HUB_CHANNEL_SERVICE_KEY
     )
       return c.json({ code: 'unauthorized' }, 401);
     const body = await c.req.raw.text();
     if (body.length > 64_000) return c.json({ code: 'request_too_large' }, 413);
+    if (
+      !(await verifyHubOutcomeCallback({
+        hubUrl: c.env.AUTH_HUB_URL,
+        rawBody: body,
+        headers: c.req.raw.headers,
+        // The origin the Hub signs for: the configured public URL when
+        // set (a Worker reachable under several hostnames), else the
+        // origin this request came in on.
+        audience: callbackAudience(c.env.ORACLE_PUBLIC_URL, c.req.url),
+        ...(c.env.AUTH_HUB ? { fetcher: c.env.AUTH_HUB } : {}),
+      }))
+    )
+      return c.json({ code: 'unauthorized' }, 401);
     try {
       const outcome = parseOutcome(JSON.parse(body));
       await userStub(c.env, outcome.ownerDid).recordHubActionOutcome(outcome);