@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/plugins/pod-creator/sub-agents.ts

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper';
+import type {
+  PluginSubAgent,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import type { BlueprintSection } from './blueprint-types';
+import type { BlueprintStore, BlueprintStoreFor } from './blueprint-store';
+import type { CapsuleContentClient } from './capsule-content-client';
+import {
+  DESIGN_POD_ROLES,
+  type DesignPodRole,
+  type DesignPodStage,
+} from './design-pod-roles';
+import { deriveStage, sectionsView } from './stage';
+
+const isGateRole = (role: DesignPodRole): boolean =>
+  role.stage === 'evaluate' || role.stage === 'gate';
+
+/** What each lifecycle stage is accountable for, for the fallback prompts. */
+const STAGE_DUTIES: Record<DesignPodStage, string> = {
+  qualify:
+    'Score the incoming service intent for viability and fit, and give a clear go / no-go rationale the later stages can rely on.',
+  architect:
+    'Design the POD structure for your discipline — service roles, workspaces and services, claim schemas and the UDID model, or the UCAN rights model — precisely enough for the build stage to implement without guessing.',
+  build:
+    'Produce the executable artifacts for your discipline — Flow pages for the workflow and UX, or the operating playbooks and rule cards — grounded in the architect sections.',
+  evaluate:
+    'Judge the recorded design from your lens (automation feasibility, governance and risk, or the outcome contract). Be adversarial: name what breaks, and fail the gate when the blueprint does not hold up.',
+  package:
+    'Package the POD for the market — the commercial offer and marketplace listing draft, or a runnable demo — from the completed design sections.',
+  gate: 'Run final QA across every prior section and issue the launch-readiness verdict. Pass only a blueprint you would stand behind going on-chain.',
+};
+
+function sectionInstruction(role: DesignPodRole): string {
+  const verdict = isGateRole(role)
+    ? ' Include a pass|fail verdict (and blockers when failing).'
+    : '';
+  return `Use read_blueprint for the sections recorded so far (pass roles=[...] when you need a section's full content), then call submit_section exactly once with your section content.${verdict}`;
+}
+
+/** The role's registry instructions, framed for the pipeline. */
+function composePrompt(role: DesignPodRole, skillMarkdown: string): string {
+  return `${skillMarkdown}\n\n---\nYou are the \`${role.id}\` specialist in the POD design pipeline (stage: ${role.stage}). ${sectionInstruction(role)}`;
+}
+
+/** Built-in prompt used when no registry instructions are loaded for the role. */
+function fallbackPrompt(role: DesignPodRole): string {
+  return [
+    `You are the \`${role.id}\` specialist in the POD design pipeline (stage: ${role.stage}).`,
+    role.description,
+    '',
+    STAGE_DUTIES[role.stage],
+    'Ground everything in the POD brief and the sections recorded before yours; produce concrete, structured content — not commentary.',
+    '',
+    sectionInstruction(role),
+    '',
+    '(Operating from the built-in summary of this role; its registry-published instructions are not loaded.)',
+  ].join('\n');
+}
+
+const submitSchema = z.object({
+  content: z
+    .unknown()
+    .describe('Your section content to record into the POD blueprint.'),
+  verdict: z
+    .enum(['pass', 'fail'])
+    .optional()
+    .describe('For gate roles, your gate verdict.'),
+  blockers: z
+    .array(z.string())
+    .optional()
+    .describe('Blocking issues to surface when your verdict is fail.'),
+});
+
+const readSchema = z.object({
+  roles: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Role ids whose full section content to include. Omit for the compact per-section summary.',
+    ),
+});
+
+/** The narrow tool set each specialist gets: read prior context, submit once. */
+function roleTools(
+  role: DesignPodRole,
+  storeFor: BlueprintStoreFor,
+): PluginTool[] {
+  const readBlueprint = tool(
+    async (args, ctx) => {
+      const { roles } = readSchema.parse(args);
+      const bp = await storeFor(ctx).get(ctx.session.id);
+      if (!bp) {
+        return { brief: undefined, sections: [] };
+      }
+      return { brief: bp.brief, ...sectionsView(bp, roles) };
+    },
+    {
+      name: 'read_blueprint',
+      description:
+        'Read the POD brief and a compact summary of the sections recorded so far. Pass roles=[...] to include the full content of specific sections.',
+      schema: readSchema,
+      effect: 'read',
+    },
+  );
+
+  const submitSection = tool(
+    async (args, ctx) => {
+      const input = submitSchema.parse(args);
+      const section: BlueprintSection = {
+        role: role.id,
+        stage: role.stage,
+        content: input.content,
+        recordedAt: new Date().toISOString(),
+        ...(input.verdict !== undefined ? { verdict: input.verdict } : {}),
+        ...(input.blockers !== undefined ? { blockers: input.blockers } : {}),
+      };
+      await storeFor(ctx).putSection(ctx.session.id, section);
+      return { submitted: role.id, stage: role.stage };
+    },
+    {
+      name: 'submit_section',
+      description: `Record your (${role.id}) section into the POD blueprint. Call exactly once.`,
+      schema: submitSchema,
+    },
+  );
+
+  return [readBlueprint, submitSection];
+}
+
+async function resolvePrompt(
+  role: DesignPodRole,
+  rt: RuntimeContext,
+  capsules: CapsuleContentClient,
+): Promise<string> {
+  const markdown = await capsules.getSkillMarkdown(role.capsule, rt);
+  return markdown === undefined
+    ? fallbackPrompt(role)
+    : composePrompt(role, markdown);
+}
+
+async function buildSubAgent(
+  role: DesignPodRole,
+  rt: RuntimeContext,
+  storeFor: BlueprintStoreFor,
+  capsules: CapsuleContentClient,
+): Promise<PluginSubAgent> {
+  return {
+    name: role.id,
+    description: role.description,
+    systemPrompt: await resolvePrompt(role, rt, capsules),
+    tools: roleTools(role, storeFor),
+    model: 'subagent',
+    forwardTools: true,
+  };
+}
+
+/**
+ * Build the specialist sub-agents for the current request, gated to the
+ * blueprint's current stage. Returns only that stage's specialist(s) — never
+ * all twelve — so the conductor's tool surface stays small and the pipeline
+ * order is enforced, and none at all before a blueprint exists. Each
+ * sub-agent's system prompt is the role's registry `SKILL.md`, fetched via the
+ * capsule client, with a built-in fallback when there is no fetcher or the
+ * registry is unavailable.
+ *
+ * The specialists' tools resolve the store from THEIR call's context (the
+ * sub-agent runs later in the turn), never from the `rt` that built them.
+ */
+export async function buildStageSubAgents(
+  rt: RuntimeContext,
+  storeFor: BlueprintStoreFor,
+  capsules: CapsuleContentClient,
+): Promise<PluginSubAgent[]> {
+  const store: BlueprintStore = storeFor(rt);
+  const bp = await store.get(rt.session.id);
+  // No design in this thread: nothing to offer. This hook runs on every turn
+  // of every user whether or not the capability is loaded, so it must stay a
+  // single local read until `start_pod_design` has opened a blueprint (the
+  // qualify specialist appears on the following turn).
+  if (!bp) return [];
+  const stage = deriveStage(bp);
+  const roles = DESIGN_POD_ROLES.filter((role) => role.stage === stage);
+  return Promise.all(
+    roles.map((role) => buildSubAgent(role, rt, storeFor, capsules)),
+  );
+}

