@ixo/oracle-runtime-workers 0.22.0 → 0.23.0

package/src/core/runtime-context.ts

@@ -189,6 +189,8 @@ export interface AmbientServices {
    * `DecisionProviderUnavailableError`.
    */
   decisions?: DecisionEvaluator;
+  actionProposals?: RuntimeContext['actionProposals'];
+  hubActions?: RuntimeContext['hubActions'];
   /** Host task scheduler for the current user, when the host provides one. */
   tasks?: import('../plugin-api/types').OracleTasksSurface;
   /** Host user-preferences store for the current user, when provided. */
@@ -323,6 +325,12 @@ export interface RuntimeSessionContext {
   client: 'portal' | 'matrix' | 'slack' | 'channel';
   wsId?: string;
   requestId: string;
+  runId?: string;
+  channel?: {
+    provider: string;
+    bindingId: string;
+    bindingRevision: number;
+  };
   roomId?: string;
   surface?: SessionSurface;
 }
@@ -528,6 +536,10 @@ export function buildRuntimeContext<TConfig = MergedConfig>(
     logger: ambient.logger,
     abortSignal,
     ...(ambient.tasks ? { tasks: ambient.tasks } : {}),
+    ...(ambient.actionProposals
+      ? { actionProposals: ambient.actionProposals }
+      : {}),
+    ...(ambient.hubActions ? { hubActions: ambient.hubActions } : {}),
     ...(ambient.preferences ? { preferences: ambient.preferences } : {}),
     ...(ambient.kv ? { kv: ambient.kv } : {}),
     ...(ambient.frontend ? { frontend: ambient.frontend } : {}),

package/src/delivery/plan.ts

@@ -1,3 +1,5 @@
+import { ActionReferenceSchema } from '@ixo/ixo-transaction/action-proposals';
+import { parseReference } from '@ixo/action-protocol';
 /**
  * A finished run → its Reply Plan. Built once, when the run finishes, from
  * the turn's own messages (the model's checkpointed history is never
@@ -160,11 +162,42 @@ export function draftReplyPlan(input: {
         );
       else parts.push({ kind: 'spill', key: `step-${i}`, spill: shape.spill });
     }
-    for (const call of step.toolCalls)
+    for (const call of step.toolCalls) {
+      if (call.name === 'request_hub_action') {
+        try {
+          const result = JSON.parse(input.toolResults.get(call.id) ?? 'null');
+          if (result?.status === 'prepared') {
+            const actionReference = parseReference(result.actionReference);
+            if (
+              typeof result.summary === 'string' &&
+              result.summary === actionReference.title
+            )
+              parts.push({
+                kind: 'hub-action',
+                actionReference,
+                summary: result.summary,
+              });
+          }
+        } catch {
+          // Only a parsed tool result becomes a structured Hub reference.
+        }
+      }
+      if (call.name === 'prepare_action') {
+        try {
+          const result = JSON.parse(input.toolResults.get(call.id) ?? 'null');
+          if (result?.status === 'prepared') {
+            const ref = ActionReferenceSchema.safeParse(result.action);
+            if (ref.success) parts.push({ kind: 'action', action: ref.data });
+          }
+        } catch {
+          /* A malformed result is not an action reference. */
+        }
+      }
       if (call.name === CREATE_ARTIFACT_TOOL)
         parts.push(
           ...createArtifactParts(call.args, input.toolResults.get(call.id)),
         );
+    }
   });
   return parts;
 }
@@ -221,7 +254,15 @@ function capParts(parts: PlanPart[], limits: ChatLimits): ReplyContent[] {
     (part): ReplyContent =>
       part.kind === 'text'
         ? { kind: 'text', text: part.text }
-        : { kind: 'artifact', artifact: part.artifact },
+        : part.kind === 'artifact'
+          ? { kind: 'artifact', artifact: part.artifact }
+          : part.kind === 'action'
+            ? { kind: 'action', action: part.action }
+            : {
+                kind: 'hub-action',
+                actionReference: part.actionReference,
+                summary: part.summary,
+              },
   );
 }
 

package/src/delivery/schema.ts

