@ixo/oracle-runtime-workers 0.2.0

package/src/core/main-agent-types.ts

@@ -0,0 +1,123 @@
+import type { AgentMiddleware } from 'langchain';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { BaseCheckpointSaver } from '@langchain/langgraph';
+import type { ReactAgent } from 'langchain';
+import { z } from 'zod';
+import type {
+  ChatOpenAIFields,
+  MergedConfig,
+  ModelRole,
+  OracleIdentity,
+} from '../plugin-api/types';
+import type { Registries } from './registries';
+import type { AmbientServices, RunConfigContext } from './runtime-context';
+import type { TMainAgentGraphState } from './state';
+
+/** The 6 internal registries the runtime composes. */
+export type MainAgentRegistries = Registries;
+
+export const mainAgentRequestContextSchema = z.object({
+  user: z.object({
+    did: z.string(),
+    matrixUserId: z.string(),
+    ucanDelegation: z.any(),
+    timezone: z.string().optional(),
+    currentTime: z.string().optional(),
+  }),
+  session: z.object({
+    id: z.string(),
+    client: z.enum(['portal', 'matrix', 'slack']),
+    requestId: z.string(),
+    wsId: z.string().optional(),
+    roomId: z.string().optional(),
+  }),
+  history: z
+    .object({
+      userContext: z.record(z.string(), z.unknown()).optional(),
+    })
+    .optional(),
+  /**
+   * Per-request model override, already validated against the catalog
+   * allow-list (`isAllowedModel`). Absent → the agent uses the default
+   * `main` model.
+   */
+  model: z.string().optional(),
+});
+
+/** Per-request shape — exposes only what the main-agent build needs. */
+export type MainAgentRequestContext = z.infer<
+  typeof mainAgentRequestContextSchema
+>;
+
+/**
+ * Optional hooks the consuming host provides to keep host-specific behaviour
+ * (model selection, prompt section snippets) out of the runtime.
+ */
+export interface MainAgentHooks {
+  /** Optional model resolver. Default: `ambient.llm.get`. */
+  resolveModel?: (
+    role: ModelRole,
+    params?: ChatOpenAIFields,
+  ) => ReturnType<AmbientServices['llm']['get']>;
+  /** Look up a human-readable page title for the page-context middleware. */
+  getRoomTitle?: (roomId: string) => Promise<string | undefined>;
+  /** Cheap classification model used by the safety-guardrail middleware. */
+  safetyModel?: BaseChatModel;
+  /** Tool names whose `ToolMessage` outputs should be stripped between turns. */
+  validationSkipToolNames?: string[];
+  /** Operational-mode block — overridden when a richer mode applies. */
+  operationalMode?: string;
+  /** Degraded-services notice appended to the system prompt body. */
+  degradedServicesBlock?: string;
+  /**
+   * Host middlewares appended after the always-on stack and the plugins'
+   * (e.g. the Matrix `work_status` card driver, which needs a per-object
+   * producer the core cannot construct).
+   */
+  middlewares?: AgentMiddleware[];
+}
+
+export interface MainAgentArgs {
+  registries: MainAgentRegistries;
+  identity: OracleIdentity;
+  config: MergedConfig;
+  requestCtx: MainAgentRequestContext;
+  ambient: AmbientServices;
+  state: Partial<TMainAgentGraphState>;
+  availablePlugins: ReadonlySet<string>;
+  /**
+   * Checkpointer for the user's thread state. On Workers the Durable Object
+   * owns it (SQLite over DO storage) and passes it in per turn; omit for a
+   * stateless build (tests).
+   */
+  checkpointer?: BaseCheckpointSaver;
+  /**
+   * The turn's abort signal. Forwarded to the request-time plugin hooks
+   * (`getRequestTools` / `getRequestSubAgents`) through their `RuntimeContext`
+   * so a cancelled turn also cancels the network calls those hooks make. The
+   * caller still passes the same signal to `agent.invoke` / `agent.stream`.
+   */
+  abortSignal?: AbortSignal;
+  /** Provider of a BYO turn (`runtime.context.byo`); absent on platform turns. */
+  byoProvider?: string;
+  hooks?: MainAgentHooks;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CompiledMainAgent = ReactAgent<any>;
+
+/** What `createMainAgent` resolves to. */
+export interface MainAgentBuildResult {
+  /** The compiled LangChain agent — call `invoke` / `stream` on it. */
+  agent: CompiledMainAgent;
+  /** The composed system prompt the agent was built with (diagnostics). */
+  systemPrompt: string;
+  /** Names of every tool bound to the agent, in binding order. */
+  boundToolNames: string[];
+  /**
+   * The request's `{ user, session }` channel. Tools already fall back to it,
+   * but pass it as `context` in the `invoke` / `stream` config so LangChain
+   * middlewares and sub-agents see the same channel the Node runtime provides.
+   */
+  context: RunConfigContext;
+}

package/src/core/main-agent.ts

@@ -0,0 +1,399 @@
+import {
+  createAgent,
+  toolRetryMiddleware,
+  type StructuredTool,
+} from 'langchain';
+import type {
+  PluginContext,
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+  SharedAccessors,
+} from '../plugin-api/types';
+import type { MainAgentArgs, MainAgentBuildResult } from './main-agent-types';
+import { renderTier1, type Tier1Entry } from './manifest';
+import { buildMetaTools } from './meta-tools';
+import {
+  createByoHistorySanitizerMiddleware,
+  createCapabilityGateMiddleware,
+  createPageContextMiddleware,
+  createSafetyGuardrailMiddleware,
+  createSummarizationMiddleware,
+  createToolRepetitionGuardMiddleware,
+  createToolValidationMiddleware,
+} from './middlewares';
+import {
+  composePrompt,
+  formatTimeContext,
+  formatUserPreferences,
+} from './prompt-composer';
+import { formatByPlugin, type ManifestRegistry } from './registries';
+import {
+  buildPluginContext,
+  buildRuntimeContext,
+  type RunConfig,
+  type RuntimeStateInput,
+} from './runtime-context';
+import { MainAgentGraphState } from './state';
+import { collectSubAgentsWithFallback } from './sub-agent-fallback';
+import { computeSubAgentToolName } from './subagent-as-tool';
+import { wrapPluginTool } from './wrap-plugin-tool';
+
+const PLUGIN_LOGGER_COMPONENT = 'main-agent';
+
+const DEFAULT_OPERATIONAL_MODE = [
+  '**General conversation mode**',
+  '',
+  'Default to conversation mode, using available capabilities for recall, search, and task delegation.',
+].join('\n');
+
+type CollectedTool = { pluginName: string; tool: PluginTool };
+
+/** Map plugin name → effective `manifest.visibility` (default `on-demand`). */
+function visibilityIndex(
+  manifests: ManifestRegistry,
+): Map<string, NonNullable<PluginManifest['visibility']>> {
+  const out = new Map<string, NonNullable<PluginManifest['visibility']>>();
+  for (const { pluginName, manifest } of manifests.collect()) {
+    out.set(pluginName, manifest.visibility ?? 'on-demand');
+  }
+  return out;
+}
+
+/**
+ * Filter collected tools by their effective visibility — per-tool override
+ * wins; otherwise the plugin's manifest visibility decides.
+ */
+function selectByVisibility(
+  tools: CollectedTool[],
+  manifestViz: Map<string, NonNullable<PluginManifest['visibility']>>,
+  visibility: NonNullable<PluginManifest['visibility']>,
+): CollectedTool[] {
+  return tools.filter(({ pluginName, tool }) => {
+    const effective =
+      tool.visibility ?? manifestViz.get(pluginName) ?? 'on-demand';
+    return effective === visibility;
+  });
+}
+
+/**
+ * Build a compiled main agent from the runtime's registries plus per-request
+ * context. Same pipeline as the Node runtime — tools from the registries
+ * (boot cache + request hooks, collected concurrently with per-plugin failure
+ * isolation), visibility partition, meta-tools, sub-agents as tools, the
+ * fixed middleware order, prompt composition — minus the branches that do not
+ * exist on Workers (the commerce lane, Slack, Matrix group chats, and the
+ * ChatGPT-subscription history sanitizer). The Matrix `work_status` card
+ * driver arrives as a host middleware (`hooks.middlewares`); page context and
+ * the safety guardrail install when the host supplies `hooks.getRoomTitle` /
+ * `hooks.safetyModel`, exactly as on Node.
+ */
+export async function createMainAgent(
+  args: MainAgentArgs,
+): Promise<MainAgentBuildResult> {
+  const {
+    registries,
+    identity,
+    config,
+    requestCtx,
+    ambient,
+    state,
+    availablePlugins,
+    checkpointer,
+    abortSignal,
+    byoProvider,
+    hooks,
+  } = args;
+
+  // ── 1. Plugin context (boot-time, no per-request fields) ────────────────
+  const buildCtx: PluginContext = buildPluginContext({
+    config,
+    identity,
+    availablePlugins,
+    logger: ambient.logger,
+    pluginName: PLUGIN_LOGGER_COMPONENT,
+  });
+
+  // ── 2. Request-time runtime context (drives getRequestTools/...SubAgents) ─
+  ambient.logger.debug?.(
+    `[MainAgent] state.loadedPlugins:`,
+    state.loadedPlugins,
+  );
+
+  const loadedSet = new Set<string>(state.loadedPlugins ?? []);
+  // Carry the prior request state (browserTools, agActions, …) into the
+  // per-request RuntimeContext and the tool-wrapper closures, but NOT the
+  // message history: keeping the full `messages` array here would pin the
+  // entire history inside every tool closure for the whole run, and it would
+  // be the WRONG history anyway — this snapshot is taken before the turn
+  // runs. Tools that must describe the conversation read
+  // `ctx.history.messages`, which `buildRuntimeContext` fills from
+  // LangGraph's live `ToolRuntime.state` at call time.
+  //
+  // Explicit fields come last so they win over the spread (notably
+  // `loadedPlugins`, which must be the de-duped Set, not the raw state array).
+  const wrapState: RuntimeStateInput = {
+    ...state,
+    messages: [],
+    userContext: state.userContext,
+    loadedPlugins: loadedSet,
+  };
+
+  // `ctx.shared` — read accessors other plugins registered via
+  // `getSharedState()`, evaluated lazily against the live context.
+  const sharedFactory = (ctx: RuntimeContext): SharedAccessors =>
+    registries.sharedState.build(ctx.history.state, ctx);
+
+  const runConfig: RunConfig = {
+    context: {
+      user: {
+        did: requestCtx.user.did,
+        matrixUserId: requestCtx.user.matrixUserId,
+        ucanDelegation: requestCtx.user.ucanDelegation,
+        timezone: requestCtx.user.timezone,
+        currentTime: requestCtx.user.currentTime,
+      },
+      session: {
+        id: requestCtx.session.id,
+        client: requestCtx.session.client,
+        requestId: requestCtx.session.requestId,
+        wsId: requestCtx.session.wsId,
+        roomId: requestCtx.session.roomId,
+      },
+      ...(byoProvider ? { byo: { provider: byoProvider, active: true } } : {}),
+    },
+    ...(abortSignal ? { signal: abortSignal } : {}),
+  };
+  const rtCtx = buildRuntimeContext(
+    runConfig,
+    ambient,
+    wrapState,
+    sharedFactory,
+  );
+
+  // ── 3. Resolve registries (boot-time + request-time contributions) ──────
+  // Tool and sub-agent collection are independent request-time fan-outs
+  // (each may open network connections); run them concurrently so the
+  // slower of the two — not their sum — gates the build.
+  const [allTools, subAgentEntries] = await Promise.all([
+    registries.tools.collect(buildCtx, rtCtx),
+    registries.subAgents.collect(buildCtx, rtCtx),
+  ]);
+
+  // The per-turn tool-surface line. Request tools are named in full (there
+  // are only a handful and they are the ones that vary turn to turn); the
+  // full bound list, boot tools included, stays at debug.
+  const requestTools = allTools.filter(({ origin }) => origin === 'request');
+  ambient.logger.log(
+    `[main-agent] tool surface: ${allTools.length} tools ` +
+      `(boot ${allTools.length - requestTools.length}, request ${requestTools.length}) ` +
+      `— request tools: ${formatByPlugin(requestTools) || '∅'}`,
+  );
+  ambient.logger.debug?.(
+    `[main-agent] full tool surface: ${formatByPlugin(allTools) || '∅'}`,
+  );
+  const manifestEntries = registries.manifests.collect();
+  const manifestViz = visibilityIndex(registries.manifests);
+  const titleByPlugin = new Map(
+    manifestEntries.map(({ pluginName, manifest }) => [
+      pluginName,
+      manifest.title,
+    ]),
+  );
+
+  const eagerTools = selectByVisibility(allTools, manifestViz, 'always');
+  // Bind ALL on-demand tools at compile time — gating happens per model call
+  // in `CapabilityGateMiddleware` based on the live `loadedPlugins` state.
+  // This lets `load_capability` take effect on the very next LLM call inside
+  // the same run, instead of waiting for the next request to rebuild.
+  const onDemandTools = selectByVisibility(allTools, manifestViz, 'on-demand');
+  const silentTools = selectByVisibility(allTools, manifestViz, 'silent');
+
+  // ── 4. Wrap tools (meta + plugin) so handlers receive a RuntimeContext ──
+  const metaTools = buildMetaTools({
+    manifestRegistry: registries.manifests,
+    toolRegistry: registries.tools,
+  });
+
+  const fallbackContext = runConfig.context;
+  const wrap = (entry: CollectedTool) =>
+    wrapPluginTool(entry.tool, {
+      ambient,
+      state: wrapState,
+      pluginTitle: titleByPlugin.get(entry.pluginName),
+      sharedFactory,
+      fallbackContext,
+    });
+
+  // ── 5. Sub-agents — bind all at compile time; gating happens at runtime ─
+  // Sub-agents share the tool namespace with plugin tools, so they go through
+  // the same `CapabilityGateMiddleware` filter as plugin tools.
+  const subAgentTools = await collectSubAgentsWithFallback({
+    registry: registries.subAgents,
+    buildCtx,
+    ambient,
+    state: wrapState,
+    userDid: requestCtx.user.did,
+    sessionId: requestCtx.session.id,
+    rtCtx,
+    sharedFactory,
+    fallbackContext,
+    subAgents: subAgentEntries,
+  });
+
+  ambient.logger.debug?.(
+    `[main-agent] binding summary (all bound; gated at runtime): ` +
+      `eager=${eagerTools.length} onDemand=${onDemandTools.length} silent=${silentTools.length} ` +
+      `subAgents=${subAgentEntries.length} loadedPlugins=[${Array.from(loadedSet).join(', ')}]`,
+  );
+
+  const tools: StructuredTool[] = [
+    ...metaTools.map((t) =>
+      wrapPluginTool(t, {
+        ambient,
+        state: wrapState,
+        sharedFactory,
+        fallbackContext,
+      }),
+    ),
+    ...eagerTools.map(wrap),
+    ...onDemandTools.map(wrap),
+    ...silentTools.map(wrap),
+    ...subAgentTools,
+  ];
+
+  // Lookups used by `CapabilityGateMiddleware` to gate on-demand plugins
+  // and sub-agents per model call. Meta-tools omitted from the map are
+  // pass-through.
+  const pluginByToolName = new Map<string, string>();
+  const visibilityByToolName = new Map<
+    string,
+    NonNullable<PluginManifest['visibility']>
+  >();
+  for (const { pluginName, tool } of allTools) {
+    pluginByToolName.set(tool.name, pluginName);
+    const effective =
+      tool.visibility ?? manifestViz.get(pluginName) ?? 'on-demand';
+    visibilityByToolName.set(tool.name, effective);
+  }
+  for (const { pluginName, subAgent } of subAgentEntries) {
+    const toolName = computeSubAgentToolName(subAgent.name);
+    pluginByToolName.set(toolName, pluginName);
+    visibilityByToolName.set(
+      toolName,
+      manifestViz.get(pluginName) ?? 'on-demand',
+    );
+  }
+
+  // ── 6. Middleware stack — always-on + plugin contributions ──────────────
+  const pluginMiddlewares = registries.middlewares
+    .collect(buildCtx)
+    .map(({ middleware }) => middleware);
+
+  // The summarization middleware needs the same resolver so a host's
+  // `hooks.resolveModel` override covers the summary model too.
+  const resolveModel = hooks?.resolveModel ?? ambient.llm.get.bind(ambient.llm);
+
+  const middleware = [
+    // Outermost, as on Node: rewrite cross-provider reasoning residue before
+    // the summarizer condenses (a well-formed) history.
+    createByoHistorySanitizerMiddleware({ logger: ambient.logger }),
+    // Condense long threads before everything tool-related.
+    // Without this, thread state — reloaded, re-serialized, and re-uploaded to
+    // the owner store on every turn — grows without bound.
+    createSummarizationMiddleware({ model: resolveModel('routing') }),
+    createCapabilityGateMiddleware({
+      pluginByToolName,
+      visibilityByToolName,
+      logger: ambient.logger,
+    }),
+    createToolValidationMiddleware({
+      skipToolNames: hooks?.validationSkipToolNames,
+      logger: ambient.logger,
+    }),
+    createToolRepetitionGuardMiddleware({ logger: ambient.logger }),
+    toolRetryMiddleware({ onFailure: (error) => error.message }),
+    // Same host-gated pair as the Node runtime: the page-context block needs a
+    // title lookup, the safety guardrail a classification model.
+    ...(hooks?.getRoomTitle
+      ? [
+          createPageContextMiddleware({
+            getRoomTitle: hooks.getRoomTitle,
+            logger: ambient.logger,
+          }),
+        ]
+      : []),
+    ...(hooks?.safetyModel
+      ? [
+          createSafetyGuardrailMiddleware({
+            safetyModel: hooks.safetyModel,
+            logger: ambient.logger,
+          }),
+        ]
+      : []),
+    ...pluginMiddlewares,
+    ...(hooks?.middlewares ?? []),
+  ];
+
+  // ── 7. Prompt composition ───────────────────────────────────────────────
+  const eagerEntries: Tier1Entry[] = manifestEntries.filter(
+    ({ manifest }) => manifest.visibility === 'always',
+  );
+  const tier1 = renderTier1({ manifests: eagerEntries });
+  for (const warning of tier1.warnings) ambient.logger.warn(warning);
+
+  const customInstructions = identity.prompt?.customInstructions?.trim() ?? '';
+
+  const systemPrompt = await composePrompt({
+    identity,
+    capabilityBlock: tier1.block,
+    customInstructions,
+    operationalMode: hooks?.operationalMode ?? DEFAULT_OPERATIONAL_MODE,
+    userPreferencesContext: formatUserPreferences(state.userPreferences),
+    userContext: state.userContext,
+    timeContext: formatTimeContext(
+      requestCtx.user.timezone,
+      requestCtx.user.currentTime,
+    ),
+    currentEntityDid: state.currentEntityDid ?? '',
+    oracleNameOverride: state.userPreferences?.agentName,
+    degradedServicesBlock: hooks?.degradedServicesBlock,
+  });
+
+  // ── 8. Model ────────────────────────────────────────────────────────────
+  // A per-request model (already allow-list-validated by the caller) wins
+  // over the role default; the adapter honours `params.model`.
+  const model = resolveModel(
+    'main',
+    requestCtx.model ? { model: requestCtx.model } : undefined,
+  );
+
+  // ── 9. Compile ──────────────────────────────────────────────────────────
+  const agent = createAgent({
+    model,
+    tools,
+    middleware,
+    stateSchema: MainAgentGraphState,
+    systemPrompt,
+    ...(checkpointer ? { checkpointer } : {}),
+    name: identity.name,
+  });
+
+  return {
+    agent,
+    systemPrompt,
+    boundToolNames: tools.map((t) => t.name),
+    context: runConfig.context,
+  };
+}
+
+export { MainAgentGraphState };
+export type {
+  CompiledMainAgent,
+  MainAgentArgs,
+  MainAgentBuildResult,
+  MainAgentHooks,
+  MainAgentRegistries,
+  MainAgentRequestContext,
+} from './main-agent-types';
+export type { TMainAgentGraphState } from './state';