package/src/plugins/portal/action-log.ts

@@ -1,7 +1,8 @@
 /**
  * The Node runtime's `logActionToMatrix`: a best-effort `ixo.action.log`
  * room event recording a frontend action (browser tool / AG-UI action) and
- * its outcome, posted only when the turn has a room. Never throws.
+ * its outcome, posted only when the turn has a room. Never throws. Frontend
+ * calls log through `logFrontendAction`, which keeps their content out.
  *
  * Retried across a gateway restart (the gateway object is replaced on every
  * deploy and can be drained mid-turn) and handed to the host to keep alive
@@ -10,6 +11,7 @@
  * response lost between the homeserver's ack and the reply to the gateway
  * is deduplicated instead of logged twice.
  */
+import { summarizeFrontendResult } from '@ixo/common/ai/frontend-bridge';
 import { retryGateway, type RetryGatewayOptions } from '../../do/gateway-retry';
 import { retryTxnId } from '../../matrix/txn-id';
 import type { RuntimeContext } from '../../plugin-api/types';
@@ -59,3 +61,21 @@ export function logActionToMatrix(
   );
   ctx.background?.(work);
 }
+
+/**
+ * Log a finished frontend call (browser tool / AG-UI action). The room event
+ * is a diagnostic trail, readable by everyone in the room: it records the
+ * invocation id, a Portal command id when the result carries one, and
+ * whether the outcome is unknown — never the arguments or the result body,
+ * which carry the user's content.
+ */
+export function logFrontendAction(
+  ctx: Pick<RuntimeContext, 'matrix' | 'session' | 'logger' | 'background'>,
+  call: { name: string; invocationId: string | undefined; result: unknown },
+): void {
+  logActionToMatrix(ctx, {
+    name: call.name,
+    args: {},
+    ...summarizeFrontendResult(call.result, call.invocationId),
+  });
+}

