@ixo/oracle-runtime-workers 0.21.2 → 0.23.0

package/src/core/tool-scheduler.ts

@@ -2,18 +2,61 @@
  * Bounded tool concurrency for one user object, shared by every session and
  * every turn that object runs:
  *
- *   - writes run one at a time (a mutation never races another mutation of
- *     the same user's data, even from two simultaneous sessions);
- *   - reads run up to `maxReads` at a time;
- *   - sub-agent dispatches run up to `maxSubagents` at a time, in their own
- *     lane so a child waiting for one of the parent's slots can never
- *     deadlock the parent.
+ *   - `write`: one at a time across every session (a mutation never races
+ *     another mutation of the same user's data, even from two simultaneous
+ *     sessions);
+ *   - `read`: up to `maxReads` at a time across every session;
+ *   - `frontend:<sessionId>`: a tool that acts in the user's browser
+ *     (`PluginTool.surface: 'frontend'`), one at a time per session and
+ *     never in the user-wide lanes above, so a call parked while its chat
+ *     has no tab holds no slot another chat needs;
+ *   - `subagent:<sessionId>`: sub-agent dispatches, up to `maxSubagents` at
+ *     a time per session, in their own lane so a child waiting for one of
+ *     the parent's slots can never deadlock the parent, and a dispatch
+ *     waiting in one chat (an inner frontend call parked) never holds up
+ *     another chat's.
+ *
+ * The per-session lanes are created on demand and removed once idle (no
+ * call in flight or queued), so only busy ones exist.
  *
  * A wait is cancelled by the turn's abort signal: the waiter leaves the
  * queue and the signal's reason is thrown, so an aborted turn never holds a
  * slot it will not use.
  */
-export type ToolLane = 'read' | 'write' | 'subagent';
+export type ToolLane = 'read' | 'write' | 'frontend' | 'subagent';
+
+/** The lanes kept per session (`frontend:<sessionId>`, `subagent:<sessionId>`). */
+export type SessionToolLane = Extract<ToolLane, 'frontend' | 'subagent'>;
+
+const isSessionLane = (lane: ToolLane): lane is SessionToolLane =>
+  lane === 'frontend' || lane === 'subagent';
+
+/** The key of a per-session lane: `frontend:<sessionId>` or `subagent:<sessionId>`. */
+export function sessionLaneKey(
+  lane: SessionToolLane,
+  sessionId: string,
+): string {
+  return `${lane}:${sessionId}`;
+}
+
+export interface LaneOccupancy {
+  inFlight: number;
+  queued: number;
+}
+
+export interface ToolSchedulerSnapshot {
+  read: LaneOccupancy;
+  write: LaneOccupancy;
+  /** Summed over every session's frontend lane. */
+  frontend: LaneOccupancy;
+  /** Summed over every session's sub-agent lane. */
+  subagent: LaneOccupancy;
+  /**
+   * Per-session lanes by key (`sessionLaneKey`); only lanes with a call in
+   * flight or queued exist.
+   */
+  sessionLanes: Record<string, LaneOccupancy>;
+}
 
 class Lane {
   private active = 0;
@@ -65,6 +108,14 @@ class Lane {
   get queued(): number {
     return this.waiting.length;
   }
+
+  get idle(): boolean {
+    return this.active === 0 && this.waiting.length === 0;
+  }
+
+  get occupancy(): LaneOccupancy {
+    return { inFlight: this.active, queued: this.waiting.length };
+  }
 }
 
 /** The signal's reason as an Error (an aborter may pass any value). */
@@ -86,40 +137,94 @@ export interface ToolSchedulerOptions {
 }
 
 export class ToolScheduler {
-  private readonly lanes: Record<ToolLane, Lane>;
+  private readonly read: Lane;
+  private readonly write = new Lane(1);
+  private readonly maxSubagents: number;
+  /** Per-session lanes by `sessionLaneKey`; an idle lane is removed. */
+  private readonly sessionLanes = new Map<
+    string,
+    { kind: SessionToolLane; lane: Lane }
+  >();
 
   constructor(options: ToolSchedulerOptions = {}) {
-    this.lanes = {
-      write: new Lane(1),
-      read: new Lane(options.maxReads ?? 4),
-      subagent: new Lane(options.maxSubagents ?? 4),
-    };
+    this.read = new Lane(options.maxReads ?? 4);
+    this.maxSubagents = options.maxSubagents ?? 4;
   }
 
+  /**
+   * Run `action` once a slot of `lane` is free. `sessionId` keys the
+   * per-session lanes (`frontend`, `subagent`) and is required for them; the
+   * user-wide `read` and `write` lanes ignore it.
+   */
   async run<T>(
     lane: ToolLane,
     signal: AbortSignal | undefined,
     action: () => Promise<T>,
+    sessionId?: string,
   ): Promise<T> {
-    const slot = this.lanes[lane];
-    await slot.acquire(signal);
+    const key = isSessionLane(lane)
+      ? sessionLaneKey(lane, requireSessionId(lane, sessionId))
+      : undefined;
+    const slot = this.laneFor(lane, key);
+    try {
+      await slot.acquire(signal);
+    } catch (error) {
+      this.dropIfIdle(key, slot);
+      throw error;
+    }
     try {
       return await action();
     } finally {
       slot.release();
+      this.dropIfIdle(key, slot);
     }
   }
 
-  /** Occupancy per lane (diagnostics). */
-  snapshot(): Record<ToolLane, { inFlight: number; queued: number }> {
-    const entry = (lane: Lane) => ({
-      inFlight: lane.inFlight,
-      queued: lane.queued,
-    });
+  /** Occupancy per lane (diagnostics: `GET /debug/runs`). */
+  snapshot(): ToolSchedulerSnapshot {
+    const sessionLanes: Record<string, LaneOccupancy> = {};
+    const summed: Record<SessionToolLane, LaneOccupancy> = {
+      frontend: { inFlight: 0, queued: 0 },
+      subagent: { inFlight: 0, queued: 0 },
+    };
+    for (const [key, { kind, lane }] of this.sessionLanes) {
+      sessionLanes[key] = lane.occupancy;
+      summed[kind].inFlight += lane.inFlight;
+      summed[kind].queued += lane.queued;
+    }
     return {
-      read: entry(this.lanes.read),
-      write: entry(this.lanes.write),
-      subagent: entry(this.lanes.subagent),
+      read: this.read.occupancy,
+      write: this.write.occupancy,
+      frontend: summed.frontend,
+      subagent: summed.subagent,
+      sessionLanes,
     };
   }
+
+  private laneFor(lane: ToolLane, key: string | undefined): Lane {
+    if (!isSessionLane(lane) || key === undefined)
+      return lane === 'read' ? this.read : this.write;
+    const existing = this.sessionLanes.get(key);
+    if (existing) return existing.lane;
+    const created = new Lane(lane === 'frontend' ? 1 : this.maxSubagents);
+    this.sessionLanes.set(key, { kind: lane, lane: created });
+    return created;
+  }
+
+  private dropIfIdle(key: string | undefined, slot: Lane): void {
+    if (key === undefined || !slot.idle) return;
+    if (this.sessionLanes.get(key)?.lane === slot)
+      this.sessionLanes.delete(key);
+  }
+}
+
+function requireSessionId(
+  lane: SessionToolLane,
+  sessionId: string | undefined,
+): string {
+  if (sessionId === undefined)
+    throw new TypeError(
+      `ToolScheduler.run: the ${lane} lane is kept per session; pass the call's sessionId.`,
+    );
+  return sessionId;
 }

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/active-runs.ts

@@ -0,0 +1,171 @@
+/**
+ * The user-wide view of runs: which of the user's chats are busy right now
+ * (`GET /runs/active`, and `activeRun` on the rows of `GET /sessions`).
+ * Task runs (`task:<id>` sessions) are not chats and stay out, as they stay
+ * out of the session list; Matrix and channel runs are the user's chats
+ * whichever client sent the message, and are in.
+ */
+import type { FrontendWaitingFor } from '../plugin-api/types';
+import { TASK_SESSION_PREFIX } from '../tasks/scheduler';
+import type { RunSummary, SessionSummary } from './contracts';
+import { runSummaryOf } from './run-request';
+import { ACTIVE_RUN_STATUSES, type RunRecord } from './run-store';
+
+/**
+ * Every active (queued / running / recovering) chat run, oldest first (run
+ * id breaks a tie). `live` are the coordinator's records, `stored` the
+ * store's active rows (`RunStore.listActive()`): a run in both is listed
+ * once with its live record, which is ahead of the row between writes (a
+ * dequeued run is `running` in memory before its row says so). After a boot
+ * whose recovery scan succeeded every active row is live and the host
+ * passes no `stored` rows: a run leaves the live map before its row is
+ * closed, so a row read then would still say it runs.
+ */
+export function activeChatRuns(
+  live: Iterable<RunRecord>,
+  stored: Iterable<RunRecord>,
+): RunRecord[] {
+  const byRunId = new Map<string, RunRecord>();
+  for (const record of stored) byRunId.set(record.runId, record);
+  for (const record of live) byRunId.set(record.runId, record);
+  return [...byRunId.values()]
+    .filter(
+      (record) =>
+        ACTIVE_RUN_STATUSES.has(record.status) &&
+        !record.sessionId.startsWith(TASK_SESSION_PREFIX),
+    )
+    .sort(
+      (a, b) =>
+        (a.startedAt < b.startedAt ? -1 : a.startedAt > b.startedAt ? 1 : 0) ||
+        a.runId.localeCompare(b.runId),
+    );
+}
+
+/** The room a run's stored request names (`turn.roomId`), if any. */
+export function storedTurnRoomId(request: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(request);
+  } catch {
+    return undefined;
+  }
+  const turn: unknown =
+    typeof parsed === 'object' && parsed !== null
+      ? Reflect.get(parsed, 'turn')
+      : undefined;
+  const roomId: unknown =
+    typeof turn === 'object' && turn !== null
+      ? Reflect.get(turn, 'roomId')
+      : undefined;
+  return typeof roomId === 'string' ? roomId : undefined;
+}
+
+/**
+ * The runs of the chats `GET /sessions` lists: with a main oracle room, only
+ * sessions in that room (`sessionRooms`: the room of each run's session
+ * that has a row). A run whose session has no row yet — a Matrix thread is
+ * recorded inside its first attempt — is placed by the room its request
+ * names; a Portal run without one is listed (the Portal opens its sessions
+ * in the main room). Without a main room every chat is listed, as
+ * `listSessions` lists every session then. Task runs are already out
+ * (`activeChatRuns`).
+ */
+export function listedChatRuns(
+  runs: readonly RunRecord[],
+  o: {
+    mainRoomId: string | null;
+    sessionRooms: ReadonlyMap<string, string | null>;
+  },
+): RunRecord[] {
+  const { mainRoomId, sessionRooms } = o;
+  if (mainRoomId === null) return [...runs];
+  return runs.filter((run) => {
+    if (sessionRooms.has(run.sessionId))
+      return sessionRooms.get(run.sessionId) === mainRoomId;
+    const roomId = storedTurnRoomId(run.request);
+    if (roomId !== undefined) return roomId === mainRoomId;
+    return run.client === 'portal';
+  });
+}
+
+/** `running` before `recovering` before `queued`, as `RunStore.activeForSession` ranks them. */
+const STATUS_RANK: Partial<Record<RunRecord['status'], number>> = {
+  running: 0,
+  recovering: 1,
+  queued: 2,
+};
+
+/**
+ * The run each session is busy with, from `activeChatRuns` (oldest first):
+ * the running or recovering one, else the oldest queued one — the run
+ * `GET /sessions/:id/run` reports for that session.
+ */
+export function activeRunBySession(
+  runs: readonly RunRecord[],
+): Map<string, RunRecord> {
+  const bySession = new Map<string, RunRecord>();
+  for (const run of runs) {
+    const current = bySession.get(run.sessionId);
+    if (
+      !current ||
+      (STATUS_RANK[run.status] ?? 3) < (STATUS_RANK[current.status] ?? 3)
+    )
+      bySession.set(run.sessionId, run);
+  }
+  return bySession;
+}
+
+/**
+ * The session's parked frontend call, if any (`ctx.frontend.parkedFor`):
+ * the object's live realtime state, never stored.
+ */
+export type ParkedCallLookup = (sessionId: string) => FrontendWaitingFor | null;
+
+/**
+ * `summary` with `waitingFor` set when the run executes (`running` or
+ * `recovering`) and its session has a parked call: only the executing run
+ * of a session can have made one. No field at all otherwise (a queued run,
+ * a run that is over).
+ */
+export function withWaitingFor(
+  summary: RunSummary,
+  parkedFor?: ParkedCallLookup,
+): RunSummary {
+  if (
+    !parkedFor ||
+    (summary.status !== 'running' && summary.status !== 'recovering')
+  )
+    return summary;
+  const waitingFor = parkedFor(summary.sessionId);
+  return waitingFor ? { ...summary, waitingFor } : summary;
+}
+
+/** A run as the user-wide listings report it: without the kept reply text. */
+export function activeRunSummaryOf(
+  record: RunRecord,
+  parkedFor?: ParkedCallLookup,
+): RunSummary {
+  return withWaitingFor(
+    runSummaryOf(record, { withPartialText: false }),
+    parkedFor,
+  );
+}
+
+/**
+ * Session rows with `activeRun` set on the ones that have an active run.
+ * A row without one gets no field at all (never `null`), so clients that
+ * predate it see the rows they always did.
+ */
+export function withActiveRuns(
+  sessions: readonly SessionSummary[],
+  runs: readonly RunRecord[],
+  parkedFor?: ParkedCallLookup,
+): SessionSummary[] {
+  const bySession = activeRunBySession(runs);
+  return sessions.map((session) => {
+    const run = bySession.get(session.sessionId);
+    return run
+      ? { ...session, activeRun: activeRunSummaryOf(run, parkedFor) }
+      : session;
+  });
+}

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 } : {}),