@ixo/oracle-runtime 0.0.1

package/dist/plugins/memory/memory-ucan.js

@@ -0,0 +1,43 @@
+/**
+ * Build the headers needed to call the Memory Engine MCP server on behalf of
+ * the current user.
+ *
+ *   1. Resolve the memory service DID via `runCtx.ucan.resolveServiceDid`
+ *      (delegates the did:web lookup + cache to the Tier-0 UCAN service).
+ *   2. Mint an `ixo:memory` invocation using the user's signing key.
+ *   3. Layer the resulting Bearer token plus the active `x-room-id`.
+ *
+ * UCAN-only — no Matrix-OpenID fallback. If minting fails for any reason
+ * (no signing key, no cached delegation, did:web unresolved) the function
+ * returns `null` so callers can degrade silently rather than leak a
+ * half-built request to the upstream service.
+ */
+export async function buildMemoryHeaders(runCtx, memoryMcpUrl) {
+    const memoryDid = await runCtx.ucan.resolveServiceDid(memoryMcpUrl);
+    if (!memoryDid)
+        return null;
+    try {
+        const invocation = await runCtx.ucan.mintInvocation({
+            did: memoryDid,
+            capability: 'ixo:memory',
+        });
+        if (!invocation || invocation.length === 0)
+            return null;
+        const headers = {
+            Authorization: `Bearer ${invocation}`,
+            'X-Auth-Type': 'ucan',
+            'User-Agent': 'LangChain-MCP-Client/1.0',
+        };
+        if (runCtx.session.roomId) {
+            headers['x-room-id'] = runCtx.session.roomId;
+        }
+        return headers;
+    }
+    catch (error) {
+        const detail = error instanceof Error
+            ? `${error.name}: ${error.message}`
+            : String(error);
+        runCtx.logger.warn(`[memory] failed to mint UCAN invocation: ${detail}`);
+        return null;
+    }
+}

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

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginManifest, PluginTool, RuntimeContext, UserContextData } from '../../plugin-api/types.js';
+import { type MemoryMcpFactory } from './memory-tools.js';
+export interface MemoryPluginOptions {
+    /**
+     * Override the MCP-tools factory. Defaults to an HTTP MCP client against
+     * `MEMORY_MCP_URL` authenticated with a per-request UCAN invocation.
+     */
+    mcpFactory?: (memoryMcpUrl: string) => MemoryMcpFactory;
+    /**
+     * Filter the upstream tool surface. Defaults to {@link DEFAULT_MEMORY_TOOLS}
+     * (search + add + delete-episode). Pass an explicit list to expose
+     * `clear`, `add_oracle_knowledge`, etc.
+     */
+    selectedTools?: readonly string[];
+}
+/**
+ * Memory plugin. Surfaces upstream Memory Engine MCP tools directly — the
+ * agent sees the upstream names (`memory-engine__search_memory_engine`,
+ * `memory-engine__add_memory`, ...) with the upstream's own schemas. This
+ * matches the apps/app pattern that worked in production and avoids
+ * schema-mismatch failures from a local wrapper layer.
+ *
+ * Tool list is fetched per-request via `getRequestTools` because the MCP
+ * headers depend on the in-flight user's UCAN delegation.
+ *
+ * The runtime forwards memory tools into every sub-agent's tool list
+ * (filter in `main-agent.ts`), except `memory-engine__clear` — destructive,
+ * main-agent-only.
+ */
+export declare class MemoryPlugin extends OraclePlugin {
+    static readonly NAME = "memory";
+    readonly name = "memory";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    readonly configSchema: z.ZodObject<{
+        MEMORY_MCP_URL: z.ZodString;
+        MEMORY_ENGINE_URL: z.ZodString;
+    }, z.core.$strip>;
+    readonly autoDetectHint = "MEMORY_MCP_URL";
+    private readonly mcpFactory;
+    private readonly selectedTools;
+    constructor(options?: MemoryPluginOptions);
+    autoDetect(env: NodeJS.ProcessEnv): boolean;
+    getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]>;
+    getSharedState(): Record<string, (state: {
+        userContext?: UserContextData;
+    }, runCtx: RuntimeContext) => unknown>;
+}
+//# sourceMappingURL=memory.plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/memory/memory.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EAEV,cAAc,EACd,UAAU,EACV,cAAc,EACd,eAAe,EAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAgC3B,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,gBAAgB,CAAC;IACxD;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAOD;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAY;IAEhC,QAAQ,CAAC,IAAI,YAAqB;IAElC,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAE7B,SAAkB,YAAY;;;sBAAgB;IAE9C,SAAkB,cAAc,oBAAoB;IAEpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6C;IAExE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;gBAEtC,OAAO,GAAE,mBAAwB;IAMpC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAIrC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAMnE,cAAc,IAAI,MAAM,CAC/B,MAAM,EACN,CACE,KAAK,EAAE;QAAE,WAAW,CAAC,EAAE,eAAe,CAAA;KAAE,EACxC,MAAM,EAAE,cAAc,KACnB,OAAO,CACb;CAKF"}

