@pandi-coding-agent/pandi-podman 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @pandi-coding-agent/pandi-podman
+
+Corré una orden puntual en un contenedor Podman efímero sin abrir una superficie genérica de Docker/Podman. Usalo cuando
+necesitás una herramienta Linux acotada y descartable; para administrar imágenes, volúmenes, builds o deploys, usá la
+CLI de Podman directamente. La extensión usa argv, nunca shell, y su `run` no puede montar el host, publicar puertos ni
+elevar privilegios. 🐼
+
+## Inicio rápido
+
+```bash
+/podman status
+/podman run quay.io/podman/hello:latest -- /hello
+/podman list
+```
+
+El `run` usa red aislada por defecto. Cuando una tarea realmente necesita red dentro del contenedor, hacelo explícito:
+
+```bash
+/podman run --network default alpine:latest -- wget -qO- https://example.com
+```
+
+## Instalación
+
+```bash
+# Desde npm
+pi install npm:@pandi-coding-agent/pandi-podman
+
+# Desde este repositorio
+pi install ./extensions/pandi-podman
+pi install -l ./extensions/pandi-podman
+pi --no-extensions -e ./extensions/pandi-podman
+```
+
+Instalá Podman por separado: en macOS, `brew install podman`; en Linux, usá el gestor de paquetes de la distribución.
+macOS y Windows ejecutan contenedores dentro de una Podman machine; iniciala una vez con `podman machine init` y usá
+`/podman machine-start` cuando esté detenida.
+
+## Superficie
+
+| Surface          | Acciones                                                                   | Para qué                                                              |
+| ---------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `/podman`        | `status`, `list`, `run`, `stop`, `remove`, `machine-list`, `machine-start` | Operación humana, selector en TUI y confirmación para borrar.         |
+| `podman_sandbox` | Las mismas acciones explícitas                                             | Tool del modelo, con `command: string[]` y `force: true` para borrar. |
+
+### Comandos
+
+```text
+/podman [status]
+/podman list
+/podman run [--network none|default] <image> -- <cmd...>
+/podman stop <container>
+/podman remove <container>
+/podman machine-list
+/podman machine-start [name]
+```
+
+`/podman` sin argumentos abre el selector de acciones en la TUI; fuera de ella equivale a `status`. `remove` pide
+confirmación y no elimina nada en modo headless.
+
+### Tool `podman_sandbox`
+
+La tool recibe una `action` y solo estos campos para `run`:
+
+| Campo            | Significado                                                      |
+| ---------------- | ---------------------------------------------------------------- |
+| `image`          | Referencia OCI, por ejemplo `quay.io/podman/hello:latest`.       |
+| `command`        | Array argv obligatorio, por ejemplo `["uname", "-a"]`.           |
+| `network`        | `none` por defecto; `default` es opt-in explícito.               |
+| `workdir`        | Ruta absoluta dentro del contenedor.                             |
+| `cpus`, `memory` | Límites que solo pueden endurecer los defaults de 2 CPU y 1G.    |
+| `name`           | Contenedor para `stop`/`remove`, o máquina para `machine-start`. |
+| `force`          | Obligatorio para `remove`.                                       |
+
+Ejemplo mínimo:
+
+```jsonc
+{
+  "action": "run",
+  "image": "quay.io/podman/hello:latest",
+  "command": ["/hello"],
+}
+```
+
+## Política del sandbox
+
+Cada `run` genera este tipo de ejecución: contenedor efímero (`--rm`), sin red por defecto, filesystem raíz read-only,
+`/tmp` temporal, `--cap-drop ALL`, `no-new-privileges`, 256 PIDs, 2 CPU y 1G de memoria. La extensión no expone
+mounts/volumes, puertos, variables de entorno, devices, capabilities extra, `--privileged` ni flags libres.
+
+| Necesitás…                                  | Elegí                                      |
+| ------------------------------------------- | ------------------------------------------ |
+| Ejecutar una orden aislada y descartable    | `podman_sandbox` / `/podman run`           |
+| Red dentro de un run puntual                | `network: "default"` / `--network default` |
+| Un contenedor existente                     | `/podman list`, `stop` o `remove`          |
+| Imágenes, mounts, puertos, builds o compose | La CLI `podman` directa                    |
+| Una micro-VM Apple para código no confiable | `container_sandbox` de `pandi-container`   |
+
+## Seguridad y límites
+
+- Podman no es una frontera de seguridad infalible contra código hostil, especialmente en Linux. Evaluá la confianza de
+  la imagen y del comando antes de ejecutarlos.
+- Aunque el contenedor no recibe mounts del host, un pull de imagen y un `run` tienen efectos operativos en el almacén
+  de Podman. La extensión no intenta ocultarlo.
+- `remove` solo avanza con una confirmación TUI o `force: true` explícito en la tool. `stop` y `machine-start` no son
+  destructivos, pero sí cambian estado.
+- En macOS/Windows, `status` muestra las máquinas disponibles aunque la conexión de Podman esté caída y propone
+  `/podman machine-start`.
+- Cada llamada tiene un timeout de 120 s; `PI_PODMAN_TIMEOUT_MS` permite ampliarlo para pulls lentos o comandos
+  legítimamente largos.
+
+## Desarrollo
+
+La suite no crea contenedores reales: prueba argv exactos, fixtures JSON, handlers con runner inyectado y abort/CLI
+ausente reales. Corréla en forma aislada:
+
+```bash
+node --test extensions/pandi-podman/tests/integration/podman-extension.test.mjs
+```
+
+Después verificá TypeScript, Markdown y los syncs del paquete antes de probar una sesión Pi viva en un worktree aparte.

package/command-handler.ts

