@ixo/oracle-runtime 0.0.1

package/dist/plugins/sandbox/sandbox-write-blob.d.ts

@@ -0,0 +1,22 @@
+import type { PluginTool } from '../../plugin-api/types.js';
+import type { SandboxMcpTool } from './sandbox.plugin.js';
+export interface CreateSandboxWriteBlobToolParams {
+    /** Upstream MCP `sandbox_write_file` tool — looked up once per request from
+     * the MCP client's tool list. Required; without it the wrapper has nothing
+     * to forward to. */
+    sandboxWriteFileTool: SandboxMcpTool;
+}
+/**
+ * `sandbox_write_blob` — companion to `mint_invocation`. Takes a `blobId`
+ * (server-side stored long string) and a sandbox path; looks up the blob in
+ * the `BlobStore` and calls the underlying `sandbox_write_file` MCP tool
+ * with the value. The LLM only ever passes the short blobId + path — long
+ * base64 strings (UCAN CARs etc.) never enter its context, so they can't be
+ * corrupted in transit.
+ *
+ * The plugin must only register this tool when the upstream `sandbox_write_file`
+ * tool exists AND the request has a known user DID — without either the
+ * wrapper degrades into an always-failing stub, which is worse than absent.
+ */
+export declare function createSandboxWriteBlobTool(params: CreateSandboxWriteBlobToolParams): PluginTool;
+//# sourceMappingURL=sandbox-write-blob.d.ts.map

package/dist/plugins/sandbox/sandbox-write-blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-write-blob.d.ts","sourceRoot":"","sources":["../../../src/plugins/sandbox/sandbox-write-blob.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,2BAA2B,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAyB1D,MAAM,WAAW,gCAAgC;IAC/C;;wBAEoB;IACpB,oBAAoB,EAAE,cAAc,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,gCAAgC,GACvC,UAAU,CAqDZ"}

