@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/flows/actions.ts

@@ -0,0 +1,190 @@
+/**
+ * Action catalog access. Wraps the editor registry (`getAllActions`/`getAction`/
+ * `getActionByCan`) and merges the plugin-side metadata overlay (action-metadata.ts)
+ * to power discovery (`list_actions`/`describe_action`) and the event-capability
+ * validation that `onEvent` relies on (spec §2.3).
+ *
+ * The `action` identifier exposed to the agent is the registry `type` (e.g.
+ * "qi/email.send") — never the `can` (leak guard, §1).
+ */
+import type { ActionDefinition, OutputSchemaField } from '@ixo/editor/core';
+import { getAllActions, getAction, getActionByCan } from '@ixo/editor/core';
+import { ACTION_METADATA, type OverlayEntry } from './action-metadata';
+
+/** The lifecycle hook types any step can attach via `on` (spec Appendix A.4). */
+export const HOOK_TYPES = [
+  'sendEmail',
+  'addLinkedEntity',
+  'sendMatrixDM',
+] as const;
+
+export interface ActionSummary {
+  action: string;
+  summary: string;
+  whenToUse: string[];
+  tags: string[];
+}
+
+export interface ActionField {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+}
+
+export interface ActionEvent {
+  name: string;
+  displayName?: string;
+  description?: string;
+}
+
+export interface ActionDescription {
+  action: string;
+  summary: string;
+  whenToUse: string[];
+  whenNotToUse: string[];
+  inputs: ActionField[];
+  /**
+   * Whether this action's input requirements are known. False means the field
+   * list above is NOT authoritative — the agent must ask the user what the step
+   * needs rather than assume it takes no inputs.
+   */
+  inputsDeclared: boolean;
+  outputs: ActionField[];
+  events: ActionEvent[];
+  hooks: string[];
+  isForm: boolean;
+  requiresConfirmation: boolean;
+}
+
+/** Resolve a friendly `action` (registry type, or a `can`) to its definition. */
+export function getActionDef(action: string): ActionDefinition | undefined {
+  return getAction(action) ?? getActionByCan(action);
+}
+
+function overlayFor(def: ActionDefinition): OverlayEntry {
+  return ACTION_METADATA[def.type] ?? {};
+}
+
+/**
+ * Whether `onEvent` can target this action as a source (spec §2.3): it must be
+ * `eligibleForEventTrigger` AND declare at least one event.
+ */
+export function isEventCapable(def: ActionDefinition): boolean {
+  if (!def.eligibleForEventTrigger) return false;
+  return (
+    (def.events?.length ?? 0) > 0 || typeof def.getDynamicEvents === 'function'
+  );
+}
+
+/**
+ * Whether a step is a human-form action (`qi/form.submit` / `qi/human.form.submit`
+ * and friends). Form steps need special output handling: they emit one bundled
+ * `answers` object rather than per-field outputs, so discovery + linkage expand
+ * the individual question paths separately (see `formOutputFields`).
+ */
+export function isFormAction(def: ActionDefinition): boolean {
+  return def.can === 'human/form' || /form|survey/i.test(def.type);
+}
+
+type InputSchemaShape =
+  | {
+      properties?: Record<string, { type?: string; description?: string }>;
+      required?: string[];
+    }
+  | undefined;
+
+/** Whether we have any authoritative input-requirement data for this action. */
+function hasDeclaredInputs(
+  def: ActionDefinition,
+  overlay: OverlayEntry,
+): boolean {
+  if ((overlay.inputPorts?.length ?? 0) > 0) return true;
+  return !!(def.inputSchema as InputSchemaShape)?.properties;
+}
+
+/**
+ * The action's input fields. The registry's `inputSchema` is the single source
+ * of truth for requirements (each action declares its required inputs); the
+ * overlay's `inputPorts` are only a fallback for an action that ships none.
+ * Empty when neither is present — pair with `hasDeclaredInputs` so callers know
+ * the difference between "no inputs" and "inputs unknown".
+ */
+function inputFields(
+  def: ActionDefinition,
+  overlay: OverlayEntry,
+): ActionField[] {
+  const schema = def.inputSchema as InputSchemaShape;
+  const props = schema?.properties;
+  if (props) {
+    const required = new Set(schema?.required ?? []);
+    return Object.entries(props).map(([name, spec]) => ({
+      name,
+      type: typeof spec?.type === 'string' ? spec.type : 'unknown',
+      required: required.has(name),
+      description: spec?.description,
+    }));
+  }
+  if (overlay.inputPorts && overlay.inputPorts.length > 0) {
+    return overlay.inputPorts.map((p) => ({
+      name: p.path,
+      type: p.portType,
+      required: p.required ?? false,
+      description: p.description,
+    }));
+  }
+  return [];
+}
+
+function outputFields(def: ActionDefinition): ActionField[] {
+  const out: OutputSchemaField[] | undefined = def.outputSchema;
+  if (!out) return [];
+  return out.map((f) => ({
+    name: f.path,
+    type: f.type,
+    description: f.description,
+  }));
+}
+
+export function listActions(filter?: {
+  category?: string;
+  tag?: string;
+}): ActionSummary[] {
+  const result: ActionSummary[] = [];
+  for (const def of getAllActions()) {
+    const overlay = overlayFor(def);
+    if (filter?.tag && !(overlay.tags ?? []).includes(filter.tag)) continue;
+    result.push({
+      action: def.type,
+      summary: overlay.summary ?? '',
+      whenToUse: overlay.whenToUse ?? [],
+      tags: overlay.tags ?? [],
+    });
+  }
+  return result.sort((a, b) => a.action.localeCompare(b.action));
+}
+
+export function describeAction(action: string): ActionDescription | null {
+  const def = getActionDef(action);
+  if (!def) return null;
+  const overlay = overlayFor(def);
+  return {
+    action: def.type,
+    summary: overlay.summary ?? '',
+    whenToUse: overlay.whenToUse ?? [],
+    whenNotToUse: overlay.whenNotToUse ?? [],
+    inputs: inputFields(def, overlay),
+    inputsDeclared: hasDeclaredInputs(def, overlay),
+    outputs: outputFields(def),
+    events: (def.events ?? []).map(
+      (e: { name: string; displayName?: string; description?: string }) => ({
+        name: e.name,
+        displayName: e.displayName,
+        description: e.description,
+      }),
+    ),
+    hooks: [...HOOK_TYPES],
+    isForm: isFormAction(def),
+    requiresConfirmation: def.defaultRequiresConfirmation,
+  };
+}

