@ixo/oracle-runtime 0.0.1

package/dist/graph/prompt-composer.js

@@ -0,0 +1,315 @@
+import { PromptTemplate } from '@langchain/core/prompts';
+/**
+ * The Slack constraints text. Identical to apps/app — kept here so the
+ * runtime owns its own copy and the prompt composer is self-contained.
+ */
+export const SLACK_FORMATTING_CONSTRAINTS_CONTENT = `## Slack Formatting
+
+Slack doesn't render markdown tables. When responding in a Slack session:
+- Use bullet lists with bold labels ("• **Name:** value") instead of tables
+- Use numbered lists for sequential data
+- When delegating to sub-agents, ask them for list-based formatting (no tables)
+
+`;
+/** Headers used for each populated memory-context sub-section. */
+const CONTEXT_SECTION_LABELS = {
+    identity: 'Personal identity',
+    work: 'Work & professional',
+    goals: 'Goals & aspirations',
+    interests: 'Interests & expertise',
+    relationships: 'Relationships & social',
+    recent: 'Recent activity',
+};
+/**
+ * Format a single memory-engine context section as mid-density rich content.
+ *
+ * Goal: enough high-level signal that the agent can converse without re-querying,
+ * but compact enough that six categorical sections don't blow up the prompt.
+ * The agent can always deep-dive via the search_memory_engine tool.
+ *
+ * Layout per section (in priority order):
+ *   1. **Key entities** with summaries — entity.summary contains the richest
+ *      multi-fact synthesis graphiti produces (e.g. "user had a 1:1 with Carlos
+ *      at 2pm today; user agreed to do the database migration in three phases").
+ *   2. **Facts** — short relationship-level bullets for breadth.
+ *   3. **Recent episodes** — raw source text, only when `includeEpisodes` is on.
+ *
+ * Returns `null` when the slot has no usable content — composer drops the
+ * sub-section entirely rather than emitting an empty header.
+ */
+/**
+ * Render a single SearchEnhancedResponse slot. Dumps everything the memory
+ * engine returned — entities (with their multi-fact summaries), facts,
+ * episodes (raw source text), and communities (topic clusters). The server
+ * already caps result counts via per-query max_* settings, so no further
+ * truncation is needed here.
+ *
+ * Returns `null` for an empty/missing slot so the composer can skip the
+ * sub-section entirely instead of printing a bare header.
+ */
+function formatContextSection(data) {
+    if (!data)
+        return null;
+    const { entities, facts, episodes, communities } = data;
+    if (!entities?.length &&
+        !facts?.length &&
+        !episodes?.length &&
+        !communities?.length) {
+        return null;
+    }
+    const lines = [];
+    if (entities?.length) {
+        lines.push('_Key entities:_');
+        for (const e of entities) {
+            const labels = e.labels.filter((l) => l !== 'Entity').join('/');
+            const tag = labels ? ` (${labels})` : '';
+            const summary = e.summary?.trim();
+            lines.push(summary ? `- **${e.name}**${tag}: ${summary}` : `- **${e.name}**${tag}`);
+        }
+    }
+    if (facts?.length) {
+        if (lines.length)
+            lines.push('');
+        lines.push('_Facts:_');
+        for (const f of facts) {
+            const text = f.fact?.trim();
+            if (text)
+                lines.push(`- ${text}`);
+        }
+    }
+    if (episodes?.length) {
+        if (lines.length)
+            lines.push('');
+        lines.push('_Episodes (raw):_');
+        for (const ep of episodes) {
+            const content = ep.content?.trim();
+            if (!content)
+                continue;
+            const date = ep.created_at?.slice(0, 10) ?? '';
+            lines.push(date ? `- *${date}* — ${content}` : `- ${content}`);
+        }
+    }
+    if (communities?.length) {
+        if (lines.length)
+            lines.push('');
+        lines.push('_Topic clusters:_');
+        for (const c of communities) {
+            const summary = c.summary?.trim();
+            lines.push(summary ? `- **${c.name}**: ${summary}` : `- **${c.name}**`);
+        }
+    }
+    return lines.length ? lines.join('\n') : null;
+}
+/**
+ * Render the memory-context block — empty string when nothing is populated.
+ *
+ * The runtime always feeds in the strongly-typed UserContextData shape from
+ * @ixo/common (see memory-engine.service.ts gatherUserContext), but the
+ * plugin-api surface keeps it as `Record<string, unknown>` to avoid forcing
+ * plugins to depend on the common package. Cast once at this boundary.
+ */
+function buildContextBlock(userContext) {
+    if (!userContext)
+        return '';
+    const typed = userContext;
+    const sections = [];
+    for (const key of Object.keys(CONTEXT_SECTION_LABELS)) {
+        const formatted = formatContextSection(typed[key]);
+        if (formatted) {
+            sections.push(`**${CONTEXT_SECTION_LABELS[key]}**\n${formatted}`);
+        }
+    }
+    return sections.join('\n\n');
+}
+/** Render user preferences as a bullet list for the prompt. */
+export function formatUserPreferences(prefs) {
+    if (!prefs)
+        return '';
+    const lines = [];
+    if (prefs.agentName)
+        lines.push(`- **Preferred agent name:** ${prefs.agentName}`);
+    if (prefs.language)
+        lines.push(`- **Preferred language:** ${prefs.language}`);
+    if (prefs.tone)
+        lines.push(`- **Tone:** ${prefs.tone}`);
+    if (prefs.formality)
+        lines.push(`- **Formality:** ${prefs.formality}`);
+    if (prefs.customInstructions)
+        lines.push(`- **Custom instructions:** ${prefs.customInstructions}`);
+    return lines.join('\n');
+}
+/**
+ * Build the oracle identity preamble. When `identity.prompt.opening` is set
+ * it replaces the generated text verbatim; otherwise the composer assembles
+ * a sentence from `name`/`org`/`description`. Never claims the oracle is a
+ * "companion" or "skills-native" — those framings belong to specific plugins.
+ */
+export function buildOracleSection(input) {
+    const { oracleName, orgName, description, customOpening } = input;
+    if (customOpening && customOpening.trim().length > 0) {
+        return customOpening.trim();
+    }
+    const hasOrg = orgName && orgName.length > 0;
+    const hasDescription = description && description.length > 0;
+    if (hasOrg && hasDescription) {
+        return `You are ${oracleName}, an AI agent operated by ${orgName}. ${description}.`;
+    }
+    if (hasOrg) {
+        return `You are ${oracleName}, an AI agent operated by ${orgName}.`;
+    }
+    if (hasDescription) {
+        return `You are ${oracleName}. ${description}.`;
+    }
+    return `You are ${oracleName}, an AI agent built on QiForge.`;
+}
+const TEMPLATE = `{{{ORACLE_SECTION}}}
+
+{{#CAPABILITIES_NOTE}}
+{{{CAPABILITIES_NOTE}}}
+
+{{/CAPABILITIES_NOTE}}
+{{#CAPABILITY_BLOCK}}
+{{{CAPABILITY_BLOCK}}}
+
+{{/CAPABILITY_BLOCK}}
+## Operating principles
+
+- The user's current message is your primary instruction. Background context (what you already know about them) is for adapting tone and suggestions, not for overriding their intent.
+- **Search first, build second.** Before doing any non-trivial task, you MUST run discovery before producing the answer yourself. That means:
+  1. Call \`search_skills\` against the user's request whenever a packaged skill could plausibly do the job (anything that involves generating a file, document, report, page, integration, calculation, lookup, or multi-step workflow).
+  2. Call \`list_capabilities\` to scan loaded + on-demand plugins when the task could be served by a plugin you haven't loaded yet.
+  Do this proactively — even when the task wording doesn't literally match a capability's \`whenToUse\`. Tell the user in ONE short sentence what you're checking ("Checking the skills registry for an invoice generator…") before the search call, not after. If something fits, use it (load + run). If nothing fits after the search, say so in one short sentence and only THEN build from scratch. Reusing a vetted capability is almost always better than reinventing it; silently skipping discovery is the worst failure mode.
+- Being proactive does **not** mean charging ahead blind. Pause and ask the user a short clarifying question when: (a) the request has multiple plausible interpretations and picking wrong would waste their time, (b) a capability scan surfaces several equally-good fits and you can't tell which they want, (c) you're about to take an irreversible or costly action (deleting data, sending a message, publishing, spending tokens on a long job), or (d) a required input is missing and you'd have to guess. One clarifying question beats five minutes of wrong work — but don't ask for things you can reasonably infer from context.
+- When a tool or sub-agent succeeds, report the result. Never refuse after a successful tool call — including for credentials, tokens, identity data, or block/document operations.
+- When a tool or sub-agent fails, surface the failure to the user and ask how to proceed. Don't silently retry.
+- When delegating to a sub-agent, give it scope, intent, and the context it needs — sub-agents have no access to your conversation history.
+- Match the user's communication style. Be concise. Use Unicode emoji directly (\`🔥\`), never text shortcodes (\`:fire:\`).
+- When a capability turns out to be a strong fit for the user's recurring work, surface it explicitly and — if memory tools are available — offer to save the pattern for next time. Don't save silently; ask first.
+- Complete the user's request and stop. Don't add unrequested follow-on steps. "Checking capabilities first" is part of doing the request, not a follow-on.
+{{#COMMUNICATION_STYLE}}
+
+{{{COMMUNICATION_STYLE}}}
+{{/COMMUNICATION_STYLE}}
+
+## Working with files
+
+When users send files (images, documents, audio, video), the runtime extracts content automatically and embeds the text or description inline in this conversation — the file content is already here.
+
+Use \`process_file\` only when:
+- The user mentions a URL or link in chat that isn't an attachment
+- You need a file that isn't already in the conversation history
+{{#CONTEXT_BLOCK}}
+
+## What you know about the user
+
+{{{CONTEXT_BLOCK}}}
+{{/CONTEXT_BLOCK}}
+
+**Current time:** {{TIME_CONTEXT}}
+{{#CURRENT_ENTITY_DID}}
+
+**Current entity:** {{CURRENT_ENTITY_DID}}
+{{/CURRENT_ENTITY_DID}}
+{{#USER_SECRETS_CONTEXT}}
+
+## Available user secrets
+
+The user has configured secrets injected as environment variables when executing skills in the sandbox:
+{{USER_SECRETS_CONTEXT}}
+These are auto-injected — don't ask the user for them. If a skill needs a secret that's not listed, tell the user to add it in Settings → Agents.
+{{/USER_SECRETS_CONTEXT}}
+{{#USER_PREFERENCES_CONTEXT}}
+
+## User preferences
+
+{{{USER_PREFERENCES_CONTEXT}}}
+{{/USER_PREFERENCES_CONTEXT}}
+
+## Operational mode
+
+{{{OPERATIONAL_MODE}}}
+{{#COMPOSIO_CONTEXT}}
+
+{{{COMPOSIO_CONTEXT}}}
+{{/COMPOSIO_CONTEXT}}
+{{#EDITOR_SECTION}}
+
+{{{EDITOR_SECTION}}}
+{{/EDITOR_SECTION}}
+{{#SLACK_FORMATTING_CONSTRAINTS}}
+
+{{{SLACK_FORMATTING_CONSTRAINTS}}}
+{{/SLACK_FORMATTING_CONSTRAINTS}}
+`;
+const PROMPT_TEMPLATE = new PromptTemplate({
+    template: TEMPLATE,
+    inputVariables: [
+        'ORACLE_SECTION',
+        'CAPABILITIES_NOTE',
+        'CAPABILITY_BLOCK',
+        'COMMUNICATION_STYLE',
+        'CONTEXT_BLOCK',
+        'TIME_CONTEXT',
+        'CURRENT_ENTITY_DID',
+        'OPERATIONAL_MODE',
+        'EDITOR_SECTION',
+        'SLACK_FORMATTING_CONSTRAINTS',
+        'USER_SECRETS_CONTEXT',
+        'COMPOSIO_CONTEXT',
+        'USER_PREFERENCES_CONTEXT',
+    ],
+    templateFormat: 'mustache',
+});
+/**
+ * Compose the runtime's system prompt. Slots split into:
+ *   - **identity** — from `OracleConfig` (custom opening or generated).
+ *   - **capabilities** — author note (config.prompt.capabilities) + Tier-1 block.
+ *   - **operating principles** — fixed + optional `communicationStyle` from config.
+ *   - **working with files** — runtime-universal (FileProcessingService).
+ *   - **context** — only populated memory sub-sections render; empty ones skipped.
+ *   - **operational mode / composio / editor / slack** — existing plugin hooks.
+ */
+export async function composePrompt(input) {
+    const oracleName = input.oracleNameOverride ?? input.identity.name;
+    const oracleSection = buildOracleSection({
+        oracleName,
+        orgName: input.identity.org,
+        description: input.identity.description,
+        customOpening: input.identity.prompt?.opening,
+    });
+    const capabilitiesNote = input.identity.prompt?.capabilities?.trim() ?? '';
+    const communicationStyle = input.identity.prompt?.communicationStyle?.trim() ?? '';
+    const rendered = await PROMPT_TEMPLATE.format({
+        ORACLE_SECTION: oracleSection,
+        CAPABILITIES_NOTE: capabilitiesNote,
+        CAPABILITY_BLOCK: input.capabilityBlock,
+        COMMUNICATION_STYLE: communicationStyle,
+        CONTEXT_BLOCK: buildContextBlock(input.userContext),
+        TIME_CONTEXT: input.timeContext,
+        CURRENT_ENTITY_DID: input.currentEntityDid,
+        OPERATIONAL_MODE: input.operationalMode,
+        EDITOR_SECTION: input.editorSection,
+        SLACK_FORMATTING_CONSTRAINTS: input.slackFormattingConstraints,
+        USER_SECRETS_CONTEXT: input.userSecretsContext,
+        COMPOSIO_CONTEXT: input.composioContext,
+        USER_PREFERENCES_CONTEXT: input.userPreferencesContext,
+    });
+    if (input.degradedServicesBlock && input.degradedServicesBlock.length > 0) {
+        return `${rendered}\n\n---\n\n## Degraded services\n\n${input.degradedServicesBlock}\n`;
+    }
+    return rendered;
+}
+/**
+ * Format a (timezone, currentTime) pair into a stable prompt block. Public so
+ * forks driving their own `composePrompt` calls can re-use it.
+ */
+export function formatTimeContext(timezone, currentTime) {
+    if (!timezone && !currentTime)
+        return 'Not available.';
+    const parts = [];
+    if (currentTime)
+        parts.push(currentTime);
+    if (timezone)
+        parts.push(`(${timezone})`);
+    return parts.join(' ') || 'Not available.';
+}