package/src/plugins/portal/declared-tools.ts

@@ -0,0 +1,90 @@
+/**
+ * Validation for the tools a browser declares in a turn body (the Portal's
+ * `tools[]` and AG-UI's `agActions[]`). The declarations come from the
+ * client on every request, so each request is checked on its own: the boot
+ * time collision check never sees them.
+ *
+ * An entry is dropped (never repaired) when its name is not a valid tool
+ * name, repeats an earlier entry's name, or is reserved (`reservedNames`,
+ * e.g. the server's own tool names), or when its description or schema is
+ * over the size cap. At most {@link MAX_DECLARED_TOOLS} entries are kept.
+ */
+
+/** Tool names the model providers accept, and nothing else. */
+export const DECLARED_TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** Declared tools kept per request; further entries are dropped. */
+export const MAX_DECLARED_TOOLS = 64;
+/** Characters of one declared tool's description. */
+export const MAX_DECLARED_DESCRIPTION_CHARS = 2_048;
+/** Characters of one declared tool's JSON schema, serialised. */
+export const MAX_DECLARED_SCHEMA_CHARS = 16_384;
+
+export interface DeclaredTool {
+  name: string;
+  description: string;
+  schema: Record<string, unknown>;
+}
+
+export interface DroppedDeclaration {
+  name: string;
+  reason: string;
+}
+
+function schemaLength(schema: Record<string, unknown>): number {
+  try {
+    return JSON.stringify(schema).length;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+/** The entries that may become tools this turn, plus why the others did not. */
+export function sanitizeDeclaredTools<T extends DeclaredTool>(
+  entries: readonly T[],
+  reservedNames: ReadonlySet<string> = new Set(),
+): { kept: T[]; dropped: DroppedDeclaration[] } {
+  const kept: T[] = [];
+  const dropped: DroppedDeclaration[] = [];
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    const { name } = entry;
+    let reason: string | undefined;
+    if (!DECLARED_TOOL_NAME_PATTERN.test(name)) reason = 'invalid name';
+    else if (seen.has(name)) reason = 'duplicate name';
+    else if (reservedNames.has(name)) reason = 'name taken by a server tool';
+    else if (entry.description.length > MAX_DECLARED_DESCRIPTION_CHARS)
+      reason = `description over ${MAX_DECLARED_DESCRIPTION_CHARS} characters`;
+    else if (schemaLength(entry.schema) > MAX_DECLARED_SCHEMA_CHARS)
+      reason = `schema over ${MAX_DECLARED_SCHEMA_CHARS} characters`;
+    else if (kept.length >= MAX_DECLARED_TOOLS)
+      reason = `more than ${MAX_DECLARED_TOOLS} tools declared`;
+    if (DECLARED_TOOL_NAME_PATTERN.test(name)) seen.add(name);
+    if (reason) dropped.push({ name: name.slice(0, 64), reason });
+    else kept.push(entry);
+  }
+  return { kept, dropped };
+}
+
+/** Dropped entries named in {@link describeDropped}; the rest are counted. */
+const MAX_DROPPED_NAMED = 5;
+
+/**
+ * One log line for a request's dropped declarations (`undefined` when none
+ * were dropped): the count plus the first few names and reasons, so a client
+ * declaring thousands of bad entries still costs one bounded line.
+ */
+export function describeDropped(
+  kind: string,
+  dropped: readonly DroppedDeclaration[],
+): string | undefined {
+  if (dropped.length === 0) return undefined;
+  const named = dropped
+    .slice(0, MAX_DROPPED_NAMED)
+    .map(({ name, reason }) => `"${name}" (${reason})`)
+    .join(', ');
+  const more =
+    dropped.length > MAX_DROPPED_NAMED
+      ? ` and ${dropped.length - MAX_DROPPED_NAMED} more`
+      : '';
+  return `Ignoring ${dropped.length} declared ${kind}: ${named}${more}`;
+}

package/src/plugins/portal/portal.plugin.ts

@@ -23,7 +23,8 @@ import type {
   PluginTool,
   RuntimeContext,
 } from '../../plugin-api/types';
-import { logActionToMatrix } from './action-log';
+import { logFrontendAction } from './action-log';
+import { describeDropped, sanitizeDeclaredTools } from './declared-tools';
 
 const manifest: PluginManifest = {
   title: 'Portal',
@@ -53,6 +54,20 @@ const manifest: PluginManifest = {
 
 export const BROWSER_TOOL_TIMEOUT_MS = 15_000;
 
+/**
+ * The Portal's Topic write tool. Its commands can take a while to settle in
+ * the browser (several Matrix writes), so it gets a longer window before the
+ * call is reported as an unknown outcome.
+ */
+export const TOPIC_MUTATION_TOOL = 'mutate_topic';
+export const TOPIC_MUTATION_TIMEOUT_MS = 120_000;
+
+export function browserToolTimeoutMs(toolName: string): number {
+  return toolName === TOPIC_MUTATION_TOOL
+    ? TOPIC_MUTATION_TIMEOUT_MS
+    : BROWSER_TOOL_TIMEOUT_MS;
+}
+
 const BROWSER_TOOL_SHAPE = z.object({
   name: z.string(),
   description: z.string(),
@@ -61,12 +76,16 @@ const BROWSER_TOOL_SHAPE = z.object({
 
 const ARGS_RECORD_SHAPE = z.record(z.string(), z.unknown());
 
+/** The client's browser tools; a name declared twice keeps its first descriptor. */
 export function parseBrowserTools(value: unknown): BrowserToolCall[] {
   if (!Array.isArray(value)) return [];
   const out: BrowserToolCall[] = [];
+  const names = new Set<string>();
   for (const entry of value) {
     const parsed = BROWSER_TOOL_SHAPE.safeParse(entry);
-    if (parsed.success) out.push(parsed.data);
+    if (!parsed.success || names.has(parsed.data.name)) continue;
+    names.add(parsed.data.name);
+    out.push(parsed.data);
   }
   return out;
 }
@@ -154,36 +173,43 @@ export function buildBrowserTool(
         descriptor,
         ctx.config,
       );
-      // Node uses `tc-<requestId>`; the suffix keeps two browser tool calls in
-      // one turn from sharing an id (the client echoes it back verbatim).
-      const toolCallId = `tc-${ctx.session.requestId || 'noreq'}-${crypto
-        .randomUUID()
-        .slice(0, 8)}`;
+      // The bridge makes every invocation unique (`tc-<requestId>:<uuid>`).
+      let invocationId: string | undefined;
       const result = await frontend.callBrowserTool({
         sessionId,
-        toolCallId,
+        toolCallId: `tc-${ctx.session.requestId || 'noreq'}`,
         toolName: descriptor.name,
         args,
-        timeoutMs: BROWSER_TOOL_TIMEOUT_MS,
-      });
-      logActionToMatrix(ctx, {
-        name: descriptor.name,
-        args,
-        result,
-        success: true,
+        timeoutMs: browserToolTimeoutMs(descriptor.name),
+        signal: ctx.abortSignal,
+        onInvocation: (id) => {
+          invocationId = id;
+        },
       });
+      logFrontendAction(ctx, { name: descriptor.name, invocationId, result });
       return result;
     },
     {
       name: descriptor.name,
       description: descriptor.description,
       schema,
+      // A browser step (scroll, page, click) repeated is a new step.
+      repeatable: true,
     },
   );
 }
 
+/**
+ * The browser tools declared on this request that may become tools: invalid,
+ * duplicate and oversized declarations are dropped (`declared-tools.ts`).
+ */
 function readBrowserTools(rtCtx: RuntimeContext): BrowserToolCall[] {
-  return parseBrowserTools(rtCtx.history.state.browserTools);
+  const { kept, dropped } = sanitizeDeclaredTools(
+    parseBrowserTools(rtCtx.history.state.browserTools),
+  );
+  const summary = describeDropped('browser tools', dropped);
+  if (summary) rtCtx.logger.warn(summary);
+  return kept;
 }
 
 export class PortalPlugin extends OraclePlugin {

package/src/plugins/sandbox/sandbox-bridge.ts

@@ -1,6 +1,7 @@
 import { MultiServerMCPClient } from '@langchain/mcp-adapters';
 import type { RuntimeContext } from '../../plugin-api/types';
 import { base64ToBytes } from '../base64';
+import { withCallTimeout } from '../mcp-call-timeout';
 import { adaptMcpClientTools } from '../mcp-tool-adapter';
 import { createDefaultAuthBuilder, SANDBOX_RUN_TOOL_NAME } from './sandbox-mcp';
 import type {
@@ -12,8 +13,21 @@ import type {
 /** Upstream tool name the sandbox MCP surfaces for byte-perfect file writes. */
 export const SANDBOX_WRITE_FILE_TOOL_NAME = 'sandbox_write_file';
 
-/** Per-call timeout for the sandbox MCP client (matches sandbox.plugin.ts). */
-const SANDBOX_MCP_TIMEOUT_MS = 180_000;
+/**
+ * Per-call timeout for every sandbox MCP tool call. It is the MCP request's
+ * own timeout (as `metadata.timeoutMs`, see `mcp-tool-adapter.ts`) and is
+ * also enforced with {@link withCallTimeout}, which closes the client on
+ * expiry; never as the client's `defaultToolTimeout`.
+ */
+export const SANDBOX_MCP_TIMEOUT_MS = 180_000;
+
+/**
+ * Largest file the bridge moves in either direction. A transfer is buffered
+ * whole in the isolate several times over (base64 text in the MCP result,
+ * its decoded bytes, the upload copy), so the cap keeps one transfer far
+ * below the 128 MB isolate limit. Equal to the VFS vision-read cap.
+ */
+export const MAX_SANDBOX_TRANSFER_BYTES = 10 * 1024 * 1024;
 
 /** Only destination the sandbox accepts for `sandbox_write_file` writes. */
 export const WORKSPACE_DATA_PREFIX = '/workspace/data/';
@@ -21,6 +35,12 @@ export const WORKSPACE_DATA_PREFIX = '/workspace/data/';
 /** Sentinel echoed by the read command when the source file is absent. */
 export const SANDBOX_NO_FILE_SENTINEL = '__SANDBOX_NOFILE__';
 
+/**
+ * Sentinel echoed by the read command, followed by the size in bytes, when
+ * the source file exceeds {@link MAX_SANDBOX_TRANSFER_BYTES}.
+ */
+export const SANDBOX_TOO_LARGE_SENTINEL = '__SANDBOX_TOOLARGE__';
+
 /**
  * Shown when the user hasn't authorized the oracle to use the sandbox — the
  * default auth builder can't mint an `ixo:sandbox` invocation, so there's no
@@ -41,7 +61,10 @@ export const defaultSandboxMcpClientFactory: SandboxMcpClientFactory = (
 ) => {
   const client = new MultiServerMCPClient(config);
   const wrapper: SandboxMcpClientLike = {
-    getTools: async () => adaptMcpClientTools(await client.getTools(), console),
+    getTools: async () =>
+      adaptMcpClientTools(await client.getTools(), console, {
+        requestTimeoutMs: SANDBOX_MCP_TIMEOUT_MS,
+      }),
     close: () => client.close(),
   };
   return wrapper;
@@ -201,7 +224,6 @@ export async function getSandboxBridge(
         headers,
       },
     },
-    defaultToolTimeout: SANDBOX_MCP_TIMEOUT_MS,
     useStandardContentBlocks: true,
   });
 
@@ -236,23 +258,57 @@ export async function getSandboxBridge(
     };
   }
 
-  return { run, writeFile, close };
+  // Each invocation is bounded by a timer that is always cleared; on timeout
+  // the client is closed so the abandoned request cannot keep the object
+  // busy.
+  const bounded = (t: SandboxMcpTool): SandboxMcpTool => ({
+    ...t,
+    invoke: (input: unknown) =>
+      withCallTimeout(
+        () => t.invoke(input),
+        SANDBOX_MCP_TIMEOUT_MS,
+        `sandbox tool ${t.name}`,
+        close,
+      ),
+  });
+
+  return { run: bounded(run), writeFile: bounded(writeFile), close };
+}
+
+/**
+ * Shell command that prints the file as one base64 line, or a sentinel when
+ * it is missing or larger than {@link MAX_SANDBOX_TRANSFER_BYTES}. The size
+ * is checked inside the sandbox so an oversized file is never encoded or
+ * sent. `sandboxPath` must already have passed {@link hasShellUnsafeChars}.
+ */
+export function sandboxReadCommand(sandboxPath: string): string {
+  const p = `'${sandboxPath}'`;
+  return [
+    `if [ ! -f ${p} ]; then echo ${SANDBOX_NO_FILE_SENTINEL};`,
+    `else s=$(stat -c%s ${p});`,
+    `if [ "$s" -gt ${MAX_SANDBOX_TRANSFER_BYTES} ]; then echo ${SANDBOX_TOO_LARGE_SENTINEL}:$s;`,
+    `else base64 -w0 ${p}; fi; fi`,
+  ].join(' ');
 }
 
 /**
  * Read a file out of the sandbox as bytes, base64-hopping over `sandbox_run`
  * so binary content survives the transport. Non-throwing — a missing file, a
- * failed command, and undecodable output all come back as `{ error }` with an
- * agent-facing message.
+ * file over {@link MAX_SANDBOX_TRANSFER_BYTES}, a failed command, and
+ * undecodable output all come back as `{ error }` with an agent-facing
+ * message.
  */
 export async function readSandboxFile(
   bridge: Pick<SandboxBridge, 'run'>,
   sandboxPath: string,
 ): Promise<{ bytes: Uint8Array } | { error: string }> {
+  if (hasShellUnsafeChars(sandboxPath)) {
+    return {
+      error: `The sandbox path contains characters I can't safely handle (quotes or newlines).`,
+    };
+  }
   const read = readSandboxResult(
-    await bridge.run.invoke({
-      code: `test -f '${sandboxPath}' && base64 -w0 '${sandboxPath}' || echo ${SANDBOX_NO_FILE_SENTINEL}`,
-    }),
+    await bridge.run.invoke({ code: sandboxReadCommand(sandboxPath) }),
   );
   if (!read.ok) {
     return {
@@ -263,6 +319,19 @@ export async function readSandboxFile(
   if (stdout === SANDBOX_NO_FILE_SENTINEL) {
     return { error: `No file at \`${sandboxPath}\` in the sandbox.` };
   }
+  if (stdout.startsWith(`${SANDBOX_TOO_LARGE_SENTINEL}:`)) {
+    const size = stdout.slice(SANDBOX_TOO_LARGE_SENTINEL.length + 1);
+    return {
+      error: `\`${sandboxPath}\` is ${size} bytes; files moved out of the sandbox are limited to ${MAX_SANDBOX_TRANSFER_BYTES} bytes.`,
+    };
+  }
+  // Defence in depth for a sandbox that ignored the size check: base64
+  // inflates by 4/3, so anything longer decodes past the cap.
+  if (stdout.length > Math.ceil(MAX_SANDBOX_TRANSFER_BYTES / 3) * 4) {
+    return {
+      error: `\`${sandboxPath}\` is larger than the ${MAX_SANDBOX_TRANSFER_BYTES}-byte limit for files moved out of the sandbox.`,
+    };
+  }
   try {
     return { bytes: base64ToBytes(stdout) };
   } catch {

package/src/plugins/sandbox/sandbox-mcp.ts

@@ -1,4 +1,5 @@
 import type { RuntimeContext } from '../../plugin-api/types';
+import { SANDBOX_CAPABILITY } from '../delegated-capabilities';
 
 /** Tool name surfaced by the upstream sandbox MCP. */
 export const SANDBOX_RUN_TOOL_NAME = 'sandbox_run';
@@ -70,10 +71,10 @@ export function createDefaultAuthBuilder(): SandboxAuthBuilder {
     if (sandboxDid) {
       try {
         const invocation = await runCtx.ucan.mintInvocation(
-          { did: sandboxDid, capability: 'ixo:sandbox' },
+          { did: sandboxDid, capability: SANDBOX_CAPABILITY.resource },
           // Claim the ability the user's delegation actually grants. A `'*'`
           // claim is satisfiable only by a `'*'` grant.
-          { can: 'sandbox/*' },
+          { can: SANDBOX_CAPABILITY.action },
         );
         if (invocation) {
           headers.Authorization = `Bearer ${invocation}`;

package/src/plugins/sandbox/sandbox-write-blob.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { tool as pluginTool } from '../../plugin-api/tool-helper';
 import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+import { readSandboxResult } from './sandbox-bridge';
 import type { SandboxMcpTool } from './sandbox.plugin';
 
 const sandboxWriteBlobSchema = z.object({
@@ -80,10 +81,19 @@ export function createSandboxWriteBlobTool(
           content: blob.value,
           encoding: 'utf8',
         });
+        // The sandbox reports a rejected write (bad path, quota) as a
+        // returned `success:false` envelope, not a throw.
+        const outcome = readSandboxResult(result);
+        if (!outcome.ok) {
+          return JSON.stringify({
+            success: false,
+            error: `sandbox_write_file failed: ${outcome.text}`,
+          });
+        }
         return JSON.stringify({
           success: true,
           path,
-          bytesWritten: blob.value.length,
+          bytesWritten: new TextEncoder().encode(blob.value).byteLength,
           blobName: blob.name,
           note: typeof result === 'string' ? result : undefined,
         });

package/src/plugins/sandbox/sandbox.plugin.ts

@@ -7,13 +7,17 @@ import type {
   PluginTool,
   RuntimeContext,
 } from '../../plugin-api/types';
-import { defaultSandboxMcpClientFactory } from './sandbox-bridge';
+import {
+  defaultSandboxMcpClientFactory,
+  SANDBOX_MCP_TIMEOUT_MS,
+} from './sandbox-bridge';
 import {
   createDefaultAuthBuilder,
   parseOracleSecrets,
   type SandboxAuthBuilder,
 } from './sandbox-mcp';
 import { createSandboxWriteBlobTool } from './sandbox-write-blob';
+import { SANDBOX_CAPABILITY } from '../delegated-capabilities';
 
 /**
  * Env this plugin owns. Unlike the Node runtime — whose Tier-0 base schema
@@ -131,6 +135,7 @@ const manifest: PluginManifest = {
   stability: 'stable',
   category: 'core',
   tags: ['sandbox', 'execution', 'workspace', 'artifacts'],
+  requires: [SANDBOX_CAPABILITY],
 };
 
 /** Minimal MCP-client surface — declared structurally so tests can stub it. */
@@ -151,9 +156,6 @@ export type SandboxMcpClientFactory = (
   config: ClientConfig,
 ) => SandboxMcpClientLike;
 
-/** Per-tool timeout for sandbox MCP calls (matches the Node runtime wiring). */
-const SANDBOX_MCP_TIMEOUT_MS = 180_000;
-
 /**
  * How long a request's lazily-connected MCP client survives after its last
  * invocation before being closed (a later call reconnects).
@@ -349,12 +351,7 @@ export class SandboxPlugin extends OraclePlugin {
       return this.toPluginTools(lazyUpstream, rtCtx);
     }
 
-    const userSecretIndex = await rtCtx.secrets.getIndex();
-    const userSecretKeys = Object.keys(userSecretIndex);
-    const userSecrets: Record<string, string> =
-      userSecretKeys.length > 0
-        ? await rtCtx.secrets.getValues(userSecretKeys)
-        : {};
+    const userSecrets = await rtCtx.secrets.getAll();
 
     const headers = await this.authBuilder(
       {
@@ -524,12 +521,7 @@ export class SandboxPlugin extends OraclePlugin {
     rtCtx: RuntimeContext;
   }): Promise<{ client: SandboxMcpClientLike; tools: SandboxMcpTool[] }> {
     const { sandboxMcpUrl, skillsServiceUrl, oracleSecrets, rtCtx } = args;
-    const userSecretIndex = await rtCtx.secrets.getIndex();
-    const userSecretKeys = Object.keys(userSecretIndex);
-    const userSecrets: Record<string, string> =
-      userSecretKeys.length > 0
-        ? await rtCtx.secrets.getValues(userSecretKeys)
-        : {};
+    const userSecrets = await rtCtx.secrets.getAll();
 
     const headers = await this.authBuilder(
       { sandboxMcpUrl, skillsServiceUrl, oracleSecrets, userSecrets },