feat(codemode): add opt-in scripted tool execution

docs/configuration.md

@@ -102,6 +102,37 @@ The dedicated MCP tools `grep`, `glob`, and `ls` are not exposed. Each mode uses
 its shell tool with programs such as `rg`, `find`, and `ls` when it needs those
 operations.
 
+### Experimental Code Mode
+
+Set `DEVSPACE_EXPERIMENTAL_CODE_MODE=1` **when starting the server** to try
+JavaScript-based tool composition without changing `tools.mode`:
+
+```sh
+DEVSPACE_EXPERIMENTAL_CODE_MODE=1 pnpm dev
+```
+
+This overrides the model-facing coding tools with `open_workspace`, `execute`,
+`poll_execution`, `cancel_execution`, and `show_changes`. When native artifact
+download is enabled, `download_artifact` remains a separate tool. The existing
+Codex primitives are available *inside* `execute`, with their JavaScript signatures
+returned by `open_workspace` and `workspace_id` bound automatically. Scripts can
+use top-level `await` and `return`, but cannot import modules or access Node.js
+globals directly.
+
+`execute` returns a result immediately when possible, or an `execution_id` after
+its yield window (10 seconds by default, 12 seconds maximum). Use
+`poll_execution` with that ID to await completion without rerunning the script,
+or `cancel_execution` to stop it. Long-running nested `exec_command` calls return
+`session_id` for polling via `tools.write_stdin` inside the script.
+
+The experimental runtime has a five-minute script deadline, up to 32 nested tool
+calls and four simultaneous nested calls. Sessions and results are in memory only
+and are lost on server restart. Tool calls already performed are **not rolled
+back** when a script fails or is cancelled.
+
+Unset the variable or set it to `0` and restart to restore the configured tool
+surface. This experimental switch is not a persistent config key.
+
 DevSpace attaches Apps UI metadata only to `open_workspace` and `show_changes`.
 This avoids rendering an iframe for every read, edit, search, or command call.
 Setting `ui.enabled` to `false` removes the metadata but does not remove the
@@ -197,7 +228,9 @@ Windows; the tool is not registered on BSD.
 
 ## Environment boundary
 
-Only two user-facing DevSpace environment variables remain:
+Only two persistent user-facing DevSpace environment variables remain
+(apart from temporary experiment switches such as
+`DEVSPACE_EXPERIMENTAL_CODE_MODE`):
 
 | Variable | Purpose |
 | --- | --- |

package.json

@@ -52,6 +52,7 @@
     "@anthropic-ai/claude-agent-sdk": "0.3.200",
     "@anthropic-ai/sandbox-runtime": "0.0.71",
     "@clack/prompts": "^1.5.1",
+    "@earendil-works/pi-codemode": "1.1.0",
     "@earendil-works/pi-coding-agent": "^0.80.3",
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/node": "^2.0.0",

