@ixo/oracle-runtime 0.0.1

package/dist/plugin-api/types.d.ts

@@ -0,0 +1,378 @@
+import type { RequestMethod } from '@nestjs/common';
+import type { z } from 'zod';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+/**
+ * Route shape returned by `OraclePlugin.getAuthExcludedRoutes()`. Mirrors the
+ * NestJS `RouteInfo` accepted by `MiddlewareConsumer.exclude(...)` so the
+ * runtime can pass these straight through.
+ */
+export interface AuthExcludedRoute {
+    /** Path under the plugin's controller, e.g. `weather/now`. Leading slash optional. */
+    path: string;
+    /** HTTP method. Defaults to `RequestMethod.ALL` when omitted. */
+    method?: RequestMethod;
+}
+/** Merged Zod-validated env vars (core schema + every loaded plugin's `configSchema`). */
+export type MergedConfig = Record<string, unknown>;
+/** Plugin-scoped logger. */
+export interface Logger {
+    log(message: unknown, ...optional: unknown[]): void;
+    error(message: unknown, ...optional: unknown[]): void;
+    warn(message: unknown, ...optional: unknown[]): void;
+    debug?(message: unknown, ...optional: unknown[]): void;
+    verbose?(message: unknown, ...optional: unknown[]): void;
+    /**
+     * Returns a new logger that auto-prefixes records with the given context.
+     * Optional — when absent, the same logger is returned unchanged.
+     */
+    child?(bindings: Record<string, unknown>): Logger;
+}
+/** LLM role tag used by `ctx.llm.get(role)`. Aligned with current `ModelRole`. */
+export type ModelRole = 'main' | 'subagent' | 'utility' | (string & {});
+/** Optional fields forwarded to ChatOpenAI when materialising an LLM. */
+export type ChatOpenAIFields = Record<string, unknown>;
+/** UCAN delegation envelope. */
+export interface UcanDelegation {
+    readonly raw: string;
+    readonly issuer?: string;
+    readonly audience?: string;
+    readonly capabilities?: ReadonlyArray<{
+        resource: string;
+        action: string;
+    }>;
+}
+/** Per-room secret index. */
+export type SecretIndex = Record<string, {
+    readonly key: string;
+    readonly version?: number;
+}>;
+/** Snapshot of a Matrix room's state events. */
+export interface RoomStateSnapshot {
+    readonly roomId: string;
+    readonly state: ReadonlyArray<unknown>;
+}
+/** A single Matrix room event. */
+export interface MatrixEvent {
+    readonly eventId: string;
+    readonly type: string;
+    readonly content: unknown;
+    readonly senderId?: string;
+    readonly originServerTs?: number;
+}
+/** Memory-enriched user context (mirrors `state.userContext`). */
+export type UserContextData = Record<string, unknown>;
+/** Read-only view over the LangGraph annotation state. */
+export interface ReadonlyState {
+    readonly messages: readonly BaseMessage[];
+    readonly userContext?: UserContextData;
+    readonly loadedPlugins?: ReadonlySet<string>;
+    readonly [key: string]: unknown;
+}
+/**
+ * Read accessors registered by other plugins via `getSharedState()`.
+ * Forks can extend this via declaration merging (e.g. `userProfile`).
+ */
+export interface SharedAccessors {
+    readonly [key: string]: unknown;
+}
+export type ToolCallEventPayload = Record<string, unknown>;
+export type ActionCallEventPayload = Record<string, unknown>;
+export type RenderComponentEventPayload = Record<string, unknown>;
+export type ReasoningEventPayload = Record<string, unknown>;
+export type BrowserToolCallEventPayload = Record<string, unknown>;
+export type RouterEventPayload = Record<string, unknown>;
+export type MessageCacheInvalidationPayload = Record<string, unknown>;
+import type { AgentMiddleware } from 'langchain';
+export type { AgentMiddleware };
+/**
+ * The agent's structured interface to a plugin. Drives Tier-1 prompt
+ * composition and powers `list_capabilities` discovery.
+ */
+export interface PluginManifest {
+    /** Human-readable name. */
+    title: string;
+    /** One-line description shown in the Tier-1 prompt for `always` plugins. */
+    summary: string;
+    /** Triggers — when the agent should consider this plugin. */
+    whenToUse: string[];
+    /** Anti-patterns — when the agent should NOT use this plugin. */
+    whenNotToUse?: string[];
+    /** Few-shot examples teaching the agent how to invoke the plugin. */
+    examples?: ManifestExample[];
+    /** Categorization for grouping and filtering. */
+    tags?: string[];
+    category?: 'data' | 'communication' | 'automation' | 'memory' | 'integration' | 'ui' | 'auth' | 'observability' | 'core';
+    /**
+     * Discovery and loading mode:
+     *  - `always`    — tools bound to agent at boot; listed in Tier-1 prompt.
+     *  - `on-demand` — tools NOT bound; manifest discoverable via
+     *                  `list_capabilities`; agent calls `load_capability(name)`
+     *                  to load.
+     *  - `silent`    — invisible to agent; runs as middleware-only.
+     *
+     * Default: `on-demand`.
+     */
+    visibility?: 'always' | 'on-demand' | 'silent';
+    /** Stability hint surfaced to the agent (`experimental` → warning footnote). */
+    stability?: 'stable' | 'beta' | 'experimental';
+}
+export interface ManifestExample {
+    /** Representative user message. */
+    user: string;
+    /** Optional reasoning. */
+    thought?: string;
+    /** Tool the agent should call. */
+    tool: string;
+    /** Tool args. */
+    args?: Record<string, unknown>;
+}
+/**
+ * Author-provided prompt customization. Every field is optional — when absent
+ * the runtime falls back to its built-in defaults. Authored once, baked into
+ * the system prompt at build time.
+ */
+export interface OraclePromptConfig {
+    /**
+     * Full replacement of the identity preamble. When set, used verbatim as the
+     * opening paragraph. When unset, the composer generates one from
+     * `name`/`org`/`description`.
+     */
+    opening?: string;
+    /**
+     * Appended to the runtime's operating-principles section. Use for tone,
+     * voice, formality, or oracle-specific behavioral hints.
+     */
+    communicationStyle?: string;
+    /**
+     * Author-written elevator pitch for what this oracle does. Rendered above
+     * the plugin-derived capability list — additive, not a replacement.
+     */
+    capabilities?: string;
+}
+/**
+ * Developer-facing oracle config. Passed inline to `createOracleApp`. The
+ * runtime fills in `entityDid` from the `ORACLE_ENTITY_DID` env var and
+ * combines this with bundled defaults to build the internal `OracleIdentity`.
+ */
+export interface OracleConfig {
+    /** Oracle display name. Required. */
+    name: string;
+    /** Sponsoring organization. Optional — composer falls back gracefully. */
+    org?: string;
+    /** One-line description of what this oracle is for. */
+    description?: string;
+    /** Optional prompt customization (opening, communicationStyle, capabilities). */
+    prompt?: OraclePromptConfig;
+}
+/**
+ * Identity of the oracle running this plugin. Built by the runtime from
+ * `OracleConfig` + `ORACLE_ENTITY_DID` env var. Plugins read it via
+ * `PluginContext.identity` / `RuntimeContext` and should treat it as
+ * read-only.
+ */
+export interface OracleIdentity {
+    name: string;
+    org: string;
+    description: string;
+    entityDid: string;
+    /** Author-provided prompt customization. Undefined when not configured. */
+    prompt?: OraclePromptConfig;
+}
+/**
+ * Passed to plugin methods called at request build time
+ * (`getTools`, `getSubAgents`, `getMiddlewares`). Lives once per request build.
+ *
+ * Holds no user, no session, no live socket, no request data.
+ */
+export interface PluginContext<TConfig = MergedConfig> {
+    /** Merged Zod-validated env vars (core + all loaded plugins' configSchemas). */
+    config: TConfig;
+    /** Identity of this oracle. */
+    identity: OracleIdentity;
+    /** Set of plugin names currently loaded — drives soft-dep branching. */
+    availablePlugins: ReadonlySet<string>;
+    /** Plugin-scoped logger (auto-prefixed with the plugin's name). */
+    logger: Logger;
+}
+/**
+ * Passed to tool handlers, sub-agent handlers, and to plugin middlewares' hook
+ * functions. Built fresh per graph invocation.
+ */
+export interface RuntimeContext<TConfig = MergedConfig> {
+    /** Authenticated user identity (validated by core auth middleware). */
+    user: {
+        did: string;
+        /** e.g. `@did-ixo-ixo1abc:ixo.world`. */
+        matrixUserId: string;
+        ucanDelegation: UcanDelegation;
+        timezone?: string;
+        currentTime?: string;
+    };
+    /** Session info from `SessionsService`. */
+    session: {
+        /** = `thread_id`; thread root `eventId`. */
+        id: string;
+        client: 'portal' | 'matrix' | 'slack';
+        wsId?: string;
+        requestId: string;
+        roomId?: string;
+    };
+    /** Read-only view over the graph state's history. */
+    history: {
+        messages: readonly BaseMessage[];
+        recent: (n: number) => BaseMessage[];
+        /** Memory enrichment from existing `state.userContext`. */
+        userContext: UserContextData;
+        /** Typed view over `Annotation.Root`. */
+        state: ReadonlyState;
+    };
+    /** Same merged Zod-validated env. */
+    config: TConfig;
+    /** Set of plugin names currently loaded (boot-fixed). */
+    availablePlugins: ReadonlySet<string>;
+    /** Plugins the agent has loaded for THIS thread via `load_capability`. */
+    loadedPlugins: ReadonlySet<string>;
+    /** Per-room secrets (JWE-encrypted, 24h cache; today's `SecretsService`). */
+    secrets: {
+        getIndex: () => Promise<SecretIndex>;
+        getValues: (keys: string[]) => Promise<Record<string, string>>;
+    };
+    /**
+     * Short-TTL keyed value store for content the LLM should never relay
+     * verbatim (UCAN invocation CARs, JWTs, signed envelopes, etc.). A
+     * producing tool stores the value and returns a short hex blobId; a
+     * consuming tool looks the value up server-side and forwards it on. Blobs
+     * are namespaced by issuing user DID — cross-user reads always miss.
+     */
+    blobStore: {
+        /** Store a value and return a fresh `blob_<16 hex>` id. TTL clamped to
+         * the service's `MAX_TTL_SECONDS` (24h); defaults to `DEFAULT_TTL_SECONDS`
+         * (1h) when omitted. Pass `userDid` from a trusted source — never from
+         * LLM-supplied arguments. */
+        put: (params: {
+            userDid: string;
+            name: string;
+            value: string;
+            ttlSeconds?: number;
+        }) => Promise<string>;
+        /** Retrieve a blob by id, scoped to the requesting user. Returns `null`
+         * if the blob doesn't exist, has expired, or belongs to a different user. */
+        get: (params: {
+            userDid: string;
+            blobId: string;
+        }) => Promise<{
+            name: string;
+            value: string;
+        } | null>;
+        /** Lightweight format check (`blob_<16 hex>`). Use in tool input handlers
+         * to reject malformed IDs before paying for a cache lookup. */
+        isValidBlobId: (value: unknown) => value is string;
+    };
+    /** Matrix client, scoped operations only. */
+    matrix: {
+        postToRoom: (roomId: string, content: unknown) => Promise<string>;
+        getRoomState: (roomId: string) => Promise<RoomStateSnapshot>;
+        getEventById: (roomId: string, eventId: string) => Promise<MatrixEvent>;
+    };
+    /** UCAN authorization helpers. */
+    ucan: {
+        requireCapability: (resource: string, action: string) => void;
+        hasCapability: (resource: string, action: string) => boolean;
+        mintInvocation: (target: {
+            did: string;
+            capability: string;
+        }, opts?: {
+            skipCache?: boolean;
+        }) => Promise<string>;
+        /**
+         * Resolve a downstream service URL to its did:web identifier. Returns
+         * `null` when the document is missing or has no `id` — used by plugins
+         * minting service-targeted UCAN invocations.
+         */
+        resolveServiceDid: (serviceUrl: string) => Promise<string | null>;
+        /**
+         * `true` once the oracle has loaded its Ed25519 signing mnemonic. Plugins
+         * gate registration of mint-capable tools on this — without a key, minting
+         * is a no-op and the tool should surface an error rather than pretend.
+         */
+        hasSigningKey: () => boolean;
+        /**
+         * Mint a UCAN invocation from a directly-supplied delegation CAR (rather
+         * than a per-user cached one). Used by the editor's `mint_invocation`
+         * tool: it reads the CAR from a flow's Y.Doc by CID and re-mints a fresh
+         * single-use invocation targeted at a specific service route.
+         */
+        createInvocationFromDelegation: (delegationCar: string, serviceUrl: string, capability: {
+            can: string;
+            with: string;
+        }, options?: {
+            maxTtlSeconds?: number;
+        }) => Promise<{
+            invocation: string;
+        } | {
+            error: string;
+        }>;
+    };
+    /** LLM provider. */
+    llm: {
+        get: (role: ModelRole, params?: ChatOpenAIFields) => BaseChatModel;
+    };
+    /** Typed event emitter (today's `@ixo/oracles-events` 7 event types). */
+    emit: {
+        toolCall: (payload: ToolCallEventPayload) => void;
+        actionCall: (payload: ActionCallEventPayload) => void;
+        renderComponent: (payload: RenderComponentEventPayload) => void;
+        reasoning: (payload: ReasoningEventPayload) => void;
+        browserToolCall: (payload: BrowserToolCallEventPayload) => void;
+        router: (payload: RouterEventPayload) => void;
+        messageCacheInvalidation: (payload: MessageCacheInvalidationPayload) => void;
+    };
+    /** Plugin-scoped logger. */
+    logger: Logger;
+    /** Propagates from the HTTP request / graph invocation. */
+    abortSignal: AbortSignal;
+    /** Read accessors for state owned by other plugins. */
+    shared: SharedAccessors;
+    /**
+     * Identifier of the inbound tool call that triggered this handler, when
+     * available. Undefined for direct/test invocations. Used by tools that
+     * return a LangGraph `Command` and need to append a matching `ToolMessage`
+     * to the state update.
+     */
+    toolCallId?: string;
+}
+export interface PluginTool {
+    name: string;
+    description: string;
+    schema: z.ZodType;
+    handler: (args: unknown, ctx: RuntimeContext) => Promise<unknown>;
+    /** Override visibility — by default inherits from the plugin's `manifest.visibility`. */
+    visibility?: 'always' | 'on-demand' | 'silent';
+}
+export interface PluginSubAgent {
+    /** Tool name the agent will see (e.g. `call_memory_agent`). */
+    name: string;
+    description: string;
+    systemPrompt: string | ((ctx: PluginContext) => string);
+    tools: PluginTool[] | ((ctx: PluginContext) => PluginTool[]);
+    /** LLM role; default `subagent`. */
+    model?: ModelRole;
+    /** Sub-agent-scoped middleware (e.g. summarization for long conversations). */
+    middlewares?: AgentMiddleware[];
+    /**
+     * Forward this sub-agent's internal tool calls + results into the parent
+     * graph's message history so the UI renders them in the main chat.
+     *
+     *   - `true` → forward ALL of this sub-agent's own tools
+     *   - `false` / omitted → forward nothing
+     *   - `string[]` → forward only the listed tool names
+     *
+     * Runtime-injected passthrough tools (e.g. memory CRUD) are never
+     * forwarded — they're already on the main agent.
+     */
+    forwardTools?: boolean | string[];
+    /** Called after sub-agent completes; can emit follow-up events. */
+    onComplete?: (result: string, ctx: RuntimeContext) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugin-api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugin-api/types.ts"],"names":[],"mappings":"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"}

package/dist/plugin-api/types.js

@@ -0,0 +1 @@
+export {};

package/dist/plugins/agui/agui-agent.d.ts

@@ -0,0 +1,10 @@
+import type { PluginSubAgent, PluginTool } from '../../plugin-api/types.js';
+/**
+ * Build the AG-UI sub-agent. Tools are derived per-request from
+ * `state.agActions` (one PluginTool per declared action). Reasoning disabled
+ * on purpose: this is a structured tool-calling task, not a reasoning task —
+ * reasoning mode causes the model to narrate its plan in free text instead of
+ * emitting the tool call.
+ */
+export declare function createAguiSubAgent(tools: PluginTool[]): PluginSubAgent;
+//# sourceMappingURL=agui-agent.d.ts.map

package/dist/plugins/agui/agui-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agui-agent.d.ts","sourceRoot":"","sources":["../../../src/plugins/agui/agui-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AA+F5E;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,cAAc,CActE"}

package/dist/plugins/agui/agui-agent.js

@@ -0,0 +1,110 @@
+const formatToolDocs = (tools) => {
+    if (!tools.length) {
+        return '- No AG-UI tools configured.';
+    }
+    return tools
+        .map((t) => {
+        const description = t.description?.trim() ?? 'No description provided.';
+        return `- \`${t.name}\`: ${description}`;
+    })
+        .join('\n');
+};
+const buildAguiPrompt = (toolsDoc) => `
+You are the AG-UI Agent — a specialized sub-agent that generates interactive UI
+components in the user's browser by calling AG-UI (Agent Generated UI) tools.
+
+## 🚨 THE ONLY RULE THAT MATTERS
+
+**If the task gives you enough parameters to call a tool, you MUST call the tool. You are FORBIDDEN from responding with text alone when a tool call is possible.**
+
+Your response counts as a failure if you say things like "I've created the table" or "The visualization is ready" without actually invoking an AG-UI tool in this turn. The user sees nothing if you don't call the tool — your natural-language summary is meaningless on its own.
+
+## What are AG-UI Tools?
+AG-UI tools dynamically generate interactive components (tables, charts, forms,
+etc.) that render directly in the client's browser. They execute instantly
+without backend processing.
+
+## Available AG-UI Tools
+${toolsDoc}
+
+## Worked Example — fruits table
+
+\`\`\`
+Task: "Create a data table with these 5 fruits: [{name: 'Apple', color: 'Red', price: 1.5}, ...]"
+
+Your action: call create_data_table with
+  {
+    id: "fruits_table",
+    title: "Fruits",
+    data: [{name: "Apple", color: "Red", price: 1.5}, ...],
+    columns: [
+      {key: "name", label: "Fruit"},
+      {key: "color", label: "Color"},
+      {key: "price", label: "Avg Price"}
+    ]
+  }
+
+Your message: "Here's the fruits table."
+\`\`\`
+
+## Message Output Rules (after the tool call)
+
+Your message to the main agent should ONLY be a short natural-language
+confirmation — NEVER the data, JSON, or a text rendition of the UI.
+
+**✅ DO:**
+- Call the AG-UI tool FIRST.
+- Then add one short sentence like "Here's the fruits table" or "Rendered the revenue chart."
+
+**❌ DON'T:**
+- Output data as markdown tables in your message.
+- Display JSON or raw rows in your message.
+- Recreate the table/chart/list as text — the canvas already shows it.
+- Reply "I've created …" without actually having called the tool.
+
+## Schema Compliance
+- STRICTLY follow each tool's schema.
+- All required fields must be present and correctly typed.
+- Extract parameters verbatim from the task — do not substitute, guess, or reformat values.
+- Validation errors cause the tool to fail silently — double-check before calling.
+
+## Task Discipline
+- You are a one-shot sub-agent invoked by the main agent. Your single task
+  message is ALL the context you have. Do not assume prior conversation state.
+- If the task is unclear or missing critical details, STOP immediately and
+  return a clear message explaining what's missing. Do NOT guess.
+- Never loop or retry the same failing approach. If the first attempt fails,
+  stop and return a clear error — the main agent will re-invoke you if needed.
+
+## Workflow
+1. Parse the task. Identify which tool to use and which parameters to pass.
+2. Extract parameters verbatim from the task.
+3. **CALL THE TOOL.** This is not optional.
+4. Add one short confirmation sentence.
+`.trim();
+const buildAguiDescription = (tools) => {
+    const names = tools.map((t) => t.name).join(', ') || 'no configured tools';
+    return `Specialized AG-UI Agent that generates interactive UI components (tables, charts, forms) in the user's browser. Available tools: (${names}).`;
+};
+/**
+ * Build the AG-UI sub-agent. Tools are derived per-request from
+ * `state.agActions` (one PluginTool per declared action). Reasoning disabled
+ * on purpose: this is a structured tool-calling task, not a reasoning task —
+ * reasoning mode causes the model to narrate its plan in free text instead of
+ * emitting the tool call.
+ */
+export function createAguiSubAgent(tools) {
+    const toolsDoc = formatToolDocs(tools);
+    return {
+        name: 'AG-UI Agent',
+        description: buildAguiDescription(tools),
+        systemPrompt: buildAguiPrompt(toolsDoc),
+        tools,
+        model: 'subagent',
+        middlewares: [],
+        // AG-UI action invocations must surface in the main chat so the UI can
+        // render the corresponding component events. Forward every action this
+        // sub-agent exposes — the tool list IS the action list.
+        forwardTools: true,
+    };
+}

package/dist/plugins/agui/agui.plugin.d.ts

@@ -0,0 +1,16 @@
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginManifest, PluginSubAgent, RuntimeContext } from '../../plugin-api/types.js';
+/**
+ * AG-UI plugin (Portal copilot). The sub-agent is built per-request from
+ * `state.agActions` — the client declares its renderable actions on each
+ * `sendMessage`, the runtime wraps each into a PluginTool, and the agent
+ * decides whether to delegate. When no actions are declared the plugin
+ * contributes nothing.
+ */
+export declare class AGUIPlugin extends OraclePlugin {
+    readonly name = "agui";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    getRequestSubAgents(rtCtx: RuntimeContext): Promise<PluginSubAgent[]>;
+}
+//# sourceMappingURL=agui.plugin.d.ts.map