@@ -0,0 +1,102 @@
+/**
+ * Comando `/podman` para personas.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parsePodmanCommand, parseRunOptions } from "./command.js";
+import { completePodmanArgs, resolvePodmanInput } from "./command-menu.js";
+import { buildHandlerOpts } from "./handler-opts.js";
+import { notify } from "./notify.js";
+import {
+	type HandlerResult,
+	runList,
+	runMachineList,
+	runMachineStart,
+	runPodman,
+	runRemove,
+	runSandbox,
+	runStatus,
+	runStop,
+} from "./podman.js";
+
+export const HELP_TEXT = [
+	"Uso:",
+	"  /podman [status]                                  resumen de Podman",
+	"  /podman list                                      lista todos los contenedores",
+	"  /podman run [--network none|default] <image> -- <cmd...>  sandbox efímero restringido",
+	"  /podman stop <container>                          detiene un contenedor",
+	"  /podman remove <container>                        elimina un contenedor (pide confirmación)",
+	"  /podman machine-list                              lista las máquinas de Podman",
+	"  /podman machine-start [name]                      inicia una máquina existente",
+	"",
+	"Los sandboxes no montan el host, no publican puertos, eliminan capacidades y usan red none por defecto.",
+	"`--network default` es opt-in; no hay flags libres ni acceso a secretos del host.",
+].join("\n");
+
+async function runCommand(ctx: ExtensionContext, input: string): Promise<void> {
+	const parsed = parsePodmanCommand(await resolvePodmanInput(input, ctx));
+	const opts = buildHandlerOpts(ctx.cwd, ctx.signal);
+	if (parsed.action === "help" || parsed.action === "-h" || parsed.action === "--help") {
+		notify(ctx, HELP_TEXT, "info");
+		return;
+	}
+
+	let result: HandlerResult;
+	switch (parsed.action) {
+		case "status":
+			result = await runStatus(runPodman, opts);
+			break;
+		case "list":
+		case "ls":
+			result = await runList(runPodman, opts);
+			break;
+		case "run": {
+			const runOptions = parseRunOptions(parsed.rest);
+			if (runOptions.error) {
+				notify(ctx, runOptions.error, "warning");
+				return;
+			}
+			result = await runSandbox(
+				runPodman,
+				{ image: runOptions.image ?? "", network: runOptions.network, command: parsed.command },
+				opts,
+			);
+			break;
+		}
+		case "stop":
+			result = await runStop(runPodman, { name: parsed.rest[0] }, opts);
+			break;
+		case "remove":
+		case "rm": {
+			const name = parsed.rest[0] ?? "";
+			const force = ctx.hasUI
+				? await ctx.ui.confirm(
+						"¿Eliminar el contenedor de Podman?",
+						`Esto elimina permanentemente el contenedor "${name}".`,
+					)
+				: false;
+			result = await runRemove(runPodman, { name, force }, opts);
+			break;
+		}
+		case "machine-list":
+			result = await runMachineList(runPodman, opts);
+			break;
+		case "machine-start":
+			result = await runMachineStart(runPodman, { name: parsed.rest[0] }, opts);
+			break;
+		default:
+			notify(ctx, `Subcomando desconocido: ${parsed.action}\n\n${HELP_TEXT}`, "warning");
+			return;
+	}
+	notify(ctx, result.text, result.ok ? "info" : "error");
+}
+
+export function registerPodmanCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("podman", {
+		description: "Administrá sandboxes de Podman: status | list | run | stop | remove | machine-list | machine-start",
+		getArgumentCompletions: completePodmanArgs,
+		handler: async (args, ctx) => {
+			await runCommand(ctx, args);
+		},
+	});
+}

package/command-menu.ts

@@ -0,0 +1,28 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const PODMAN_ACTIONS = [
+	{ value: "status", description: "resumen de Podman y sus recursos" },
+	{ value: "list", description: "lista todos los contenedores" },
+	{ value: "run", description: "ejecuta un sandbox efímero restringido" },
+	{ value: "stop", description: "detiene un contenedor" },
+	{ value: "remove", description: "elimina un contenedor (pide confirmación)" },
+	{ value: "machine-list", description: "lista máquinas de Podman" },
+	{ value: "machine-start", description: "inicia una máquina de Podman" },
+] as const;
+
+const ACTION_NAMES = PODMAN_ACTIONS.map(({ value }) => value);
+export const PODMAN_SELECT_ITEMS = PODMAN_ACTIONS.map(({ value, description }) => `${value} — ${description}`);
+
+export function completePodmanArgs(prefix: string): { value: string; label: string }[] | null {
+	if (prefix.trim().split(/\s+/).length > 1) return null;
+	const needle = prefix.trim().toLowerCase();
+	const matches = ACTION_NAMES.filter((action) => action.startsWith(needle));
+	return matches.length ? matches.map((value) => ({ value, label: value })) : null;
+}
+
+export async function resolvePodmanInput(input: string, ctx: ExtensionContext): Promise<string> {
+	const trimmed = input.trim();
+	if (trimmed || !ctx.hasUI || typeof ctx.ui?.select !== "function") return trimmed;
+	const choice = await ctx.ui.select("Acción de Podman", PODMAN_SELECT_ITEMS);
+	return choice?.split(/\s+/)[0] ?? "";
+}

package/command.ts

@@ -0,0 +1,37 @@
+/** Parseo deliberadamente pequeño para `/podman`; los comandos internos llegan como argv tras `--`. */
+
+export function parsePodmanCommand(input: string): { action: string; rest: string[]; command: string[] } {
+	const trimmed = (input ?? "").trim();
+	const separator = trimmed.indexOf(" -- ");
+	const head = separator >= 0 ? trimmed.slice(0, separator) : trimmed;
+	const command =
+		separator >= 0
+			? trimmed
+					.slice(separator + 4)
+					.split(/\s+/)
+					.filter(Boolean)
+			: [];
+	const tokens = head.split(/\s+/).filter(Boolean);
+	const action = (tokens.shift() ?? "status").toLowerCase();
+	return { action, rest: tokens, command };
+}
+
+/** `/podman run` solo acepta una política de red explícita; no es un passthrough de flags. */
+export function parseRunOptions(tokens: string[]): { image?: string; network?: "none" | "default"; error?: string } {
+	let network: "none" | "default" | undefined;
+	const positional: string[] = [];
+	for (let index = 0; index < tokens.length; index += 1) {
+		const token = tokens[index];
+		if (token === "--network") {
+			const value = tokens[index + 1];
+			if (value !== "none" && value !== "default") return { error: "--network solo acepta none o default." };
+			network = value;
+			index += 1;
+			continue;
+		}
+		if (token.startsWith("-")) return { error: `run no admite la flag ${token}.` };
+		positional.push(token);
+	}
+	if (positional.length !== 1) return { error: "run requiere exactamente una image antes de --." };
+	return { image: positional[0], network };
+}