package/dist/plugins/memory/memory.plugin.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { createDefaultMemoryMcpFactory, DEFAULT_MEMORY_TOOLS, fetchMemoryTools, } from './memory-tools.js';
+const configSchema = z.object({
+    MEMORY_MCP_URL: z.string().url('MEMORY_MCP_URL must be a valid HTTP(S) URL.'),
+    MEMORY_ENGINE_URL: z
+        .string()
+        .url('MEMORY_ENGINE_URL must be a valid HTTP(S) URL.'),
+});
+const manifest = {
+    title: 'Memory',
+    summary: 'Durable memory across conversations: who the user is, what you have made for them, and what worked.',
+    whenToUse: [
+        'First contact (no prior context loaded): greet, ask their name and what they want help with, then save what they tell you.',
+        'You learn something durable about the user — name, role, ongoing project, a constraint, a relationship.',
+        'You create an artifact for the user (file, document, edit, generated content): record what it is, what it is for, and the structural choices you made.',
+        'The user expresses satisfaction or dissatisfaction with something you produced: capture what worked or what did not — tone, length, structure, style — against that artifact entry.',
+        'The user references something they told you before, or something you made before.',
+    ],
+    whenNotToUse: [
+        'Ephemeral conversation-only state (use the current message thread).',
+        'Behavioral preferences about how to respond (call the user-preferences tool instead).',
+        'Public web facts that are not specific to this user (use a web-search capability).',
+        'Anything the user asked you to forget or framed as temporary.',
+    ],
+    tags: ['memory', 'recall', 'artifacts', 'personalization'],
+    category: 'memory',
+    visibility: 'always',
+    stability: 'stable',
+};
+function resolveMemoryUrl(config) {
+    const parsed = configSchema.parse(config);
+    return parsed.MEMORY_MCP_URL;
+}
+/**
+ * Memory plugin. Surfaces upstream Memory Engine MCP tools directly — the
+ * agent sees the upstream names (`memory-engine__search_memory_engine`,
+ * `memory-engine__add_memory`, ...) with the upstream's own schemas. This
+ * matches the apps/app pattern that worked in production and avoids
+ * schema-mismatch failures from a local wrapper layer.
+ *
+ * Tool list is fetched per-request via `getRequestTools` because the MCP
+ * headers depend on the in-flight user's UCAN delegation.
+ *
+ * The runtime forwards memory tools into every sub-agent's tool list
+ * (filter in `main-agent.ts`), except `memory-engine__clear` — destructive,
+ * main-agent-only.
+ */
+export class MemoryPlugin extends OraclePlugin {
+    static NAME = 'memory';
+    name = MemoryPlugin.NAME;
+    version = '1.0.0';
+    manifest = manifest;
+    configSchema = configSchema;
+    autoDetectHint = 'MEMORY_MCP_URL';
+    mcpFactory;
+    selectedTools;
+    constructor(options = {}) {
+        super();
+        this.mcpFactory = options.mcpFactory ?? createDefaultMemoryMcpFactory;
+        this.selectedTools = options.selectedTools ?? DEFAULT_MEMORY_TOOLS;
+    }
+    autoDetect(env) {
+        return Boolean(env.MEMORY_MCP_URL);
+    }
+    async getRequestTools(rtCtx) {
+        const memoryUrl = resolveMemoryUrl(rtCtx.config);
+        const factory = this.mcpFactory(memoryUrl);
+        return fetchMemoryTools(rtCtx, factory, this.selectedTools);
+    }
+    getSharedState() {
+        return {
+            userProfile: (state) => state.userContext,
+        };
+    }
+}