package/dist/graph/state.d.ts

@@ -0,0 +1,65 @@
+import { type BaseMessage } from '@langchain/core/messages';
+import type { UserContextData } from '../plugin-api/types.js';
+/**
+ * Per-user preferences stored alongside the thread state. Mirrors the apps/app
+ * shape but is kept loose so plugins can extend the contract via declaration
+ * merging without touching this schema.
+ */
+export interface UserPreferences {
+    agentName?: string;
+    language?: string;
+    tone?: string;
+    formality?: string;
+    customInstructions?: string;
+    [key: string]: unknown;
+}
+/** Browser-side tool descriptor injected per request from the client. */
+export interface BrowserToolCall {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+}
+/** AG-UI action descriptor injected per request from the client. */
+export interface AgAction {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    hasRender?: boolean;
+}
+/**
+ * Master annotation state for the runtime's main agent. Mirrors the inlined
+ * state schema previously living in apps/app — the runtime is the single
+ * source of truth now.
+ *
+ * Plugin-owned state (e.g. `editorRoomId`, `spaceId`) stays in this schema
+ * for now to preserve behaviour parity. Plugins read it through their own
+ * middlewares; the runtime never branches on these fields directly.
+ */
+export declare const MainAgentGraphState: import("@langchain/langgraph").AnnotationRoot<{
+    config: import("@langchain/langgraph").BaseChannel<{
+        wsId?: string;
+        did: string;
+    }, {
+        wsId?: string;
+        did: string;
+    } | import("@langchain/langgraph").OverwriteValue<{
+        wsId?: string;
+        did: string;
+    }>, unknown>;
+    client: import("@langchain/langgraph").BaseChannel<"portal" | "matrix" | "slack", "portal" | "matrix" | "slack" | import("@langchain/langgraph").OverwriteValue<"portal" | "matrix" | "slack">, unknown>;
+    messages: import("@langchain/langgraph").BaseChannel<BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[], BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[] | import("@langchain/langgraph").OverwriteValue<BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[]>, unknown>;
+    editorRoomId: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    spaceId: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    currentEntityDid: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+    browserTools: import("@langchain/langgraph").BaseChannel<BrowserToolCall[] | undefined, BrowserToolCall[] | import("@langchain/langgraph").OverwriteValue<BrowserToolCall[] | undefined> | undefined, unknown>;
+    agActions: import("@langchain/langgraph").BaseChannel<AgAction[] | undefined, AgAction[] | import("@langchain/langgraph").OverwriteValue<AgAction[] | undefined> | undefined, unknown>;
+    userContext: import("@langchain/langgraph").BaseChannel<UserContextData, UserContextData | import("@langchain/langgraph").OverwriteValue<UserContextData>, unknown>;
+    userPreferences: import("@langchain/langgraph").BaseChannel<UserPreferences | undefined, UserPreferences | import("@langchain/langgraph").OverwriteValue<UserPreferences | undefined> | undefined, unknown>;
+    /**
+     * Names of plugins the agent has loaded for this thread via
+     * `load_capability`. Set-union reducer: plugins are added, never removed.
+     */
+    loadedPlugins: import("@langchain/langgraph").BaseChannel<string[], string[] | import("@langchain/langgraph").OverwriteValue<string[]>, unknown>;
+}>;
+export type TMainAgentGraphState = typeof MainAgentGraphState.State;
+//# sourceMappingURL=state.d.ts.map