package/src/plugins/flows/edit.ts

@@ -0,0 +1,314 @@
+/**
+ * Per-block / delta edit dispatcher (spec §4.2). Every mutation touches only
+ * its target step; unrelated steps' data is never rewritten or dropped.
+ *
+ * All edits run in oracle-runtime's native yjs on the connected provider doc
+ * (the editor package's fragment helpers are cross-version-broken here — see
+ * read.ts). Value-prop writes reuse the editor plugin's native `editBlock`
+ * (which writes the BlockNote shape the portal renders); remove/reorder reuse
+ * its native `deleteBlock`/`moveBlock` and we keep the `qi.flow.*` maps in sync.
+ *
+ * Conditions are written DIRECTLY as `props.conditions` in the FE evaluator's
+ * operator vocabulary (never via the compiler's `cap.condition`, which never
+ * evaluates — see translator.ts).
+ */
+import type { Doc as YDoc } from 'yjs';
+import * as Y from 'yjs';
+import { deleteBlock, editBlock, findParentOf } from './ydoc-helpers';
+import { getActionDef, isEventCapable } from './actions';
+import { FlowError } from './errors';
+import { readFlowSpec } from './read';
+import {
+  BLOCK_ID_PREFIX,
+  blockIdToStepId,
+  buildConditionsProp,
+  canToAction,
+  friendlyInputsToNb,
+  stepIdToBlockId,
+} from './translator';
+import type { Condition } from './types';
+
+const DOC = 'document';
+
+function requireStep(doc: YDoc, stepId: string): string {
+  if (!doc.getMap('qi.flow.nodes').has(stepId)) {
+    throw new FlowError('step_not_found', `No step "${stepId}" in this flow.`);
+  }
+  return stepIdToBlockId(stepId);
+}
+
+/** Write a set of value props onto a step's block (per-block, lossless). */
+export function setStepProps(
+  doc: YDoc,
+  stepId: string,
+  props: Record<string, string>,
+): void {
+  const blockId = requireStep(doc, stepId);
+  editBlock(doc, { blockId, attributes: { props }, docName: DOC });
+}
+
+export function setStepInputs(
+  doc: YDoc,
+  stepId: string,
+  inputs: Record<string, unknown>,
+): void {
+  setStepProps(doc, stepId, {
+    inputs: JSON.stringify(friendlyInputsToNb(inputs) ?? {}),
+  });
+}
+
+export function setStepConditions(
+  doc: YDoc,
+  stepId: string,
+  conditions: Condition[],
+): void {
+  setStepProps(doc, stepId, {
+    conditions: conditions.length > 0 ? buildConditionsProp(conditions) : '',
+  });
+}
+
+export function setStepSchedule(
+  doc: YDoc,
+  stepId: string,
+  due: { at?: string; within?: string; afterCommitment?: string } | undefined,
+  commitTo?: string,
+): void {
+  setStepProps(doc, stepId, {
+    ttlAbsoluteDueDate: due?.at ?? '',
+    ttlFromEnablement: due?.within ?? '',
+    ttlFromCommitment: commitTo ?? due?.afterCommitment ?? '',
+  });
+}
+
+export function setStepAssignment(
+  doc: YDoc,
+  stepId: string,
+  assignTo: string | undefined,
+): void {
+  // The portal shows + nudges the assignee from `props.assignment`; the
+  // `authorisedActors` whitelist also lets that actor run the step. Write both
+  // so the assignee is visible AND authorized; clear both when unassigned.
+  setStepProps(doc, stepId, {
+    assignment: assignTo
+      ? JSON.stringify({ assignedActor: { did: assignTo } })
+      : '',
+    authorisedActors: assignTo ? JSON.stringify([assignTo]) : '',
+  });
+}
+
+export function setStepConfirmation(
+  doc: YDoc,
+  stepId: string,
+  requireConfirmation: boolean,
+): void {
+  setStepProps(doc, stepId, {
+    requiresConfirmation: requireConfirmation ? 'true' : '',
+  });
+}
+
+/** Update the stable semantic phase stored on the compiled Flow node. */
+export function setStepPhase(
+  doc: YDoc,
+  stepId: string,
+  phase: string | undefined,
+): void {
+  requireStep(doc, stepId);
+  const node = doc.getMap('qi.flow.nodes').get(stepId);
+  if (!(node instanceof Y.Map)) {
+    throw new FlowError('step_not_found', `No step "${stepId}" in this flow.`);
+  }
+  doc.transact(() => {
+    if (phase) node.set('phase', phase);
+    else node.delete('phase');
+  });
+}
+
+/** Persist the human-only versus agent-capable execution boundary. */
+export function setStepExecution(
+  doc: YDoc,
+  stepId: string,
+  execution: 'human-only' | 'agent-capable',
+): void {
+  setStepProps(doc, stepId, {
+    flowAgentExecutionMode:
+      execution === 'human-only' ? 'human-only' : 'saved-input',
+  });
+}
+
+/** Persist governed skill requirements used by Flow Agent actor matching. */
+export function setStepSkills(
+  doc: YDoc,
+  stepId: string,
+  skills: string[],
+): void {
+  setStepProps(doc, stepId, {
+    requiredSkill: skills[0] ?? '',
+    requiredSkills: skills.length > 0 ? JSON.stringify(skills) : '',
+  });
+}
+
+/**
+ * Set a step's trigger to `manual` (default) or `flow-start`. Writes the same
+ * `trigger`/`triggerMode` props the compiler would. Event triggers are written
+ * by {@link setStepEventTrigger}; setting `manual` here clears one.
+ */
+export function setStepTrigger(
+  doc: YDoc,
+  stepId: string,
+  trigger: 'manual' | 'flow-start',
+): void {
+  const type = trigger === 'flow-start' ? 'flow.start' : 'manual';
+  setStepProps(doc, stepId, {
+    trigger: trigger === 'flow-start' ? JSON.stringify({ type }) : '',
+    triggerMode: type,
+  });
+}
+
+/**
+ * Auto-trigger a step when an upstream step emits an event. Writes the same
+ * `trigger`/`triggerMode` props the compiler would for a `block.event` trigger.
+ * The stored `sourceBlockId` carries the BLOCK id (`flow_block_<stepId>`) —
+ * that is what the FE reconciler matches against the source block's real `.id`
+ * — while callers keep passing the friendly step id.
+ */
+export function setStepEventTrigger(
+  doc: YDoc,
+  stepId: string,
+  onEvent: { fromStep: string; event: string },
+): void {
+  if (onEvent.fromStep.startsWith(BLOCK_ID_PREFIX)) {
+    throw new FlowError(
+      'validation_failed',
+      `"${onEvent.fromStep}" is an internal block id — use the short step id ("${blockIdToStepId(onEvent.fromStep)}").`,
+    );
+  }
+  const sourceBlockId = requireStep(doc, onEvent.fromStep);
+
+  // Same event-capability rule validate_flow enforces at plan level (spec §2.3).
+  const source = doc.getMap('qi.flow.nodes').get(onEvent.fromStep);
+  const registryType =
+    source instanceof Y.Map ? source.get('registryType') : undefined;
+  const can = source instanceof Y.Map ? source.get('can') : undefined;
+  const action =
+    typeof registryType === 'string'
+      ? registryType
+      : typeof can === 'string'
+        ? canToAction(can)
+        : undefined;
+  const def = action ? getActionDef(action) : undefined;
+  if (def && !isEventCapable(def)) {
+    throw new FlowError(
+      'validation_failed',
+      `Step "${stepId}" can't auto-trigger on "${onEvent.fromStep}" — its action "${action}" cannot emit events. ` +
+        'Use ordering (after) + an input reference instead.',
+    );
+  }
+
+  setStepProps(doc, stepId, {
+    trigger: JSON.stringify({
+      type: 'block.event',
+      sourceBlockId,
+      eventName: onEvent.event,
+    }),
+    triggerMode: 'block.event',
+  });
+}
+
+/** Steps that depend on `stepId` (via an input ref or a condition source). */
+function referrersOf(doc: YDoc, ref: string, stepId: string): string[] {
+  const flow = readFlowSpec(doc, ref);
+  if (!flow) return [];
+  const referrers: string[] = [];
+  for (const step of flow.steps) {
+    if (step.id === stepId) continue;
+    const refsInput = Object.values(step.inputs ?? {}).some(
+      (v) =>
+        typeof v === 'string' && new RegExp(`\\{\\{\\s*${stepId}\\.`).test(v),
+    );
+    const conds = [
+      ...(step.runWhen ? [step.runWhen] : []),
+      ...(step.conditions ?? []),
+    ];
+    const refsCondition = conds.some((c) => c.fromStep === stepId);
+    const refsEvent = step.onEvent?.fromStep === stepId;
+    if (refsInput || refsCondition || refsEvent) referrers.push(step.id);
+  }
+  return referrers;
+}
+
+/** Remove a step entirely: fragment block + every `qi.flow.*` trace + runtime. Rejects if referenced. */
+export function removeStep(doc: YDoc, ref: string, stepId: string): void {
+  const blockId = requireStep(doc, stepId);
+  const referrers = referrersOf(doc, ref, stepId);
+  if (referrers.length > 0) {
+    throw new FlowError(
+      'referenced',
+      `Can't remove "${stepId}" — it is used by ${referrers.join(', ')}. Update those steps first.`,
+    );
+  }
+
+  doc.transact(() => {
+    doc.getMap('qi.flow.nodes').delete(stepId);
+    doc.getMap('qi.flow.blockIndex').delete(stepId);
+    doc.getMap('runtime').delete(blockId);
+
+    const order = doc.getArray<string>('qi.flow.order');
+    const idx = order.toArray().indexOf(stepId);
+    if (idx >= 0) order.delete(idx, 1);
+
+    const edges = doc.getMap('qi.flow.edges');
+    const toDelete: string[] = [];
+    edges.forEach((value, edgeId) => {
+      const edge = value as { source?: unknown; target?: unknown } | undefined;
+      if (edge && (edge.source === stepId || edge.target === stepId))
+        toDelete.push(edgeId);
+    });
+    for (const edgeId of toDelete) edges.delete(edgeId);
+  });
+
+  deleteBlock(doc, { blockId, docName: DOC });
+}
+
+/** Reorder a step to a new 0-based index. Sequence is display-only; runtime/edges untouched. */
+export function reorderStep(doc: YDoc, stepId: string, toIndex: number): void {
+  const blockId = requireStep(doc, stepId);
+  const orderArr = doc.getArray<string>('qi.flow.order');
+  const current = orderArr.toArray();
+  const from = current.indexOf(stepId);
+  if (from < 0)
+    throw new FlowError('step_not_found', `No step "${stepId}" in this flow.`);
+
+  const target = Math.max(0, Math.min(toIndex, current.length - 1));
+  if (target === from) return;
+
+  const without = current.filter((id) => id !== stepId);
+  without.splice(target, 0, stepId);
+
+  doc.transact(() => {
+    // Move the fragment block by CLONE (yjs can't reinsert a deleted element).
+    const fragment = doc.getXmlFragment(DOC);
+    const found = findParentOf(fragment, blockId);
+    if (found) {
+      const element = found.parent.toArray()[found.index];
+      if (element instanceof Y.XmlElement) {
+        const clone = element.clone();
+        found.parent.delete(found.index, 1);
+        found.parent.insert(Math.min(target, found.parent.length), [clone]);
+      }
+    }
+    orderArr.delete(0, orderArr.length);
+    orderArr.push(without);
+  });
+}
+
+/** Update flow-level metadata (title / goal). */
+export function updateFlowMeta(
+  doc: YDoc,
+  patch: { title?: string; goal?: string },
+): void {
+  const meta = doc.getMap('qi.flow.meta');
+  doc.transact(() => {
+    if (patch.title !== undefined) meta.set('title', patch.title);
+    if (patch.goal !== undefined) meta.set('goal', patch.goal);
+  });
+}