src/code-mode-executions.ts

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import type { CodemodeResult } from "@earendil-works/pi-codemode";
+import type { ProcessSessionManager } from "./process-sessions.js";
+import type { CodeModeRegistry } from "./code-mode-registry.js";
+
+export const MAX_CODE_MODE_YIELD_MS = 12_000;
+const DEFAULT_YIELD_MS = 10_000;
+const DEFAULT_POLL_MS = 5_000;
+const MAX_SCRIPT_MS = 5 * 60_000;
+const MAX_CALLS = 32;
+const MAX_CONCURRENT_CALLS = 4;
+const COMPLETED_TTL_MS = 5 * 60_000;
+
+type Status = "running" | "completed" | "failed" | "cancelled";
+
+interface Execution {
+  id: string;
+  workspaceId: string;
+  status: Status;
+  controller: AbortController;
+  done: Promise<void>;
+  result?: CodemodeResult;
+  error?: string;
+  startedAt: number;
+  finishedAt?: number;
+  processSessionIds: Set<number>;
+  cleanupTimer?: NodeJS.Timeout;
+}
+
+export interface ExecutionSnapshot {
+  execution_id: string;
+  running: boolean;
+  status: Status;
+  result?: unknown;
+  output?: string[];
+  error?: string;
+  calls?: CodemodeResult["calls"];
+}
+
+function yieldWindow(ms: number | undefined, fallback: number): number {
+  return ms === undefined ? fallback : Math.min(ms, MAX_CODE_MODE_YIELD_MS);
+}
+
+export class CodeModeExecutions {
+  private readonly executions = new Map<string, Execution>();
+
+  constructor(
+    private readonly registry: CodeModeRegistry,
+    private readonly processes: ProcessSessionManager,
+  ) {}
+
+  async start(workspaceId: string, code: string, yieldTimeMs?: number): Promise<ExecutionSnapshot> {
+    const id = randomUUID();
+    const execution: Execution = {
+      id,
+      workspaceId,
+      status: "running",
+      controller: new AbortController(),
+      done: Promise.resolve(),
+      startedAt: performance.now(),
+      processSessionIds: new Set(),
+    };
+    this.executions.set(id, execution);
+    execution.done = this.run(execution, code);
+    await this.wait(execution, yieldWindow(yieldTimeMs, DEFAULT_YIELD_MS));
+    return this.snapshot(execution);
+  }
+
+  async poll(workspaceId: string, id: string, yieldTimeMs?: number): Promise<ExecutionSnapshot> {
+    const execution = this.get(workspaceId, id);
+    await this.wait(execution, yieldWindow(yieldTimeMs, DEFAULT_POLL_MS));
+    return this.snapshot(execution);
+  }
+
+  cancel(workspaceId: string, id: string): ExecutionSnapshot {
+    const execution = this.get(workspaceId, id);
+    if (execution.status === "running") {
+      execution.controller.abort(new Error("Execution cancelled by user."));
+      this.terminateProcesses(execution);
+    }
+    return this.snapshot(execution);
+  }
+
+  async shutdown(): Promise<void> {
+    for (const execution of this.executions.values()) {
+      if (execution.cleanupTimer) clearTimeout(execution.cleanupTimer);
+      if (execution.status === "running") {
+        execution.controller.abort(new Error("DevSpace shutting down."));
+        this.terminateProcesses(execution);
+      }
+    }
+    await Promise.allSettled([...this.executions.values()].map((execution) => execution.done));
+    this.executions.clear();
+  }
+
+  private get(workspaceId: string, id: string): Execution {
+    const execution = this.executions.get(id);
+    if (!execution || execution.workspaceId !== workspaceId) {
+      throw new Error("Code execution does not exist in this workspace.");
+    }
+    return execution;
+  }
+
+  private snapshot(execution: Execution): ExecutionSnapshot {
+    const result = execution.result;
+    return {
+      execution_id: execution.id,
+      running: execution.status === "running",
+      status: execution.status,
+      ...(result?.ok ? { result: result.value } : {}),
+      ...(result ? {
+        output: result.output.filter((item) => item.type === "text").map((item) => item.text),
+        calls: result.calls,
+      } : {}),
+      ...(execution.error ? { error: execution.error } : {}),
+    };
+  }
+
+  private async wait(execution: Execution, ms: number): Promise<void> {
+    let timer: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        execution.done,
+        new Promise<void>((resolve) => { timer = setTimeout(resolve, ms); }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  private terminateProcesses(execution: Execution): void {
+    for (const id of execution.processSessionIds) {
+      try {
+        this.processes.terminate(execution.workspaceId, id);
+      } catch {
+        // A process might have finished and been reaped already.
+      }
+    }
+  }
+
+  private async run(execution: Execution, code: string): Promise<void> {
+    try {
+      // The worker and WASM runtime are loaded only when the experimental mode runs a script.
+      const { CodemodeSandbox } = await import("@earendil-works/pi-codemode");
+      let calls = 0;
+      let active = 0;
+      const waiters: Array<() => void> = [];
+      const tools = this.registry.tools(execution.workspaceId, (id) => execution.processSessionIds.add(id))
+        .map((tool) => ({
+          ...tool,
+          execute: async (args: unknown, context: Parameters<typeof tool.execute>[1]) => {
+            if (++calls > MAX_CALLS) throw new Error(`Code Mode limit exceeded: ${MAX_CALLS} tool calls.`);
+            if (active >= MAX_CONCURRENT_CALLS) await new Promise<void>((resolve) => waiters.push(resolve));
+            active++;
+            try {
+              if (execution.controller.signal.aborted) throw new Error("Code execution cancelled.");
+              return await tool.execute(args, context);
+            } finally {
+              active--;
+              waiters.shift()?.();
+            }
+          },
+        }));
+      const sandbox = new CodemodeSandbox({
+        tools,
+        timeoutMs: MAX_SCRIPT_MS,
+        memoryLimitBytes: 256 * 1024 * 1024,
+      });
+      try {
+        execution.result = await sandbox.execute(code, { signal: execution.controller.signal });
+        execution.status = execution.controller.signal.aborted ? "cancelled" : execution.result.ok ? "completed" : "failed";
+        if (!execution.result.ok) execution.error = execution.result.error.message;
+      } finally {
+        await sandbox.close();
+      }
+    } catch (error) {
+      execution.error = error instanceof Error ? error.message : String(error);
+      execution.status = execution.controller.signal.aborted ? "cancelled" : "failed";
+    } finally {
+      if (execution.status !== "completed") this.terminateProcesses(execution);
+      execution.finishedAt = performance.now();
+      execution.cleanupTimer = setTimeout(() => this.executions.delete(execution.id), COMPLETED_TTL_MS);
+      execution.cleanupTimer.unref();
+    }
+  }
+}

src/code-mode-registry.ts

@@ -0,0 +1,77 @@
+import {
+  renderDeclarations,
+  type CodemodeTool,
+} from "@earendil-works/pi-codemode";
+import * as z from "zod/v4";
+import type { McpRegistrationTarget } from "./mcp-modern-server.js";
+import { contentText } from "./tool-surfaces/shared.js";
+import type { ToolContent } from "./tool-surfaces/types.js";
+
+type Handler = (input: Record<string, unknown>, extra: { signal: AbortSignal }) => Promise<{
+  isError?: boolean;
+  content?: ToolContent[];
+  structuredContent?: Record<string, unknown>;
+}>;
+
+interface Entry {
+  name: string;
+  description: string;
+  input: z.ZodObject<z.ZodRawShape>;
+  output: z.ZodObject<z.ZodRawShape>;
+  handler: Handler;
+}
+
+/** Records the real MCP registrations, so Code Mode never duplicates their handlers or schemas. */
+export class CodeModeRegistry {
+  private readonly entries = new Map<string, Entry>();
+
+  readonly registrationTarget: McpRegistrationTarget = {
+    registerTool: ((name: string, definition: Record<string, unknown>, handler: Handler) => {
+      const input = z.object(definition.inputSchema as z.ZodRawShape);
+      const output = z.object(definition.outputSchema as z.ZodRawShape);
+      this.entries.set(name, {
+        name,
+        description: definition.description as string,
+        input,
+        output,
+        handler,
+      });
+      // This target collects internal registrations; nothing is registered with the MCP host.
+      return undefined;
+    }) as unknown as McpRegistrationTarget["registerTool"],
+    registerResource: (() => undefined) as unknown as McpRegistrationTarget["registerResource"],
+  };
+
+  signatures(): string {
+    return renderDeclarations({ tools: [...this.entries.values()].map((entry) => ({
+      name: entry.name,
+      description: entry.description,
+      inputSchema: z.toJSONSchema(entry.input.omit({ workspace_id: true })),
+      outputSchema: z.toJSONSchema(entry.output),
+      execute: () => undefined,
+    })) });
+  }
+
+  tools(workspaceId: string, onProcessSession: (id: number) => void): CodemodeTool[] {
+    return [...this.entries.values()].map((entry) => ({
+      name: entry.name,
+      description: entry.description,
+      inputSchema: z.toJSONSchema(entry.input.omit({ workspace_id: true })),
+      outputSchema: z.toJSONSchema(entry.output),
+      execute: async (value: unknown, { signal }) => {
+        if (signal.aborted) throw new Error("Code execution cancelled.");
+        const parsed = entry.input.safeParse({ ...(typeof value === "object" && value !== null ? value : {}), workspace_id: workspaceId });
+        if (!parsed.success) throw new Error(parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+        const response = await entry.handler(parsed.data, { signal });
+        if (response.isError) throw new Error(contentText(response.content ?? []) || `${entry.name} failed`);
+        const result = response.structuredContent ?? { result: contentText(response.content ?? []) };
+        const validated = entry.output.safeParse(result);
+        if (!validated.success) throw new Error(`Invalid ${entry.name} response: ${validated.error.message}`);
+        if (entry.name === "exec_command" && result.running === true && typeof result.session_id === "number") {
+          onProcessSession(result.session_id);
+        }
+        return result;
+      },
+    }));
+  }
+}

src/config.test.ts

@@ -19,6 +19,9 @@ try {
   assert.deepEqual(defaults.allowedRoots, [process.cwd()]);
   assert.deepEqual(defaults.allowedHosts, ["localhost", "127.0.0.1", "::1"]);
   assert.equal(defaults.toolMode, "codex");
+  assert.equal(defaults.experimentalCodeMode, false);
+  assert.equal(loadConfig({ ...env, DEVSPACE_EXPERIMENTAL_CODE_MODE: "1" }).experimentalCodeMode, true);
+  assert.equal(loadConfig({ ...env, DEVSPACE_EXPERIMENTAL_CODE_MODE: "0" }).experimentalCodeMode, false);
   assert.equal(defaults.uiEnabled, true);
   assert.equal(defaults.skillsEnabled, true);
   assert.equal(defaults.artifactsEnabled, false);

src/config.ts

@@ -17,6 +17,7 @@ export interface ServerConfig {
   allowedHosts: string[];
   publicBaseUrl: string;
   toolMode: ToolMode;
+  experimentalCodeMode: boolean;
   uiEnabled: boolean;
   stateDir: string;
   worktreeRoot: string;
@@ -66,6 +67,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
     allowedHosts: normalizeAllowedHosts(derivedAllowedHosts),
     publicBaseUrl,
     toolMode: stored.tools.mode,
+    experimentalCodeMode: env.DEVSPACE_EXPERIMENTAL_CODE_MODE === "1",
     uiEnabled: stored.ui.enabled,
     stateDir: normalizePath(stored.storage.stateDir),
     worktreeRoot: normalizePath(stored.workspaces.worktreeRoot),