package/dist/graph/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/graph/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,oEAAoE;AACpE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;eAErB,MAAM;aACR,MAAM;;eADJ,MAAM;aACR,MAAM;;eADJ,MAAM;aACR,MAAM;;;;;;;;;;;IAmDb;;;OAGG;;EAMH,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,OAAO,mBAAmB,CAAC,KAAK,CAAC"}

package/dist/graph/state.js

@@ -0,0 +1,60 @@
+import { Annotation, messagesStateReducer } from '@langchain/langgraph';
+/**
+ * Master annotation state for the runtime's main agent. Mirrors the inlined
+ * state schema previously living in apps/app — the runtime is the single
+ * source of truth now.
+ *
+ * Plugin-owned state (e.g. `editorRoomId`, `spaceId`) stays in this schema
+ * for now to preserve behaviour parity. Plugins read it through their own
+ * middlewares; the runtime never branches on these fields directly.
+ */
+export const MainAgentGraphState = Annotation.Root({
+    config: Annotation({
+        default: () => ({ did: '', wsId: '' }),
+        reducer: (prev, curr) => ({ ...prev, ...curr }),
+    }),
+    client: Annotation({
+        default: () => 'portal',
+        reducer: (_, curr) => curr,
+    }),
+    messages: Annotation({
+        reducer: messagesStateReducer,
+        default: () => [],
+    }),
+    editorRoomId: Annotation({
+        default: () => undefined,
+        reducer: (_, curr) => curr,
+    }),
+    spaceId: Annotation({
+        default: () => undefined,
+        reducer: (_, curr) => curr,
+    }),
+    currentEntityDid: Annotation({
+        default: () => undefined,
+        reducer: (_, curr) => curr,
+    }),
+    browserTools: Annotation({
+        default: () => [],
+        reducer: (_, curr) => curr,
+    }),
+    agActions: Annotation({
+        default: () => [],
+        reducer: (_, curr) => curr,
+    }),
+    userContext: Annotation({
+        default: () => ({}),
+        reducer: (prev, curr) => ({ ...prev, ...curr }),
+    }),
+    userPreferences: Annotation({
+        default: () => undefined,
+        reducer: (_, curr) => curr,
+    }),
+    /**
+     * Names of plugins the agent has loaded for this thread via
+     * `load_capability`. Set-union reducer: plugins are added, never removed.
+     */
+    loadedPlugins: Annotation({
+        reducer: (current, update) => Array.from(new Set([...(current ?? []), ...(update ?? [])])),
+        default: () => [],
+    }),
+});