package/src/plugins/flows/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * Uniform error model (spec §6.1). Tools never throw to the agent; expected
+ * failures come back as `{ ok: false, error: { code, message } }` with
+ * friendly, leak-safe messages.
+ */
+export type FlowErrorCode =
+  | 'no_flow_ref'
+  | 'not_in_room'
+  | 'flow_not_found'
+  | 'validation_failed'
+  | 'step_not_found'
+  | 'referenced'
+  | 'unknown_action'
+  | 'error';
+
+export class FlowError extends Error {
+  constructor(
+    readonly code: FlowErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'FlowError';
+  }
+}
+
+export interface ToolErrorResult {
+  ok: false;
+  error: { code: FlowErrorCode; message: string };
+}
+
+/** Normalize any thrown value into the structured tool-error result. */
+export function toToolError(err: unknown): ToolErrorResult {
+  if (err instanceof FlowError) {
+    return { ok: false, error: { code: err.code, message: err.message } };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return { ok: false, error: { code: 'error', message } };
+}

package/src/plugins/flows/explain.ts

@@ -0,0 +1,43 @@
+/**
+ * Plain-language step explanation (spec §3.6, `explain_step`). Read-only: it
+ * describes what a step will do and the inputs it will run with, so the agent
+ * can explain a step to the user before they run it. The action's diff resolver
+ * (Appendix A.7) is a later enhancement — this version reports intent + inputs.
+ */
+import type { Doc as YDoc } from 'yjs';
+import { describeAction } from './actions';
+import { readFlowSpec } from './read';
+import type { StepStatus } from './types';
+
+export interface StepExplanation {
+  willDo: string;
+  action: string;
+  inputs: Record<string, unknown>;
+  requiresConfirmation: boolean;
+  status?: StepStatus;
+}
+
+export function explainStep(
+  doc: YDoc,
+  ref: string,
+  stepId: string,
+): StepExplanation | null {
+  const flow = readFlowSpec(doc, ref);
+  const step = flow?.steps.find((s) => s.id === stepId);
+  if (!step) return null;
+
+  const description = describeAction(step.action);
+  const summary = description?.summary?.trim();
+  const willDo = summary
+    ? summary
+    : `Runs the "${step.action}" action${step.title ? ` (${step.title})` : ''}.`;
+
+  return {
+    willDo,
+    action: step.action,
+    inputs: step.inputs ?? {},
+    requiresConfirmation:
+      step.requireConfirmation ?? description?.requiresConfirmation ?? false,
+    status: step.status,
+  };
+}

package/src/plugins/flows/flow-doc.ts

@@ -0,0 +1,111 @@
+/**
+ * Connect to a flow's Matrix-backed Y.Doc and run a unit of work against it,
+ * then dispose. This is the only place the plugin touches Matrix; every read
+ * and mutation goes through `withFlowDoc`. We reuse the editor plugin's
+ * provider, config builder, and matrix-client resolver verbatim — the flows
+ * plugin never re-implements the connection.
+ *
+ * `flowRef` IS the Matrix room id (opaque to the agent). The default flow
+ * (when the agent omits `ref`) is the one bound to `state.editorRoomId`.
+ */
+import type { Doc as YDoc } from 'yjs';
+import type { MatrixClient } from 'matrix-js-sdk';
+import { MatrixProviderManager, type AppConfig } from '../editor/provider';
+import { buildBlocknoteToolsConfig } from '../editor/editor-config';
+import { resolveEditorMatrixClient } from '../editor/editor-mx';
+import { isUserInRoom } from '../editor/room-membership';
+import type { RuntimeContext } from '../../plugin-api/types';
+import { FlowError } from './errors';
+
+interface MatrixCreds {
+  baseUrl: string;
+  userId: string;
+  accessToken: string;
+}
+
+async function readMatrixCreds(rtCtx: RuntimeContext): Promise<MatrixCreds> {
+  try {
+    const { baseUrl, userId, accessToken } =
+      await rtCtx.matrix.botCredentials();
+    return { baseUrl, userId, accessToken };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new FlowError(
+      'error',
+      `Matrix is not available for this oracle: ${detail}`,
+    );
+  }
+}
+
+/** The flow handle for a request: the explicit `ref`, else the open flow's room. */
+export function resolveFlowRef(rtCtx: RuntimeContext, ref?: string): string {
+  const candidate = ref ?? rtCtx.history.state.editorRoomId;
+  if (typeof candidate === 'string' && candidate.length > 0) return candidate;
+  throw new FlowError(
+    'no_flow_ref',
+    'No flow is open. Create a flow first, or specify which flow to use.',
+  );
+}
+
+/** Enforce the room-membership guard (fail closed). */
+export async function requireRoomMembership(
+  rtCtx: RuntimeContext,
+  roomId: string,
+): Promise<void> {
+  if (!(await isUserInRoom(rtCtx, roomId, rtCtx.user.matrixUserId))) {
+    throw new FlowError('not_in_room', 'You do not have access to this flow.');
+  }
+}
+
+/**
+ * Resolve a Matrix client for compile-driven authoring (`setupFlowFromBaseUcan`),
+ * which manages its own provider/doc rather than taking the one `withFlowDoc` opens.
+ */
+export async function resolveFlowsMatrixClient(
+  rtCtx: RuntimeContext,
+  injectedClient: MatrixClient | undefined,
+): Promise<MatrixClient> {
+  return resolveEditorMatrixClient({
+    ...(await readMatrixCreds(rtCtx)),
+    matrixClient: injectedClient,
+  });
+}
+
+function buildAppConfig(creds: MatrixCreds, roomId: string): AppConfig {
+  const base = buildBlocknoteToolsConfig(creds);
+  return {
+    matrix: { ...base.matrix, room: { type: 'id', value: roomId } },
+    provider: { ...base.provider },
+    blocknote: { ...base.blocknote },
+  };
+}
+
+/**
+ * Resolve the flow ref, enforce the room-membership guard (fail closed), open
+ * the room's Y.Doc, run `fn`, and always dispose the provider.
+ */
+export async function withFlowDoc<T>(
+  rtCtx: RuntimeContext,
+  ref: string | undefined,
+  injectedClient: MatrixClient | undefined,
+  fn: (doc: YDoc, roomId: string) => Promise<T>,
+): Promise<T> {
+  const roomId = resolveFlowRef(rtCtx, ref);
+  await requireRoomMembership(rtCtx, roomId);
+
+  const creds = await readMatrixCreds(rtCtx);
+  const matrixClient = await resolveEditorMatrixClient({
+    ...creds,
+    matrixClient: injectedClient,
+  });
+  const manager = new MatrixProviderManager(
+    matrixClient,
+    buildAppConfig(creds, roomId),
+  );
+  try {
+    const { doc } = await manager.init();
+    return await fn(doc, roomId);
+  } finally {
+    await manager.dispose();
+  }
+}