package/dist/plugins/memory/types.d.ts

@@ -0,0 +1,75 @@
+export type ComparisonOperator = '=' | '<>' | '>' | '<' | '>=' | '<=' | 'IS NULL' | 'IS NOT NULL';
+/** A single date filter condition. `date` can be omitted for IS NULL / IS NOT NULL. */
+export interface DateFilter {
+    date?: string;
+    comparison_operator: ComparisonOperator;
+}
+/**
+ * Date filters are passed as groups of OR-conditions combined with AND between groups:
+ *   [[a, b], [c]]  →  (a OR b) AND (c)
+ */
+export type DateFilterGroups = DateFilter[][];
+export type SearchStrategy = 'balanced' | 'diverse' | 'precise' | 'contextual' | 'recent_memory' | 'facts_only' | 'entities_only' | 'topics_only';
+export type KnowledgeLevel = 'user' | 'oracle' | 'both';
+export type EntityType = 'Person' | 'Trait' | 'Value' | 'Identity' | 'Attribute' | 'Emotion' | 'Stress' | 'CopingStrategy' | 'Job' | 'Project' | 'Skill' | 'Tool' | 'Organization' | 'Goal' | 'Milestone' | 'Habit' | 'Routine' | 'Pattern' | 'Interest' | 'Hobby' | 'Content' | 'Preference' | 'Product' | 'Expertise' | 'LearningGoal' | 'Resource' | 'Location' | 'Experience' | 'Event' | 'Group' | 'Pet' | 'CommunicationStyle' | 'Language' | 'Task' | 'Belief' | 'Cause' | 'Procedure' | 'Agent' | 'SmartAccount' | 'OutcomeUnit' | 'Claim' | 'Evaluation' | 'ServiceEvent' | 'Payment' | 'VerifiableCredential';
+export type EdgeType = 'Knows' | 'WorksWith' | 'Causes' | 'Enables' | 'Blocks' | 'PartOf' | 'BelongsTo' | 'Practices' | 'Uses' | 'Pursuing' | 'Requires' | 'Achieved' | 'EmployedAt' | 'WorksOn' | 'Manages' | 'LivesAt' | 'VisitedLocation' | 'LocatedIn' | 'Prefers' | 'Likes' | 'Dislikes' | 'InterestedIn' | 'ExpertiseIn' | 'Studying' | 'LearnedFrom' | 'Triggers' | 'Motivates' | 'ManagesVia' | 'Influences' | 'Supports' | 'MemberOf' | 'Owns' | 'CurrentlyIs' | 'WasPreviously' | 'AlignedWith' | 'ConflictsWith' | 'RelatesTo' | 'OWNS' | 'CONTROLS' | 'SUBMITS_CLAIM' | 'HAS_EVALUATION' | 'RESULTS_IN_OUTCOME' | 'TRIGGERS_PAYMENT' | 'PAYS_FOR_SERVICE' | 'HAS_IDENTITY';
+/** memory-engine__search_memory_engine */
+export interface SearchMemoryInput {
+    query: string;
+    strategy: SearchStrategy;
+    /** @default 'both' */
+    knowledge_level?: KnowledgeLevel;
+    /** UUID of a node to use as the graph traversal center */
+    center_node_uuid?: string;
+    node_labels?: EntityType[];
+    edge_types?: EdgeType[];
+    /** Filter on the edge/node valid_at timestamp */
+    valid_at?: DateFilterGroups;
+    /** Filter on the edge/node invalid_at timestamp */
+    invalid_at?: DateFilterGroups;
+    /** Filter on the edge/node created_at timestamp */
+    created_at?: DateFilterGroups;
+    /** Filter on the edge/node expired_at timestamp */
+    expired_at?: DateFilterGroups;
+}
+/** memory-engine__add_memory */
+export interface AddMemoryInput {
+    /** Short label / title for the memory */
+    name: string;
+    /** The actual content/text to store */
+    content: string;
+    /** @default 'text' */
+    source?: string;
+    /** @default '' */
+    source_description?: string;
+}
+/** memory-engine__add_oracle_knowledge */
+export interface AddOracleKnowledgeInput {
+    name: string;
+    content: string;
+    /** Must be true — agent must get explicit user confirmation before calling */
+    confirmed_insertion_from_user: boolean;
+    knowledge_space_type: 'public' | 'private';
+    /** @default 'text' */
+    source?: string;
+    /** @default '' */
+    source_description?: string;
+}
+/** memory-engine__delete_episode */
+export interface DeleteEpisodeInput {
+    episode_uuid: string;
+    /** Must be true — agent must get explicit user confirmation before calling */
+    confirmed_deletion_from_user: boolean;
+}
+/** memory-engine__delete_edge */
+export interface DeleteEdgeInput {
+    edge_uuid: string;
+    /** Must be true — agent must get explicit user confirmation before calling */
+    confirmed_deletion_from_user: boolean;
+}
+/** memory-engine__clear */
+export interface ClearMemorySpaceInput {
+    /** Must be true — agent must get explicit user confirmation before calling */
+    confirmed_deletion_from_user: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/memory/types.d.ts.map

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

package/dist/plugins/memory/types.js

@@ -0,0 +1,2 @@
+// ─── Shared primitives ────────────────────────────────────────────────────────
+export {};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/portal/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/plugins/portal/index.js

@@ -0,0 +1,2 @@
+export { PortalPlugin } from './portal.plugin.js';
+export { createPortalSubAgent } from './portal-agent.js';

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

@@ -0,0 +1,9 @@
+import type { PluginSubAgent, PluginTool } from '../../plugin-api/types.js';
+/**
+ * Build the Portal sub-agent. Tools are derived per-request from
+ * `state.browserTools` (one PluginTool per declared browser tool). The
+ * resulting sub-agent calls the FE-declared tools and waits for the
+ * reverse-flowed result.
+ */
+export declare function createPortalSubAgent(tools: PluginTool[]): PluginSubAgent;
+//# sourceMappingURL=portal-agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"portal-agent.d.ts","sourceRoot":"","sources":["../../../src/plugins/portal/portal-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAoE5E;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,cAAc,CAUxE"}

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

@@ -0,0 +1,70 @@
+const sharedExpectations = `
+You are the Portal Agent for this workspace. Your entire job is to operate the
+user portal/UI on behalf of the user by calling the available tools responsibly.
+
+Core expectations:
+- Be the helpful front-line assistant for anything that can be done via the
+  portal tools you have access to.
+- Never guess which tool to use—reference each tool's description and required
+  inputs before invoking it.
+- Narrate your intent before triggering a tool, confirm the result afterwards,
+  and clearly communicate next steps or follow-up questions.
+- Respect safety, data-privacy, and authorization boundaries described by each
+  tool.
+
+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.
+`.trim();
+const workflowGuidelines = `
+### Workflow
+1. Clarify the user's goal and map it to one (or more) portal tools.
+2. Consult each tool's description before invoking it — verify required inputs.
+3. Pass parameters exactly as documented; never guess IDs or omit required fields.
+4. Summarize results back to the user, highlighting any outstanding actions or follow-ups.
+5. If no tool can satisfy the request, explain why and suggest alternatives.
+`.trim();
+const formatToolDocs = (tools) => {
+    if (!tools.length) {
+        return '- No portal tools configured. Ask a human operator for support.';
+    }
+    return tools
+        .map((t) => {
+        const description = t.description?.trim() ?? 'No description provided.';
+        return `- \`${t.name}\`: ${description}`;
+    })
+        .join('\n');
+};
+const buildPortalPrompt = ({ toolsDoc, extraInstructions, }) => `
+${sharedExpectations}
+
+### Available Portal Tools
+${toolsDoc}
+
+${workflowGuidelines}
+
+${extraInstructions ? `### Additional Instructions\n${extraInstructions}` : ''}
+`.trim();
+const buildPortalDescription = (tools) => {
+    const names = tools.map((t) => t.name).join(', ') || 'no configured tools';
+    return `Specialized Portal Agent that executes user-facing portal/UI actions. Supported actions: (${names}).`;
+};
+/**
+ * Build the Portal sub-agent. Tools are derived per-request from
+ * `state.browserTools` (one PluginTool per declared browser tool). The
+ * resulting sub-agent calls the FE-declared tools and waits for the
+ * reverse-flowed result.
+ */
+export function createPortalSubAgent(tools) {
+    const toolsDoc = formatToolDocs(tools);
+    return {
+        name: 'Portal Agent',
+        description: buildPortalDescription(tools),
+        systemPrompt: buildPortalPrompt({ toolsDoc }),
+        tools,
+        model: 'subagent',
+        middlewares: [],
+    };
+}

package/dist/plugins/portal/portal.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';
+/**
+ * Portal plugin. The sub-agent is built per-request from `state.browserTools`
+ * — the client declares its browser-side tools on each `sendMessage`, the
+ * runtime wraps each into a PluginTool, and the agent decides whether to
+ * delegate. When no browser tools are declared the plugin contributes
+ * nothing.
+ */
+export declare class PortalPlugin extends OraclePlugin {
+    readonly name = "portal";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    getRequestSubAgents(rtCtx: RuntimeContext): Promise<PluginSubAgent[]>;
+}
+//# sourceMappingURL=portal.plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"portal.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/portal/portal.plugin.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEjE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EAEd,cAAc,EACf,MAAM,2BAA2B,CAAC;AAgHnC;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,QAAQ,CAAC,IAAI,YAAY;IAEzB,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/portal/portal.plugin.js

@@ -0,0 +1,115 @@
+import { callBrowserTool, logActionToMatrix } from '@ixo/common';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { tool } from '../../plugin-api/tool-helper.js';
+import { createPortalSubAgent } from './portal-agent.js';
+const manifest = {
+    title: 'Portal',
+    summary: "Browser-side actions on the user's Portal UI — opens URLs, manipulates the DOM, runs FE-defined browser tools.",
+    whenToUse: [
+        'User asks for an action the Portal FE exposes as a browser tool (declared in `state.browserTools`).',
+        "A task needs a browser-side capability the server can't do alone — open a URL in the user's tab, click a Portal button, fill a form.",
+    ],
+    whenNotToUse: [
+        'No browser tools are declared on this request (sub-agent is not built).',
+        'The task can be completed purely server-side (use a server tool or sub-agent).',
+    ],
+    examples: [
+        {
+            user: 'Open my workspace and navigate to the Reports page.',
+            thought: 'Portal exposes navigation as a browser tool — delegate via call_portal_agent with the target URL.',
+            tool: 'call_portal_agent',
+        },
+    ],
+    tags: ['portal', 'browser', 'ui'],
+    category: 'ui',
+    visibility: 'on-demand',
+    stability: 'stable',
+};
+/** Default per-tool timeout — matches today's `parserBrowserTool`. */
+const BROWSER_TOOL_TIMEOUT_MS = 15_000;
+const BROWSER_TOOL_SHAPE = z.object({
+    name: z.string(),
+    description: z.string(),
+    schema: z.record(z.string(), z.unknown()),
+});
+const ARGS_RECORD_SHAPE = z.record(z.string(), z.unknown());
+function parseBrowserTools(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        const parsed = BROWSER_TOOL_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 browser tool to
+ * the user's frontend via the existing `callBrowserTool` helper and waits for
+ * the result. Mirrors today's `parserBrowserTool` behaviour (matrix logging on
+ * success, `tc-${requestId}` tool-call id) but sources `sessionId`,
+ * `requestId`, and `roomId` from `RuntimeContext` instead of LangChain's
+ * configurable bag.
+ */
+function buildBrowserTool(descriptor) {
+    return tool(async (input, ctx) => {
+        const sessionId = ctx.session.id;
+        if (!sessionId) {
+            throw new Error('sessionId is required for browser tools');
+        }
+        const args = parseArgs(input);
+        const requestId = ctx.session.requestId;
+        const toolCallId = `tc-${requestId ?? 'noreq'}`;
+        const result = await callBrowserTool({
+            sessionId,
+            toolCallId,
+            toolName: descriptor.name,
+            args,
+            timeout: BROWSER_TOOL_TIMEOUT_MS,
+        });
+        if (ctx.session.roomId) {
+            void logActionToMatrix({
+                name: descriptor.name,
+                args,
+                result,
+                success: true,
+            }, {
+                roomId: ctx.session.roomId,
+                threadId: sessionId,
+            });
+        }
+        return result;
+    }, {
+        name: descriptor.name,
+        description: descriptor.description,
+        schema: z.fromJSONSchema(descriptor.schema),
+    });
+}
+function readBrowserTools(rtCtx) {
+    return parseBrowserTools(rtCtx.history.state.browserTools);
+}
+/**
+ * Portal plugin. The sub-agent is built per-request from `state.browserTools`
+ * — the client declares its browser-side tools on each `sendMessage`, the
+ * runtime wraps each into a PluginTool, and the agent decides whether to
+ * delegate. When no browser tools are declared the plugin contributes
+ * nothing.
+ */
+export class PortalPlugin extends OraclePlugin {
+    name = 'portal';
+    version = '1.0.0';
+    manifest = manifest;
+    async getRequestSubAgents(rtCtx) {
+        const browserTools = readBrowserTools(rtCtx);
+        if (browserTools.length === 0)
+            return [];
+        const tools = browserTools.map(buildBrowserTool);
+        return [createPortalSubAgent(tools)];
+    }
+}

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

@@ -0,0 +1,3 @@
+export { SandboxPlugin, type SandboxMcpClientFactory, type SandboxMcpClientLike, type SandboxMcpTool, type SandboxPluginOptions, } from './sandbox.plugin.js';
+export { parseOracleSecrets, SANDBOX_RUN_TOOL_NAME, type SandboxAuthBuilder, type SandboxHeaderInputs, } from './sandbox-mcp.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC"}

package/dist/plugins/sandbox/index.js

@@ -0,0 +1,2 @@
+export { SandboxPlugin, } from './sandbox.plugin.js';
+export { parseOracleSecrets, SANDBOX_RUN_TOOL_NAME, } from './sandbox-mcp.js';

package/dist/plugins/sandbox/sandbox-mcp.d.ts

@@ -0,0 +1,46 @@
+import type { RuntimeContext } from '../../plugin-api/types.js';
+/** Tool name surfaced by the upstream sandbox MCP. */
+export declare const SANDBOX_RUN_TOOL_NAME = "sandbox_run";
+/**
+ * Parse the `ORACLE_SECRETS` env value (format: `KEY1=value1,KEY2=value2`).
+ *
+ * Lifted from `apps/app/src/graph/agents/main-agent.ts` (lines 752-763).
+ * Whitespace around keys and values is trimmed; entries lacking an `=` or
+ * an empty key/value are skipped silently so a stray comma can't break boot.
+ */
+export declare function parseOracleSecrets(raw: string): Record<string, string>;
+/** Inputs to a {@link SandboxAuthBuilder} invocation. */
+export interface SandboxHeaderInputs {
+    /** Sandbox MCP base URL — resolved to a did:web audience. */
+    sandboxMcpUrl: string;
+    /** Optional skills-service base URL for the X-Skills-Invocation header. */
+    skillsServiceUrl?: string;
+    /** Oracle operator secrets — mapped to `x-os-{key}` headers. */
+    oracleSecrets: Record<string, string>;
+    /** Per-room user secrets — mapped to `x-us-{key}` headers. */
+    userSecrets: Record<string, string>;
+}
+/**
+ * Mints the headers needed to call the sandbox MCP server on behalf of
+ * the current user. Encapsulates the four security-sensitive steps:
+ *
+ * 1. Resolve the sandbox service DID via did:web.
+ * 2. Mint an `ixo:sandbox` UCAN invocation → `Authorization: Bearer ...`.
+ * 3. Optionally mint a parallel `ixo:skills` invocation →
+ *    `X-Skills-Invocation: ...` (forwarded by sandbox to the skills service).
+ * 4. Layer oracle + user secrets as `x-os-*` / `x-us-*` headers.
+ *
+ * UCAN-only — no Matrix-OpenID fallback. If minting fails for any reason
+ * (no signing key, no cached delegation, did:web unresolved) the returned
+ * header set simply omits the relevant token and the downstream service
+ * surfaces a clean unauthorized error instead of leaking a half-built
+ * request.
+ */
+export type SandboxAuthBuilder = (inputs: SandboxHeaderInputs, runCtx: RuntimeContext) => Promise<Record<string, string>>;
+/**
+ * Default {@link SandboxAuthBuilder}. Service-DID resolution and caching is
+ * delegated to `runCtx.ucan.resolveServiceDid` (cached per origin inside the
+ * Tier-0 UCAN service), so this builder is stateless.
+ */
+export declare function createDefaultAuthBuilder(): SandboxAuthBuilder;
+//# sourceMappingURL=sandbox-mcp.d.ts.map

package/dist/plugins/sandbox/sandbox-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-mcp.d.ts","sourceRoot":"","sources":["../../../src/plugins/sandbox/sandbox-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWtE;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAErC;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,CA8D7D"}

package/dist/plugins/sandbox/sandbox-mcp.js

@@ -0,0 +1,80 @@
+/** Tool name surfaced by the upstream sandbox MCP. */
+export const SANDBOX_RUN_TOOL_NAME = 'sandbox_run';
+/**
+ * Parse the `ORACLE_SECRETS` env value (format: `KEY1=value1,KEY2=value2`).
+ *
+ * Lifted from `apps/app/src/graph/agents/main-agent.ts` (lines 752-763).
+ * Whitespace around keys and values is trimmed; entries lacking an `=` or
+ * an empty key/value are skipped silently so a stray comma can't break boot.
+ */
+export function parseOracleSecrets(raw) {
+    const out = {};
+    if (!raw)
+        return out;
+    for (const pair of raw.split(',')) {
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx <= 0)
+            continue;
+        const key = pair.slice(0, eqIdx).trim();
+        const val = pair.slice(eqIdx + 1).trim();
+        if (key && val)
+            out[key] = val;
+    }
+    return out;
+}
+/**
+ * Default {@link SandboxAuthBuilder}. Service-DID resolution and caching is
+ * delegated to `runCtx.ucan.resolveServiceDid` (cached per origin inside the
+ * Tier-0 UCAN service), so this builder is stateless.
+ */
+export function createDefaultAuthBuilder() {
+    return async (inputs, runCtx) => {
+        const headers = {};
+        const sandboxDid = await runCtx.ucan.resolveServiceDid(inputs.sandboxMcpUrl);
+        if (sandboxDid) {
+            try {
+                const invocation = await runCtx.ucan.mintInvocation({
+                    did: sandboxDid,
+                    capability: 'ixo:sandbox',
+                });
+                if (invocation) {
+                    headers.Authorization = `Bearer ${invocation}`;
+                    headers['X-Auth-Type'] = 'ucan';
+                }
+            }
+            catch (error) {
+                const detail = error instanceof Error
+                    ? `${error.name}: ${error.message}`
+                    : String(error);
+                runCtx.logger.warn(`[sandbox] failed to mint sandbox UCAN invocation: ${detail}`);
+            }
+        }
+        if (inputs.skillsServiceUrl) {
+            const skillsDid = await runCtx.ucan.resolveServiceDid(inputs.skillsServiceUrl);
+            if (skillsDid) {
+                try {
+                    const skillsInvocation = await runCtx.ucan.mintInvocation({
+                        did: skillsDid,
+                        capability: 'ixo:skills',
+                    });
+                    if (skillsInvocation) {
+                        headers['X-Skills-Invocation'] = skillsInvocation;
+                    }
+                }
+                catch (error) {
+                    const detail = error instanceof Error
+                        ? `${error.name}: ${error.message}`
+                        : String(error);
+                    runCtx.logger.warn(`[sandbox] failed to mint skills UCAN invocation: ${detail}`);
+                }
+            }
+        }
+        for (const [k, v] of Object.entries(inputs.oracleSecrets)) {
+            headers[`x-os-${k.toLowerCase()}`] = v;
+        }
+        for (const [k, v] of Object.entries(inputs.userSecrets)) {
+            headers[`x-us-${k.toLowerCase()}`] = v;
+        }
+        return headers;
+    };
+}