@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/plugins/agui/agui.plugin.ts

@@ -20,7 +20,11 @@ import type {
   PluginTool,
   RuntimeContext,
 } from '../../plugin-api/types';
-import { logActionToMatrix } from '../portal/action-log';
+import { logFrontendAction } from '../portal/action-log';
+import {
+  describeDropped,
+  sanitizeDeclaredTools,
+} from '../portal/declared-tools';
 import { createAguiSubAgent } from './agui-agent';
 
 const manifest: PluginManifest = {
@@ -60,12 +64,16 @@ const AG_ACTION_SHAPE = z.object({
 
 const ARGS_RECORD_SHAPE = z.record(z.string(), z.unknown());
 
+/** The client's AG-UI actions; a name declared twice keeps its first descriptor. */
 export function parseAgActions(value: unknown): AgAction[] {
   if (!Array.isArray(value)) return [];
   const out: AgAction[] = [];
+  const names = new Set<string>();
   for (const entry of value) {
     const parsed = AG_ACTION_SHAPE.safeParse(entry);
-    if (parsed.success) out.push(parsed.data);
+    if (!parsed.success || names.has(parsed.data.name)) continue;
+    names.add(parsed.data.name);
+    out.push(parsed.data);
   }
   return out;
 }
@@ -95,36 +103,43 @@ export function buildActionTool(action: AgAction): PluginTool | null {
           `No browser is connected to session ${sessionId}, so AG-UI action ${action.name} cannot run — the client must open the realtime (socket.io) channel for this session first.`,
         );
       }
-      const args = parseArgs(input);
-      const requestId = ctx.session.requestId;
-      const toolCallId = `ag_${requestId || 'noreq'}_${crypto
-        .randomUUID()
-        .slice(0, 8)}`;
+      // The bridge makes every invocation unique (`ag_<requestId>:<uuid>`).
+      let invocationId: string | undefined;
       const result = await frontend.callAgAction({
         sessionId,
-        toolCallId,
+        toolCallId: `ag_${ctx.session.requestId || 'noreq'}`,
         toolName: action.name,
-        args,
+        args: parseArgs(input),
         timeoutMs: AG_ACTION_TIMEOUT_MS,
+        signal: ctx.abortSignal,
+        onInvocation: (id) => {
+          invocationId = id;
+        },
       });
-      logActionToMatrix(ctx, {
-        name: action.name,
-        args,
-        result,
-        success: true,
-      });
+      logFrontendAction(ctx, { name: action.name, invocationId, result });
       return JSON.stringify(result);
     },
     {
       name: action.name,
       description: action.description,
       schema,
+      // A UI action on the user's screen: running it again is a new action.
+      repeatable: true,
     },
   );
 }
 