package/dist/graph/sub-agent-fallback.d.ts

@@ -0,0 +1,56 @@
+import type { StructuredTool } from 'langchain';
+import type { PluginContext, PluginSubAgent, RuntimeContext } from '../plugin-api/types.js';
+import type { RegisteredSubAgent, SubAgentRegistry } from '../registries/subagent-registry.js';
+import type { AmbientServices } from '../runtime-context/ambient.js';
+import type { RuntimeStateInput } from '../runtime-context/build-runtime.js';
+import { type AgentSpec } from './subagent-as-tool.js';
+/** Inputs for collecting and wrapping sub-agents. */
+export interface CollectSubAgentsInput {
+    registry: SubAgentRegistry;
+    buildCtx: PluginContext;
+    ambient: AmbientServices;
+    /** Snapshot of state used when handlers need to build a `RuntimeContext`. */
+    state: RuntimeStateInput;
+    /** User DID — used for thread-scoped checkpointing. */
+    userDid: string;
+    /** Session ID — used for thread/run scoping. */
+    sessionId: string;
+    /**
+     * Optional per-request runtime context. Plumbed through to
+     * `SubAgentRegistry.collect` so plugins implementing `getRequestSubAgents`
+     * can branch on live state (e.g. AG-UI actions).
+     */
+    rtCtx?: RuntimeContext;
+    /**
+     * Optional adaptor turning a `PluginSubAgent` into the `AgentSpec` shape
+     * understood by `createSubagentAsTool`. Default wraps each `PluginTool`
+     * via `wrapPluginTool` so its handler receives a real `RuntimeContext`,
+     * and resolves the sub-agent's `model` role via `ambient.llm.get(...)`.
+     */
+    toAgentSpec?: (subAgent: PluginSubAgent, buildCtx: PluginContext, ambient: AmbientServices, state: RuntimeStateInput) => AgentSpec;
+    /**
+     * Tools the runtime wants every sub-agent to be able to call (e.g. the
+     * non-destructive memory CRUD tools the memory plugin contributes to the
+     * main agent). Appended to each sub-agent's own tool list when the inner
+     * `createAgent` is built — the sub-agent's tools take precedence in name
+     * collisions.
+     */
+    passthroughTools?: StructuredTool[];
+    /**
+     * Optional pre-collected sub-agent list. When provided, the registry is not
+     * queried — callers that need to filter the entries (e.g. by visibility +
+     * `loadedPlugins`) collect from the registry themselves, apply the filter,
+     * and pass the result here.
+     */
+    subAgents?: RegisteredSubAgent[];
+}
+/**
+ * Collect sub-agents from the registry and wrap each as a LangChain tool
+ * using `createSubagentAsTool`. A failure inside any one sub-agent's
+ * conversion logs via `ambient.logger` and is dropped from the list — the
+ * graph still builds with the others, matching apps/app's `Promise.allSettled`
+ * pattern.
+ */
+export declare function collectSubAgentsWithFallback(input: CollectSubAgentsInput): Promise<StructuredTool[]>;
+export type { RuntimeContext };
+//# sourceMappingURL=sub-agent-fallback.d.ts.map