@@ -1,3 +1,5 @@
+import { ActionReferenceSchema } from '@ixo/ixo-transaction/action-proposals';
+import { parseReference, type ActionReferenceV1 } from '@ixo/action-protocol';
 import { z } from 'zod';
 import type { ReplyContent, ReplyPlan } from './types';
 
@@ -19,6 +21,24 @@ export const ReplyPlanSchema = z.object({
         kind: z.literal('text'),
         text: z.string(),
       }),
+      z.object({
+        partId: z.string(),
+        kind: z.literal('action'),
+        action: ActionReferenceSchema,
+      }),
+      z.object({
+        partId: z.string(),
+        kind: z.literal('hub-action'),
+        actionReference: z.custom<ActionReferenceV1>((value) => {
+          try {
+            parseReference(value);
+            return true;
+          } catch {
+            return false;
+          }
+        }),
+        summary: z.string().min(1).max(80),
+      }),
       z.object({
         partId: z.string(),
         kind: z.literal('artifact'),
@@ -55,7 +75,11 @@ export function planText(plan: { parts: readonly ReplyContent[] }): string {
     .map((part) =>
       part.kind === 'text'
         ? part.text
-        : `[${linkLabel(part.artifact.title)}](${part.artifact.url})`,
+        : part.kind === 'action'
+          ? `[${linkLabel(part.action.title)}](${part.action.url})`
+          : part.kind === 'hub-action'
+            ? `[${linkLabel(part.summary)}](${part.actionReference.url})`
+            : `[${linkLabel(part.artifact.title)}](${part.artifact.url})`,
     )
     .join('\n\n');
 }

package/src/delivery/types.ts

@@ -1,3 +1,5 @@
+import type { ActionReference } from '@ixo/ixo-transaction/action-proposals';
+import type { ActionReferenceV1 } from '@ixo/action-protocol';
 /**
  * Chat delivery: how a finished turn reaches a chat surface (an IXO Channels
  * provider such as WhatsApp, or a Matrix room) as a few short messages and
@@ -70,12 +72,21 @@ export interface ArtifactRef {
  */
 export type ReplyPart =
   | { partId: string; kind: 'text'; text: string }
-  | { partId: string; kind: 'artifact'; artifact: ArtifactRef };
+  | { partId: string; kind: 'artifact'; artifact: ArtifactRef }
+  | { partId: string; kind: 'action'; action: ActionReference }
+  | {
+      partId: string;
+      kind: 'hub-action';
+      actionReference: ActionReferenceV1;
+      summary: string;
+    };
 
 /** A part before it is numbered: what a plan is assembled from. */
 export type ReplyContent =
   | { kind: 'text'; text: string }
-  | { kind: 'artifact'; artifact: ArtifactRef };
+  | { kind: 'artifact'; artifact: ArtifactRef }
+  | { kind: 'action'; action: ActionReference }
+  | { kind: 'hub-action'; actionReference: ActionReferenceV1; summary: string };
 
 /** What a chat surface delivers for one finished run, in delivery order. */
 export interface ReplyPlan {

package/src/do/ambient.ts

@@ -267,6 +267,8 @@ export function createUcanAdapter(
 
 export interface CreateAmbientInput {
   /** Host task scheduler surface for this user, when tasks are enabled. */
+  actionProposals?: AmbientServices['actionProposals'];
+  hubActions?: AmbientServices['hubActions'];
   tasks?: import('../plugin-api/types').OracleTasksSurface;
   preferences?: import('../plugin-api/types').UserPreferencesSurface;
   /** `ctx.kv` over the user's working copy (`SqliteUserKv`). */
@@ -302,6 +304,10 @@ export function createAmbientServices(
 ): AmbientServices {
   return {
     ...(input.tasks ? { tasks: input.tasks } : {}),
+    ...(input.actionProposals
+      ? { actionProposals: input.actionProposals }
+      : {}),
+    ...(input.hubActions ? { hubActions: input.hubActions } : {}),
     ...(input.preferences ? { preferences: input.preferences } : {}),
     ...(input.kv ? { kv: input.kv } : {}),
     ...(input.frontend ? { frontend: input.frontend } : {}),

package/src/do/contracts.ts

@@ -1,3 +1,9 @@
+import type {
+  BeginTopicStep,
+  TopicReceiptReferences,
+} from '@ixo/ixo-transaction/topic-proposals';
+import type { ProposalCommand } from '../action-proposals/store';
+import type { ActionOutcomeV1 } from '@ixo/action-protocol';
 import type {
   TopicDeliverableCommand,
   TopicDeliverableResult,
@@ -50,6 +56,12 @@ import type { DomainContextProvenance } from '../core/domain-context';
 /** Bindings every oracle Worker must declare (see the example `wrangler.jsonc`). */
 export interface OracleWorkerEnv {
   TOPIC_DELIVERABLES_ENABLED?: string;
+  ACTION_PROPOSALS_RPC_TESTNET?: string;
+  ACTION_PROPOSALS_RPC_DEVNET?: string;
+  ACTION_PROPOSALS_RPC_MAINNET?: string;
+  ACTION_PROPOSALS_ENABLED?: string;
+  ACTION_TOPIC_PROPOSALS_ENABLED?: string;
+  ACTION_PROPOSALS_PORTAL_ORIGIN?: string;
   USER_ORACLE: DurableObjectNamespace<UserOracleObject>;
   MATRIX_GATEWAY: DurableObjectNamespace<MatrixGatewayObject>;
 
@@ -72,6 +84,8 @@ export interface OracleWorkerEnv {
   AUTH_HUB?: Fetcher;
   AUTH_HUB_URL?: string;
   AUTH_HUB_CHANNEL_SERVICE_KEY?: string;
+  HUB_ACTIONS_ENABLED?: string;
+  AUTH_HUB_ACTION_OUTCOME_KEY?: string;
 
   // --- matrix -------------------------------------------------------------
   MATRIX_BASE_URL: string;
@@ -371,6 +385,7 @@ export interface TurnRequest {
     /** A provider id (`/^[a-z][a-z0-9_-]{0,31}$/`), e.g. `whatsapp`. */
     provider: string;
     bindingId: string;
+    bindingRevision?: number;
     remoteMessageRef: string;
   };
   executionProfile?: TaskExecutionProfile;
@@ -721,6 +736,7 @@ export interface StorageStatus {
  * piped straight to the client.
  */
 export interface UserOracleObject extends Rpc.DurableObjectBranded {
+  recordHubActionOutcome(outcome: ActionOutcomeV1): Promise<void>;
   topicDeliverable(
     identity: TurnIdentity,
     operationId: string,
@@ -759,6 +775,18 @@ export interface UserOracleObject extends Rpc.DurableObjectBranded {
     opts?: { limit?: number; offset?: number },
   ): Promise<{ sessions: SessionSummary[]; total: number }>;
   deleteSession(identity: TurnIdentity, sessionId: string): Promise<boolean>;
+  actionProposal(
+    identity: TurnIdentity,
+    id: string,
+    command?:
+      | ProposalCommand
+      | { kind: 'topic-reconcile'; input: TopicReceiptReferences },
+  ): Promise<JsonString | null>;
+  beginTopicStep(
+    identity: TurnIdentity,
+    id: string,
+    input: BeginTopicStep,
+  ): Promise<JsonString | null>;
   /** `GET /artifacts/:id` — the owner's canonical copy, or null. */
   artifact(
     identity: TurnIdentity,
@@ -1066,6 +1094,17 @@ export interface MatrixGatewayObject extends Rpc.DurableObjectBranded {
   ): Promise<string>;
   /** Full room state as a JSON-encoded array of `{ type, state_key, content, sender, event_id }`. */
   getRoomState(roomId: string): Promise<JsonString>;
+  getTopicRoomState(roomId: string): Promise<JsonString>;
+  getTopicEvent(
+    roomId: string,
+    eventId: string,
+    opts?: { deadlineAt?: number },
+  ): Promise<JsonString | null>;
+  getTopicHistory(
+    roomId: string,
+    root: string,
+    opts?: { deadlineAt?: number; sender?: string },
+  ): Promise<JsonString>;
   /** One timeline event (decrypted when E2EE) as JSON `{ event_id, type, content, sender, origin_server_ts }`, or null. */
   getEvent(roomId: string, eventId: string): Promise<JsonString | null>;
   /**