+/**
+ * The AG-UI actions declared on this request that may become tools: invalid,
+ * duplicate and oversized declarations are dropped (`declared-tools.ts`).
+ */
 function readAgActions(rtCtx: RuntimeContext): AgAction[] {
-  return parseAgActions(rtCtx.history.state.agActions);
+  const { kept, dropped } = sanitizeDeclaredTools(
+    parseAgActions(rtCtx.history.state.agActions),
+  );
+  const summary = describeDropped('AG-UI actions', dropped);
+  if (summary) rtCtx.logger.warn(summary);
+  return kept;
 }
 
 export class AGUIPlugin extends OraclePlugin {

package/src/plugins/composio/composio-tools.ts

@@ -2,6 +2,7 @@ import { Composio } from '@composio/core';
 import { LangchainProvider } from '@composio/langchain';
 import { z } from 'zod';
 import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+import { withCallTimeout } from '../mcp-call-timeout';
 
 /**
  * Minimal shape of a LangChain `DynamicStructuredTool` the composio session
@@ -110,9 +111,10 @@ const refreshInFlight = new Set<string>();
 
 /**
  * Drop long-expired entries (and, if still over the cap, the
- * soonest-to-expire ones). Runs on every cache write, so in a long-running
- * multi-tenant isolate one-off users' schemas are reclaimed instead of
- * accumulating for the isolate lifetime. Entries get one extra TTL of grace
+ * soonest-to-expire ones). Runs on every cache lookup and write, so in a
+ * long-running multi-tenant isolate one-off users' schemas are reclaimed
+ * instead of accumulating for the isolate lifetime, even when the replacement
+ * session open fails and no write follows. Entries get one extra TTL of grace
  * past expiry — a recently-expired entry is still served stale while its
  * background refresh runs, so reclaiming it immediately would put the
  * session-open round-trip back on that user's next turn.
@@ -209,10 +211,47 @@ function normalizeArgs(toolName: string, args: unknown): unknown {
   };
 }
 
+/**
+ * Upper bound on one Composio tool call. The Composio SDK gives each HTTP
+ * attempt 60 s and retries a timed-out or failed attempt twice with a short
+ * back-off (about 182 s in the worst case), so this sits just past that and
+ * the SDK's own answer arrives first. What it catches is what the SDK leaves
+ * open: its timer stops once the response headers arrive, so a body that
+ * stalls after them would otherwise be waited on forever.
+ */
+export const COMPOSIO_TOOL_TIMEOUT_MS = 190_000;
+
+/**
+ * A promise that rejects when `signal` aborts (at once if it already has),
+ * plus the call that stops listening. The SDK's LangChain tools take no
+ * signal, so the turn's cancellation is applied by racing against this.
+ */
+function rejectOnAbort(signal: AbortSignal): {
+  promise: Promise<never>;
+  dispose: () => void;
+} {
+  let onAbort = (): void => undefined;
+  const promise = new Promise<never>((_, reject) => {
+    onAbort = () => {
+      const reason: unknown = signal.reason;
+      reject(reason instanceof Error ? reason : new Error(String(reason)));
+    };
+  });
+  if (signal.aborted) onAbort();
+  else signal.addEventListener('abort', onAbort, { once: true });
+  return {
+    promise,
+    dispose: () => signal.removeEventListener('abort', onAbort),
+  };
+}
+
 /**
  * Wrap a single composio session tool as a {@link PluginTool}. The handler
- * forwards the args through the underlying `invoke` and propagates errors so
- * the agent surfaces a clean failure rather than a silent empty response.
+ * forwards the args through the underlying `invoke`, bounded by
+ * {@link COMPOSIO_TOOL_TIMEOUT_MS} and the turn's abort signal (the request
+ * itself is abandoned, not cancelled: the SDK offers no way to stop it), and
+ * propagates errors so the agent surfaces a clean failure rather than a
+ * silent empty response.
  */
 function wrapAsPluginTool(sessionTool: ComposioSessionTool): PluginTool {
   return {
@@ -220,8 +259,17 @@ function wrapAsPluginTool(sessionTool: ComposioSessionTool): PluginTool {
     description: sessionTool.description,
     schema: toolSchema(sessionTool.schema),
     handler: async (args, ctx: RuntimeContext) => {
+      const cancelled = rejectOnAbort(ctx.abortSignal);
       try {
-        return await sessionTool.invoke(normalizeArgs(sessionTool.name, args));
+        return await withCallTimeout(
+          () =>
+            Promise.race([
+              sessionTool.invoke(normalizeArgs(sessionTool.name, args)),
+              cancelled.promise,
+            ]),
+          COMPOSIO_TOOL_TIMEOUT_MS,
+          `composio tool ${sessionTool.name}`,
+        );
       } catch (error) {
         const detail =
           error instanceof Error
@@ -231,6 +279,8 @@ function wrapAsPluginTool(sessionTool: ComposioSessionTool): PluginTool {
           `[composio] tool "${sessionTool.name}" failed: ${detail}`,
         );
         throw error;
+      } finally {
+        cancelled.dispose();
       }
     },
   };
@@ -307,6 +357,7 @@ export async function createComposioTools(
   };
 
   const cacheKey = defsCacheKey(opts.baseUrl, opts.userId);
+  if (opts.defsCache) pruneDefsCache(opts.defsCache, Date.now());
   const cached = opts.defsCache?.get(cacheKey);
   if (cached) {
     // An expired entry is served as-is (the session meta-toolset only shifts

package/src/plugins/composio/composio-ucan.ts

@@ -1,4 +1,5 @@
 import type { RuntimeContext } from '../../plugin-api/types';
+import { SANDBOX_CAPABILITY } from '../delegated-capabilities';
 import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
 
 /**
@@ -33,11 +34,11 @@ export async function mintComposioInvocation(
   // `401 REPLAY: Invocation has already been used`. Mint fresh every call.
   return mintInvocationSafely(
     runCtx,
-    { did: composioDid, capability: 'ixo:sandbox' },
+    { did: composioDid, capability: SANDBOX_CAPABILITY.resource },
     'composio',
     // can: composio routes through the sandbox capability, and the user's
     // delegation grants `sandbox/*`. A `'*'` claim is satisfiable only by a
     // `'*'` grant — `'*'.startsWith('sandbox/')` is false.
-    { skipCache: true, can: 'sandbox/*' },
+    { skipCache: true, can: SANDBOX_CAPABILITY.action },
   );
 }

package/src/plugins/composio/composio.plugin.ts

@@ -11,6 +11,7 @@ import {
   type ComposioSessionFactory,
 } from './composio-tools';
 import { mintComposioInvocation } from './composio-ucan';
+import { SANDBOX_CAPABILITY } from '../delegated-capabilities';
 
 const configSchema = z.object({
   COMPOSIO_API_KEY: z.string().min(1, 'COMPOSIO_API_KEY must not be empty.'),
@@ -100,6 +101,7 @@ const manifest: PluginManifest = {
   category: 'integration',
   visibility: 'on-demand',
   stability: 'stable',
+  requires: [SANDBOX_CAPABILITY],
 };
 
 export interface ComposioPluginOptions {

package/src/plugins/delegated-capabilities.ts

@@ -0,0 +1,25 @@
+/**
+ * Capabilities bundled plugins prove through the user's delegation to this
+ * oracle. Each is both the plugin's `manifest.requires` and the capability
+ * its invocations claim, so what the gate checks and what the downstream
+ * service is shown cannot drift apart. A plugin that authorizes some other
+ * way (VFS fetches its own `ixo:filesystem` delegation from the UCAN store)
+ * or degrades without a grant (skills fall back to public capsules) declares
+ * nothing.
+ */
+export interface DelegatedCapability {
+  readonly resource: string;
+  readonly action: string;
+}
+
+/** Memory Engine MCP: the memory plugin's tools. */
+export const MEMORY_CAPABILITY: DelegatedCapability = {
+  resource: 'ixo:memory',
+  action: 'memory/*',
+};
+
+/** Sandbox MCP, and Composio, which routes through the sandbox. */
+export const SANDBOX_CAPABILITY: DelegatedCapability = {
+  resource: 'ixo:sandbox',
+  action: 'sandbox/*',
+};

package/src/plugins/editor/content-session.ts

@@ -5,17 +5,19 @@
  * document. It enforces, in this order:
  *
  *   1. a live flow is read-only            → `read_only_flow`
- *   2. the provider already knows it cannot write → `needs_access`
+ *   2. an earlier write in this session failed → the same answer as step 6
  *   3. the oracle's power level is below the room's write threshold → `needs_access`
  *   4. the prop allowlist (the caller's `plan` step) → `prop_not_editable` etc.
  *   5. one `doc.transact()` for the whole batch
- *   6. `await provider.waitForFlush()` **before** success is reported
- *   7. a post-flush write check                → `needs_access`
+ *   6. the provider manager's bounded `flush()` **before** success is reported:
+ *      a forbidden write → `needs_access`, a definite refusal (413, 401,
+ *      400) → `error`, an unacknowledged one → `write_not_saved`
  *
- * Steps 6 and 7 exist because matrix-crdt writes are fire-and-forget: a Y.Doc
- * mutation always "succeeds" locally, and a homeserver rejection surfaces only
- * once the batched update is actually sent. Reporting success before the flush
- * is how tools ended up claiming edits that never landed.
+ * Step 6 exists because matrix-crdt writes are fire-and-forget: a Y.Doc
+ * mutation always "succeeds" locally, and a homeserver rejection or a failed
+ * delivery surfaces only once the batched update is actually sent. Reporting
+ * success before the flush is how tools ended up claiming edits that never
+ * landed.
  */
 
 import type { MatrixClient } from 'matrix-js-sdk';
@@ -29,36 +31,40 @@ import {
 } from './document-model';
 import {
   editorError,
-  flushTimeout,
   isEditorFailure,
   needsAccess,
   readOnlyFlow,
+  writeNotSaved,
+  writeRefused,
   type EditorFailure,
 } from './failures';
 import {
+  DOC_UPDATE_EVENT_TYPE,
   MatrixProviderManager,
   RoomNotAccessibleError,
   type AppConfig,
+  type DocWriteFailure,
 } from './provider';
 
 const logger = createConsoleLogger({ module: 'editor-content-session' });
 
-/** The Matrix event type matrix-crdt writes Y.Doc updates as. */
-const CRDT_UPDATE_EVENT_TYPE = 'matrix-crdt.doc_update';
-
 /** Rooms whose canonical alias starts with this hold live flows. */
 const FLOW_ALIAS_PREFIX = '#flow-';
 
-/** How long to wait for a write to reach the homeserver before giving up. */
-const FLUSH_TIMEOUT_MS = 20_000;
-
 /**
- * What the write path needs from the CRDT provider. `MatrixProvider` satisfies
- * it; narrowing keeps the guards testable without a Matrix connection.
+ * What the write path needs from the document's provider manager.
+ * `MatrixProviderManager` satisfies it; narrowing keeps the guards testable
+ * without a Matrix connection.
  */
 export interface DocumentWriter {
-  readonly canWrite: boolean;
-  waitForFlush(): Promise<void>;
+  /** Why an earlier write did not reach the room, if one did not. */
+  readonly writeFailure: DocWriteFailure | undefined;
+  /**
+   * Wait (bounded by the provider's own deadline and write-retry budget)
+   * until every change made so far has been sent; resolves to the failure
+   * when one did not land.
+   */
+  flush(): Promise<DocWriteFailure | undefined>;
 }
 
 /** What the write path needs from the Matrix client. */
@@ -73,7 +79,7 @@ export interface RoomStateReader {
 
 export interface DocumentSession {
   doc: Y.Doc;
-  provider: DocumentWriter;
+  writer: DocumentWriter;
   matrixClient: RoomStateReader;
   roomId: string;
   /** Canonical alias, when the homeserver exposes one. */
@@ -136,18 +142,41 @@ async function resolveAlias(
   }
 }
 
+/** Where a document lives and the client that reaches it. */
+export interface DocumentParams {
+  matrixClient: MatrixClient;
+  appConfig: AppConfig;
+}
+
+/** An open document plus the call that releases it. */
+export interface OpenedDocument {
+  session: DocumentSession;
+  dispose: () => Promise<void>;
+}
+
+/** Opens a document; a failure to reach it comes back typed, never thrown. */
+export type DocumentOpener = (
+  params: DocumentParams,
+) => Promise<OpenedDocument | EditorFailure>;
+
+/** A thrown open/work error, as the typed failure a tool returns. */
+function documentFailure(error: unknown, roomId: string): EditorFailure {
+  if (error instanceof RoomNotAccessibleError) {
+    return needsAccess(roomId, 'this assistant cannot open the document');
+  }
+  const detail = error instanceof Error ? error.message : String(error);
+  logger.warn(`Failed to open document ${roomId}: ${detail}`);
+  return editorError(`Could not open the document: ${detail}`, roomId);
+}
+
 /**
- * Open the room's Y.Doc, run `work`, and always dispose the provider.
- *
- * Access problems come back as typed failures rather than exceptions, so every
- * tool can return them straight to the agent.
+ * Open the room's Y.Doc through matrix-crdt. On failure the provider is
+ * already disposed; on success the caller owns `dispose`.
  */
-export async function withDocument<T>(
-  params: { matrixClient: MatrixClient; appConfig: AppConfig },
-  work: (session: DocumentSession) => Promise<T>,
-): Promise<T | EditorFailure> {
-  const { matrixClient, appConfig } = params;
-
+export const openDocumentSession: DocumentOpener = async ({
+  matrixClient,
+  appConfig,
+}) => {
   let roomId: string;
   try {
     roomId = await resolveRoomId(matrixClient, appConfig);
@@ -158,26 +187,97 @@ export async function withDocument<T>(
 
   const manager = new MatrixProviderManager(matrixClient, appConfig);
   try {
-    const { doc, provider } = await manager.init();
+    const { doc } = await manager.init();
     const alias = await resolveAlias(matrixClient, appConfig, roomId);
-    return await work({
-      doc,
-      provider,
-      matrixClient,
-      roomId,
-      alias,
-      isFlow: isFlowAlias(alias),
-    });
+    return {
+      session: {
+        doc,
+        writer: manager,
+        matrixClient,
+        roomId,
+        alias,
+        isFlow: isFlowAlias(alias),
+      },
+      dispose: () => manager.dispose(),
+    };
   } catch (error) {
-    if (error instanceof RoomNotAccessibleError) {
-      return needsAccess(roomId, 'this assistant cannot open the document');
-    }
-    const detail = error instanceof Error ? error.message : String(error);
-    logger.warn(`Failed to open document ${roomId}: ${detail}`);
-    return editorError(`Could not open the document: ${detail}`, roomId);
-  } finally {
     await manager.dispose();
+    return documentFailure(error, roomId);
   }
+};
+
+/**
+ * How the content tools reach their document. `use` runs `work` against an
+ * open session; access problems and thrown errors come back as typed
+ * failures so every tool can return them straight to the agent.
+ */
+export interface DocumentSource {
+  use<T>(
+    work: (session: DocumentSession) => Promise<T>,
+  ): Promise<T | EditorFailure>;
+}
+
+/**
+ * One document session shared by every tool call until `close()`: opened on
+ * the first `use` (so a run that never touches the document never opens it),
+ * then reused, so a multi-step task pays the join, history walk and settle
+ * delay once. Reads see the live doc; writes still go through
+ * `applyDocumentEdit`. A failed open is not remembered — the next `use`
+ * tries again. After `close()` every `use` is refused; `close()` waits for
+ * calls still running (a write awaiting its flush) before disposing, so a
+ * cancelled run never destroys the doc under an in-flight write.
+ */
+export function sharedDocumentSource(
+  params: DocumentParams,
+  open: DocumentOpener = openDocumentSession,
+): DocumentSource & { close(): Promise<void> } {
+  let opening: Promise<OpenedDocument | EditorFailure> | null = null;
+  let closed = false;
+  const inFlight = new Set<Promise<unknown>>();
+
+  const acquire = (): Promise<OpenedDocument | EditorFailure> => {
+    if (opening) return opening;
+    const attempt = open(params);
+    opening = attempt;
+    void attempt.then((result) => {
+      if (isEditorFailure(result) && opening === attempt) opening = null;
+    });
+    return attempt;
+  };
+
+  const run = async <T>(
+    work: (session: DocumentSession) => Promise<T>,
+  ): Promise<T | EditorFailure> => {
+    const opened = await acquire();
+    if (isEditorFailure(opened)) return opened;
+    try {
+      return await work(opened.session);
+    } catch (error) {
+      return documentFailure(error, opened.session.roomId);
+    }
+  };
+
+  return {
+    async use(work) {
+      if (closed) return editorError('The document session has ended.');
+      const call = run(work);
+      inFlight.add(call);
+      try {
+        return await call;
+      } finally {
+        inFlight.delete(call);
+      }
+    },
+    async close() {
+      closed = true;
+      await Promise.allSettled([...inFlight]);
+      const pending = opening;
+      opening = null;
+      if (!pending) return;
+      const opened = await pending;
+      if (!isEditorFailure(opened)) await opened.dispose();
+    },
+  };
 }
 
 /** A live flow's room alias is `#flow-…`; a page's is `#page-…`. */
@@ -223,7 +323,7 @@ export async function canOracleWrite(
   const eventsDefault = numberAt(content, 'events_default', 0);
   const required = numberAt(
     content.events,
-    CRDT_UPDATE_EVENT_TYPE,
+    DOC_UPDATE_EVENT_TYPE,
     eventsDefault,
   );
 
@@ -231,34 +331,20 @@ export async function canOracleWrite(
 }
 
 /**
- * `canWrite` is a live getter that flips when the homeserver rejects a write,
- * so it is read through a call rather than inline: a direct property read would
- * let the compiler narrow it to its earlier value.
+ * The tool result for a write that did not land: the homeserver forbidding it
+ * means the assistant lacks access; a definite refusal means nothing was
+ * stored; otherwise delivery is uncertain.
  */
-function currentlyWritable(writer: DocumentWriter): boolean {
-  return writer.canWrite;
-}
-
-async function waitForFlushBounded(
-  provider: DocumentWriter,
-): Promise<'flushed' | 'timeout' | 'error'> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<'timeout'>((resolve) => {
-    timer = setTimeout(() => resolve('timeout'), FLUSH_TIMEOUT_MS);
-  });
-  try {
-    return await Promise.race([
-      provider.waitForFlush().then((): 'flushed' => 'flushed'),
-      timeout,
-    ]);
-  } catch (error) {
-    logger.warn(
-      `waitForFlush rejected: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    return 'error';
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
+function writeFailureResult(
+  failure: DocWriteFailure,
+  roomId: string,
+  forbiddenDetail: string,
+): EditorFailure {
+  if (failure.kind === 'forbidden') return needsAccess(roomId, forbiddenDetail);
+  logger.warn(`Document write to ${roomId} not delivered: ${failure.detail}`);
+  return failure.mayHaveLanded
+    ? writeNotSaved(roomId, failure.detail)
+    : writeRefused(roomId, failure.detail);
 }
 
 /**
@@ -283,8 +369,12 @@ export async function applyDocumentEdit<TPlan, TResult>(
     return readOnlyFlow(session.roomId, session.alias);
   }
 
-  if (!currentlyWritable(session.provider)) {
-    return needsAccess(
+  // Once a write in this session has failed, the provider refuses every
+  // further one, so report that failure instead of attempting another.
+  const earlier = session.writer.writeFailure;
+  if (earlier) {
+    return writeFailureResult(
+      earlier,
       session.roomId,
       'a previous write to this document was rejected',
     );
@@ -313,15 +403,15 @@ export async function applyDocumentEdit<TPlan, TResult>(
     if (titleSeed) seedDocumentTitle(session.doc, titleSeed);
   }, EDIT_ORIGIN);
 
-  const flush = await waitForFlushBounded(session.provider);
-  if (flush !== 'flushed') {
-    return flushTimeout(session.roomId);
-  }
-
-  // The homeserver's verdict only arrives with the flush; a rejection here
+  // The homeserver's verdict only arrives with the flush; a failure here
   // means the mutation exists locally but never reached the room.
-  if (!currentlyWritable(session.provider)) {
-    return needsAccess(session.roomId, 'the homeserver rejected the write');
+  const failure = await session.writer.flush();
+  if (failure) {
+    return writeFailureResult(
+      failure,
+      session.roomId,
+      'the homeserver rejected the write',
+    );
   }
 
   if (result === undefined) {