package/handler-opts.ts

@@ -0,0 +1,13 @@
+/**
+ * Opciones compartidas por comando y tool: cwd, signal y timeout de Podman.
+ */
+
+import { DEFAULT_PODMAN_TIMEOUT_MS, parseTimeoutMs } from "./podman.js";
+
+export function buildHandlerOpts(cwd: string, signal: AbortSignal | null | undefined) {
+	return {
+		cwd,
+		signal: signal ?? undefined,
+		timeoutMs: parseTimeoutMs(process.env.PI_PODMAN_TIMEOUT_MS, DEFAULT_PODMAN_TIMEOUT_MS),
+	};
+}

package/index.ts

@@ -0,0 +1,14 @@
+/**
+ * pandi-podman: superficie reducida de Podman para Pi.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerPodmanCommand } from "./command-handler.js";
+import { registerPodmanSandboxTool } from "./tool-handler.js";
+
+export * from "./public-api.js";
+
+export default function podmanExtension(pi: ExtensionAPI): void {
+	registerPodmanCommand(pi);
+	registerPodmanSandboxTool(pi);
+}

package/notify.ts

@@ -0,0 +1,53 @@
+/**
+ * Helper de notificación al usuario, local a esta extensión para que siga
+ * siendo autocontenida.
+ *
+ * DUPLICACIÓN INTENCIONAL: vive una copia byte-idéntica en cada extensión que
+ * la necesita (pandi-plan, pandi-loop, pandi-goal, pandi-dynamic-workflows), en
+ * vez de un import cross-extension `../shared/`. Pi carga cada extensión de
+ * forma autocontenida (un solo archivo o un directorio con sus PROPIOS helpers,
+ * vía resolución de filesystem de jiti), así que un import `../shared/` solo
+ * resuelve mientras todo el paquete está co-instalado y se rompe bajo
+ * distribución por extensión. Mantené las copias sincronizadas a mano; la
+ * función es chica y estable.
+ *
+ * Desacoplado del SDK mediante un contexto STRUCTURAL mínimo (`NotifyContext`),
+ * así que no importa `ExtensionContext`; cualquier `ExtensionContext` real lo
+ * satisface.
+ *
+ * NOTE: esta familia autocontenida ahora también comparte el contrato
+ * endurecido de ruteo a stderr. pandi-docs lleva el mismo comportamiento con un
+ * import directo del contexto del SDK, y pandi-mdview todavía conserva un tipo de
+ * contexto solo de comando.
+ */
+
+export type NotifyType = "info" | "warning" | "error";
+
+export interface NotifyContext {
+	mode: string;
+	hasUI: boolean;
+	ui?: { notify(message: string, type?: NotifyType): void };
+}
+
+/**
+ * Muestra un mensaje al usuario.
+ *
+ * - modo print: escribe info en stdout, warnings/errors en stderr, y retorna.
+ * - interactivo con UI: delega en `ctx.ui.notify`.
+ * - headless sin UI: mantiene info en silencio, pero muestra warnings/errors en stderr.
+ *
+ * El guard de truthiness de `ctx.ui` preserva un no-op para test doubles
+ * estructurales que omiten `ui`, aunque la invariante real es que `hasUI`
+ * implica `ui`.
+ */
+export function notify(ctx: NotifyContext, message: string, type: NotifyType = "info"): void {
+	if (ctx.mode === "print") {
+		(type === "info" ? console.log : console.error)(message);
+		return;
+	}
+	if (ctx.hasUI && ctx.ui) {
+		ctx.ui.notify(message, type);
+		return;
+	}
+	if (type !== "info") console.error(message);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@pandi-coding-agent/pandi-podman",
+	"version": "0.1.0",
+	"description": "Extensión de Pi para ejecutar sandboxes efímeros y restringidos con Podman mediante /podman y la tool podman_sandbox.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/andrestobelem/pandi-extensions.git",
+		"directory": "extensions/pandi-podman"
+	},
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"podman",
+		"container",
+		"sandbox"
+	],
+	"files": [
+		"index.ts",
+		"public-api.ts",
+		"podman.ts",
+		"command-handler.ts",
+		"command.ts",
+		"command-menu.ts",
+		"handler-opts.ts",
+		"notify.ts",
+		"tool-handler.ts",
+		"tool-results.ts",
+		"README.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "^0.80.3",
+		"@earendil-works/pi-coding-agent": "^0.80.3",
+		"typebox": "^1.1.38"
+	}
+}

package/podman.ts

