@useatlas/create 0.0.2 → 0.0.4

package/templates/nextjs-standalone/src/lib/plugins/__tests__/wiring.test.ts

@@ -1,7 +1,8 @@
 import { describe, test, expect, beforeEach, mock } from "bun:test";
 import { PluginRegistry } from "../registry";
 import type { PluginLike, PluginContextLike } from "../registry";
-import { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins } from "../wiring";
+import { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins, wireSandboxPlugins } from "../wiring";
+import type { SandboxExecBackend } from "../wiring";
 
 const minimalCtx: PluginContextLike = {
   db: null,
@@ -15,9 +16,9 @@ const minimalCtx: PluginContextLike = {
 
 function makeMockConnectionRegistry() {
   return {
-    registered: [] as { id: string; conn: unknown; dbType: string; description?: string; validate?: unknown }[],
-    async registerDirect(id: string, conn: unknown, dbType: string, description?: string, validate?: unknown) {
-      this.registered.push({ id, conn, dbType, description, validate });
+    registered: [] as { id: string; conn: unknown; dbType: string; description?: string; validate?: unknown; meta?: unknown }[],
+    registerDirect(id: string, conn: unknown, dbType: string, description?: string, validate?: unknown, meta?: unknown) {
+      this.registered.push({ id, conn, dbType, description, validate, meta });
     },
   };
 }
@@ -49,7 +50,7 @@ function makeDatasourcePlugin(
   };
   return {
     id,
-    type: "datasource",
+    types: ["datasource"],
     version: "1.0.0",
     connection: {
       create: () => conn,
@@ -66,7 +67,7 @@ function makeDatasourcePlugin(
 function makeActionPlugin(id: string, opts?: { unhealthy?: boolean }): PluginLike {
   return {
     id,
-    type: "action",
+    types: ["action"],
     version: "1.0.0",
     actions: [
       {
@@ -88,7 +89,7 @@ function makeActionPlugin(id: string, opts?: { unhealthy?: boolean }): PluginLik
 function makeInteractionPlugin(id: string, routesFn: (app: unknown) => void, opts?: { unhealthy?: boolean }): PluginLike {
   return {
     id,
-    type: "interaction",
+    types: ["interaction"],
     version: "1.0.0",
     routes: routesFn,
     ...(opts?.unhealthy
@@ -127,7 +128,7 @@ describe("wireDatasourcePlugins", () => {
     const validator = (q: string) => ({ valid: /^SELECT/i.test(q) });
     const plugin: PluginLike = {
       id: "validated-ds",
-      type: "datasource",
+      types: ["datasource"],
       version: "1.0.0",
       connection: {
         create: () => ({ query: async () => ({ columns: [], rows: [] }), close: async () => {} }),
@@ -147,6 +148,47 @@ describe("wireDatasourcePlugins", () => {
     expect(connRegistry.registered[0].validate).toBe(validator);
   });
 
+  test("passes parserDialect and forbiddenPatterns through meta", async () => {
+    const patterns = [/^\s*(KILL)\b/i];
+    const plugin: PluginLike = {
+      id: "meta-ds",
+      types: ["datasource"],
+      version: "1.0.0",
+      connection: {
+        create: () => ({ query: async () => ({ columns: [], rows: [] }), close: async () => {} }),
+        dbType: "clickhouse",
+        parserDialect: "PostgresQL",
+        forbiddenPatterns: patterns,
+      },
+    };
+    registry.register(plugin);
+    await registry.initializeAll(minimalCtx);
+
+    await wireDatasourcePlugins(
+      registry,
+      connRegistry as unknown as import("@atlas/api/lib/db/connection").ConnectionRegistry,
+    );
+
+    expect(connRegistry.registered).toHaveLength(1);
+    expect(connRegistry.registered[0].meta).toEqual({
+      parserDialect: "PostgresQL",
+      forbiddenPatterns: patterns,
+    });
+  });
+
+  test("passes undefined meta when no parserDialect or forbiddenPatterns", async () => {
+    registry.register(makeDatasourcePlugin("plain-meta"));
+    await registry.initializeAll(minimalCtx);
+
+    await wireDatasourcePlugins(
+      registry,
+      connRegistry as unknown as import("@atlas/api/lib/db/connection").ConnectionRegistry,
+    );
+
+    expect(connRegistry.registered).toHaveLength(1);
+    expect(connRegistry.registered[0].meta).toBeUndefined();
+  });
+
   test("passes undefined validate when not provided", async () => {
     registry.register(makeDatasourcePlugin("plain-ds"));
     await registry.initializeAll(minimalCtx);
@@ -179,7 +221,7 @@ describe("wireDatasourcePlugins", () => {
   test("continues when one create() throws and returns failures", async () => {
     const failingPlugin: PluginLike = {
       id: "failing-ds",
-      type: "datasource",
+      types: ["datasource"],
       version: "1.0.0",
       connection: {
         create: () => { throw new Error("conn failed"); },
@@ -389,7 +431,7 @@ describe("wireActionPlugins", () => {
   test("registers all actions from a multi-action plugin", async () => {
     const plugin: PluginLike = {
       id: "multi-action",
-      type: "action",
+      types: ["action"],
       version: "1.0.0",
       actions: [
         { name: "action-a", description: "A", tool: {}, actionType: "t", reversible: false, defaultApproval: "manual", requiredCredentials: [] },
@@ -421,7 +463,7 @@ describe("wireActionPlugins", () => {
 
     const plugin: PluginLike = {
       id: "fail-action",
-      type: "action",
+      types: ["action"],
       version: "1.0.0",
       actions: [
         { name: "fail-action", description: "Fails", tool: {}, actionType: "t", reversible: false, defaultApproval: "manual", requiredCredentials: [] },
@@ -485,7 +527,7 @@ describe("wireInteractionPlugins", () => {
     const fakeApp = { route: mock(() => {}) };
     const routelessPlugin: PluginLike = {
       id: "stdio-interaction",
-      type: "interaction",
+      types: ["interaction"],
       version: "1.0.0",
       // No routes property — like MCP stdio transport
     };
@@ -506,7 +548,7 @@ describe("wireInteractionPlugins", () => {
 function makeContextPlugin(id: string, loadFn: () => Promise<string>, opts?: { unhealthy?: boolean }): PluginLike {
   return {
     id,
-    type: "context",
+    types: ["context"],
     version: "1.0.0",
     contextProvider: { load: loadFn },
     ...(opts?.unhealthy
@@ -571,7 +613,7 @@ describe("wireContextPlugins", () => {
   test("skips context plugins without contextProvider", async () => {
     const noProvider: PluginLike = {
       id: "no-provider",
-      type: "context",
+      types: ["context"],
       version: "1.0.0",
     };
     registry.register(noProvider);
@@ -583,3 +625,175 @@ describe("wireContextPlugins", () => {
     expect(result.failed).toEqual([]);
   });
 });
+
+// --- wireSandboxPlugins ---
+
+function makeMockBackend(tag: string): SandboxExecBackend {
+  return {
+    exec: async (command: string) => ({
+      stdout: `[${tag}] ${command}`,
+      stderr: "",
+      exitCode: 0,
+    }),
+  };
+}
+
+function makeSandboxPlugin(
+  id: string,
+  opts?: { priority?: number; createFn?: (root: string) => Promise<SandboxExecBackend> | SandboxExecBackend; unhealthy?: boolean },
+): PluginLike {
+  return {
+    id,
+    types: ["sandbox"],
+    version: "1.0.0",
+    sandbox: {
+      create: opts?.createFn ?? (async () => makeMockBackend(id)),
+      ...(opts?.priority !== undefined ? { priority: opts.priority } : {}),
+    },
+    ...(opts?.unhealthy
+      ? { initialize: async () => { throw new Error("fail"); } }
+      : {}),
+  };
+}
+
+describe("wireSandboxPlugins", () => {
+  let registry: PluginRegistry;
+
+  beforeEach(() => {
+    registry = new PluginRegistry();
+  });
+
+  test("returns backend from a single sandbox plugin", async () => {
+    registry.register(makeSandboxPlugin("my-sandbox"));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).not.toBeNull();
+    expect(result.pluginId).toBe("my-sandbox");
+    expect(result.failed).toEqual([]);
+  });
+
+  test("selects highest-priority plugin", async () => {
+    registry.register(makeSandboxPlugin("low", { priority: 40 }));
+    registry.register(makeSandboxPlugin("high", { priority: 90 }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("high");
+    const output = await result.backend!.exec("ls");
+    expect(output.stdout).toContain("[high]");
+  });
+
+  test("uses default priority (60) when omitted", async () => {
+    registry.register(makeSandboxPlugin("explicit-low", { priority: 50 }));
+    registry.register(makeSandboxPlugin("default-priority")); // no priority → 60
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("default-priority");
+  });
+
+  test("falls through to next plugin when create() throws", async () => {
+    registry.register(makeSandboxPlugin("broken", {
+      priority: 90,
+      createFn: async () => { throw new Error("init failed"); },
+    }));
+    registry.register(makeSandboxPlugin("working", { priority: 50 }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("working");
+    expect(result.failed).toHaveLength(1);
+    expect(result.failed[0].pluginId).toBe("broken");
+    expect(result.failed[0].error).toBe("init failed");
+  });
+
+  test("returns null when all plugins fail", async () => {
+    registry.register(makeSandboxPlugin("broken-1", {
+      createFn: async () => { throw new Error("fail 1"); },
+    }));
+    registry.register(makeSandboxPlugin("broken-2", {
+      createFn: async () => { throw new Error("fail 2"); },
+    }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).toBeNull();
+    expect(result.pluginId).toBeNull();
+    expect(result.failed).toHaveLength(2);
+  });
+
+  test("returns null when no sandbox plugins registered", async () => {
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).toBeNull();
+    expect(result.pluginId).toBeNull();
+    expect(result.failed).toEqual([]);
+  });
+
+  test("skips unhealthy sandbox plugins", async () => {
+    registry.register(makeSandboxPlugin("healthy"));
+    registry.register(makeSandboxPlugin("unhealthy", { unhealthy: true }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("healthy");
+    expect(result.failed).toEqual([]);
+  });
+
+  test("skips sandbox plugins missing sandbox.create()", async () => {
+    const noCreate: PluginLike = {
+      id: "no-create",
+      types: ["sandbox"],
+      version: "1.0.0",
+      // No sandbox property
+    };
+    registry.register(noCreate);
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).toBeNull();
+    expect(result.pluginId).toBeNull();
+    expect(result.failed).toEqual([]);
+  });
+
+  test("passes semanticRoot to sandbox.create()", async () => {
+    let receivedRoot: string | undefined;
+    registry.register(makeSandboxPlugin("root-check", {
+      createFn: async (root: string) => {
+        receivedRoot = root;
+        return makeMockBackend("root-check");
+      },
+    }));
+    await registry.initializeAll(minimalCtx);
+
+    await wireSandboxPlugins(registry, "/my/custom/semantic");
+
+    expect(receivedRoot).toBe("/my/custom/semantic");
+  });
+
+  test("rejects backend missing exec method from create()", async () => {
+    registry.register(makeSandboxPlugin("bad-backend", {
+      createFn: async () => ({} as SandboxExecBackend),
+    }));
+    registry.register(makeSandboxPlugin("good-backend", { priority: 40 }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    // bad-backend has default priority (60) > good-backend (40), tried first but rejected
+    expect(result.pluginId).toBe("good-backend");
+    expect(result.failed).toHaveLength(1);
+    expect(result.failed[0].pluginId).toBe("bad-backend");
+    expect(result.failed[0].error).toContain("missing exec method");
+  });
+});

package/templates/nextjs-standalone/src/lib/plugins/index.ts

@@ -4,6 +4,9 @@
 
 export { plugins, PluginRegistry } from "./registry";
 export type { PluginLike, PluginContextLike, PluginHealthResult, PluginType, PluginStatus, PluginDescription } from "./registry";
-export { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins } from "./wiring";
+export { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins, wireSandboxPlugins } from "./wiring";
+export type { SandboxExecBackend } from "./wiring";
+export { generateMigrationSQL, generateColumnMigrations, applyMigrations, runPluginMigrations, ensureMigrationsTable, getAppliedMigrations, diffSchema, prefixTableName } from "./migrate";
+export type { MigrateDB, MigrationStatement, SchemaDiff } from "./migrate";
 export { dispatchHook } from "./hooks";
 export { getPluginTools, setPluginTools, getContextFragments, setContextFragments } from "./tools";

package/templates/nextjs-standalone/src/lib/plugins/migrate.ts

@@ -273,6 +273,109 @@ export async function applyMigrations(
   return { applied, skipped };
 }
 
+// ---------------------------------------------------------------------------
+// Column migrations (ALTER TABLE ADD COLUMN)
+// ---------------------------------------------------------------------------
+
+/**
+ * Query the actual columns for a given table from information_schema.
+ * Returns a Set of lowercase column names.
+ */
+async function getExistingColumns(db: MigrateDB, tableName: string): Promise<Set<string>> {
+  const result = await db.query(
+    "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = $1",
+    [tableName],
+  );
+  return new Set(result.rows.map((r) => String(r.column_name).toLowerCase()));
+}
+
+/**
+ * Generate ALTER TABLE ADD COLUMN IF NOT EXISTS statements for fields
+ * that exist in the plugin schema but not in the actual database table.
+ *
+ * Column detection queries `information_schema.columns` in the `public`
+ * schema. Only handles column additions — column removal and type
+ * changes are not supported (require manual migration).
+ */
+export async function generateColumnMigrations(
+  db: MigrateDB,
+  plugins: PluginWithSchema[],
+): Promise<MigrationStatement[]> {
+  const statements: MigrationStatement[] = [];
+
+  for (const plugin of plugins) {
+    if (!plugin.schema) continue;
+
+    for (const [tableName, tableDef] of Object.entries(plugin.schema)) {
+      const prefixed = prefixTableName(plugin.id, tableName);
+
+      // Check if table exists at all — skip if it doesn't (CREATE TABLE will handle it)
+      const existing = await getExistingColumns(db, prefixed);
+      if (existing.size === 0) {
+        log.debug({ table: prefixed, pluginId: plugin.id }, "Table not in information_schema — skipping column migration");
+        continue;
+      }
+
+      for (const [fieldName, fieldDef] of Object.entries(tableDef.fields)) {
+        if (existing.has(fieldName.toLowerCase())) continue;
+
+        let colDef: string;
+        try {
+          colDef = fieldToSQL(fieldName, fieldDef);
+        } catch (err) {
+          throw new Error(
+            `Plugin "${plugin.id}", table "${prefixed}": ${err instanceof Error ? err.message : String(err)}`,
+            { cause: err },
+          );
+        }
+        const sql = `ALTER TABLE "${prefixed}" ADD COLUMN IF NOT EXISTS ${colDef};`;
+
+        statements.push({
+          pluginId: plugin.id,
+          tableName,
+          prefixedName: prefixed,
+          sql,
+          hash: hashSQL(sql),
+        });
+      }
+    }
+  }
+
+  return statements;
+}
+
+// ---------------------------------------------------------------------------
+// High-level orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Run all plugin schema migrations: CREATE TABLE for new tables, then
+ * ALTER TABLE ADD COLUMN for new fields on existing tables.
+ *
+ * Idempotent — safe to call on every startup.
+ */
+export async function runPluginMigrations(
+  db: MigrateDB,
+  plugins: PluginWithSchema[],
+): Promise<{ applied: string[]; skipped: string[] }> {
+  // Phase 1: CREATE TABLE
+  const createStatements = generateMigrationSQL(plugins);
+  const createResult = await applyMigrations(db, createStatements);
+
+  // Phase 2: ALTER TABLE ADD COLUMN (for tables that already existed or were just created)
+  const columnStatements = await generateColumnMigrations(db, plugins);
+  if (columnStatements.length === 0) {
+    return createResult;
+  }
+
+  const columnResult = await applyMigrations(db, columnStatements);
+
+  return {
+    applied: [...createResult.applied, ...columnResult.applied],
+    skipped: [...createResult.skipped, ...columnResult.skipped],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Diff: compare declared schema vs actual tables
 // ---------------------------------------------------------------------------

package/templates/nextjs-standalone/src/lib/plugins/registry.ts

@@ -41,7 +41,8 @@ export interface PluginContextLike {
  */
 export interface PluginLike {
   readonly id: string;
-  readonly type: PluginType;
+  /** Plugin type(s). A plugin can implement multiple types. */
+  readonly types: readonly PluginType[];
   readonly version: string;
   readonly name?: string;
   initialize?(ctx: PluginContextLike): Promise<void>;
@@ -59,7 +60,7 @@ interface PluginEntry {
 
 export interface PluginDescription {
   id: string;
-  type: PluginType;
+  types: readonly PluginType[];
   version: string;
   name: string;
   status: PluginStatus;
@@ -83,7 +84,7 @@ export class PluginRegistry {
     }
     this.idSet.add(plugin.id);
     this.entries.push({ plugin, status: "registered" });
-    log.info({ pluginId: plugin.id, type: plugin.type }, "Plugin registered");
+    log.info({ pluginId: plugin.id, types: plugin.types }, "Plugin registered");
   }
 
   /**
@@ -190,13 +191,18 @@ export class PluginRegistry {
     return this.entries.find((e) => e.plugin.id === id)?.status;
   }
 
-  /** Return plugins of the given type that are currently healthy. */
+  /** Return plugins whose types array includes the given type and are currently healthy. */
   getByType(type: PluginType): PluginLike[] {
     return this.entries
-      .filter((e) => e.plugin.type === type && e.status === "healthy")
+      .filter((e) => e.plugin.types.includes(type) && e.status === "healthy")
       .map((e) => e.plugin);
   }
 
+  /** Return all registered plugins regardless of status (for schema migrations at boot). */
+  getAll(): PluginLike[] {
+    return this.entries.map((e) => e.plugin);
+  }
+
   /** Return all healthy plugins regardless of type (for cross-cutting hooks). */
   getAllHealthy(): PluginLike[] {
     return this.entries
@@ -208,7 +214,7 @@ export class PluginRegistry {
   describe(): PluginDescription[] {
     return this.entries.map((e) => ({
       id: e.plugin.id,
-      type: e.plugin.type,
+      types: e.plugin.types,
       version: e.plugin.version,
       name: e.plugin.name ?? e.plugin.id,
       status: e.status,

package/templates/nextjs-standalone/src/lib/plugins/wiring.ts

@@ -28,6 +28,8 @@ interface DatasourceShape {
     create(): Promise<{ query(sql: string, timeoutMs?: number): Promise<unknown>; close(): Promise<void> }> | { query(sql: string, timeoutMs?: number): Promise<unknown>; close(): Promise<void> };
     dbType: string;
     validate?(query: string): { valid: boolean; reason?: string };
+    parserDialect?: string;
+    forbiddenPatterns?: RegExp[];
   };
   entities?: unknown[] | (() => Promise<unknown[]> | unknown[]);
   dialect?: string;
@@ -51,7 +53,7 @@ interface InteractionShape {
 
 function hasContextProvider(p: PluginLike): p is PluginLike & ContextShape {
   return (
-    p.type === "context" &&
+    p.types.includes("context") &&
     typeof (p as Record<string, unknown>).contextProvider === "object" &&
     (p as Record<string, unknown>).contextProvider !== null &&
     typeof ((p as Record<string, unknown>).contextProvider as Record<string, unknown>)?.load === "function"
@@ -60,18 +62,18 @@ function hasContextProvider(p: PluginLike): p is PluginLike & ContextShape {
 
 function hasDatasource(p: PluginLike): p is PluginLike & DatasourceShape {
   return (
-    p.type === "datasource" &&
+    p.types.includes("datasource") &&
     typeof (p as Record<string, unknown>).connection === "object" &&
     (p as Record<string, unknown>).connection !== null
   );
 }
 
 function hasActions(p: PluginLike): p is PluginLike & ActionShape {
-  return p.type === "action" && Array.isArray((p as Record<string, unknown>).actions);
+  return p.types.includes("action") && Array.isArray((p as Record<string, unknown>).actions);
 }
 
 function hasRoutes(p: PluginLike): p is PluginLike & InteractionShape {
-  return p.type === "interaction" && typeof (p as Record<string, unknown>).routes === "function";
+  return p.types.includes("interaction") && typeof (p as Record<string, unknown>).routes === "function";
 }
 
 // ---------------------------------------------------------------------------
@@ -106,12 +108,16 @@ export async function wireDatasourcePlugins(
     }
     try {
       const conn = await plugin.connection.create();
+      const meta = (plugin.connection.parserDialect || plugin.connection.forbiddenPatterns)
+        ? { parserDialect: plugin.connection.parserDialect, forbiddenPatterns: plugin.connection.forbiddenPatterns }
+        : undefined;
       await connRegistry.registerDirect(
         plugin.id,
         conn as Parameters<ConnectionRegistry["registerDirect"]>[1],
         plugin.connection.dbType as Parameters<ConnectionRegistry["registerDirect"]>[2],
         plugin.name ?? plugin.id,
         plugin.connection.validate,
+        meta,
       );
       wired.push(plugin.id);
       log.info({ pluginId: plugin.id, dbType: plugin.connection.dbType }, "Datasource plugin wired");
@@ -254,6 +260,109 @@ export async function wireInteractionPlugins(
   return { wired, failed };
 }
 
+// ---------------------------------------------------------------------------
+// Sandbox plugins
+// ---------------------------------------------------------------------------
+
+/**
+ * Duplicated from @useatlas/plugin-sdk/types to avoid runtime SDK dependency.
+ * Keep in sync — explore-sdk-compat.test.ts verifies structural equivalence.
+ */
+const SANDBOX_DEFAULT_PRIORITY = 60;
+
+/**
+ * Minimal interface for a sandbox execution backend.
+ * Structurally identical to ExploreBackend in explore.ts — duplicated here
+ * to avoid a circular dependency (explore.ts imports from wiring.ts).
+ * Changes to either interface should be mirrored.
+ */
+export interface SandboxExecBackend {
+  exec(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+  close?(): Promise<void>;
+}
+
+interface SandboxShape {
+  sandbox: {
+    create(root: string): Promise<SandboxExecBackend> | SandboxExecBackend;
+    priority?: number;
+  };
+}
+
+function hasSandbox(p: PluginLike): p is PluginLike & SandboxShape {
+  return (
+    p.types.includes("sandbox") &&
+    typeof (p as Record<string, unknown>).sandbox === "object" &&
+    (p as Record<string, unknown>).sandbox !== null &&
+    typeof ((p as Record<string, unknown>).sandbox as Record<string, unknown>)?.create === "function"
+  );
+}
+
+/**
+ * Discover sandbox plugins, sort by priority (highest first), and try to
+ * create a backend from each until one succeeds.
+ *
+ * Unlike other wire functions, sandbox plugins are not registered into a
+ * global registry — the caller receives a single backend instance directly.
+ *
+ * NOTE: In practice, called lazily from getExploreBackend() on the first
+ * explore command (not at startup), because the explore backend is cached
+ * as a singleton and depends on runtime environment detection.
+ */
+export async function wireSandboxPlugins(
+  pluginRegistry: PluginRegistry,
+  semanticRoot: string,
+): Promise<{
+  backend: SandboxExecBackend | null;
+  pluginId: string | null;
+  failed: Array<{ pluginId: string; error: string }>;
+}> {
+  const sandboxPlugins = pluginRegistry.getByType("sandbox");
+  const failed: Array<{ pluginId: string; error: string }> = [];
+
+  if (sandboxPlugins.length === 0) {
+    return { backend: null, pluginId: null, failed };
+  }
+
+  // Filter to valid sandbox plugins, sort by priority descending
+  const valid = sandboxPlugins.filter(hasSandbox);
+  if (valid.length === 0) {
+    for (const sp of sandboxPlugins) {
+      log.warn({ pluginId: sp.id }, "Sandbox plugin missing sandbox.create() — skipped");
+    }
+    return { backend: null, pluginId: null, failed };
+  }
+
+  const sorted = [...valid].sort((a, b) => {
+    const pa = a.sandbox.priority ?? SANDBOX_DEFAULT_PRIORITY;
+    const pb = b.sandbox.priority ?? SANDBOX_DEFAULT_PRIORITY;
+    return pb - pa;
+  });
+
+  for (const sp of sorted) {
+    try {
+      const backend = await sp.sandbox.create(semanticRoot);
+      if (!backend || typeof backend.exec !== "function") {
+        const msg = "create() returned invalid backend (missing exec method)";
+        failed.push({ pluginId: sp.id, error: msg });
+        log.error({ pluginId: sp.id }, msg);
+        continue;
+      }
+      log.info({ pluginId: sp.id }, "Using sandbox plugin for explore backend");
+      return { backend, pluginId: sp.id, failed };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      failed.push({ pluginId: sp.id, error: msg });
+      log.error(
+        { pluginId: sp.id, err: err instanceof Error ? err : new Error(String(err)) },
+        "Sandbox plugin create() failed, trying next",
+      );
+    }
+  }
+
+  log.error({ count: sorted.length }, "All sandbox plugins failed to create a backend");
+  return { backend: null, pluginId: null, failed };
+}
+
 /**
  * For each healthy context plugin, call `contextProvider.load()` and collect
  * the returned text fragments. Fragments are injected into the agent system