@ixo/oracle-runtime-workers 0.25.0 → 0.27.0

package/src/core/env.ts

@@ -3,6 +3,7 @@ import {
   decisionProviderEnvShape,
 } from '@ixo/common/ai/decisions';
 import { z } from 'zod';
+import { channelRoutingEnvShape } from '../channels/routing';
 import type { OraclePlugin } from '../plugin-api/oracle-plugin';
 import type { Logger } from '../plugin-api/types';
 import { NOOP_LOGGER } from './utils';
@@ -16,6 +17,7 @@ import {
   USER_CONTEXT_BLOCKING_CAP_MS_DEFAULT,
   USER_CONTEXT_CACHE_TTL_MS_DEFAULT,
 } from '../memory/user-context-fetcher';
+import { CHANNEL_HISTORY_INDEX_DEBOUNCE_MS_DEFAULT } from '../memory/session-history-indexer';
 
 /**
  * Tier-0 (core) environment for the Workers runtime. Mirrors
@@ -303,6 +305,7 @@ export const baseEnvSchema = z.object({
   // runtime consumer of Decisions. It predicts the on-demand plugin a message
   // needs and preloads it for the turn; it needs a `DECISION_PROVIDER`.
   ...capabilityRouterEnvShape,
+  ...channelRoutingEnvShape,
 
   // --- durable runs (docs/plans/durable-runs.md) ---------------------------
   // Parsed by `runDurabilityConfig` (src/do/run-store.ts) with defaults:
@@ -393,6 +396,20 @@ export const baseEnvSchema = z.object({
     .min(1_000)
     .max(3_600_000)
     .default(USER_CONTEXT_CACHE_TTL_MS_DEFAULT),
+  /**
+   * How long a channel session must be quiet after its last finished run
+   * before its new history is indexed into the memory engine (ms): a burst
+   * of messages is one upload, and one prefetch-cache invalidation. `0`
+   * indexes after every finished run. At most 10 min: the wait is an
+   * in-memory timer that keeps the user object resident, and a Durable
+   * Object keeps pending work alive for 15 min at most.
+   */
+  CHANNEL_HISTORY_INDEX_DEBOUNCE_MS: z.coerce
+    .number()
+    .int()
+    .min(0)
+    .max(600_000)
+    .default(CHANNEL_HISTORY_INDEX_DEBOUNCE_MS_DEFAULT),
 
   // --- misc ---------------------------------------------------------------
   LOG_LEVEL: z.string().default('info'),

package/src/do/contracts.ts

