@ixo/oracle-runtime 0.0.1

package/dist/registries/tool-registry.d.ts

@@ -0,0 +1,74 @@
+import type { OraclePlugin } from '../plugin-api/oracle-plugin.js';
+import type { PluginContext, PluginTool, RuntimeContext } from '../plugin-api/types.js';
+/** A collected tool tagged with the plugin that contributed it. */
+export interface RegisteredTool {
+    pluginName: string;
+    tool: PluginTool;
+}
+/**
+ * Stores plugins that contribute tools and resolves them lazily by invoking
+ * each plugin's `getTools(buildCtx)` once at collection time.
+ *
+ * Tools live in a flat namespace — duplicate names across plugins are a
+ * boot error caught by `assertNoCollisions()`.
+ *
+ * Boot-time outputs from `getTools(buildCtx)` are cached after the first
+ * `collectBoot(buildCtx)` call. The request hot path only re-runs each
+ * plugin's `getRequestTools(rtCtx)` — request-time variation lives there.
+ *
+ * ## Cache safety / cross-user isolation
+ *
+ * `PluginContext` (the `buildCtx` passed to `getTools`) is **defined by
+ * `plugin-api/types.ts` to hold no user, session, or request data** — it
+ * only carries `{ config, identity, availablePlugins, logger }`, all
+ * oracle-scoped and stable for the process lifetime.
+ *
+ * Cached `PluginTool` objects are therefore safe to share between users:
+ * their handlers receive a fresh `RuntimeContext` from `wrapPluginTool`
+ * on every invocation, and that per-request context is what carries
+ * `user.did`, `session.id`, `ucanDelegation`, etc. The cache stores
+ * static tool definitions; per-request wrapping is always fresh.
+ */
+export declare class ToolRegistry {
+    private readonly plugins;
+    private bootCache;
+    private collected;
+    /** Add a plugin whose `getTools` will be called at `collect()` time. */
+    register(plugin: OraclePlugin): void;
+    /**
+     * Run every plugin's `getTools(buildCtx)` once and cache the result. Safe
+     * to call multiple times — subsequent calls return the cached list.
+     */
+    collectBoot(buildCtx: PluginContext): Promise<RegisteredTool[]>;
+    /**
+     * Run every plugin's `getRequestTools(rtCtx)`. Does NOT touch the boot
+     * cache — boot-time tools must be collected via `collectBoot(buildCtx)`
+     * before the first request.
+     */
+    collectRequest(rtCtx: RuntimeContext): Promise<RegisteredTool[]>;
+    /**
+     * Combined boot + request collection used by the main agent build. Uses
+     * the cached boot output when present so per-request rebuilds skip the
+     * `getTools` invocations that don't depend on runtime state.
+     */
+    collect(buildCtx: PluginContext, rtCtx?: RuntimeContext): Promise<RegisteredTool[]>;
+    /** The flat list of tool names produced by the most recent `collect()`. */
+    toolNames(): string[];
+    /**
+     * Tool names contributed by a given plugin in the most recent `collect()`
+     * (or `collectBoot()` if no full collection has happened yet).
+     */
+    toolNamesForPlugin(pluginName: string): string[];
+    /**
+     * The tools contributed by a given plugin in the most recent collection
+     * (boot-only if a full request collection has not yet happened).
+     */
+    toolsForPlugin(pluginName: string): PluginTool[];
+    /**
+     * Throw if two plugins contribute a tool with the same name. The error
+     * message names every colliding plugin pair so the boot log points at the
+     * actual conflict.
+     */
+    assertNoCollisions(): void;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/registries/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/registries/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACf,MAAM,wBAAwB,CAAC;AAEhC,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,SAAS,CAAiC;IAElD,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAMpC;;;OAGG;IACG,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAcrE;;;;OAIG;IACG,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAYtE;;;;OAIG;IACG,OAAO,CACX,QAAQ,EAAE,aAAa,EACvB,KAAK,CAAC,EAAE,cAAc,GACrB,OAAO,CAAC,cAAc,EAAE,CAAC;IAQ5B,2EAA2E;IAC3E,SAAS,IAAI,MAAM,EAAE;IAMrB;;;OAGG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAMhD;;;OAGG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,EAAE;IAMhD;;;;OAIG;IACH,kBAAkB,IAAI,IAAI;CAuB3B"}

package/dist/registries/tool-registry.js

@@ -0,0 +1,130 @@
+/**
+ * Stores plugins that contribute tools and resolves them lazily by invoking
+ * each plugin's `getTools(buildCtx)` once at collection time.
+ *
+ * Tools live in a flat namespace — duplicate names across plugins are a
+ * boot error caught by `assertNoCollisions()`.
+ *
+ * Boot-time outputs from `getTools(buildCtx)` are cached after the first
+ * `collectBoot(buildCtx)` call. The request hot path only re-runs each
+ * plugin's `getRequestTools(rtCtx)` — request-time variation lives there.
+ *
+ * ## Cache safety / cross-user isolation
+ *
+ * `PluginContext` (the `buildCtx` passed to `getTools`) is **defined by
+ * `plugin-api/types.ts` to hold no user, session, or request data** — it
+ * only carries `{ config, identity, availablePlugins, logger }`, all
+ * oracle-scoped and stable for the process lifetime.
+ *
+ * Cached `PluginTool` objects are therefore safe to share between users:
+ * their handlers receive a fresh `RuntimeContext` from `wrapPluginTool`
+ * on every invocation, and that per-request context is what carries
+ * `user.did`, `session.id`, `ucanDelegation`, etc. The cache stores
+ * static tool definitions; per-request wrapping is always fresh.
+ */
+export class ToolRegistry {
+    plugins = [];
+    bootCache = null;
+    collected = null;
+    /** Add a plugin whose `getTools` will be called at `collect()` time. */
+    register(plugin) {
+        this.plugins.push(plugin);
+        this.bootCache = null;
+        this.collected = null;
+    }
+    /**
+     * Run every plugin's `getTools(buildCtx)` once and cache the result. Safe
+     * to call multiple times — subsequent calls return the cached list.
+     */
+    async collectBoot(buildCtx) {
+        if (this.bootCache !== null)
+            return this.bootCache;
+        const out = [];
+        for (const plugin of this.plugins) {
+            if (!plugin.getTools)
+                continue;
+            const tools = await plugin.getTools(buildCtx);
+            for (const tool of tools) {
+                out.push({ pluginName: plugin.name, tool });
+            }
+        }
+        this.bootCache = out;
+        return out;
+    }
+    /**
+     * Run every plugin's `getRequestTools(rtCtx)`. Does NOT touch the boot
+     * cache — boot-time tools must be collected via `collectBoot(buildCtx)`
+     * before the first request.
+     */
+    async collectRequest(rtCtx) {
+        const out = [];
+        for (const plugin of this.plugins) {
+            if (!plugin.getRequestTools)
+                continue;
+            const requestTools = await plugin.getRequestTools(rtCtx);
+            for (const tool of requestTools) {
+                out.push({ pluginName: plugin.name, tool });
+            }
+        }
+        return out;
+    }
+    /**
+     * Combined boot + request collection used by the main agent build. Uses
+     * the cached boot output when present so per-request rebuilds skip the
+     * `getTools` invocations that don't depend on runtime state.
+     */
+    async collect(buildCtx, rtCtx) {
+        const boot = await this.collectBoot(buildCtx);
+        const request = rtCtx ? await this.collectRequest(rtCtx) : [];
+        const out = [...boot, ...request];
+        this.collected = out;
+        return out;
+    }
+    /** The flat list of tool names produced by the most recent `collect()`. */
+    toolNames() {
+        return (this.collected ?? this.bootCache ?? []).map((entry) => entry.tool.name);
+    }
+    /**
+     * Tool names contributed by a given plugin in the most recent `collect()`
+     * (or `collectBoot()` if no full collection has happened yet).
+     */
+    toolNamesForPlugin(pluginName) {
+        return (this.collected ?? this.bootCache ?? [])
+            .filter((entry) => entry.pluginName === pluginName)
+            .map((entry) => entry.tool.name);
+    }
+    /**
+     * The tools contributed by a given plugin in the most recent collection
+     * (boot-only if a full request collection has not yet happened).
+     */
+    toolsForPlugin(pluginName) {
+        return (this.collected ?? this.bootCache ?? [])
+            .filter((entry) => entry.pluginName === pluginName)
+            .map((entry) => entry.tool);
+    }
+    /**
+     * Throw if two plugins contribute a tool with the same name. The error
+     * message names every colliding plugin pair so the boot log points at the
+     * actual conflict.
+     */
+    assertNoCollisions() {
+        const source = this.collected ?? this.bootCache;
+        if (source === null) {
+            throw new Error('ToolRegistry.assertNoCollisions called before collect');
+        }
+        const seen = new Map();
+        const collisions = [];
+        for (const { pluginName, tool } of source) {
+            const prev = seen.get(tool.name);
+            if (prev !== undefined && prev !== pluginName) {
+                collisions.push(`Tool "${tool.name}" registered by both "${prev}" and "${pluginName}"`);
+            }
+            else if (prev === undefined) {
+                seen.set(tool.name, pluginName);
+            }
+        }
+        if (collisions.length > 0) {
+            throw new Error(`ToolRegistry: tool name collisions detected:\n  - ${collisions.join('\n  - ')}`);
+        }
+    }
+}

package/dist/runtime-context/ambient.d.ts

@@ -0,0 +1,118 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { ChatOpenAIFields, Logger, MatrixEvent, ModelRole, OracleIdentity, RoomStateSnapshot, SecretIndex } from '../plugin-api/types.js';
+/**
+ * Per-room secrets adapter. Wraps the host's secrets service so plugins
+ * never reach for a singleton directly.
+ */
+export interface SecretsAdapter {
+    getIndex(roomId: string): Promise<SecretIndex>;
+    getValues(roomId: string, keys: string[]): Promise<Record<string, string>>;
+}
+/**
+ * Blob-store adapter — short-TTL keyed store for content that should never
+ * be relayed through the LLM. Wraps `BlobStoreService` so plugins reach
+ * it only via the narrow `rtCtx.blobStore` shape.
+ */
+export interface BlobStoreAdapter {
+    put(params: {
+        userDid: string;
+        name: string;
+        value: string;
+        ttlSeconds?: number;
+    }): Promise<string>;
+    get(params: {
+        userDid: string;
+        blobId: string;
+    }): Promise<{
+        name: string;
+        value: string;
+    } | null>;
+    isValidBlobId(value: unknown): value is string;
+}
+/** Matrix adapter exposing only scoped operations a plugin should ever need. */
+export interface MatrixAdapter {
+    postToRoom(roomId: string, content: unknown): Promise<string>;
+    getRoomState(roomId: string): Promise<RoomStateSnapshot>;
+    getEventById(roomId: string, eventId: string): Promise<MatrixEvent>;
+}
+/** LLM adapter — turns role tags into chat models. */
+export interface LlmAdapter {
+    get(role: ModelRole, params?: ChatOpenAIFields): BaseChatModel;
+}
+/** UCAN adapter — capability checks and downstream invocation minting. */
+export interface UcanAdapter {
+    hasCapability(delegation: {
+        capabilities?: ReadonlyArray<{
+            resource: string;
+            action: string;
+        }>;
+    } | undefined, resource: string, action: string): boolean;
+    requireCapability(delegation: {
+        capabilities?: ReadonlyArray<{
+            resource: string;
+            action: string;
+        }>;
+    } | undefined, resource: string, action: string): void;
+    mintInvocation(userDid: string, target: {
+        did: string;
+        capability: string;
+    }, opts?: {
+        skipCache?: boolean;
+    }): Promise<string>;
+    /**
+     * Resolve a downstream service URL to its did:web identifier (fetched
+     * once from `/.well-known/did.json` and cached by origin). Returns `null`
+     * when the document is missing or has no `id` — callers degrade gracefully
+     * instead of throwing.
+     */
+    resolveServiceDid(serviceUrl: string): Promise<string | null>;
+    /**
+     * `true` once the oracle has loaded its Ed25519 signing mnemonic at boot.
+     * Plugins that mint downstream invocations (e.g. the editor's
+     * `mint_invocation` tool) gate registration on this — without a signing
+     * key, minting is a no-op and the tool should advertise an error instead
+     * of pretending to work.
+     */
+    hasSigningKey(): boolean;
+    /**
+     * Mint a UCAN invocation from a directly-supplied delegation CAR — used
+     * when the caller has the user's signed delegation in hand (typically read
+     * from a flow's Y.Doc by CID) and wants a freshly-targeted invocation
+     * against a specific service route. Returns `{ invocation }` on success
+     * or `{ error }` with a surfaced-verbatim reason on failure (signing key
+     * missing, delegation audience mismatch, did:web unreachable, etc.).
+     */
+    createInvocationFromDelegation(delegationCar: string, serviceUrl: string, capability: {
+        can: string;
+        with: string;
+    }, options?: {
+        maxTtlSeconds?: number;
+    }): Promise<{
+        invocation: string;
+    } | {
+        error: string;
+    }>;
+}
+/** Raw event payload — what callers pass before the scoped emitter adds session/request ids. */
+export type RawEventPayload = Record<string, unknown>;
+/** Low-level event sink used by the scoped emitter. */
+export interface EmitAdapter {
+    emit(eventName: string, payload: RawEventPayload): void;
+}
+/**
+ * Ambient services bag captured once at boot. Lives behind PluginContext /
+ * RuntimeContext synthesis — never exposed to plugin authors directly.
+ */
+export interface AmbientServices {
+    config: Record<string, unknown>;
+    identity: OracleIdentity;
+    availablePlugins: ReadonlySet<string>;
+    secrets: SecretsAdapter;
+    blobStore: BlobStoreAdapter;
+    matrix: MatrixAdapter;
+    llm: LlmAdapter;
+    emit: EmitAdapter;
+    ucan: UcanAdapter;
+    logger: Logger;
+}
+//# sourceMappingURL=ambient.d.ts.map

package/dist/runtime-context/ambient.d.ts.map

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

package/dist/runtime-context/ambient.js

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

package/dist/runtime-context/build-plugin.d.ts

@@ -0,0 +1,20 @@
+import type { Logger, MergedConfig, OracleIdentity, PluginContext } from '../plugin-api/types.js';
+export interface BuildPluginContextInput<TConfig = MergedConfig> {
+    /** Merged Zod-validated env (core + every loaded plugin's `configSchema`). */
+    config: TConfig;
+    /** Identity of this oracle, set by the fork at `createOracleApp`. */
+    identity: OracleIdentity;
+    /** Names of the plugins resolved at boot. */
+    availablePlugins: ReadonlySet<string>;
+    /** Base logger; auto-bound to the calling plugin's name when supported. */
+    logger: Logger;
+    /** Plugin name used to scope the logger. */
+    pluginName: string;
+}
+/**
+ * Build the boot-time PluginContext passed to plugin methods that produce
+ * tools, sub-agents and middlewares. Lives once per request build — holds no
+ * user, no session, no live socket, no request data.
+ */
+export declare function buildPluginContext<TConfig = MergedConfig>(input: BuildPluginContextInput<TConfig>): PluginContext<TConfig>;
+//# sourceMappingURL=build-plugin.d.ts.map

package/dist/runtime-context/build-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-plugin.d.ts","sourceRoot":"","sources":["../../src/runtime-context/build-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,YAAY,EACZ,cAAc,EACd,aAAa,EACd,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,uBAAuB,CAAC,OAAO,GAAG,YAAY;IAC7D,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,QAAQ,EAAE,cAAc,CAAC;IACzB,6CAA6C;IAC7C,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAG,YAAY,EACvD,KAAK,EAAE,uBAAuB,CAAC,OAAO,CAAC,GACtC,aAAa,CAAC,OAAO,CAAC,CAWxB"}

package/dist/runtime-context/build-plugin.js

@@ -0,0 +1,16 @@
+/**
+ * Build the boot-time PluginContext passed to plugin methods that produce
+ * tools, sub-agents and middlewares. Lives once per request build — holds no
+ * user, no session, no live socket, no request data.
+ */
+export function buildPluginContext(input) {
+    const scopedLogger = input.logger.child
+        ? input.logger.child({ plugin: input.pluginName })
+        : input.logger;
+    return {
+        config: input.config,
+        identity: input.identity,
+        availablePlugins: input.availablePlugins,
+        logger: scopedLogger,
+    };
+}

package/dist/runtime-context/build-runtime.d.ts

@@ -0,0 +1,60 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { MergedConfig, RuntimeContext, SharedAccessors, UcanDelegation, UserContextData } from '../plugin-api/types.js';
+import type { AmbientServices } from './ambient.js';
+/** Fixed empty `shared` accessors — frozen so callers can't mutate. */
+declare const EMPTY_SHARED: SharedAccessors;
+/**
+ * The user channel passed in via LangGraph's per-run context. Mirrors today's
+ * `state.config` + auth headers consumed by the request middleware.
+ */
+export interface RuntimeUserContext {
+    did: string;
+    matrixUserId: string;
+    ucanDelegation: UcanDelegation;
+    timezone?: string;
+    currentTime?: string;
+}
+/** Session info threaded through from `SessionsService`. */
+export interface RuntimeSessionContext {
+    id: string;
+    client: 'portal' | 'matrix' | 'slack';
+    wsId?: string;
+    requestId: string;
+    roomId?: string;
+}
+/** What LangGraph hands us at invocation time on `runtime.context`. */
+export interface RunConfigContext {
+    user: RuntimeUserContext;
+    session: RuntimeSessionContext;
+}
+/**
+ * The `runtime` argument passed to a tool handler in LangGraph v1. We read
+ * the `context` channel, the optional `signal`, and the optional `toolCall`
+ * (populated by LangChain when the handler runs in response to a model tool
+ * call — surfaced on `RuntimeContext.toolCallId`).
+ */
+export interface RunConfig {
+    context: RunConfigContext;
+    signal?: AbortSignal;
+    toolCall?: {
+        id?: string;
+    };
+}
+/**
+ * Minimum shape of the graph state that build-runtime depends on. Real graphs
+ * extend this freely.
+ */
+export interface RuntimeStateInput {
+    messages: readonly BaseMessage[];
+    userContext?: UserContextData;
+    loadedPlugins?: ReadonlySet<string>;
+    [key: string]: unknown;
+}
+/**
+ * Build the per-request RuntimeContext exposed to tool handlers, sub-agent
+ * handlers and plugin-middleware hooks. Synthesizes user/session from the
+ * LangGraph runtime channel, history from state, and the rest from ambient.
+ */
+export declare function buildRuntimeContext<TConfig = MergedConfig>(runConfig: RunConfig, ambient: AmbientServices, state: RuntimeStateInput): RuntimeContext<TConfig>;
+export { EMPTY_SHARED };
+//# sourceMappingURL=build-runtime.d.ts.map

package/dist/runtime-context/build-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime-context/build-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EACV,YAAY,EAEZ,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,uEAAuE;AACvE,QAAA,MAAM,YAAY,EAAE,eAAmC,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IACjC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAG,YAAY,EACxD,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,iBAAiB,GACvB,cAAc,CAAC,OAAO,CAAC,CA+FzB;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/runtime-context/build-runtime.js

@@ -0,0 +1,81 @@
+import { createScopedEmitter } from '../events/scoped-emitter.js';
+/** Fixed empty `shared` accessors — frozen so callers can't mutate. */
+const EMPTY_SHARED = Object.freeze({});
+/**
+ * Build the per-request RuntimeContext exposed to tool handlers, sub-agent
+ * handlers and plugin-middleware hooks. Synthesizes user/session from the
+ * LangGraph runtime channel, history from state, and the rest from ambient.
+ */
+export function buildRuntimeContext(runConfig, ambient, state) {
+    const session = runConfig.context.session;
+    const user = runConfig.context.user;
+    const messages = state.messages ?? [];
+    const userContext = state.userContext ?? {};
+    const loadedPlugins = state.loadedPlugins ?? new Set();
+    const recent = (n) => n <= 0 ? [] : messages.slice(Math.max(0, messages.length - n));
+    const readonlyState = {
+        ...state,
+        messages,
+        userContext,
+        loadedPlugins,
+    };
+    const emit = createScopedEmitter({ sessionId: session.id, requestId: session.requestId }, ambient.emit);
+    const abortSignal = runConfig.signal ?? new AbortController().signal;
+    const delegation = user.ucanDelegation;
+    return {
+        user,
+        session,
+        history: {
+            messages,
+            recent,
+            userContext,
+            state: readonlyState,
+        },
+        config: ambient.config,
+        availablePlugins: ambient.availablePlugins,
+        loadedPlugins,
+        secrets: {
+            getIndex: () => {
+                if (!session.roomId) {
+                    return Promise.resolve({});
+                }
+                return ambient.secrets.getIndex(session.roomId);
+            },
+            getValues: (keys) => {
+                if (!session.roomId) {
+                    return Promise.resolve({});
+                }
+                return ambient.secrets.getValues(session.roomId, keys);
+            },
+        },
+        blobStore: {
+            put: (params) => ambient.blobStore.put(params),
+            get: (params) => ambient.blobStore.get(params),
+            isValidBlobId: (value) => ambient.blobStore.isValidBlobId(value),
+        },
+        matrix: {
+            postToRoom: (roomId, content) => ambient.matrix.postToRoom(roomId, content),
+            getRoomState: (roomId) => ambient.matrix.getRoomState(roomId),
+            getEventById: (roomId, eventId) => ambient.matrix.getEventById(roomId, eventId),
+        },
+        ucan: {
+            hasCapability: (resource, action) => ambient.ucan.hasCapability(delegation, resource, action),
+            requireCapability: (resource, action) => {
+                ambient.ucan.requireCapability(delegation, resource, action);
+            },
+            mintInvocation: (target, opts) => ambient.ucan.mintInvocation(user.did, target, opts),
+            resolveServiceDid: (serviceUrl) => ambient.ucan.resolveServiceDid(serviceUrl),
+            hasSigningKey: () => ambient.ucan.hasSigningKey(),
+            createInvocationFromDelegation: (car, serviceUrl, capability, opts) => ambient.ucan.createInvocationFromDelegation(car, serviceUrl, capability, opts),
+        },
+        llm: {
+            get: (role, params) => ambient.llm.get(role, params),
+        },
+        emit,
+        logger: ambient.logger,
+        abortSignal,
+        shared: EMPTY_SHARED,
+        ...(runConfig.toolCall?.id ? { toolCallId: runConfig.toolCall.id } : {}),
+    };
+}
+export { EMPTY_SHARED };

package/dist/testing/create-test-runtime.d.ts

@@ -0,0 +1,95 @@
+import { type BaseMessage } from '@langchain/core/messages';
+import { type FeatureToggle } from '../bootstrap/plugin-loader.js';
+import type { OraclePlugin } from '../plugin-api/oracle-plugin.js';
+import type { Logger, OracleIdentity, PluginManifest, PluginTool, ReadonlyState, RuntimeContext } from '../plugin-api/types.js';
+import { type FetchHandler, type MockMatrixOverrides } from './mocks.js';
+/** Options accepted by `createTestRuntime`. */
+export interface CreateTestRuntimeOptions {
+    /** Plugins under test. Resolved via the production plugin loader. */
+    plugins: OraclePlugin[];
+    /**
+     * Feature toggles, same shape as `createOracleApp`. Defaults to `'auto'`
+     * for plugins that have an `autoDetect`, otherwise on.
+     */
+    features?: Partial<Record<string, FeatureToggle>>;
+    /** Merged config (env vars). Plugins read this through `ctx.config`. */
+    config?: Record<string, unknown>;
+    /** Override fields on the synthesized RuntimeContext.user. */
+    user?: Partial<RuntimeContext['user']>;
+    /** Override fields on the synthesized RuntimeContext.session. */
+    session?: Partial<RuntimeContext['session']>;
+    /** Override fields on the read-only state passed to invoked handlers. */
+    state?: Partial<ReadonlyState>;
+    /** Override the identity exposed to plugin builders. */
+    identity?: Partial<OracleIdentity>;
+    /** Logger. Defaults to a `vi.fn()`-backed no-op. */
+    logger?: Logger;
+    /** Mock adapter overrides. */
+    mocks?: {
+        fetch?: FetchHandler;
+        matrix?: MockMatrixOverrides;
+        secrets?: Record<string, string>;
+        llm?: {
+            respondWith?: string | string[];
+        };
+    };
+}
+/** A `list_capabilities`-shaped row. */
+export interface CapabilityListing {
+    name: string;
+    summary: string;
+    visibility: NonNullable<PluginManifest['visibility']>;
+    loaded: boolean;
+    category?: PluginManifest['category'];
+    tags: string[];
+}
+/** Public surface of the test runtime. */
+export interface TestRuntime {
+    /** Invoke a tool by its registered name. */
+    invokeTool: (name: string, args: unknown) => Promise<unknown>;
+    /** Invoke a middleware's hooks in isolation. */
+    invokeMiddleware: (nameOrIndex: string | number, state: Record<string, unknown>, runtime?: {
+        context?: Record<string, unknown>;
+    }) => Promise<{
+        before?: unknown;
+        after?: unknown;
+    }>;
+    /** Invoke a sub-agent with a textual task; returns the LLM's first response. */
+    invokeSubAgent: (name: string, task: string) => Promise<string>;
+    /** List tools. Filter by plugin if supplied. */
+    listTools: (plugin?: string) => PluginTool[];
+    /** Read a plugin's manifest. Throws if unknown. */
+    getManifest: (plugin: string) => PluginManifest;
+    /** Same shape as the `list_capabilities` meta-tool. */
+    listCapabilities: () => CapabilityListing[];
+    /** Add a plugin to `loadedPlugins` for subsequent calls. */
+    loadCapability: (name: string) => void;
+    /** Throws on any registry collision. */
+    assertNoCollisions: () => void;
+    /** Throws on any invalid manifest. */
+    assertManifestValid: () => void;
+    /**
+     * Stub for full agent invocation. Throws — full agent assembly lands once
+     * `createMainAgent` is consumed by `createOracleApp`.
+     */
+    invokeAgent: (messages: BaseMessage[]) => Promise<{
+        messages: BaseMessage[];
+    }>;
+    /** Mock-control surface; rebinds the underlying ambient services. */
+    mocks: {
+        matrix: (overrides: MockMatrixOverrides) => void;
+        fetch: (handler: FetchHandler) => void;
+    };
+    /** Cleanup — releases anything the harness allocated. */
+    close: () => Promise<void>;
+}
+/**
+ * Build a `TestRuntime` for unit-testing one or more plugins in isolation.
+ *
+ * The harness wires the same registries the production runtime does, so
+ * collisions, manifest validation, and meta-tool behavior all match what
+ * an oracle would see at boot. It does NOT spin up Matrix, Redis, or a
+ * real LLM — every ambient service is replaced with a mock by default.
+ */
+export declare function createTestRuntime(opts: CreateTestRuntimeOptions): Promise<TestRuntime>;
+//# sourceMappingURL=create-test-runtime.d.ts.map

package/dist/testing/create-test-runtime.d.ts.map

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