package/dist/plugins/agui/agui.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agui.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/agui/agui.plugin.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEjE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EAEd,cAAc,EACf,MAAM,2BAA2B,CAAC;AAiHnC;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,YAAY;IAC1C,QAAQ,CAAC,IAAI,UAAU;IAEvB,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAEd,mBAAmB,CAChC,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,cAAc,EAAE,CAAC;CAO7B"}

package/dist/plugins/agui/agui.plugin.js

@@ -0,0 +1,117 @@
+import { callAgAction, logActionToMatrix } from '@ixo/common';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { tool } from '../../plugin-api/tool-helper.js';
+import { createAguiSubAgent } from './agui-agent.js';
+const manifest = {
+    title: 'AG-UI',
+    summary: "Renders interactive UI components (tables, charts, forms) in the user's browser via AG-UI actions.",
+    whenToUse: [
+        'User asks for an interactive table, chart, or form to be rendered.',
+        'A response is best shown as a structured UI component rather than plain text.',
+    ],
+    whenNotToUse: [
+        'No AG-UI actions are declared on this request (sub-agent is not built).',
+        "A plain text answer is sufficient — don't render UI just because you can.",
+    ],
+    examples: [
+        {
+            user: 'Show me the results as a table.',
+            thought: 'Structured display — delegate to call_ag-ui_agent with the rows.',
+            tool: 'call_ag-ui_agent',
+        },
+    ],
+    tags: ['agui', 'ui', 'portal', 'copilot'],
+    category: 'ui',
+    visibility: 'on-demand',
+    stability: 'stable',
+};
+/** Default per-action timeout — matches today's `parserActionTool`. */
+const ACTION_TIMEOUT_MS = 15_000;
+const AG_ACTION_SHAPE = z.object({
+    name: z.string(),
+    description: z.string(),
+    schema: z.record(z.string(), z.unknown()),
+    hasRender: z.boolean().optional(),
+});
+const ARGS_RECORD_SHAPE = z.record(z.string(), z.unknown());
+function parseAgActions(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        const parsed = AG_ACTION_SHAPE.safeParse(entry);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out;
+}
+function parseArgs(input) {
+    const parsed = ARGS_RECORD_SHAPE.safeParse(input ?? {});
+    return parsed.success ? parsed.data : {};
+}
+/**
+ * Build a single PluginTool that, when invoked, dispatches the AG-UI action to
+ * the user's frontend via the existing `callAgAction` helper and waits for the
+ * result. Mirrors today's `parserActionTool` behaviour (matrix logging on
+ * success, unique tool-call id per invocation) but sources `sessionId`,
+ * `requestId`, and `roomId` from `RuntimeContext` instead of LangChain'
+ * configurable bag.
+ */
+function buildActionTool(action) {
+    return tool(async (input, ctx) => {
+        const sessionId = ctx.session.id;
+        if (!sessionId) {
+            throw new Error('sessionId is required for AG-UI actions');
+        }
+        const args = parseArgs(input);
+        const requestId = ctx.session.requestId;
+        const toolCallId = `ag_${requestId || 'noreq'}_${randomUUID().slice(0, 8)}`;
+        const result = await callAgAction({
+            sessionId,
+            toolCallId,
+            toolName: action.name,
+            args,
+            timeout: ACTION_TIMEOUT_MS,
+        });
+        if (ctx.session.roomId) {
+            void logActionToMatrix({
+                name: action.name,
+                args,
+                result,
+                success: true,
+            }, {
+                roomId: ctx.session.roomId,
+                threadId: sessionId,
+            });
+        }
+        return JSON.stringify(result);
+    }, {
+        name: action.name,
+        description: action.description,
+        schema: z.fromJSONSchema(action.schema),
+    });
+}
+function readAgActions(rtCtx) {
+    return parseAgActions(rtCtx.history.state.agActions);
+}
+/**
+ * AG-UI plugin (Portal copilot). The sub-agent is built per-request from
+ * `state.agActions` — the client declares its renderable actions on each
+ * `sendMessage`, the runtime wraps each into a PluginTool, and the agent
+ * decides whether to delegate. When no actions are declared the plugin
+ * contributes nothing.
+ */
+export class AGUIPlugin extends OraclePlugin {
+    name = 'agui';
+    version = '1.0.0';
+    manifest = manifest;
+    async getRequestSubAgents(rtCtx) {
+        const actions = readAgActions(rtCtx);
+        if (actions.length === 0)
+            return [];
+        const tools = actions.map(buildActionTool);
+        return [createAguiSubAgent(tools)];
+    }
+}

package/dist/plugins/agui/index.d.ts

@@ -0,0 +1,3 @@
+export { AGUIPlugin } from './agui.plugin.js';
+export { createAguiSubAgent } from './agui-agent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/agui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/agui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/plugins/agui/index.js

@@ -0,0 +1,2 @@
+export { AGUIPlugin } from './agui.plugin.js';
+export { createAguiSubAgent } from './agui-agent.js';