feat(python): expose Pyodide python/python3 CLI + pin secure-exec preview

- rpc-client: route python/python3 through the direct command path (like node)
- e2e: tests/python-cli.test.ts (-c, vm.exec, /workspace script+argv, -m, python3, stdin) — 6/6 green
- docs: add Python Runtime page (why Pyodide vs native wasip1 build, virtual-OS integration matrix, packages/native modules, pip, gaps vs CPython)
- pin @secure-exec/* to published preview 0.0.0-python-cli.d4b0bd4 (crates build from clone at d4b0bd4)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

.claude/commands/goal.md

@@ -0,0 +1,21 @@
+---
+description: Add a Pyodide-powered `python` CLI runtime to agentOS (full CPython parity)
+---
+
+# Goal: Pyodide-powered `python` CLI in agentOS
+
+- Spec (read first): `~/.agents/specs/python-cli-pyodide.md`
+- Workspaces: secure-exec `/home/nathan/secure-exec-python-cli` · agent-os `/home/nathan/agent-os-python-cli`
+
+## Acceptance criteria
+
+- [ ] `python -c "print(1+1)"` → `2`
+- [ ] `python script.py a b` runs the file with correct `sys.argv`
+- [ ] `sh -c "python script.py"` works (nested child_process / agent shell path)
+- [ ] `python -m <module>` runs a module
+- [ ] `echo "print(1)" | python -` reads the program from stdin
+- [ ] bare `python` gives an interactive REPL (PS1/PS2, clean EOF exit)
+- [ ] `pip install <pure-python pkg>` then `import` succeeds (micropip; egress via kernel policy)
+- [ ] All paths run through Pyodide, covered by secure-exec wire tests + ≥1 agent-os e2e test
+- [ ] TS `GuestRuntimeKind` includes `"python"`; `/bin/python` exists and resolves on PATH
+- [ ] Pushed state pins a published secure-exec preview (no local `path:`/`link:` deps)

packages/core/src/sidecar/rpc-client.ts

@@ -191,7 +191,12 @@ function canUseDirectExec(
 	driver: string | undefined,
 	commandName: string | undefined,
 ): boolean {
-	return driver === "wasmvm" || (driver === "node" && commandName === "node");
+	return (
+		driver === "wasmvm" ||
+		(driver === "node" && commandName === "node") ||
+		(driver === "python" &&
+			(commandName === "python" || commandName === "python3"))
+	);
 }
 
 function shellSingleQuote(value: string): string {
@@ -2342,6 +2347,10 @@ function buildCommandMap(
 		["node", "node"],
 		["npm", "node"],
 		["npx", "node"],
+		// `python` / `python3` are served by the embedded Pyodide runtime,
+		// mirroring how `node` is served by the embedded V8 runtime.
+		["python", "python"],
+		["python3", "python"],
 	]);
 	for (const name of commandGuestPaths.keys()) {
 		commands.set(name, "wasmvm");

packages/core/tests/python-cli.test.ts

@@ -0,0 +1,97 @@
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { AgentOs } from "../src/index.js";
+
+// End-to-end coverage for the Pyodide-powered `python` / `python3` CLI exposed
+// by secure-exec, driven through the public AgentOs API. `python` resolves as a
+// runtime command (like `node`), so `vm.exec()` / `vm.execArgv()` route it
+// directly to the embedded Pyodide runtime — no guest shell or WASM commands
+// required. Scripts must live under `/workspace`, the path the Python runtime
+// bridges into Pyodide's filesystem.
+describe("python CLI (Pyodide runtime)", () => {
+	let vm: AgentOs;
+
+	beforeAll(async () => {
+		vm = await AgentOs.create();
+	}, 120_000);
+
+	afterAll(async () => {
+		await vm?.dispose();
+	});
+
+	test(
+		"python -c runs inline code",
+		async () => {
+			const result = await vm.execArgv("python", ["-c", "print(1 + 1)"]);
+			expect(result.exitCode, result.stderr).toBe(0);
+			expect(result.stdout.trim()).toBe("2");
+		},
+		120_000,
+	);
+
+	test(
+		"python via vm.exec (agent command path) runs inline code",
+		async () => {
+			const result = await vm.exec('python -c "print(2 + 3)"');
+			expect(result.exitCode, result.stderr).toBe(0);
+			expect(result.stdout.trim()).toBe("5");
+		},
+		120_000,
+	);
+
+	test(
+		"python runs a /workspace script file with sys.argv",
+		async () => {
+			await vm.mkdir("/workspace");
+			await vm.writeFile(
+				"/workspace/argv.py",
+				"import sys\nprint(','.join(sys.argv))\n",
+			);
+			const result = await vm.execArgv("python", [
+				"/workspace/argv.py",
+				"alpha",
+				"beta",
+			]);
+			expect(result.exitCode, result.stderr).toBe(0);
+			expect(result.stdout.trim()).toBe("/workspace/argv.py,alpha,beta");
+		},
+		120_000,
+	);
+
+	test(
+		"python -m runs a module",
+		async () => {
+			const result = await vm.execArgv("python", ["-m", "this"]);
+			expect(result.exitCode, result.stderr).toBe(0);
+			expect(result.stdout).toContain("Beautiful is better than ugly");
+		},
+		120_000,
+	);
+
+	test(
+		"python3 alias runs inline code",
+		async () => {
+			const result = await vm.execArgv("python3", ["-c", "print(6 * 7)"]);
+			expect(result.exitCode, result.stderr).toBe(0);
+			expect(result.stdout.trim()).toBe("42");
+		},
+		120_000,
+	);
+
+	test(
+		"python - reads the program from stdin",
+		async () => {
+			const chunks: string[] = [];
+			const { pid } = vm.spawn("python", ["-"], {
+				onStdout: (data) => chunks.push(Buffer.from(data).toString("utf8")),
+			});
+			vm.writeProcessStdin(pid, "print('from stdin program')\n");
+			vm.closeProcessStdin(pid);
+			const exitCode = await vm.waitProcess(pid);
+			// Native-sidecar process_output can lag the exit notification by a turn.
+			await new Promise((resolve) => setTimeout(resolve, 0));
+			expect(exitCode).toBe(0);
+			expect(chunks.join("")).toContain("from stdin program");
+		},
+		120_000,
+	);
+});