@@ -0,0 +1,617 @@
+/**
+ * Núcleo standalone de pandi-podman: spawn argv, parseo JSON y handlers puros.
+ *
+ * Podman nunca recibe una cadena de shell. Los handlers solo construyen el
+ * subconjunto reducido de argv que publica la extensión, para que la tool no
+ * se convierta en un passthrough de mounts, puertos o privilegios del host.
+ */
+
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+
+export interface PodmanResult {
+	ok: boolean;
+	stdout: string;
+	stderr: string;
+	exitCode?: number;
+	/** true únicamente cuando venció timeoutMs. */
+	timedOut?: boolean;
+	/** true únicamente cuando la AbortSignal externa pidió terminar el proceso. */
+	aborted?: boolean;
+	/** Señal que cerró al hijo, incluida SIGKILL después de agotar la gracia. */
+	signal?: NodeJS.Signals;
+	stdoutTruncated?: boolean;
+	stderrTruncated?: boolean;
+	spawnError?: string;
+}
+
+export interface RunPodmanOptions {
+	cwd?: string;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	bin?: string;
+}
+
+export const DEFAULT_PODMAN_TIMEOUT_MS = 120_000;
+export const MIN_PODMAN_TIMEOUT_MS = 1_000;
+const MAX_PODMAN_OUTPUT_BYTES = 1_000_000;
+const PODMAN_TERMINATION_GRACE_MS = 250;
+const DEFAULT_CPUS = 2;
+const DEFAULT_MEMORY = "1G";
+const DEFAULT_PIDS_LIMIT = 256;
+
+export function parseTimeoutMs(raw: string | undefined, fallback = DEFAULT_PODMAN_TIMEOUT_MS): number {
+	const value = Number(raw);
+	if (!Number.isFinite(value) || value <= 0) return fallback;
+	return Math.max(MIN_PODMAN_TIMEOUT_MS, Math.floor(value));
+}
+
+export type RunPodman = (args: string[], options?: RunPodmanOptions) => Promise<PodmanResult>;
+
+function createBoundedOutput(): {
+	append(chunk: Buffer | string): void;
+	readonly text: string;
+	readonly truncated: boolean;
+} {
+	const decoder = new StringDecoder("utf8");
+	const chunks: string[] = [];
+	let bytes = 0;
+	let truncated = false;
+	let finalized: string | undefined;
+	return {
+		append(chunk): void {
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			const remaining = MAX_PODMAN_OUTPUT_BYTES - bytes;
+			if (buffer.length > remaining) truncated = true;
+			if (remaining <= 0) return;
+			const kept = buffer.length <= remaining ? buffer : buffer.subarray(0, remaining);
+			const decoded = decoder.write(kept);
+			if (decoded) chunks.push(decoded);
+			bytes += kept.length;
+		},
+		get text(): string {
+			if (finalized === undefined) {
+				if (!truncated) {
+					const tail = decoder.end();
+					if (tail) chunks.push(tail);
+				}
+				finalized = chunks.join("");
+			}
+			return finalized;
+		},
+		get truncated(): boolean {
+			return truncated;
+		},
+	};
+}
+
+/** Ejecuta la CLI sin shell; errores del proceso vuelven como datos para la UI/tool. */
+export function runPodman(args: string[], options: RunPodmanOptions = {}): Promise<PodmanResult> {
+	const { cwd, signal, timeoutMs = DEFAULT_PODMAN_TIMEOUT_MS, bin = "podman" } = options;
+	return new Promise((resolve) => {
+		const stdout = createBoundedOutput();
+		const stderr = createBoundedOutput();
+		let settled = false;
+		let termination: "timeout" | "abort" | undefined;
+		let spawnError: string | undefined;
+		let timeoutTimer: NodeJS.Timeout | undefined;
+		let killTimer: NodeJS.Timeout | undefined;
+		const useProcessGroup = process.platform !== "win32";
+		const child = spawn(bin, args, { cwd, detached: useProcessGroup, windowsHide: true });
+
+		const sendSignal = (processSignal: NodeJS.Signals): void => {
+			if (useProcessGroup && child.pid && child.pid !== process.pid) {
+				try {
+					process.kill(-child.pid, processSignal);
+					return;
+				} catch {
+					// El fallback conserva el comportamiento en hosts sin group kill.
+				}
+			}
+			try {
+				child.kill(processSignal);
+			} catch {
+				// El proceso ya cerró.
+			}
+		};
+
+		const finish = (code: number | null, childSignal: NodeJS.Signals | null): void => {
+			if (settled) return;
+			settled = true;
+			if (timeoutTimer) clearTimeout(timeoutTimer);
+			if (killTimer) clearTimeout(killTimer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve({
+				ok: !spawnError && !termination && code === 0,
+				stdout: stdout.text,
+				stderr: stderr.text,
+				exitCode: spawnError ? undefined : (code ?? undefined),
+				timedOut: termination === "timeout",
+				aborted: termination === "abort",
+				signal: childSignal ?? undefined,
+				stdoutTruncated: stdout.truncated,
+				stderrTruncated: stderr.truncated,
+				spawnError,
+			});
+		};
+
+		const terminate = (reason: "timeout" | "abort"): void => {
+			if (settled || termination) return;
+			termination = reason;
+			sendSignal("SIGTERM");
+			killTimer = setTimeout(() => {
+				if (!settled) sendSignal("SIGKILL");
+			}, PODMAN_TERMINATION_GRACE_MS);
+			killTimer.unref?.();
+		};
+
+		const onAbort = (): void => terminate("abort");
+
+		child.stdout?.on("data", (chunk: Buffer) => stdout.append(chunk));
+		child.stderr?.on("data", (chunk: Buffer) => stderr.append(chunk));
+		child.once("error", (error: Error) => {
+			spawnError = error.message;
+		});
+		child.once("close", finish);
+
+		timeoutTimer = setTimeout(() => terminate("timeout"), timeoutMs);
+		timeoutTimer.unref?.();
+		if (signal) {
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+}
+
+const CONTAINER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+
+export function validateContainerName(name: string): boolean {
+	return typeof name === "string" && CONTAINER_NAME_RE.test(name);
+}
+
+/** Acepta referencias OCI generales, pero nunca valores que Podman pueda interpretar como flags. */
+export function validateImageReference(image: string): boolean {
+	return typeof image === "string" && image.length > 0 && image.length <= 512 && /^[^\s-][^\s]*$/.test(image);
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function text(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function number(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) return Number(value);
+	return undefined;
+}
+
+export interface ContainerEntry {
+	id: string;
+	name?: string;
+	image?: string;
+	state?: string;
+	status?: string;
+	createdAt?: string;
+}
+
+export function parseContainerList(jsonText: string): ContainerEntry[] {
+	try {
+		const parsed: unknown = JSON.parse(jsonText);
+		if (!Array.isArray(parsed)) return [];
+		return parsed
+			.map((value) => record(value))
+			.filter((value): value is Record<string, unknown> => Boolean(value))
+			.map((row) => {
+				const names = Array.isArray(row.Names) ? row.Names : [];
+				return {
+					id: text(row.Id) ?? text(row.ID) ?? text(row.id) ?? "",
+					name: text(names[0]) ?? text(row.Name) ?? text(row.Names),
+					image: text(row.Image) ?? text(row.image),
+					state: text(row.State) ?? text(row.state),
+					status: text(row.Status) ?? text(row.status),
+					createdAt: text(row.CreatedAt) ?? text(row.createdAt),
+				};
+			})
+			.filter((entry) => entry.id.length > 0);
+	} catch {
+		return [];
+	}
+}
+
+export function formatContainerList(entries: ContainerEntry[]): string {
+	if (entries.length === 0) return "No hay contenedores de Podman.";
+	return entries
+		.map((entry) => `  ${entry.name ?? entry.id.slice(0, 12)}  (${entry.state ?? "?"}, ${entry.image ?? "imagen ?"})`)
+		.join("\n");
+}
+
+export interface MachineEntry {
+	name: string;
+	isDefault?: boolean;
+	running?: boolean;
+	cpus?: number;
+	memory?: number;
+	diskSize?: number;
+	vmType?: string;
+}
+
+export function parseMachineList(jsonText: string): MachineEntry[] {
+	try {
+		const parsed: unknown = JSON.parse(jsonText);
+		if (!Array.isArray(parsed)) return [];
+		return parsed
+			.map((value) => record(value))
+			.filter((value): value is Record<string, unknown> => Boolean(value))
+			.map((row) => ({
+				name: text(row.Name) ?? text(row.name) ?? "",
+				isDefault: row.Default === true || row.default === true,
+				running: row.Running === true || row.running === true,
+				cpus: number(row.CPUs) ?? number(row.cpus),
+				memory: number(row.Memory) ?? number(row.memory),
+				diskSize: number(row.DiskSize) ?? number(row.diskSize),
+				vmType: text(row.VMType) ?? text(row.vmType),
+			}))
+			.filter((entry) => entry.name.length > 0);
+	} catch {
+		return [];
+	}
+}
+
+function humanBytes(bytes: number | undefined): string {
+	if (bytes == null || bytes < 0) return "?";
+	const units = ["B", "K", "M", "G", "T"];
+	let value = bytes;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit += 1;
+	}
+	const rounded = value >= 100 || Number.isInteger(value) ? Math.round(value) : Math.round(value * 10) / 10;
+	return `${rounded}${units[unit]}`;
+}
+
+export function formatMachineList(entries: MachineEntry[]): string {
+	if (entries.length === 0) return "No hay máquinas de Podman.";
+	return entries
+		.map((entry) => {
+			const defaultMark = entry.isDefault ? "* " : "  ";
+			const bits = [
+				entry.running ? "running" : "stopped",
+				entry.vmType,
+				entry.cpus && `${entry.cpus}cpu`,
+				entry.memory && `mem=${humanBytes(entry.memory)}`,
+			]
+				.filter(Boolean)
+				.join(", ");
+			return `${defaultMark}${entry.name}  (${bits})`;
+		})
+		.join("\n");
+}
+
+export interface PodmanInfo {
+	version?: string;
+	rootless?: boolean;
+	containers?: number;
+	images?: number;
+}
+
+export function parseInfo(jsonText: string): PodmanInfo {
+	try {
+		const parsed = record(JSON.parse(jsonText));
+		const host = record(parsed?.host);
+		const security = record(host?.security);
+		const store = record(parsed?.store);
+		const containers = record(store?.containerStore);
+		const images = record(store?.imageStore);
+		const version = record(parsed?.version);
+		return {
+			version: text(version?.Version) ?? text(version?.version),
+			rootless: security?.rootless === true,
+			containers: number(containers?.number),
+			images: number(images?.number),
+		};
+	} catch {
+		return {};
+	}
+}
+
+// Constructores de argv: toda la política de superficie permitida queda visible y testeable acá.
+export function buildInfoArgs(): string[] {
+	return ["info", "--format", "json"];
+}
+
+export function buildListArgs(): string[] {
+	return ["ps", "--all", "--format", "json"];
+}
+
+export function buildMachineListArgs(): string[] {
+	return ["machine", "list", "--format", "json"];
+}
+
+export function buildMachineStartArgs(name?: string): string[] {
+	return name ? ["machine", "start", name] : ["machine", "start"];
+}
+
+export function buildStopArgs(name: string): string[] {
+	return ["stop", name];
+}
+
+export function buildRemoveArgs(name: string): string[] {
+	return ["rm", "--force", name];
+}
+
+export interface SandboxParams {
+	image: string;
+	command: string[];
+	network?: "none" | "default";
+	workdir?: string;
+	cpus?: number;
+	memory?: string;
+}
+
+export function buildRunArgs(params: SandboxParams): string[] {
+	return [
+		"run",
+		"--rm",
+		"--network",
+		params.network ?? "none",
+		// Podman propaga proxy del host por defecto; desactivarlo preserva el contrato sin env del host.
+		"--http-proxy=false",
+		"--cap-drop",
+		"ALL",
+		"--security-opt",
+		"no-new-privileges",
+		"--pids-limit",
+		String(DEFAULT_PIDS_LIMIT),
+		"--read-only",
+		"--tmpfs",
+		"/tmp:rw,nosuid,nodev,noexec",
+		"--cpus",
+		String(params.cpus ?? DEFAULT_CPUS),
+		"--memory",
+		params.memory ?? DEFAULT_MEMORY,
+		...(params.workdir ? ["--workdir", params.workdir] : []),
+		params.image,
+		...params.command,
+	];
+}
+
+const INSTALL_HINT =
+	process.platform === "darwin"
+		? "No se encontró Podman. Instalalo con: brew install podman"
+		: "No se encontró Podman. Instalalo con el gestor de paquetes de tu sistema.";
+
+function outputTruncationDetails(result: PodmanResult): Record<string, true> {
+	return {
+		...(result.stdoutTruncated ? { stdoutTruncated: true } : {}),
+		...(result.stderrTruncated ? { stderrTruncated: true } : {}),
+	};
+}
+
+function describeOutputTruncation(result: PodmanResult): string | undefined {
+	const streams = [
+		result.stdoutTruncated ? "stdout" : undefined,
+		result.stderrTruncated ? "stderr" : undefined,
+	].filter((stream): stream is string => Boolean(stream));
+	return streams.length
+		? `La salida de ${streams.join(" y ")} fue truncada al límite de ${MAX_PODMAN_OUTPUT_BYTES} bytes.`
+		: undefined;
+}
+
+export function describePodmanError(result: PodmanResult, action: string): string {
+	const truncation = describeOutputTruncation(result);
+	const withTruncation = (message: string): string => (truncation ? `${message} ${truncation}` : message);
+	if (result.spawnError)
+		return /ENOENT/i.test(result.spawnError)
+			? withTruncation(INSTALL_HINT)
+			: withTruncation(`No se pudo ejecutar \`podman ${action}\`: ${result.spawnError}`);
+	if (result.timedOut) return withTruncation(`\`podman ${action}\` agotó el tiempo de espera.`);
+	if (result.aborted) return withTruncation(`\`podman ${action}\` fue abortado.`);
+	if (result.signal) return withTruncation(`\`podman ${action}\` terminó por señal ${result.signal}.`);
+	const detail = (result.stderr || result.stdout).trim();
+	return withTruncation(
+		detail
+			? `\`podman ${action}\` falló: ${detail}`
+			: `\`podman ${action}\` falló (salida ${result.exitCode ?? "?"}).`,
+	);
+}
+
+export interface HandlerResult {
+	ok: boolean;
+	text: string;
+	details: Record<string, unknown>;
+}
+
+export interface HandlerOpts {
+	cwd?: string;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	platform?: NodeJS.Platform;
+}
+
+function handlerError(action: string, text: string, details: Record<string, unknown> = {}): HandlerResult {
+	return { ok: false, text, details: { isError: true, action, ...details } };
+}
+
+function isMachinePlatform(platform: NodeJS.Platform = process.platform): boolean {
+	return platform === "darwin" || platform === "win32";
+}
+
+function validWorkdir(workdir: string | undefined): boolean {
+	return workdir == null || (workdir.startsWith("/") && !workdir.includes("\0"));
+}
+
+function memoryBytes(memory: string): number | undefined {
+	const match = /^(\d+(?:\.\d+)?)([KMG])$/i.exec(memory);
+	if (!match) return undefined;
+	const units = { K: 1024, M: 1024 ** 2, G: 1024 ** 3 } as const;
+	return Number(match[1]) * units[match[2].toUpperCase() as keyof typeof units];
+}
+
+function validateSandbox(params: SandboxParams): string | undefined {
+	if (!validateImageReference(params.image))
+		return "run requiere una referencia de image válida, sin espacios ni flags.";
+	if (
+		!Array.isArray(params.command) ||
+		params.command.length === 0 ||
+		params.command.some((arg) => typeof arg !== "string")
+	)
+		return "run requiere un array command no vacío (argv).";
+	if (params.network != null && params.network !== "none" && params.network !== "default")
+		return "network solo puede ser 'none' (predeterminado) o 'default' (opt-in).";
+	if (!validWorkdir(params.workdir)) return "workdir debe ser una ruta absoluta dentro del contenedor.";
+	if (params.cpus != null && (!Number.isFinite(params.cpus) || params.cpus <= 0 || params.cpus > DEFAULT_CPUS))
+		return `cpus debe estar entre 0 y ${DEFAULT_CPUS}; solo se permiten límites iguales o más estrictos.`;
+	if (params.memory != null) {
+		const bytes = memoryBytes(params.memory);
+		if (bytes == null || bytes < 16 * 1024 ** 2 || bytes > 1024 ** 3)
+			return "memory debe estar entre 16M y 1G; solo se permiten límites iguales o más estrictos.";
+	}
+	return undefined;
+}
+
+export async function runStatus(run: RunPodman, opts: HandlerOpts): Promise<HandlerResult> {
+	const infoResult = await run(buildInfoArgs(), opts);
+	const infoTruncation = describeOutputTruncation(infoResult);
+	if (!infoResult.ok) {
+		if (infoTruncation)
+			return handlerError("status", describePodmanError(infoResult, "info"), outputTruncationDetails(infoResult));
+		if (!isMachinePlatform(opts.platform))
+			return handlerError("status", describePodmanError(infoResult, "info"), outputTruncationDetails(infoResult));
+		const machinesResult = await run(buildMachineListArgs(), opts);
+		const machinesTruncation = describeOutputTruncation(machinesResult);
+		if (machinesTruncation)
+			return handlerError(
+				"status",
+				machinesResult.ok ? machinesTruncation : describePodmanError(machinesResult, "machine list"),
+				outputTruncationDetails(machinesResult),
+			);
+		if (!machinesResult.ok)
+			return handlerError("status", describePodmanError(infoResult, "info"), outputTruncationDetails(infoResult));
+		const machines = parseMachineList(machinesResult.stdout);
+		return handlerError(
+			"status",
+			`Podman no está disponible. Revisá las máquinas:\n${formatMachineList(machines)}\n\nIniciá una con: /podman machine-start [name]`,
+			{ machines },
+		);
+	}
+	if (infoTruncation) return handlerError("status", infoTruncation, outputTruncationDetails(infoResult));
+	const info = parseInfo(infoResult.stdout);
+	let machines: MachineEntry[] | undefined;
+	if (isMachinePlatform(opts.platform)) {
+		const machinesResult = await run(buildMachineListArgs(), opts);
+		const machinesTruncation = describeOutputTruncation(machinesResult);
+		if (machinesTruncation)
+			return handlerError(
+				"status",
+				machinesResult.ok ? machinesTruncation : describePodmanError(machinesResult, "machine list"),
+				outputTruncationDetails(machinesResult),
+			);
+		if (machinesResult.ok) machines = parseMachineList(machinesResult.stdout);
+	}
+	const summary = [
+		`Podman ${info.version ?? "(versión desconocida)"}${info.rootless === true ? " · rootless" : ""}`,
+		info.containers != null ? `Contenedores: ${info.containers}` : null,
+		info.images != null ? `Imágenes: ${info.images}` : null,
+		machines ? `\nMáquinas:\n${formatMachineList(machines)}` : null,
+	]
+		.filter(Boolean)
+		.join("\n");
+	return { ok: true, text: summary, details: { action: "status", info, ...(machines ? { machines } : {}) } };
+}
+
+export async function runList(run: RunPodman, opts: HandlerOpts): Promise<HandlerResult> {
+	const result = await run(buildListArgs(), opts);
+	if (!result.ok) return handlerError("list", describePodmanError(result, "ps"), outputTruncationDetails(result));
+	const truncation = describeOutputTruncation(result);
+	if (truncation) return handlerError("list", truncation, outputTruncationDetails(result));
+	const containers = parseContainerList(result.stdout);
+	return {
+		ok: true,
+		text: formatContainerList(containers),
+		details: { action: "list", count: containers.length, containers },
+	};
+}
+
+export async function runSandbox(run: RunPodman, params: SandboxParams, opts: HandlerOpts): Promise<HandlerResult> {
+	const error = validateSandbox(params);
+	if (error) return handlerError("run", error);
+	const result = await run(buildRunArgs(params), opts);
+	if (!result.ok) return handlerError("run", describePodmanError(result, "run"), outputTruncationDetails(result));
+	const output = result.stdout.trim() || "(sin salida) — sandbox efímero finalizado.";
+	const truncation = describeOutputTruncation(result);
+	return {
+		ok: true,
+		text: truncation ? `${output}\n\nAdvertencia: ${truncation}` : output,
+		details: {
+			action: "run",
+			image: params.image,
+			exitCode: result.exitCode,
+			...outputTruncationDetails(result),
+		},
+	};
+}
+
+export async function runStop(run: RunPodman, params: { name?: string }, opts: HandlerOpts): Promise<HandlerResult> {
+	if (!params.name || !validateContainerName(params.name))
+		return handlerError("stop", "stop requiere un nombre de contenedor válido.");
+	const result = await run(buildStopArgs(params.name), opts);
+	if (!result.ok) return handlerError("stop", describePodmanError(result, "stop"));
+	return { ok: true, text: `Se detuvo el contenedor ${params.name}.`, details: { action: "stop", name: params.name } };
+}
+
+export async function runRemove(
+	run: RunPodman,
+	params: { name?: string; force?: boolean },
+	opts: HandlerOpts,
+): Promise<HandlerResult> {
+	if (!params.name || !validateContainerName(params.name))
+		return handlerError("remove", "remove requiere un nombre de contenedor válido.");
+	if (!params.force)
+		return handlerError("remove", `Me niego a eliminar el contenedor "${params.name}" sin force.`, {
+			needsForce: true,
+			name: params.name,
+		});
+	const result = await run(buildRemoveArgs(params.name), opts);
+	if (!result.ok) return handlerError("remove", describePodmanError(result, "rm"));
+	return {
+		ok: true,
+		text: `Se eliminó el contenedor ${params.name}.`,
+		details: { action: "remove", name: params.name },
+	};
+}
+
+export async function runMachineList(run: RunPodman, opts: HandlerOpts): Promise<HandlerResult> {
+	const result = await run(buildMachineListArgs(), opts);
+	if (!result.ok)
+		return handlerError("machine-list", describePodmanError(result, "machine list"), outputTruncationDetails(result));
+	const truncation = describeOutputTruncation(result);
+	if (truncation) return handlerError("machine-list", truncation, outputTruncationDetails(result));
+	const machines = parseMachineList(result.stdout);
+	return {
+		ok: true,
+		text: formatMachineList(machines),
+		details: { action: "machine-list", count: machines.length, machines },
+	};
+}
+
+export async function runMachineStart(
+	run: RunPodman,
+	params: { name?: string },
+	opts: HandlerOpts,
+): Promise<HandlerResult> {
+	if (params.name && !validateContainerName(params.name))
+		return handlerError("machine-start", "Nombre de máquina inválido.");
+	const result = await run(buildMachineStartArgs(params.name), opts);
+	if (!result.ok) return handlerError("machine-start", describePodmanError(result, "machine start"));
+	return {
+		ok: true,
+		text: `Se inició la máquina de Podman ${params.name ?? "predeterminada"}.`,
+		details: { action: "machine-start", name: params.name },
+	};
+}

package/public-api.ts

@@ -0,0 +1,28 @@
+export { parsePodmanCommand, parseRunOptions } from "./command.js";
+export { completePodmanArgs, PODMAN_SELECT_ITEMS, resolvePodmanInput } from "./command-menu.js";
+export {
+	buildInfoArgs,
+	buildListArgs,
+	buildMachineListArgs,
+	buildMachineStartArgs,
+	buildRemoveArgs,
+	buildRunArgs,
+	buildStopArgs,
+	describePodmanError,
+	formatContainerList,
+	formatMachineList,
+	parseContainerList,
+	parseInfo,
+	parseMachineList,
+	parseTimeoutMs,
+	runList,
+	runMachineList,
+	runMachineStart,
+	runPodman,
+	runRemove,
+	runSandbox,
+	runStatus,
+	runStop,
+	validateContainerName,
+	validateImageReference,
+} from "./podman.js";

package/tool-handler.ts

@@ -0,0 +1,101 @@
+/**
+ * Tool `podman_sandbox` invocable por el modelo.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { PODMAN_ACTIONS } from "./command-menu.js";
+import { buildHandlerOpts } from "./handler-opts.js";
+import {
+	runList,
+	runMachineList,
+	runMachineStart,
+	runPodman,
+	runRemove,
+	runSandbox,
+	runStatus,
+	runStop,
+} from "./podman.js";
+import { toolError, toToolResult } from "./tool-results.js";
+
+const ACTIONS = PODMAN_ACTIONS.map(({ value }) => value);
+
+export function registerPodmanSandboxTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "podman_sandbox",
+		label: "Sandbox de Podman",
+		description:
+			"Ejecutá y administrá un subconjunto restringido de Podman. run crea solo un contenedor efímero, sin mounts, puertos, variables de entorno, privilegios ni flags libres; usa red none, rootfs read-only, capabilities eliminadas y límites de recursos por defecto. Podman siempre se invoca con argv, nunca mediante shell.",
+		promptSnippet: "Usá podman_sandbox para un contenedor efímero y restringido cuando el usuario pida Podman.",
+		promptGuidelines: [
+			"run requiere image y command como array argv; nunca pases un string de shell.",
+			"La red está deshabilitada por defecto. Usá network:'default' solo cuando el usuario o la tarea requiera explícitamente acceso de red.",
+			"No hay mounts, puertos, secrets/env, devices ni privilegios en esta surface. No intentes suplirlos con argumentos de texto.",
+			"remove nunca borra por defecto: pasá force:true solo después de que el usuario acepte eliminar ese contenedor.",
+			"Podman no debe tratarse como una frontera infalible contra código hostil, sobre todo en Linux. Para una micro-VM Apple preferí container_sandbox cuando aplique.",
+		],
+		parameters: Type.Object({
+			action: StringEnum(ACTIONS),
+			name: Type.Optional(
+				Type.String({ description: "Nombre de contenedor para stop/remove o de máquina para machine-start." }),
+			),
+			image: Type.Optional(
+				Type.String({ description: "Referencia OCI para run, por ejemplo quay.io/podman/hello:latest." }),
+			),
+			command: Type.Optional(
+				Type.Array(Type.String(), { description: 'Para run: comando como argv, por ejemplo ["uname", "-a"].' }),
+			),
+			network: Type.Optional(
+				StringEnum(["none", "default"] as const, { description: "none por defecto; default solo como opt-in." }),
+			),
+			workdir: Type.Optional(Type.String({ description: "Ruta absoluta dentro del contenedor para run." })),
+			cpus: Type.Optional(
+				Type.Number({
+					minimum: 0.1,
+					maximum: 2,
+					description: "Límite de CPU; solo puede endurecer el default de 2.",
+				}),
+			),
+			memory: Type.Optional(
+				Type.String({ description: "Límite entre 16M y 1G; solo puede endurecer el default de 1G." }),
+			),
+			force: Type.Optional(Type.Boolean({ description: "Para remove: confirma eliminar el contenedor." })),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const opts = buildHandlerOpts(ctx.cwd, signal);
+			switch (params.action) {
+				case "status":
+					return toToolResult(await runStatus(runPodman, opts));
+				case "list":
+					return toToolResult(await runList(runPodman, opts));
+				case "run":
+					return toToolResult(
+						await runSandbox(
+							runPodman,
+							{
+								image: params.image ?? "",
+								command: params.command ?? [],
+								network: params.network,
+								workdir: params.workdir,
+								cpus: params.cpus,
+								memory: params.memory,
+							},
+							opts,
+						),
+					);
+				case "stop":
+					return toToolResult(await runStop(runPodman, { name: params.name }, opts));
+				case "remove":
+					return toToolResult(await runRemove(runPodman, { name: params.name, force: params.force }, opts));
+				case "machine-list":
+					return toToolResult(await runMachineList(runPodman, opts));
+				case "machine-start":
+					return toToolResult(await runMachineStart(runPodman, { name: params.name }, opts));
+				default:
+					return toolError(`Acción desconocida: ${params.action}`);
+			}
+		},
+	});
+}

package/tool-results.ts

@@ -0,0 +1,17 @@
+/**
+ * Adaptadores de resultado para `podman_sandbox`.
+ */
+
+import type { HandlerResult } from "./podman.js";
+
+export function toolResult(text: string, details: Record<string, unknown> = {}) {
+	return { content: [{ type: "text" as const, text }], details };
+}
+
+export function toolError(text: string, details: Record<string, unknown> = {}) {
+	return toolResult(text, { isError: true, ...details });
+}
+
+export function toToolResult(result: HandlerResult) {
+	return toolResult(result.text, result.details);
+}