@ixo/oracle-runtime-workers 0.2.0

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

@@ -0,0 +1,365 @@
+import { Composio } from '@composio/core';
+import { LangchainProvider } from '@composio/langchain';
+import { z } from 'zod';
+import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+
+/**
+ * Minimal shape of a LangChain `DynamicStructuredTool` the composio session
+ * returns. The `schema` field is typed broadly because `DynamicStructuredTool`
+ * permits either a Zod schema or a raw JSON schema; at runtime the composio
+ * `LangchainProvider` always emits Zod (via `jsonSchemaToZodSchema`), but the
+ * structural interface stays wide so a non-conforming SDK shape doesn't crash
+ * the build. {@link toolSchema} narrows the value when wrapping each entry.
+ */
+export interface ComposioSessionTool {
+  readonly name: string;
+  readonly description: string;
+  readonly schema: unknown;
+  invoke(input: unknown): Promise<unknown>;
+}
+
+/**
+ * Factory that opens a Composio session for the current user and returns the
+ * dynamic tool list. Injected into the plugin so tests can stub the SDK out
+ * entirely.
+ */
+export type ComposioSessionFactory = (
+  args: ComposioSessionFactoryArgs,
+) => Promise<ComposioSessionTool[]>;
+
+export interface ComposioSessionFactoryArgs {
+  /** Resolved at boot from the plugin's configSchema. */
+  apiKey: string;
+  /** Resolved at boot from the plugin's configSchema. */
+  baseUrl: string;
+  /** UCAN invocation token, minted per request — forwarded as a header. */
+  ucanInvocation: string;
+  /** User identifier; composio uses it as the session `user_id`. */
+  userId: string;
+  /** Optional `x-ixo-network` header value forwarded to composio. */
+  network?: string;
+}
+
+/**
+ * Default {@link ComposioSessionFactory}: opens a real Composio session using
+ * `@composio/core` + `@composio/langchain`.
+ */
+export function createDefaultComposioSessionFactory(): ComposioSessionFactory {
+  return async ({ apiKey, baseUrl, ucanInvocation, userId, network }) => {
+    const defaultHeaders: Record<string, string> = {
+      'x-ucan-invocation': ucanInvocation,
+    };
+    if (network) defaultHeaders['x-ixo-network'] = network;
+
+    const composio = new Composio({
+      apiKey,
+      provider: new LangchainProvider(),
+      baseURL: baseUrl,
+      defaultHeaders,
+    });
+    const session = await composio.create(userId);
+    const tools = await session.tools();
+    return tools;
+  };
+}
+
+/**
+ * Tool *definition* — the session-independent slice of a
+ * {@link ComposioSessionTool}. The per-user/per-request part (the UCAN
+ * invocation header baked into the session) is applied at invoke time.
+ */
+export interface ComposioToolDef {
+  name: string;
+  description: string;
+  schema: unknown;
+}
+
+export interface CachedComposioDefs {
+  defs: ComposioToolDef[];
+  expiresAt: number;
+}
+
+/** Cache of session tool definitions, keyed per user (see {@link defsCacheKey}). */
+export type ComposioDefsCache = Map<string, CachedComposioDefs>;
+
+/**
+ * The composio session surface is a stable meta-toolset (search / execute /
+ * manage-connections); it shifts only when the user's connected-account state
+ * flips. A short TTL keeps that fresh while removing the session-create +
+ * tools-list round-trips from nearly every chat turn.
+ */
+export const COMPOSIO_TOOL_DEFS_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Hard ceiling on cached users. The expired-entry sweep is what bounds the
+ * cache in practice (entries outlive their user by at most one TTL); the cap
+ * only kicks in if more distinct users than this are active inside a single
+ * TTL window, evicting the soonest-to-expire entries first.
+ */
+export const COMPOSIO_DEFS_CACHE_MAX_ENTRIES = 1000;
+
+function defsCacheKey(baseUrl: string, userId: string): string {
+  return `${baseUrl}::${userId}`;
+}
+
+/**
+ * Cache keys with a background definition refresh in flight — guards a burst
+ * of turns from each opening its own session when an entry expires.
+ */
+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
+ * 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.
+ */
+function pruneDefsCache(cache: ComposioDefsCache, now: number): void {
+  for (const [key, entry] of cache) {
+    if (entry.expiresAt + COMPOSIO_TOOL_DEFS_TTL_MS <= now) cache.delete(key);
+  }
+  const surplus = cache.size - COMPOSIO_DEFS_CACHE_MAX_ENTRIES;
+  if (surplus <= 0) return;
+  const soonestFirst = [...cache.entries()]
+    .sort((a, b) => a[1].expiresAt - b[1].expiresAt)
+    .slice(0, surplus);
+  for (const [key] of soonestFirst) cache.delete(key);
+}
+
+export interface CreateComposioToolsOptions {
+  apiKey: string;
+  baseUrl: string;
+  ucanInvocation: string;
+  userId: string;
+  network?: string;
+  /** Override the session factory — defaults to the real SDK client. */
+  sessionFactory?: ComposioSessionFactory;
+  /**
+   * Optional definitions cache (owned by the plugin instance). When provided
+   * and warm, the session open is deferred to the first actual tool
+   * invocation; when absent, every call opens a session — the pre-cache
+   * behaviour.
+   */
+  defsCache?: ComposioDefsCache;
+  /** Logger for background-refresh failures; defaults to silent. */
+  logger?: { warn(message: string): void };
+}
+
+/**
+ * Permissive fallback schema for composio tools whose `schema` field is not
+ * a Zod schema (e.g. a raw JSON schema from a non-default provider). Used by
+ * {@link toolSchema} when narrowing fails so the agent still sees the tool
+ * with a valid descriptor — the composio backend itself validates args.
+ */
+const FALLBACK_ARGS_SCHEMA = z.record(z.string(), z.unknown());
+
+/**
+ * Narrow a composio session tool's `schema` field to a Zod schema.
+ *
+ * The default `LangchainProvider` always converts the upstream JSON Schema to
+ * a Zod schema, so this branch is the hot path. Custom providers that emit
+ * raw JSON Schema (rare) fall through to the permissive record schema so the
+ * tool is still discoverable.
+ */
+function toolSchema(schema: unknown): z.ZodType {
+  return schema instanceof z.ZodType ? schema : FALLBACK_ARGS_SCHEMA;
+}
+
+/** Composio tool-router meta-tool that batches one or more tool executions. */
+const MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';
+
+/**
+ * Coerce the model's `COMPOSIO_MULTI_EXECUTE_TOOL` input to the exact envelope
+ * Composio's (strict) schema accepts: `{ tools, sync_response_to_workbench }`.
+ *
+ * The multi-execute meta-tool is the one piece of the tool-router flow the
+ * model keeps malforming — across runs it has dropped the required
+ * `sync_response_to_workbench` control flag and hallucinated extra top-level
+ * keys (e.g. a spurious `session`). Prompt guidance reduces but doesn't
+ * eliminate this. Rebuilding the envelope here is deterministic:
+ *
+ *   - keep the model's `tools` payload verbatim — the only part it must
+ *     genuinely author (a genuinely-empty call still fails upstream because
+ *     `tools` is required, which is correct: there is nothing to run);
+ *   - default `sync_response_to_workbench` to `false` (return each result
+ *     inline rather than offloading to the remote workbench) unless the model
+ *     set it explicitly;
+ *   - drop every other top-level key.
+ *
+ * This pins the envelope *shape* — a stable meta-tool contract — not any tool
+ * slugs, which live in Composio's registry and must not be hardcoded here.
+ */
+function isArgsRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeArgs(toolName: string, args: unknown): unknown {
+  if (toolName !== MULTI_EXECUTE_TOOL || !isArgsRecord(args)) {
+    return args;
+  }
+  return {
+    tools: args.tools,
+    sync_response_to_workbench:
+      typeof args.sync_response_to_workbench === 'boolean'
+        ? args.sync_response_to_workbench
+        : false,
+  };
+}
+
+/**
+ * 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.
+ */
+function wrapAsPluginTool(sessionTool: ComposioSessionTool): PluginTool {
+  return {
+    name: sessionTool.name,
+    description: sessionTool.description,
+    schema: toolSchema(sessionTool.schema),
+    handler: async (args, ctx: RuntimeContext) => {
+      try {
+        return await sessionTool.invoke(normalizeArgs(sessionTool.name, args));
+      } catch (error) {
+        const detail =
+          error instanceof Error
+            ? `${error.name}: ${error.message}`
+            : String(error);
+        ctx.logger.error(
+          `[composio] tool "${sessionTool.name}" failed: ${detail}`,
+        );
+        throw error;
+      }
+    },
+  };
+}
+
+/**
+ * Bind cached definitions to a lazily-opened session. The session (with this
+ * request's UCAN invocation) is created on the first actual invocation and
+ * shared by every composio tool in the request — turns that never call
+ * composio pay zero composio round-trips.
+ */
+function buildLazySessionTools(
+  defs: ComposioToolDef[],
+  sessionArgs: ComposioSessionFactoryArgs,
+  sessionFactory: ComposioSessionFactory,
+): PluginTool[] {
+  let sessionByName: Promise<Map<string, ComposioSessionTool>> | null = null;
+  const connect = (): Promise<Map<string, ComposioSessionTool>> => {
+    if (!sessionByName) {
+      sessionByName = sessionFactory(sessionArgs).then(
+        (tools) => new Map(tools.map((t) => [t.name, t])),
+      );
+      // A failed session open must not poison the rest of the run — clear
+      // the memo so a later invocation retries with a fresh session.
+      sessionByName.catch(() => {
+        sessionByName = null;
+      });
+    }
+    return sessionByName;
+  };
+
+  return defs.map((def) =>
+    wrapAsPluginTool({
+      name: def.name,
+      description: def.description,
+      schema: def.schema,
+      invoke: async (input: unknown) => {
+        const byName = await connect();
+        const sessionTool = byName.get(def.name);
+        if (!sessionTool) {
+          throw new Error(
+            `composio no longer exposes "${def.name}" — cached definition is stale, retry shortly.`,
+          );
+        }
+        return sessionTool.invoke(input);
+      },
+    }),
+  );
+}
+
+/**
+ * Build the composio plugin's request-time tool list.
+ *
+ *   1. Opens a composio session via the configured factory (or, with a warm
+ *      `defsCache`, defers the open to the first actual invocation).
+ *   2. Wraps each returned tool into a {@link PluginTool} that proxies args
+ *      to the session tool's `invoke`.
+ *
+ * Returns an empty list if the session factory yields no tools (e.g. the
+ * user has no connected accounts and composio omits the management tools).
+ */
+export async function createComposioTools(
+  opts: CreateComposioToolsOptions,
+): Promise<PluginTool[]> {
+  const sessionFactory =
+    opts.sessionFactory ?? createDefaultComposioSessionFactory();
+
+  const sessionArgs: ComposioSessionFactoryArgs = {
+    apiKey: opts.apiKey,
+    baseUrl: opts.baseUrl,
+    ucanInvocation: opts.ucanInvocation,
+    userId: opts.userId,
+    network: opts.network,
+  };
+
+  const cacheKey = defsCacheKey(opts.baseUrl, opts.userId);
+  const cached = opts.defsCache?.get(cacheKey);
+  if (cached) {
+    // An expired entry is served as-is (the session meta-toolset only shifts
+    // when the user's connected-account state flips) while a background
+    // refresh re-snapshots it — TTL expiry never puts the session-open +
+    // tools-list round-trips back on a chat turn.
+    const defsCache = opts.defsCache;
+    if (
+      defsCache &&
+      cached.expiresAt <= Date.now() &&
+      !refreshInFlight.has(cacheKey)
+    ) {
+      refreshInFlight.add(cacheKey);
+      void sessionFactory(sessionArgs)
+        .then((sessionTools) => {
+          defsCache.set(cacheKey, {
+            defs: sessionTools.map(({ name, description, schema }) => ({
+              name,
+              description,
+              schema,
+            })),
+            expiresAt: Date.now() + COMPOSIO_TOOL_DEFS_TTL_MS,
+          });
+          pruneDefsCache(defsCache, Date.now());
+        })
+        .catch((err: unknown) => {
+          // Keep serving the stale defs; the next expired-cache turn
+          // retries the refresh.
+          opts.logger?.warn(
+            `[composio] background tool-defs refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        })
+        .finally(() => {
+          refreshInFlight.delete(cacheKey);
+        });
+    }
+    return buildLazySessionTools(cached.defs, sessionArgs, sessionFactory);
+  }
+
+  const sessionTools = await sessionFactory(sessionArgs);
+  if (opts.defsCache) {
+    opts.defsCache.set(cacheKey, {
+      defs: sessionTools.map(({ name, description, schema }) => ({
+        name,
+        description,
+        schema,
+      })),
+      expiresAt: Date.now() + COMPOSIO_TOOL_DEFS_TTL_MS,
+    });
+    // Prune after the write so the cap accounts for the entry just added —
+    // the fresh entry has the latest expiry, so it always survives.
+    pruneDefsCache(opts.defsCache, Date.now());
+  }
+
+  return sessionTools.map(wrapAsPluginTool);
+}

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

@@ -0,0 +1,43 @@
+import type { RuntimeContext } from '../../plugin-api/types';
+import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
+
+/**
+ * Mint a UCAN invocation token addressed to the composio-worker.
+ *
+ *   1. Resolves the composio-worker DID via `runCtx.ucan.resolveServiceDid`
+ *      (delegates the did:web lookup + cache to the UCAN service).
+ *   2. Mints an `ixo:sandbox` invocation using the user's signing key.
+ *
+ * Returns `null` when DID resolution fails, when minting throws, or when no
+ * signing material is available. Every failure is contained inside the shared
+ * UCAN helpers — nothing throws past this boundary. Callers degrade silently:
+ * the composio client is simply not constructed and the plugin contributes no
+ * tools. The "no delegation present" case logs at `debug`; a genuine
+ * resolve/mint failure logs at `warn`.
+ */
+export async function mintComposioInvocation(
+  runCtx: RuntimeContext,
+  composioBaseUrl: string,
+): Promise<string | null> {
+  const composioDid = await resolveServiceDidSafely(
+    runCtx,
+    composioBaseUrl,
+    'composio',
+  );
+  if (!composioDid) return null;
+
+  // skipCache: the composio-worker enforces single-use replay protection
+  // per invocation CID (see composio-worker `lib/validation.ts`
+  // `createInvocationStore`, KV-backed, 120s default TTL). A cached
+  // invocation would be replayed on the second request and rejected with
+  // `401 REPLAY: Invocation has already been used`. Mint fresh every call.
+  return mintInvocationSafely(
+    runCtx,
+    { did: composioDid, capability: 'ixo:sandbox' },
+    '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/*' },
+  );
+}

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

@@ -0,0 +1,214 @@
+import { z } from 'zod';
+import { OraclePlugin, type PluginEnv } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import {
+  createComposioTools,
+  type ComposioDefsCache,
+  type ComposioSessionFactory,
+} from './composio-tools';
+import { mintComposioInvocation } from './composio-ucan';
+
+const configSchema = z.object({
+  COMPOSIO_API_KEY: z.string().min(1, 'COMPOSIO_API_KEY must not be empty.'),
+  COMPOSIO_BASE_URL: z
+    .string()
+    .url('COMPOSIO_BASE_URL must be a valid HTTP(S) URL.')
+    .default('https://composio.ixo.earth'),
+});
+
+/**
+ * Sibling env vars the plugin reads but does not own. `NETWORK` is declared
+ * in the core base schema; the plugin forwards it as `x-ixo-network` when
+ * present so the composio-worker can route to the right IXO environment.
+ */
+const siblingEnvSchema = z.object({
+  NETWORK: z.string().optional(),
+});
+
+const manifest: PluginManifest = {
+  title: 'Composio',
+  summary:
+    'Hundreds of integrations in one plugin: web search, news, finance, academic research, Gmail, GitHub, Linear, Slack, Google Calendar, Notion, Jira, HubSpot, and much more — all invoked on behalf of the user through Composio. When in doubt, Composio likely has a tool for it.',
+  whenToUse: [
+    'Composio exposes only a few directly-callable meta-tools: `COMPOSIO_MANAGE_CONNECTIONS` (auth), `COMPOSIO_SEARCH_TOOLS` (discover), and `COMPOSIO_MULTI_EXECUTE_TOOL` (run). Specific app tools (e.g. `GMAIL_SEND_EMAIL`, `COMPOSIO_SEARCH_FINANCE`) are NOT directly callable — discover them first, then run them through `COMPOSIO_MULTI_EXECUTE_TOOL`.',
+    'Standard flow: (1) for any connected-app action call `COMPOSIO_MANAGE_CONNECTIONS` with the toolkit FIRST — if it returns a `redirect_url`, show it as a clickable markdown link and stop; (2) call `COMPOSIO_SEARCH_TOOLS`, describing the action in natural language, to find the exact tool slug(s); (3) if unsure of a tool’s parameters, call `COMPOSIO_GET_TOOL_SCHEMAS` with those slugs to fetch their exact input schema; (4) call `COMPOSIO_MULTI_EXECUTE_TOOL` to execute.',
+    'CRITICAL — `COMPOSIO_MULTI_EXECUTE_TOOL` args are EXACTLY `{ "tools": [{ "tool_slug": "<SLUG>", "arguments": { ... } }], "sync_response_to_workbench": false }` and nothing else — no `session`, `id`, or other top-level keys. NEVER pass a tool name as a top-level key (e.g. `{ "COMPOSIO_SEARCH_FINANCE": {...} }`); always wrap each call inside the `tools` array as `tool_slug` + `arguments`.',
+    'Web, news, finance, academic, and trend searches — and fetching the readable content of a URL — live in the `COMPOSIO_SEARCH_*` family. They need no connection: discover the one you want via `COMPOSIO_SEARCH_TOOLS`, then run it through `COMPOSIO_MULTI_EXECUTE_TOOL`.',
+    'Email, calendar, issue trackers, docs, CRMs (Gmail, Outlook, Google Calendar, GitHub, Linear, Jira, Notion, Slack, HubSpot, …): verify the connection, discover the tool, then execute.',
+    'No native skill covers the requested action — discover what Composio offers with `COMPOSIO_SEARCH_TOOLS` before giving up.',
+  ],
+  whenNotToUse: [
+    'A native skill or sub-agent already covers the action more precisely — prefer the skill.',
+    'Scraping a complex page that needs JavaScript rendering or main-content extraction — use the Firecrawl sub-agent instead.',
+    'IXO entity lookups — use the Domain Indexer.',
+    'Normal conversation or general question with no search or external SaaS interaction.',
+    'NEVER write, guess, or fabricate any URL yourself — the only valid auth link is the `redirect_url` returned by `COMPOSIO_MANAGE_CONNECTIONS`. Typing a link from memory is forbidden.',
+  ],
+  examples: [
+    {
+      user: 'What is the current Bitcoin price?',
+      thought:
+        'A search task — no connection needed. Discover the right search tool first.',
+      tool: 'COMPOSIO_SEARCH_TOOLS',
+      args: {
+        query: 'search the web for live financial / crypto market prices',
+      },
+    },
+    {
+      user: '(after COMPOSIO_SEARCH_TOOLS surfaces COMPOSIO_SEARCH_FINANCE)',
+      thought:
+        'Run the discovered tool through the multi-execute meta-tool — wrapped in the tools array, never as a top-level key.',
+      tool: 'COMPOSIO_MULTI_EXECUTE_TOOL',
+      args: {
+        tools: [
+          {
+            tool_slug: 'COMPOSIO_SEARCH_FINANCE',
+            arguments: { query: 'Bitcoin price USD today' },
+          },
+        ],
+        sync_response_to_workbench: false,
+      },
+    },
+    {
+      user: 'Create a Linear issue for this bug',
+      thought:
+        'A SaaS action — verify Linear is connected before discovering or running any Linear tool.',
+      tool: 'COMPOSIO_MANAGE_CONNECTIONS',
+      args: { toolkit: 'linear' },
+    },
+    {
+      user: 'Send an email to the team',
+      thought:
+        'A SaaS action — verify Gmail is connected first, then discover GMAIL_SEND_EMAIL and run it via COMPOSIO_MULTI_EXECUTE_TOOL.',
+      tool: 'COMPOSIO_MANAGE_CONNECTIONS',
+      args: { toolkit: 'gmail' },
+    },
+  ],
+  tags: [
+    'composio',
+    'integration',
+    'saas',
+    'tools',
+    'web-search',
+    'news',
+    'finance',
+  ],
+  category: 'integration',
+  visibility: 'on-demand',
+  stability: 'stable',
+};
+
+export interface ComposioPluginOptions {
+  /**
+   * Override the session factory — primarily for tests so they can skip the
+   * real `@composio/core` client and the network call it makes.
+   */
+  sessionFactory?: ComposioSessionFactory;
+  /**
+   * Override the UCAN minting step — primarily for tests so they can return
+   * a fixed token without invoking the real UCAN service.
+   */
+  mintInvocation?: (
+    runCtx: RuntimeContext,
+    baseUrl: string,
+  ) => Promise<string | null>;
+}
+
+/**
+ * Composio plugin.
+ *
+ * Tools are discovered dynamically per request: the plugin mints a UCAN
+ * invocation addressed to the composio-worker, opens a session for the
+ * current user, and exposes each returned tool to the agent.
+ *
+ * Auth is UCAN-only — no Matrix-OpenID fallback. If minting fails (no
+ * signing key, no cached delegation, did:web unresolved) the plugin
+ * contributes zero tools and the agent simply does not see composio that
+ * request. Visibility is `on-demand` so the plugin is discoverable via
+ * `list_capabilities` rather than burning prompt budget every call.
+ */
+export class ComposioPlugin extends OraclePlugin {
+  readonly name = 'composio';
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  override readonly configSchema = configSchema;
+
+  override readonly autoDetectHint = 'COMPOSIO_API_KEY';
+
+  private readonly sessionFactoryOverride?: ComposioSessionFactory;
+  private readonly mintInvocationOverride?: (
+    runCtx: RuntimeContext,
+    baseUrl: string,
+  ) => Promise<string | null>;
+
+  /**
+   * Per-user session tool definitions. Warm entries let `createComposioTools`
+   * skip the session-open + tools-list round-trips on the chat hot path and
+   * open the session lazily on first invocation instead.
+   */
+  private readonly toolDefsCache: ComposioDefsCache = new Map();
+
+  constructor(opts: ComposioPluginOptions = {}) {
+    super();
+    this.sessionFactoryOverride = opts.sessionFactory;
+    this.mintInvocationOverride = opts.mintInvocation;
+  }
+
+  override autoDetect(env: PluginEnv): boolean {
+    return (
+      typeof env.COMPOSIO_API_KEY === 'string' &&
+      env.COMPOSIO_API_KEY.length > 0
+    );
+  }
+
+  override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
+    const parsed = configSchema.safeParse(rtCtx.config);
+    if (!parsed.success) {
+      rtCtx.logger.warn(
+        `[composio] skipping — invalid configuration: ${parsed.error.issues
+          .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+          .join('; ')}`,
+      );
+      return [];
+    }
+
+    const siblings = siblingEnvSchema.safeParse(rtCtx.config);
+    const network = siblings.success ? siblings.data.NETWORK : undefined;
+
+    const mint = this.mintInvocationOverride ?? mintComposioInvocation;
+    const ucanInvocation = await mint(rtCtx, parsed.data.COMPOSIO_BASE_URL);
+    if (!ucanInvocation) {
+      rtCtx.logger.warn(
+        '[composio] skipping — UCAN invocation could not be minted.',
+      );
+      return [];
+    }
+
+    try {
+      return await createComposioTools({
+        apiKey: parsed.data.COMPOSIO_API_KEY,
+        baseUrl: parsed.data.COMPOSIO_BASE_URL,
+        ucanInvocation,
+        userId: rtCtx.user.did,
+        network,
+        sessionFactory: this.sessionFactoryOverride,
+        defsCache: this.toolDefsCache,
+        logger: rtCtx.logger,
+      });
+    } catch (error) {
+      const detail =
+        error instanceof Error
+          ? `${error.name}: ${error.message}`
+          : String(error);
+      rtCtx.logger.error(`[composio] failed to load tools: ${detail}`);
+      return [];
+    }
+  }
+}

package/src/plugins/composio/index.ts

@@ -0,0 +1,15 @@
+export {
+  COMPOSIO_DEFS_CACHE_MAX_ENTRIES,
+  COMPOSIO_TOOL_DEFS_TTL_MS,
+  createComposioTools,
+  createDefaultComposioSessionFactory,
+  type CachedComposioDefs,
+  type ComposioDefsCache,
+  type ComposioSessionFactory,
+  type ComposioSessionFactoryArgs,
+  type ComposioSessionTool,
+  type ComposioToolDef,
+  type CreateComposioToolsOptions,
+} from './composio-tools';
+export { mintComposioInvocation } from './composio-ucan';
+export { ComposioPlugin, type ComposioPluginOptions } from './composio.plugin';

package/src/plugins/domain-indexer/domain-indexer-agent.ts

@@ -0,0 +1,57 @@
+import type { PluginSubAgent, PluginTool } from '../../plugin-api/types';
+
+const formatToolDocs = (tools: PluginTool[]): string =>
+  tools
+    .map((t) => {
+      const description = t.description?.trim() ?? 'No description provided.';
+      return `- \`${t.name}\`: ${description}`;
+    })
+    .join('\n');
+
+const buildSystemPrompt = (tools: PluginTool[]): string =>
+  `
+You are the Domain Indexer Agent. You are the specialist for searching the IXO Domain Indexer—treat it like Google for IXO entities (organizations, projects, DAOs, agents, compositions, events).
+
+Core expectations:
+- Always clarify the user’s goal and translate it into a concrete search query or DID lookup.
+- Never call tools with empty parameters; \`domain_indexer_search\` always needs a query, \`get_domain_card\` always needs a DID.
+- Explain what you are searching for, summarize the results, and cite relevant DIDs or entity names.
+- When multiple results appear, compare them briefly and suggest next steps.
+
+Task discipline:
+- You are a sub-agent invoked by the main agent. You receive a single task message — that is ALL the context you have.
+- If the task is unclear, ambiguous, or missing critical details (IDs, names, scope, what to do), do NOT guess. Instead, STOP immediately and return a clear message explaining what information you need. The main agent will ask the user and re-invoke you with a complete task.
+- Never loop or retry the same failing approach. If something fails twice, return the error and stop.
+- Complete the requested task and STOP. Do not do additional unrequested work.
+
+### Available Domain Indexer Tools
+${formatToolDocs(tools)}
+
+Workflow:
+1. Decide if you need search (find relevant entities) or a card lookup (get summary/overview/FAQ for a known DID).
+2. Provide detailed, structured tool inputs (query text, limits, filters, or DID).
+3. Parse the response—highlight summary, overview, FAQ, URLs, and keywords.
+4. Surface gaps or follow-ups — if more context is needed (from memory, portal, etc.), say so and the main agent will use the appropriate tools.
+`.trim();
+
+const buildDescription = (tools: PluginTool[]): string => {
+  const names = tools.map((t) => t.name).join(', ');
+  return `Domain Indexer specialist using (${names}) to discover IXO entities, summaries, overviews, and FAQs.`;
+};
+
+/**
+ * Build the Domain Indexer sub-agent definition. Tools are supplied by the
+ * plugin and closed over `DOMAIN_INDEXER_URL` from the merged config.
+ */
+export function createDomainIndexerSubAgent(
+  tools: PluginTool[],
+): PluginSubAgent {
+  return {
+    name: 'Domain Indexer Agent',
+    description: buildDescription(tools),
+    systemPrompt: buildSystemPrompt(tools),
+    tools,
+    model: 'subagent',
+    middlewares: [],
+  };
+}