@ixo/oracle-runtime-workers 0.30.0 → 0.32.0

package/src/channels/turns.ts

@@ -162,6 +162,14 @@ const CHANNEL_TOPIC_LOOKBACK = 5;
 /** Ids per statement: a Durable Object binds at most 100 parameters. */
 const CHANNEL_IDS_PER_STATEMENT = 50;
 
+/**
+ * The text the gateway sends for a file with no caption: `[photo]`,
+ * `[video]`, `[audio]` or `[document: <name>]`.
+ */
+export function isAttachmentPlaceholder(message: string): boolean {
+  return /^\[(?:photo|video|audio)\]$|^\[document: [^\n]*\]$/.test(message);
+}
+
 function clipCodePoints(text: string, limit: number): string {
   const points = Array.from(text);
   return points.length > limit ? points.slice(0, limit).join('') : text;
@@ -1463,7 +1471,14 @@ export class ChannelTurns {
           assignment.destination = { kind: 'session', sessionId: session };
       } else if (mode === 'on')
         assignment.destination = { kind: 'clarify', text: ambiguousThreadText };
-    } else {
+    } else if (
+      input.attachments?.length &&
+      isAttachmentPlaceholder(input.message)
+    )
+      // A file with no caption, only the gateway's placeholder: nothing to
+      // classify, so it stays in the current conversation.
+      assignment.reason = 'attachment-placeholder';
+    else {
       const candidates = await this.routingCandidates(input, baseline);
       if (candidates.length) {
         const evidence = {
@@ -1516,6 +1531,10 @@ export class ChannelTurns {
         } else assignment.reason = 'shadow';
       }
     }
+    // A clarifying question is answered instead of the message, so the files
+    // would be dropped: a turn that carries files stays where it is.
+    if (input.attachments?.length && assignment.destination.kind === 'clarify')
+      assignment.destination = { kind: 'session', sessionId: baseline };
     await this.serialize(async () => {
       await this.assertNotCancelled(input);
       await this.db.run(
@@ -1861,6 +1880,9 @@ export class ChannelTurns {
         bindingId: input.bindingId,
         bindingRevision: input.bindingRevision,
         remoteMessageRef: input.remoteMessageRef,
+        ...(input.attachments?.length
+          ? { attachments: input.attachments }
+          : {}),
         ...(replyContext ? { replyContext } : {}),
         ...(input.replyTo ? { replyTo: input.replyTo } : {}),
         ...(routing?.destination.kind === 'clarify'

package/src/core/main-agent-types.ts

@@ -9,6 +9,7 @@ import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import type { BaseCheckpointSaver } from '@langchain/langgraph';
 import type { ReactAgent } from 'langchain';
 import { z } from 'zod';
+import { ChannelAttachment } from '../channels/contract';
 import type {
   ChatOpenAIFields,
   MergedConfig,
@@ -48,6 +49,7 @@ export const mainAgentRequestContextSchema = z.object({
         provider: z.string(),
         bindingId: z.string(),
         bindingRevision: z.number().int().positive(),
+        attachments: z.array(ChannelAttachment).optional(),
       })
       .optional(),
     wsId: z.string().optional(),

package/src/core/middlewares/tool-repetition-guard.ts

@@ -7,6 +7,7 @@ import { type AgentMiddleware, createMiddleware } from 'langchain';
 import type { Logger } from '../../plugin-api/types';
 import { NOOP_LOGGER } from '../utils';
 import { isCapabilityGateRefusal } from './capability-gate';
+import { isToolNotRun } from '../tool-not-run';
 import { turnCarryOf, turnStart } from './turn-boundary';
 
 export { turnStart };
@@ -145,9 +146,11 @@ export const createToolRepetitionGuardMiddleware = (
         const msg = messages[i];
         if (!(msg instanceof ToolMessage)) continue;
         if (msg.status !== 'error') continue;
-        // The capability gate refused it without running it; after a
-        // `load_capability` the same call is the expected next step.
-        if (isCapabilityGateRefusal(msg)) continue;
+        // The capability gate refused it without running it, or the tool
+        // said it did not run until a step comes first: after that step
+        // (`load_capability`, reading the rules) the same call is the
+        // expected next one.
+        if (isCapabilityGateRefusal(msg) || isToolNotRun(msg)) continue;
         if (msg.name !== toolName) continue;
 
         const priorArgs = argsById.get(msg.tool_call_id);

package/src/core/middlewares/turn-boundary.ts

@@ -22,6 +22,7 @@ import {
 } from '@langchain/core/messages';
 import { isAttachmentViewMessage } from '../../attachments/retention';
 import { isCapabilityGateRefusal } from './capability-gate';
+import { isToolNotRun } from '../tool-not-run';
 
 export const SUMMARY_PREFIX = 'Here is a summary of the conversation to date:';
 
@@ -140,7 +141,11 @@ export function carriedCallsOfTurn(
         if (call.id) calls.set(call.id, { name: call.name, args: call.args });
       continue;
     }
-    if (!ToolMessage.isInstance(message) || isCapabilityGateRefusal(message))
+    if (
+      !ToolMessage.isInstance(message) ||
+      isCapabilityGateRefusal(message) ||
+      isToolNotRun(message)
+    )
       continue;
     const call = calls.get(message.tool_call_id);
     if (!call) continue;

package/src/core/runtime-context.ts

@@ -1,3 +1,4 @@
+import type { ChannelAttachment } from '../channels/contract';
 import {
   UNAVAILABLE_DECISION_EVALUATOR,
   type DecisionEvaluateOptions,
@@ -330,6 +331,8 @@ export interface RuntimeSessionContext {
     provider: string;
     bindingId: string;
     bindingRevision: number;
+    /** Files sent with this message (see `RuntimeContext.session.channel`). */
+    attachments?: readonly ChannelAttachment[];
   };
   roomId?: string;
   surface?: SessionSurface;

package/src/core/tool-not-run.ts

@@ -0,0 +1,30 @@
+import { ToolMessage } from '@langchain/core/messages';
+
+/** `response_metadata` key of a result whose tool did not run (never sent to a provider). */
+const NOT_RUN = 'toolNotRun';
+
+/**
+ * A tool result saying the tool did not run because another step must come
+ * first (for example reading a message type's rules before preparing it).
+ * It is an error result, so it never counts as a write that happened, and
+ * like a capability-gate refusal the repetition guard lets the identical
+ * call through once the step is done (`isToolNotRun`).
+ */
+export function toolNotRunMessage(input: {
+  toolCallId: string;
+  name: string;
+  content: string;
+}): ToolMessage {
+  return new ToolMessage({
+    tool_call_id: input.toolCallId,
+    name: input.name,
+    content: input.content,
+    status: 'error',
+    response_metadata: { [NOT_RUN]: true },
+  });
+}
+
+/** A result `toolNotRunMessage` made: the tool did not run. */
+export function isToolNotRun(message: ToolMessage): boolean {
+  return message.response_metadata?.[NOT_RUN] === true;
+}

package/src/core/wrap-plugin-tool.ts

@@ -1,3 +1,4 @@
+import { ToolMessage } from '@langchain/core/messages';
 import { Command } from '@langchain/langgraph';
 import { capToolResult, type ResultCapConfig } from './middlewares/result-cap';
 import { tool } from '@langchain/core/tools';
@@ -125,7 +126,14 @@ export function wrapPluginTool(
       if (pluginName !== undefined)
         requireToolPlane(ctx, pluginName, pluginTool);
       const output = await pluginTool.handler(args, ctx);
-      if (!resultCap || output instanceof Command || output == null)
+      // A tool's own message (a result that says the tool did not run) is
+      // returned whole, never capped into text.
+      if (
+        !resultCap ||
+        output instanceof Command ||
+        ToolMessage.isInstance(output) ||
+        output == null
+      )
         return output;
       const text = typeof output === 'string' ? output : JSON.stringify(output);
       if (typeof text !== 'string' || text.length <= resultCap.capChars)

package/src/delivery/plan.ts

@@ -165,7 +165,9 @@ export function draftReplyPlan(input: {
     for (const call of step.toolCalls) {
       if (
         call.name === 'request_hub_action' ||
-        call.name === 'request_chain_transaction'
+        call.name === 'request_chain_transaction' ||
+        // The Yoma plugin's application and claim cards.
+        call.name === 'yoma_form'
       ) {
         try {
           const result = JSON.parse(input.toolResults.get(call.id) ?? 'null');

package/src/do/contracts.ts

@@ -1,4 +1,5 @@
 import type {
+  ChannelAttachment,
   ChannelControlInput,
   ChannelControlOutcome,
   ChannelReplyContext,
@@ -400,6 +401,8 @@ export interface TurnRequest {
     replyTo?: ChannelReplyReference;
     /** Host-generated direct reply: no agent or tools run for an ambiguous destination. */
     routingClarification?: string;
+    /** Files the person sent with this message, as the gateway serves them. */
+    attachments?: ChannelAttachment[];
   };
   executionProfile?: TaskExecutionProfile;
   identity: TurnIdentity;

package/src/do/turn-attachments.ts

@@ -0,0 +1,103 @@
+/**
+ * The attachments of one turn attempt: which files the run reads, how a
+ * channel file's `channel:` reference becomes its link (server-side, never
+ * through the model), and when nothing is downloaded at all.
+ */
+import {
+  attachmentMetaFor,
+  channelAttachmentRef,
+  channelMediaOrigins,
+  createChannelMediaSource,
+  parseAttachmentInputs,
+  type AttachmentInput,
+  type ChannelAttachmentLinkStore,
+  type ChannelMediaLink,
+  type ChannelMediaSource,
+  type PreparedAttachments,
+} from '../attachments';
+import { parseChannelServiceDids } from '../channels/auth';
+import {
+  channelAttachmentInputs,
+  type ChannelAttachment,
+} from '../channels/contract';
+import type { AttachmentMeta } from '../sqlite/serialization';
+
+/** The part of a turn request the attachment inputs come from. */
+interface TurnFiles {
+  client: string;
+  attachments?: unknown;
+  channel?: { bindingId: string; attachments?: readonly ChannelAttachment[] };
+}
+
+/**
+ * What the run reads: a channel turn's files by their `channel:` reference
+ * (from the gateway's list on the request), otherwise the request body's
+ * attachments as the Portal and Matrix send them. A body can never name a
+ * `channel:` reference itself.
+ */
+export function turnAttachmentInputs(
+  req: TurnFiles,
+  bodyAttachments: unknown,
+): AttachmentInput[] {
+  const files = req.client === 'channel' ? req.channel?.attachments : undefined;
+  if (files?.length) return channelAttachmentInputs(files);
+  return parseAttachmentInputs(bodyAttachments ?? req.attachments);
+}
+
+/** A channel turn's files as the links the owner object resolves references to. */
+export function channelTurnLinks(
+  req: TurnFiles,
+): Array<ChannelMediaLink & { ref: string }> {
+  if (req.client !== 'channel' || !req.channel?.attachments?.length) return [];
+  const bindingId = req.channel.bindingId;
+  return req.channel.attachments.map((file) => ({
+    ref: channelAttachmentRef(file.sha256),
+    url: file.url,
+    sha256: file.sha256,
+    bindingId,
+  }));
+}
+
+/**
+ * The channel source of a turn in `sessionId`: a reference resolves to the
+ * turn's own files first, then to the links kept for the session; only the
+ * gateways of `CHANNEL_SERVICE_DID` are fetched from.
+ */
+export function turnChannelMediaSource(input: {
+  sessionId: string;
+  turnLinks: ReadonlyArray<ChannelMediaLink & { ref: string }>;
+  store: Pick<ChannelAttachmentLinkStore, 'get'> | null;
+  channelServiceDid: string | undefined;
+}): ChannelMediaSource {
+  return createChannelMediaSource({
+    origins: channelMediaOrigins(
+      parseChannelServiceDids(input.channelServiceDid),
+    ),
+    resolve: async (ref) => {
+      const own = input.turnLinks.find((link) => link.ref === ref);
+      if (own) return own;
+      return input.store?.get(input.sessionId, ref);
+    },
+  });
+}
+
+/**
+ * The turn's prepared attachments, or none: a resumed attempt hands the
+ * graph no new input (the person's message, with its files, is already in
+ * the checkpoint), so nothing is downloaded again; its metadata is still
+ * known for `view_attachment`.
+ */
+export async function prepareTurnAttachments(input: {
+  inputs: readonly AttachmentInput[];
+  resumed: boolean;
+  prepare: () => Promise<PreparedAttachments>;
+}): Promise<{ prepared: PreparedAttachments | null; metas: AttachmentMeta[] }> {
+  if (input.inputs.length === 0) return { prepared: null, metas: [] };
+  if (input.resumed)
+    return {
+      prepared: null,
+      metas: input.inputs.map((attachment) => attachmentMetaFor(attachment)),
+    };
+  const prepared = await input.prepare();
+  return { prepared, metas: prepared.metas };
+}