package/dist/graph/sub-agent-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent-fallback.d.ts","sourceRoot":"","sources":["../../src/graph/sub-agent-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EAEd,cAAc,EACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAG7E,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,eAAe,CAAC;IACzB,6EAA6E;IAC7E,KAAK,EAAE,iBAAiB,CAAC;IACzB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CACZ,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,iBAAiB,KACrB,SAAS,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;IACpC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAiED;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,cAAc,EAAE,CAAC,CAmD3B;AAGD,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/graph/sub-agent-fallback.js

@@ -0,0 +1,79 @@
+import { createSubagentAsTool } from './subagent-as-tool.js';
+import { wrapPluginTool } from './wrap-plugin-tool.js';
+/**
+ * Default adaptor — turns a `PluginSubAgent` into the `AgentSpec` shape
+ * required by `createSubagentAsTool`.
+ *
+ * Plugin sub-agent tools are `PluginTool[]` with `(args, ctx)` handlers; the
+ * sub-agent runs them inside its own `createAgent` call where LangChain
+ * supplies a `ToolRuntime`, not a `RuntimeContext`. Each tool is wrapped via
+ * `wrapPluginTool` so its handler observes a fully-built `RuntimeContext`
+ * (same bridge the main agent uses).
+ *
+ * The sub-agent's `model` role (default `'subagent'`) is resolved via the
+ * ambient LLM adapter and propagated to `AgentSpec.model` so the wrapping
+ * `createSubagentAsTool` can actually run a `createAgent` instead of
+ * returning the "no model configured" error path.
+ */
+function defaultToAgentSpec(subAgent, buildCtx, ambient, state, userDid, sessionId) {
+    const systemPrompt = typeof subAgent.systemPrompt === 'function'
+        ? subAgent.systemPrompt(buildCtx)
+        : subAgent.systemPrompt;
+    const pluginTools = Array.isArray(subAgent.tools)
+        ? subAgent.tools
+        : subAgent.tools(buildCtx);
+    const tools = pluginTools.map((t) => wrapPluginTool(t, { ambient, state }));
+    const model = ambient.llm.get(subAgent.model ?? 'subagent');
+    // Normalize `forwardTools`:
+    //   true       → all of this sub-agent's own tool names
+    //   string[]   → as-is
+    //   false/undef → undefined (nothing forwarded)
+    // Passthrough tools are NOT included — they're already on the main agent.
+    let forwardTools;
+    if (subAgent.forwardTools === true) {
+        forwardTools = pluginTools.map((t) => t.name);
+    }
+    else if (Array.isArray(subAgent.forwardTools)) {
+        forwardTools = subAgent.forwardTools;
+    }
+    return {
+        name: subAgent.name,
+        description: subAgent.description,
+        systemPrompt,
+        tools,
+        model,
+        middleware: subAgent.middlewares,
+        userDid,
+        sessionId,
+        ...(forwardTools ? { forwardTools } : {}),
+    };
+}
+/**
+ * Collect sub-agents from the registry and wrap each as a LangChain tool
+ * using `createSubagentAsTool`. A failure inside any one sub-agent's
+ * conversion logs via `ambient.logger` and is dropped from the list — the
+ * graph still builds with the others, matching apps/app's `Promise.allSettled`
+ * pattern.
+ */
+export async function collectSubAgentsWithFallback(input) {
+    const { registry, buildCtx, ambient, state, userDid, sessionId, rtCtx, toAgentSpec, passthroughTools, subAgents, } = input;
+    const entries = subAgents ?? (await registry.collect(buildCtx, rtCtx));
+    const results = await Promise.allSettled(entries.map(async ({ pluginName, subAgent }) => {
+        try {
+            const spec = toAgentSpec
+                ? toAgentSpec(subAgent, buildCtx, ambient, state)
+                : defaultToAgentSpec(subAgent, buildCtx, ambient, state, userDid, sessionId);
+            const withPassthrough = passthroughTools?.length
+                ? { ...spec, passthroughTools }
+                : spec;
+            return createSubagentAsTool(withPassthrough, withPassthrough.forwardTools
+                ? { forwardTools: withPassthrough.forwardTools }
+                : undefined);
+        }
+        catch (err) {
+            ambient.logger.error({ pluginName, err: err instanceof Error ? err.message : String(err) }, 'sub-agent init failed; skipping');
+            return null;
+        }
+    }));
+    return results.flatMap((r) => r.status === 'fulfilled' && r.value ? [r.value] : []);
+}