package/dist/plugins/sandbox/sandbox-write-blob.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { tool as pluginTool } from '../../plugin-api/tool-helper.js';
+const sandboxWriteBlobSchema = z.object({
+    blobId: z
+        .string()
+        .describe('The blobId returned by the tool that produced the value (e.g. mint_invocation). Format: `blob_<16 hex chars>`.'),
+    path: z
+        .string()
+        .describe('Destination path in the sandbox, e.g. `/workspace/data/<skill>/ucan_token`. Must be under /workspace/data/.'),
+});
+const SANDBOX_WRITE_BLOB_DESCRIPTION = `Write a server-stored blob to a file in the sandbox without ever paste-relaying the value through the LLM.
+
+Use this whenever a tool returns a \`blobId\` (e.g. \`mint_invocation\`'s response). Pass the blobId + the destination path; the runtime looks the value up server-side and calls sandbox_write_file with its content. The long opaque value (base64 CARs, JWTs, etc.) never enters the LLM context — eliminates string-corruption-in-relay as a failure mode.
+
+Inputs:
+  - blobId: short hex identifier returned by the producing tool (format \`blob_<16 hex chars>\`).
+  - path: destination path in the sandbox. Must be under \`/workspace/data/\` (the sandbox enforces this; writes elsewhere are rejected).
+
+Returns: \`{ success: true, path, bytesWritten }\` on success, \`{ success: false, error }\` on failure. Common errors: blob not found (re-mint and retry — for invocations this can happen on a multi-replica deployment if the lookup lands on a different process), invalid blobId format, path outside /workspace/data/.`;
+/**
+ * `sandbox_write_blob` — companion to `mint_invocation`. Takes a `blobId`
+ * (server-side stored long string) and a sandbox path; looks up the blob in
+ * the `BlobStore` and calls the underlying `sandbox_write_file` MCP tool
+ * with the value. The LLM only ever passes the short blobId + path — long
+ * base64 strings (UCAN CARs etc.) never enter its context, so they can't be
+ * corrupted in transit.
+ *
+ * The plugin must only register this tool when the upstream `sandbox_write_file`
+ * tool exists AND the request has a known user DID — without either the
+ * wrapper degrades into an always-failing stub, which is worse than absent.
+ */
+export function createSandboxWriteBlobTool(params) {
+    return pluginTool(async (rawArgs, ctx) => {
+        const { blobId, path } = sandboxWriteBlobSchema.parse(rawArgs);
+        if (!ctx.blobStore.isValidBlobId(blobId)) {
+            return JSON.stringify({
+                success: false,
+                error: `Invalid blobId format. Expected blob_<16 hex chars>, got "${blobId}".`,
+            });
+        }
+        if (typeof path !== 'string' || !path.startsWith('/workspace/data/')) {
+            return JSON.stringify({
+                success: false,
+                error: `path must be under /workspace/data/. Got: "${path}".`,
+            });
+        }
+        const userDid = ctx.user.did;
+        const blob = await ctx.blobStore.get({ userDid, blobId });
+        if (!blob) {
+            return JSON.stringify({
+                success: false,
+                error: `Blob "${blobId}" not found (expired, never existed, or owned by another user). Re-mint and retry — for single-use invocations this is expected if the blob's TTL elapsed.`,
+            });
+        }
+        try {
+            const result = await params.sandboxWriteFileTool.invoke({
+                path,
+                content: blob.value,
+                encoding: 'utf8',
+            });
+            return JSON.stringify({
+                success: true,
+                path,
+                bytesWritten: blob.value.length,
+                blobName: blob.name,
+                note: typeof result === 'string' ? result : undefined,
+            });
+        }
+        catch (err) {
+            return JSON.stringify({
+                success: false,
+                error: `sandbox_write_file failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }, {
+        name: 'sandbox_write_blob',
+        description: SANDBOX_WRITE_BLOB_DESCRIPTION,
+        schema: sandboxWriteBlobSchema,
+    });
+}

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

@@ -0,0 +1,80 @@
+import { type ClientConfig } from '@langchain/mcp-adapters';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginManifest, PluginTool, RuntimeContext } from '../../plugin-api/types.js';
+import { type SandboxAuthBuilder } from './sandbox-mcp.js';
+/** Minimal MCP-client surface — declared structurally so tests can stub it. */
+export interface SandboxMcpClientLike {
+    getTools(): Promise<SandboxMcpTool[]>;
+    close(): Promise<void>;
+}
+/** Shape of one upstream MCP tool. `@langchain/mcp-adapters` returns this. */
+export interface SandboxMcpTool {
+    name: string;
+    description: string;
+    schema: z.ZodType;
+    invoke(input: unknown): Promise<unknown>;
+}
+export type SandboxMcpClientFactory = (config: ClientConfig) => SandboxMcpClientLike;
+export interface SandboxPluginOptions {
+    /**
+     * Override the auth header builder. Tests inject a stub here to skip the
+     * did:web resolution + UCAN mint; production code lets the default builder
+     * do the network work.
+     */
+    authBuilder?: SandboxAuthBuilder;
+    /**
+     * Override the MCP-client constructor. Tests inject a stub so they can
+     * intercept the headers the plugin sends and the tools it gets back without
+     * standing up a real `MultiServerMCPClient`.
+     */
+    mcpClientFactory?: SandboxMcpClientFactory;
+    /**
+     * Opt-in to the upstream `oracle_*` management tools (`oracle_list`,
+     * `oracle_get`, `oracle_health`, `oracle_stop`, `oracle_restart`,
+     * `oracle_get_logs`). Off by default — these are operator-grade controls
+     * that most user-facing oracles should not surface to the agent. Flip this
+     * on for admin / dev-tooling oracles.
+     */
+    includeOracleManagementTools?: boolean;
+}
+/**
+ * Sandbox plugin.
+ *
+ * Surfaces every upstream sandbox MCP tool — `sandbox_run`, `sandbox_write_file`,
+ * the `artifact_*` family, `load_skill`, and the `oracle_*`
+ * management tools — to the main agent. Each tool flows through verbatim
+ * (name, description, schema all from upstream); the plugin's only job is to
+ * authenticate the MCP connection and forward operator + per-user secrets in
+ * the request headers.
+ *
+ * Headers are minted ONCE per request and include:
+ *   - `Authorization: Bearer <ixo:sandbox UCAN invocation>` + `X-Auth-Type: ucan`
+ *   - `X-Skills-Invocation` (when `SKILLS_CAPSULES_BASE_URL` is configured)
+ *   - `x-os-<name>` for each entry in `ORACLE_SECRETS`
+ *   - `x-us-<name>` for each per-room secret loaded from `SecretsService`
+ *
+ * Tools are discovered per request via {@link getRequestTools} because the
+ * MCP client has to be authenticated as the in-flight user.
+ */
+export declare class SandboxPlugin extends OraclePlugin {
+    /**
+     * Static handle other plugins use to test `availablePlugins.has(...)`
+     * without hardcoding the string. Mirrors the precedent set by `MemoryPlugin`.
+     */
+    static readonly NAME = "sandbox";
+    readonly name = "sandbox";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    readonly configSchema: z.ZodObject<{
+        SANDBOX_MCP_URL: z.ZodURL;
+    }, z.core.$strip>;
+    readonly autoDetectHint = "SANDBOX_MCP_URL";
+    private readonly authBuilder;
+    private readonly mcpClientFactory;
+    private readonly includeOracleManagementTools;
+    constructor(opts?: SandboxPluginOptions);
+    autoDetect(env: NodeJS.ProcessEnv): boolean;
+    getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]>;
+}
+//# sourceMappingURL=sandbox.plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/sandbox/sandbox.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAsG1B,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,MAAM,EAAE,YAAY,KACjB,oBAAoB,CAAC;AAK1B,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C;;;;;;OAMG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;CACxC;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,aAAa;IAEjC,QAAQ,CAAC,IAAI,aAAsB;IACnC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,QAAQ,iBAAY;IAC7B,SAAkB,YAAY;;sBAAgB;IAC9C,SAAkB,cAAc,qBAAqB;IAErD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0B;IAC3D,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAU;gBAE3C,IAAI,GAAE,oBAAyB;IAWlC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAIrC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CA+E7E"}

package/dist/plugins/sandbox/sandbox.plugin.js

@@ -0,0 +1,204 @@
+import { MultiServerMCPClient, } from '@langchain/mcp-adapters';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { createDefaultAuthBuilder, parseOracleSecrets, } from './sandbox-mcp.js';
+import { createSandboxWriteBlobTool } from './sandbox-write-blob.js';
+const configSchema = z.object({
+    SANDBOX_MCP_URL: z.url(),
+});
+/**
+ * Sibling env vars the plugin reads at boot but does not own:
+ *
+ * - `ORACLE_SECRETS` is declared in the core (Tier-0) base env schema; the
+ *   sandbox plugin parses it and injects each entry as an `x-os-*` header.
+ * - `SKILLS_CAPSULES_BASE_URL` is owned by the skills plugin. When set, the
+ *   sandbox plugin mints a parallel `ixo:skills` invocation and forwards it
+ *   as `X-Skills-Invocation` so the sandbox can call the skills service on
+ *   the user's behalf.
+ *
+ * Both fields are optional — a missing value simply skips the matching
+ * header instead of failing the plugin build.
+ */
+const siblingEnvSchema = z.object({
+    ORACLE_SECRETS: z.string().optional(),
+    SKILLS_CAPSULES_BASE_URL: z.url().optional(),
+});
+const manifest = {
+    title: 'Sandbox',
+    summary: 'Per-user Linux box for code execution. `sandbox_run` runs shell/python (writes anywhere via shell — incl. `/tmp` for scratch). `sandbox_write_file` writes raw bytes BUT only under `/workspace/data/` — paths like `/tmp/...` or `/workspace/tmp/...` are rejected; use `sandbox_run` for those.',
+    whenToUse: [
+        "Execute a skill — call `sandbox_run` with `cid` so user + oracle secrets are injected; the skill folder mounts read-only at `/workspace/skills/<skill-name>/` (use the absolute paths from `load_skill`'s `skillFiles`).",
+        'Read a skill file (SKILL.md, scripts, configs) — call `sandbox_run` with `cid` and shell: `cat /workspace/skills/<skill-name>/SKILL.md`, `ls /workspace/skills/<skill-name>/`, `grep -r "<pattern>" /workspace/skills/<skill-name>/`, or `sed -n "1,80p" <file>` for a line range. There is no dedicated `read_skill` tool.',
+        'Hit a JSON/REST API — write curl or python in `sandbox_run`. Never use a web scraper for `/api/`, `/v1/`, `/v2/`, `/v3/` endpoints.',
+        'Generate or transform a file the user (or a later turn) will re-read — write it to `/workspace/data/output/<name>` (alias `/workspace/output/`).',
+        'Re-read an attachment the user sent earlier — it was auto-archived to `/workspace/output/<filename>`; load from there.',
+        'Save a large or escape-sensitive blob (multi-line markdown, structured data) byte-perfect to `/workspace/data/...` — use `sandbox_write_file` so quoting bugs do not corrupt it.',
+        "Write a scratch / throwaway file (build artefacts, temp scripts you will execute then delete) — use `sandbox_run` with a here-doc: `cat > /tmp/<name> <<'EOF'\\n<content>\\nEOF`. Never use `sandbox_write_file` for `/tmp` or anywhere outside `/workspace/data/` — it will be rejected.",
+        'Always check the result envelope: `success === true` AND `exitCode === 0` before trusting `output`. On failure, READ the `error` text and change your approach — do not retry the same call with the same args.',
+    ],
+    whenNotToUse: [
+        'The value is already inline in chat — just use it; opening the sandbox to echo it back wastes a turn.',
+        'Fetching a URL the user just mentioned — prefer `process_file` so it auto-archives to `/workspace/output/`.',
+        'A long human-readable page (blog, article, news) — use the Firecrawl agent.',
+        'Installing native deps in cwd (`pip install -e .`, `bun install`) — `.venv`/`node_modules` get persisted to R2 and slow every future session. Install under `/tmp` (via `sandbox_run`) or inside the skill folder.',
+        '`sandbox_write_file` with a path outside `/workspace/data/` (e.g. `/tmp/foo`, `/workspace/tmp/foo`, `/workspace/output-only-if-data-prefix-missing`) — the validator hard-rejects this. For temp/scratch writes, switch to `sandbox_run`.',
+    ],
+    examples: [
+        {
+            user: "Read the pptx skill's instructions before generating slides.",
+            thought: "After `load_skill`, the SKILL.md path is the absolute path the response returned (e.g. /workspace/skills/pptx/SKILL.md). Cat it directly through sandbox_run — there's no separate read tool. Pass `cid` so the same skill context is in place.",
+            tool: 'sandbox_run',
+            args: {
+                code: 'cat /workspace/skills/pptx/SKILL.md',
+                cid: 'cid returned by list_skills / search_skills',
+            },
+        },
+        {
+            user: 'Run the price-forecast skill on the Q3 sales data.',
+            thought: 'Skill execution → pass the skill CID so user + oracle secrets are injected. Write the forecast to /workspace/data/output/ so the user can re-read it next turn.',
+            tool: 'sandbox_run',
+            args: {
+                code: 'cd /workspace/skills/price-forecast && bash run.sh "/workspace/output/q3-sales.csv" > /workspace/data/output/forecast.json',
+                cid: 'cid from list/search skills',
+            },
+        },
+        {
+            user: 'Compute monthly totals from the CSV I attached.',
+            thought: 'The attachment is at /workspace/output/<filename>. Use uv (preferred over pip in this sandbox) to materialize pandas. Write the result so the user can reuse it next turn.',
+            tool: 'sandbox_run',
+            args: {
+                code: "uv run --with pandas python -c \"import pandas as pd, json; df=pd.read_csv('/workspace/output/sales.csv'); out=df.groupby('month').sum().reset_index(); out.to_csv('/workspace/data/output/monthly_totals.csv', index=False); print(json.dumps({'rows': len(out)}))\"",
+            },
+        },
+        {
+            user: 'Save this draft report so I can come back to it tomorrow.',
+            thought: 'Multi-line markdown with quotes and code fences → write byte-perfect via sandbox_write_file (no shell-escaping). Persisted under /workspace/data so it survives across sessions.',
+            tool: 'sandbox_write_file',
+            args: {
+                path: '/workspace/data/output/draft-report.md',
+                content: '# Q3 Report\n\n## Findings\n\n...',
+            },
+        },
+        {
+            user: 'Build a one-off JS script to transform some data and run it.',
+            thought: 'Scratch script — runs once, then discarded. /tmp is the right home, but sandbox_write_file refuses anything outside /workspace/data/. Use sandbox_run with a here-doc to write + execute in one shot.',
+            tool: 'sandbox_run',
+            args: {
+                code: "cat > /tmp/transform.js <<'EOF'\nconst fs = require('fs');\nconst rows = JSON.parse(fs.readFileSync('/workspace/output/data.json'));\nconsole.log(JSON.stringify(rows.map(r => ({...r, normalized: r.value / 100}))));\nEOF\nnode /tmp/transform.js > /workspace/data/output/transformed.json",
+            },
+        },
+    ],
+    visibility: 'always',
+    stability: 'stable',
+    category: 'core',
+    tags: ['sandbox', 'execution', 'workspace', 'artifacts'],
+};
+/** Per-tool timeout for sandbox MCP calls (matches today's main-agent wiring). */
+const SANDBOX_MCP_TIMEOUT_MS = 180_000;
+/** Prefix the upstream sandbox MCP uses for operator-grade oracle controls. */
+const ORACLE_MANAGEMENT_TOOL_PREFIX = 'oracle_';
+/**
+ * Sandbox plugin.
+ *
+ * Surfaces every upstream sandbox MCP tool — `sandbox_run`, `sandbox_write_file`,
+ * the `artifact_*` family, `load_skill`, and the `oracle_*`
+ * management tools — to the main agent. Each tool flows through verbatim
+ * (name, description, schema all from upstream); the plugin's only job is to
+ * authenticate the MCP connection and forward operator + per-user secrets in
+ * the request headers.
+ *
+ * Headers are minted ONCE per request and include:
+ *   - `Authorization: Bearer <ixo:sandbox UCAN invocation>` + `X-Auth-Type: ucan`
+ *   - `X-Skills-Invocation` (when `SKILLS_CAPSULES_BASE_URL` is configured)
+ *   - `x-os-<name>` for each entry in `ORACLE_SECRETS`
+ *   - `x-us-<name>` for each per-room secret loaded from `SecretsService`
+ *
+ * Tools are discovered per request via {@link getRequestTools} because the
+ * MCP client has to be authenticated as the in-flight user.
+ */
+export class SandboxPlugin extends OraclePlugin {
+    /**
+     * Static handle other plugins use to test `availablePlugins.has(...)`
+     * without hardcoding the string. Mirrors the precedent set by `MemoryPlugin`.
+     */
+    static NAME = 'sandbox';
+    name = SandboxPlugin.NAME;
+    version = '1.0.0';
+    manifest = manifest;
+    configSchema = configSchema;
+    autoDetectHint = 'SANDBOX_MCP_URL';
+    authBuilder;
+    mcpClientFactory;
+    includeOracleManagementTools;
+    constructor(opts = {}) {
+        super();
+        this.authBuilder = opts.authBuilder ?? createDefaultAuthBuilder();
+        this.mcpClientFactory =
+            opts.mcpClientFactory ??
+                ((config) => new MultiServerMCPClient(config));
+        this.includeOracleManagementTools =
+            opts.includeOracleManagementTools ?? false;
+    }
+    autoDetect(env) {
+        return Boolean(env.SANDBOX_MCP_URL);
+    }
+    async getRequestTools(rtCtx) {
+        const parsed = configSchema.safeParse(rtCtx.config);
+        if (!parsed.success) {
+            throw new Error(`sandbox: invalid configuration: ${parsed.error.issues
+                .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+                .join('; ')}`);
+        }
+        const siblings = siblingEnvSchema.safeParse(rtCtx.config);
+        const skillsServiceUrl = siblings.success
+            ? siblings.data.SKILLS_CAPSULES_BASE_URL
+            : undefined;
+        const oracleSecretsRaw = siblings.success
+            ? (siblings.data.ORACLE_SECRETS ?? '')
+            : '';
+        const oracleSecrets = parseOracleSecrets(oracleSecretsRaw);
+        const userSecretIndex = await rtCtx.secrets.getIndex();
+        const userSecretKeys = Object.keys(userSecretIndex);
+        const userSecrets = userSecretKeys.length > 0
+            ? await rtCtx.secrets.getValues(userSecretKeys)
+            : {};
+        const headers = await this.authBuilder({
+            sandboxMcpUrl: parsed.data.SANDBOX_MCP_URL,
+            skillsServiceUrl,
+            oracleSecrets,
+            userSecrets,
+        }, rtCtx);
+        const client = this.mcpClientFactory({
+            mcpServers: {
+                sandbox: {
+                    type: 'http',
+                    url: parsed.data.SANDBOX_MCP_URL,
+                    transport: 'http',
+                    headers,
+                },
+            },
+            defaultToolTimeout: SANDBOX_MCP_TIMEOUT_MS,
+            useStandardContentBlocks: true,
+        });
+        const upstream = await client.getTools();
+        const filtered = this.includeOracleManagementTools
+            ? upstream
+            : upstream.filter((t) => !t.name.startsWith(ORACLE_MANAGEMENT_TOOL_PREFIX));
+        const upstreamTools = filtered.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            schema: tool.schema,
+            handler: async (args) => tool.invoke(args),
+        }));
+        // sandbox_write_blob — companion to mint_invocation. Synthetic wrapper
+        // that takes a server-stored blobId + a sandbox path, looks the value up
+        // server-side, and forwards it to sandbox_write_file. Only registered
+        // when sandbox_write_file is present in the upstream toolset AND the
+        // request has a known user DID (the blob store is user-DID-namespaced).
+        const sandboxWriteFileTool = filtered.find((t) => t.name === 'sandbox_write_file');
+        if (sandboxWriteFileTool && rtCtx.user.did) {
+            upstreamTools.push(createSandboxWriteBlobTool({ sandboxWriteFileTool }));
+        }
+        return upstreamTools;
+    }
+}

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

@@ -0,0 +1,3 @@
+export { SkillsPlugin, type SkillsPluginOptions } from './skills.plugin.js';
+export { createDefaultSkillsUcanBuilder, type SkillsUcanBuilder, } from './skills-ucan.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/skills/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,8BAA8B,EAC9B,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC"}

package/dist/plugins/skills/index.js

@@ -0,0 +1,2 @@
+export { SkillsPlugin } from './skills.plugin.js';
+export { createDefaultSkillsUcanBuilder, } from './skills-ucan.js';

package/dist/plugins/skills/skills-tools.d.ts

@@ -0,0 +1,20 @@
+import type { PluginTool } from '../../plugin-api/types.js';
+import type { SkillsUcanBuilder } from './skills-ucan.js';
+export interface SkillsToolsOptions {
+    /** Resolved at boot from the plugin's `configSchema`. */
+    baseUrl: string;
+    /**
+     * Routing hint forwarded to ai-skills as `X-IXO-Network`. Defaults to
+     * `mainnet` at the plugin layer when `NETWORK` is absent from config.
+     */
+    network: string;
+    /** Mints the optional `ixo:skills` UCAN per call. */
+    ucanBuilder: SkillsUcanBuilder;
+}
+/**
+ * Build the two skills tools — `list_skills` and `search_skills`. Both close
+ * over the registry base URL but defer UCAN minting to the handler so each
+ * call resolves the freshest invocation for the current user.
+ */
+export declare function createSkillsTools(opts: SkillsToolsOptions): PluginTool[];
+//# sourceMappingURL=skills-tools.d.ts.map

package/dist/plugins/skills/skills-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-tools.d.ts","sourceRoot":"","sources":["../../../src/plugins/skills/skills-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA0M1D,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,WAAW,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,UAAU,EAAE,CAkExE"}

package/dist/plugins/skills/skills-tools.js

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper.js';
+/**
+ * Raw capsule shape returned by ai-skills. Validated via Zod at the network
+ * boundary so a malformed registry response surfaces as a clean parse error
+ * rather than a downstream type-confusion bug.
+ */
+const capsuleSchema = z.object({
+    cid: z.string(),
+    name: z.string(),
+    description: z.string().default(''),
+    license: z.string().nullable().optional(),
+    compatibility: z.string().nullable().optional(),
+    allowedTools: z.string().nullable().optional(),
+    metadata: z.record(z.string(), z.string()).nullable().optional(),
+    archiveSize: z.number().optional(),
+    createdAt: z.string().optional(),
+    // Set by ai-skills when the response row is private (i.e. owned by the
+    // caller). Absent for public rows.
+    visibility: z.enum(['public', 'private']).optional(),
+    ownerDid: z.string().nullable().optional(),
+    oracleDid: z.string().nullable().optional(),
+});
+const paginationSchema = z.object({
+    total: z.number(),
+    limit: z.number(),
+    offset: z.number(),
+    hasMore: z.boolean(),
+});
+const listResponseSchema = z.object({
+    capsules: z.array(capsuleSchema),
+    pagination: paginationSchema,
+});
+const searchResponseSchema = z.object({
+    query: z.string(),
+    count: z.number(),
+    capsules: z.array(capsuleSchema),
+});
+const LIST_DESCRIPTION = `List available skills from the IXO skills registry — the caller's **published** private skills first, then public registry skills.
+
+Each entry includes:
+- title: skill name
+- description: skill description
+- path: absolute sandbox path to the skill folder
+- source: "private" (your published skill) or "public" (registry)
+- cid: required by load_skill and by sandbox_run (when the run depends on the skill). Never use a CID as a file path.`;
+const SEARCH_DESCRIPTION = `Search the caller's published skills and the public IXO registry by query.
+
+Matching published (private) skills come first, then public registry results. Each entry includes title, description, path, source ("private" | "public"), and cid.`;
+const listSchema = z.object({
+    limit: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Optional: number of skills to return (1-100, default: 20).'),
+    offset: z
+        .number()
+        .min(0)
+        .optional()
+        .describe('Optional: pagination offset (default: 0).'),
+});
+const searchSchema = z.object({
+    q: z
+        .string()
+        .min(1, 'Search query is required')
+        .describe('Search query (e.g. "pptx", "invoice", "presentation", "docx"). Required.'),
+    limit: z
+        .number()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe('Optional: max results to return (1-50, default: 10).'),
+});
+function normalizeRegistryCapsule(capsule) {
+    return {
+        title: capsule.name,
+        description: capsule.description ?? '',
+        path: `/workspace/skills/${capsule.name}`,
+        source: capsule.visibility === 'private' ? 'private' : 'public',
+        cid: capsule.cid,
+        createdAt: capsule.createdAt
+            ? new Date(capsule.createdAt).toISOString()
+            : undefined,
+    };
+}
+/**
+ * Build the auth/network header set for outbound ai-skills requests. When a
+ * UCAN invocation is available, ai-skills returns the caller's private
+ * skills alongside the public ones; without it, only public rows come back.
+ *
+ * `X-IXO-Network` is a routing hint for ai-skills' did:ixo resolver, not a
+ * capsule-storage axis.
+ */
+function buildRegistryHeaders(opts) {
+    const headers = {
+        'X-IXO-Network': opts.network,
+    };
+    if (opts.skillsUcan) {
+        headers['Authorization'] = `Bearer ${opts.skillsUcan}`;
+        headers['X-Auth-Type'] = 'ucan';
+    }
+    return headers;
+}
+async function fetchRegistryCapsules(opts, limit, offset) {
+    const url = new URL('/capsules', opts.baseUrl);
+    url.searchParams.set('limit', limit.toString());
+    url.searchParams.set('offset', offset.toString());
+    const response = await fetch(url.toString(), {
+        headers: buildRegistryHeaders(opts),
+    });
+    if (!response.ok) {
+        throw new Error(`List skills failed: ${response.statusText}`);
+    }
+    return listResponseSchema.parse(await response.json());
+}
+async function searchRegistryCapsules(opts, q, limit) {
+    const url = new URL('/capsules/search', opts.baseUrl);
+    url.searchParams.set('q', q);
+    url.searchParams.set('limit', limit.toString());
+    const response = await fetch(url.toString(), {
+        headers: buildRegistryHeaders(opts),
+    });
+    if (!response.ok) {
+        throw new Error(`Search skills failed: ${response.statusText}`);
+    }
+    const data = searchResponseSchema.parse(await response.json());
+    // Dedup by name. When a private (caller-owned) and a public row share a
+    // name, prefer the private one — the user's own skill always wins. Among
+    // entries of the same source, keep the newest by createdAt.
+    const skillsMap = new Map();
+    for (const capsule of data.capsules) {
+        const existing = skillsMap.get(capsule.name);
+        if (!existing) {
+            skillsMap.set(capsule.name, capsule);
+            continue;
+        }
+        const incomingPrivate = capsule.visibility === 'private';
+        const existingPrivate = existing.visibility === 'private';
+        if (incomingPrivate && !existingPrivate) {
+            skillsMap.set(capsule.name, capsule);
+            continue;
+        }
+        if (!incomingPrivate && existingPrivate) {
+            continue;
+        }
+        // Same visibility tier — keep the newer one.
+        const isNewer = capsule.createdAt && existing.createdAt
+            ? new Date(capsule.createdAt).getTime() >
+                new Date(existing.createdAt).getTime()
+            : false;
+        if (isNewer)
+            skillsMap.set(capsule.name, capsule);
+    }
+    return Array.from(skillsMap.values());
+}
+/**
+ * Build the two skills tools — `list_skills` and `search_skills`. Both close
+ * over the registry base URL but defer UCAN minting to the handler so each
+ * call resolves the freshest invocation for the current user.
+ */
+export function createSkillsTools(opts) {
+    const list = tool(async (rawArgs, runCtx) => {
+        const params = listSchema.parse(rawArgs);
+        const limit = params.limit ?? 20;
+        const offset = params.offset ?? 0;
+        const skillsUcan = await opts.ucanBuilder(opts.baseUrl, runCtx);
+        const registryResult = await fetchRegistryCapsules({ baseUrl: opts.baseUrl, network: opts.network, skillsUcan }, limit, offset);
+        const registry = registryResult.capsules.map(normalizeRegistryCapsule);
+        const privateRegistry = registry.filter((s) => s.source === 'private');
+        const publicRegistry = registry.filter((s) => s.source === 'public');
+        const skills = [...privateRegistry, ...publicRegistry];
+        return {
+            skills,
+            pagination: registryResult.pagination,
+            privateSkillCount: privateRegistry.length,
+        };
+    }, {
+        name: 'list_skills',
+        description: LIST_DESCRIPTION,
+        schema: listSchema,
+    });
+    const search = tool(async (rawArgs, runCtx) => {
+        const params = searchSchema.parse(rawArgs);
+        const limit = params.limit ?? 10;
+        const skillsUcan = await opts.ucanBuilder(opts.baseUrl, runCtx);
+        const capsules = await searchRegistryCapsules({ baseUrl: opts.baseUrl, network: opts.network, skillsUcan }, params.q, limit);
+        const registry = capsules.map(normalizeRegistryCapsule);
+        const privateRegistry = registry.filter((s) => s.source === 'private');
+        const publicRegistry = registry.filter((s) => s.source === 'public');
+        const skills = [...privateRegistry, ...publicRegistry];
+        return {
+            query: params.q,
+            count: skills.length,
+            privateSkillCount: privateRegistry.length,
+            skills,
+        };
+    }, {
+        name: 'search_skills',
+        description: SEARCH_DESCRIPTION,
+        schema: searchSchema,
+    });
+    return [list, search];
+}