@@ -1,3 +1,9 @@
+import type {
+  ChannelControlInput,
+  ChannelControlOutcome,
+  ChannelReplyContext,
+  ChannelReplyReference,
+} from '../channels/contract';
 import type {
   BeginTopicStep,
   TopicReceiptReferences,
@@ -314,6 +320,10 @@ export interface OracleWorkerEnv {
    * `on` preloads the predicted on-demand plugin's tools for the turn.
    */
   CAPABILITY_ROUTER?: CapabilityRouterMode;
+  /** Applies exclusively to authenticated channel admission; Portal/Matrix turns never route. */
+  CHANNEL_SEMANTIC_ROUTING?: 'off' | 'shadow' | 'on';
+  CHANNEL_SEMANTIC_ROUTING_BINDINGS?: string;
+  CHANNEL_SEMANTIC_ROUTING_MIN_PROBABILITY?: string;
 
   // --- langsmith tracing ---------------------------------------------------
   /** `'true'` traces every turn (explicit tracer — Workers has no env auto-attach). */
@@ -386,6 +396,10 @@ export interface TurnRequest {
     bindingId: string;
     bindingRevision?: number;
     remoteMessageRef: string;
+    replyContext?: ChannelReplyContext;
+    replyTo?: ChannelReplyReference;
+    /** Host-generated direct reply: no agent or tools run for an ambiguous destination. */
+    routingClarification?: string;
   };
   executionProfile?: TaskExecutionProfile;
   identity: TurnIdentity;
@@ -741,6 +755,11 @@ export interface UserOracleObject extends Rpc.DurableObjectBranded {
     operationId: string,
     command: TopicDeliverableCommand,
   ): Promise<TopicDeliverableResult>;
+  channelControl(
+    identity: TurnIdentity,
+    input: ChannelControlInput,
+    requestHash: string,
+  ): Promise<ChannelControlOutcome>;
   channelTurn(
     identity: TurnIdentity,
     input: ChannelTurnInput,

package/src/do/room-mirror.ts

@@ -1,4 +1,7 @@
-import { channelOrigin } from '../channels/contract';
+import {
+  channelOrigin,
+  type ChannelReplyReference,
+} from '../channels/contract';
 /**
  * The room mirror of HTTP chats: every Portal turn is replayed into the
  * user's oracle room as a thread under the session's marker event, the user
@@ -46,6 +49,7 @@ export interface MirrorSend {
     provider: string;
     bindingId: string;
     remoteMessageRef: string;
+    replyTo?: ChannelReplyReference;
   };
 }
 
@@ -75,6 +79,9 @@ export function mirrorEventContent(send: MirrorSend) {
     ...(send.origin
       ? {
           'org.ixo.qi.origin': channelOrigin(send.origin),
+          ...(send.origin.replyTo
+            ? { 'org.ixo.qi.reply': send.origin.replyTo }
+            : {}),
         }
       : {}),
   };

package/src/do/run-coordinator.ts

@@ -453,6 +453,33 @@ export class RunCoordinator {
     return stopped;
   }
 
+  /** Stop exactly the run a channel control names; never a later turn. */
+  abortById(runId: string): Promise<void> {
+    return this.abortByIds([runId]);
+  }
+
+  /**
+   * Stop exactly the runs a channel control names, never a later turn.
+   * Every run is signalled before any is waited for, and the wait is one
+   * shared supersede grace: a control naming many runs must answer well
+   * inside the caller's timeout. A run may still be winding down when this
+   * resolves. Runs that are not live here (ended, never begun) are skipped.
+   */
+  async abortByIds(runIds: readonly string[]): Promise<void> {
+    const runs = [...new Set(runIds)].flatMap((runId) => {
+      const run = this.live.get(runId);
+      return run ? [run] : [];
+    });
+    if (runs.length === 0) return;
+    // Queued runs first, so an attempt that ends below dequeues none of them.
+    for (const run of runs)
+      if (run.record.status === 'queued')
+        void this.cancelQueued(run, 'aborted');
+    for (const run of runs)
+      if (run.record.status !== 'queued') this.abortRun(run, 'aborted');
+    await withinGrace(this.graceMs, Promise.all(runs.map((run) => run.done)));
+  }
+
   /**
    * End every run of the session: the executing attempt is aborted, queued
    * runs and runs waiting for a recovery attempt are closed, and messages

package/src/do/transcript.ts

@@ -1,3 +1,4 @@
+import { userContent } from '../channels/replies';
 /**
  * Transcript → client DTO. Port of `@ixo/common`'s
  * `transformGraphStateMessageToListMessageResponse` so `GET /messages/:id`
@@ -13,11 +14,7 @@ import {
   isAttachmentViewMessage,
 } from '../attachments/retention';
 import { SUMMARY_PREFIX } from '../core/middlewares/summarization';
-import {
-  stripTurnTimeNote,
-  TURN_TIME_NOTE_KWARG,
-} from '../core/turn-time-note';
-import { ChannelOrigin } from '../channels/contract';
+import { ChannelOrigin, ChannelReplyReference } from '../channels/contract';
 import { CREATE_ARTIFACT_TOOL, createArtifactParts } from '../artifacts/tool';
 import { planText } from '../delivery/schema';
 import type {
@@ -59,7 +56,10 @@ export interface MessageDto {
   createdAt?: string;
   attachment?: AttachmentMeta;
   attachments?: AttachmentMeta[];
-  metadata?: { 'org.ixo.qi.origin': ChannelOrigin };
+  metadata?: {
+    'org.ixo.qi.origin': ChannelOrigin;
+    'org.ixo.qi.reply'?: ChannelReplyReference;
+  };
 }
 
 export interface ListMessagesResponse {
@@ -131,10 +131,7 @@ export function contentToText(content: BaseMessage['content']): string {
  */
 export function visibleContent(message: BaseMessage): BaseMessage['content'] {
   if (message.type !== 'human') return message.content;
-  return stripTurnTimeNote(
-    message.content,
-    message.additional_kwargs?.[TURN_TIME_NOTE_KWARG],
-  );
+  return userContent(message.content, message.additional_kwargs);
 }
 
 /** `visibleContent` as text (titles, mirrors, indexing). */
@@ -216,7 +213,13 @@ export async function transformTranscript(
       if (attachments?.length) dto.attachments = attachments;
       if (message.type === 'human') {
         const origin = ChannelOrigin.safeParse(kw['org.ixo.qi.origin']);
-        if (origin.success) dto.metadata = { 'org.ixo.qi.origin': origin.data };
+        if (origin.success) {
+          const reply = ChannelReplyReference.safeParse(kw['org.ixo.qi.reply']);
+          dto.metadata = {
+            'org.ixo.qi.origin': origin.data,
+            ...(reply.success ? { 'org.ixo.qi.reply': reply.data } : {}),
+          };
+        }
       }
       acc.push(dto);
       for (const call of dto.toolCalls ?? [])

package/src/do/turn-messages.ts

@@ -0,0 +1,54 @@
+/**
+ * Ordering of the messages a turn feeds the graph: hidden attachment context
+ * and the person's message.
+ */
+
+import {
+  AIMessage,
+  type BaseMessage,
+  type HumanMessage,
+} from '@langchain/core/messages';
+
+import type { ExtractedAttachment } from '../attachments';
+
+export interface TurnMessageParts {
+  human: HumanMessage;
+  /** Extraction-lane text: follows the HumanMessage (as on Node). */
+  extracted: readonly ExtractedAttachment[];
+  /**
+   * One line per natively-sent file naming its reference. These go BEFORE the
+   * HumanMessage so the turn never ends on an assistant message (providers
+   * reject or mis-handle an assistant-last conversation).
+   */
+  nativeNotes: readonly ExtractedAttachment[];
+  matrixRoom: boolean;
+  now?: () => Date;
+}
+
+function hiddenNote(
+  item: ExtractedAttachment,
+  matrixRoom: boolean,
+  now: () => Date,
+): AIMessage {
+  return new AIMessage({
+    content: item.text,
+    additional_kwargs: {
+      msgFromMatrixRoom: matrixRoom,
+      timestamp: now().toISOString(),
+      attachment: item.meta,
+    },
+  });
+}
+
+/**
+ * Native notes, then the HumanMessage, then the extraction-lane text. The
+ * hidden messages carry an `attachment` kwarg, which the transcript hides.
+ */
+export function assembleTurnMessages(parts: TurnMessageParts): BaseMessage[] {
+  const now = parts.now ?? (() => new Date());
+  return [
+    ...parts.nativeNotes.map((n) => hiddenNote(n, parts.matrixRoom, now)),
+    parts.human,
+    ...parts.extracted.map((n) => hiddenNote(n, parts.matrixRoom, now)),
+  ];
+}