package/dist/graph/subagent-as-tool.d.ts

@@ -0,0 +1,77 @@
+import type { BaseCheckpointSaver } from '@langchain/langgraph';
+import { type BaseMessage } from '@langchain/core/messages';
+import { createAgent, type AgentMiddleware, type StructuredTool } from 'langchain';
+import type { Logger } from '../plugin-api/types.js';
+/**
+ * Spec for an agent that runs as a one-shot sub-agent (called by a parent
+ * agent through `createSubagentAsTool`).
+ *
+ * `tools` is optional so plugin-defined sub-agents that contribute only
+ * routing logic (no tools) can still be wrapped.
+ *
+ * `passthroughTools` are runtime-injected tools (e.g. memory CRUD) that
+ * every sub-agent should be able to call regardless of which plugin owns the
+ * sub-agent. They are concatenated after `tools` when building the inner
+ * agent so the sub-agent's own tools take precedence in collisions.
+ */
+export interface AgentSpec {
+    name: string;
+    description: string;
+    tools?: StructuredTool[];
+    passthroughTools?: StructuredTool[];
+    systemPrompt: string;
+    model?: Parameters<typeof createAgent>[0]['model'];
+    middleware?: AgentMiddleware[];
+    userDid: string;
+    sessionId: string;
+    /** Appended to thread_id to scope the agent's conversation (e.g. a room ID). */
+    threadSuffix?: string;
+    /**
+     * Checkpointer (or a factory resolved per-invocation given the userDid).
+     * Sub-agents normally share the parent's per-user SQLite store; the runtime
+     * resolves it once and passes it through here so the runtime package stays
+     * decoupled from any specific storage service.
+     */
+    checkpointer?: BaseCheckpointSaver | ((userDid: string) => Promise<BaseCheckpointSaver>);
+    /** Optional logger; defaults to a no-op. */
+    logger?: Logger;
+    /**
+     * Tool names whose AIMessage(tool_calls) + ToolMessage results should be
+     * forwarded into the parent graph's messages via Command. Surfaced on the
+     * spec so adaptors (e.g. plugin → spec conversion) can resolve a plugin's
+     * declared `forwardTools` once and let the wrapper pick it up downstream.
+     */
+    forwardTools?: string[];
+}
+/**
+ * Options for createSubagentAsTool — controlled by the oracle, not the agent.
+ */
+export interface SubagentToolOptions {
+    /**
+     * Tool names whose AIMessage(tool_calls) + ToolMessage results should be
+     * forwarded into the parent graph's messages via Command.
+     * The SSE stream will pick them up as regular tool call events.
+     */
+    forwardTools?: string[];
+    /** Called after subagent completes with the full message history. Fire-and-forget. */
+    onComplete?: (messages: BaseMessage[], task: string) => void;
+}
+/**
+ * Wraps an AgentSpec as a LangChain tool. When the parent agent calls this
+ * tool with a task, an ephemeral agent runs (model + tools + systemPrompt)
+ * and the final reply text is returned.
+ *
+ * @param options.forwardTools — tool names whose calls should be pushed into
+ *   the parent graph's messages via Command (decided by the oracle).
+ */
+/**
+ * Compute the tool name the agent will see for a sub-agent given its
+ * authored name. Single source of truth — used by `createSubagentAsTool` to
+ * actually create the tool AND by the manifest validator to know what the
+ * agent will see. Keeping these in lockstep prevents silent drift.
+ *
+ * Example: `"Portal Agent"` → `"call_portal_agent"`.
+ */
+export declare function computeSubAgentToolName(subAgentName: string): string;
+export declare function createSubagentAsTool(spec: AgentSpec, options?: SubagentToolOptions): StructuredTool;
+//# sourceMappingURL=subagent-as-tool.d.ts.map

package/dist/graph/subagent-as-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-as-tool.d.ts","sourceRoot":"","sources":["../../src/graph/subagent-as-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,WAAW,CAAC;AAInB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQrD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,YAAY,CAAC,EACT,mBAAmB,GACnB,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACxD,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,sFAAsF;IACtF,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAsGD;;;;;;;GAOG;AACH;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC5B,cAAc,CA8HhB"}