Add initial version of task mode

Author: nezhar

docs/agents/index.md

@@ -260,6 +260,68 @@ The argument is resolved as an agent name/shortcut first; anything else is looke
 - **`auto_remove` (default: `true`)** — By default, containers are automatically removed when they stop. This means you cannot restart a stopped detached container; you need to `vp run` again. Set `auto_remove: false` in your [configuration](../configuration.md) if you want stopped containers to persist.
 - **Session logging** — Sessions started with `--detach` are not recorded in the VibePod session log since VibePod does not capture the interactive I/O. If you need session logging, run without `--detach`.
 
+## Task mode (headless)
+
+Run an agent non-interactively as a background task. Claude calls this "headless mode"; codex and auggie expose equivalent flags. VibePod wraps them in a uniform `vp task` command.
+
+```bash
+vp task run claude "Summarize the README"
+# ✓ Task started: 9f1e8a20b4c14e2f89d7f6a1c3e42b99
+#   container: vibepod-claude-abcdef12
+#   follow:    vp task logs 9f1e8a20b4c1 --follow
+```
+
+The command starts a detached container, writes a row to `~/.config/vibepod/tasks.db`, and returns a task id. The container is **not** auto-removed, so you can inspect logs and exit status after it finishes.
+
+### Supported agents (v1)
+
+| Agent | Invocation inside container |
+|-------|------------------------------|
+| `claude` | `claude -p "<prompt>"` |
+| `codex` | `codex exec "<prompt>"` |
+| `auggie` | `auggie --print "<prompt>"` |
+
+Other agents error with a clear message; support can be added by setting `headless_prefix` on their `AgentSpec`.
+
+### Managing tasks
+
+```bash
+vp task list                     # recent tasks + container status
+vp task list --agent claude      # filter
+vp task list --json              # machine-readable
+
+vp task logs <id>                # dump captured stdout/stderr
+vp task logs <id> --follow       # stream
+
+vp task status <id>              # state, exit code, timestamps
+vp task rm <id>                  # remove task + its (stopped) container
+vp task rm <id> -f               # kill running container before removing
+```
+
+Task ids can be abbreviated to any unique prefix (e.g., the first 12 chars shown by `vp task list`).
+
+### Passing agent flags
+
+Anything after `--` is forwarded to the agent's command after the prompt, matching the CLI's documented form (`claude -p "..." --allowedTools ...`):
+
+```bash
+vp task run claude "review staged changes" -- --output-format json
+```
+
+### Auto-approval for automation
+
+Headless tasks typically need to run without permission prompts. Pass `--ikwid` to apply the agent's documented auto-approve flag (e.g., `--dangerously-skip-permissions` for Claude):
+
+```bash
+vp task run claude "fix the failing test in auth.py" --ikwid
+```
+
+### Caveats
+
+- **No `--resume` in v1.** Task mode starts a fresh session every time. Use the agent's own resume flag via passthrough (`-- --resume <session_id>` for Claude) if you need continuity.
+- **LLM config model flag is skipped in task mode.** `llm.base_url` / `llm.api_key` / `llm.model` are still injected as env vars, but the `--model`-style CLI flag is not appended — different agents place it differently relative to subcommands. Pass an explicit model via `--`.
+- **Task containers are not auto-removed.** Run `vp task rm <id>` when you're done inspecting results.
+
 ## Reattaching a terminal
 
 Closing the terminal window that runs `vp run` does **not** stop the container — the agent keeps running in the background under Docker. This is by design: the container's lifecycle is tied to Docker, not to your shell. Use it as a feature when you want to keep a long-running session alive across terminal restarts.

src/vibepod/cli.py

@@ -7,7 +7,7 @@
 
 import typer
 
-from vibepod.commands import attach, config, doctor, list_cmd, logs, proxy, run, stop, update
+from vibepod.commands import attach, config, doctor, list_cmd, logs, proxy, run, stop, task, update
 from vibepod.constants import AGENT_SHORTCUTS, SUPPORTED_AGENTS
 
 app = typer.Typer(
@@ -30,6 +30,7 @@
 app.add_typer(config.app, name="config")
 app.add_typer(proxy.app, name="proxy")
 app.add_typer(doctor.app, name="doctor")
+app.add_typer(task.app, name="task")
 
 
 def _register_run_alias(command_name: str, agent_name: str) -> None:

src/vibepod/commands/run.py

@@ -2,11 +2,9 @@
 
 from __future__ import annotations
 
-import json
 import os
 import sys
 import time
-from datetime import datetime, timezone
 from pathlib import Path
 from typing import Annotated, Any
 
@@ -26,186 +24,23 @@
 from vibepod.core.allowed_dirs import add_allowed_dir, is_dir_allowed, is_protected_dir
 from vibepod.core.config import get_config
 from vibepod.core.docker import DockerClientError, DockerManager, _is_latest_tag
+from vibepod.core.launch import (
+    CLAUDE_TOKEN_FILENAME,
+    agent_extra_volumes as _agent_extra_volumes,
+    agent_init_commands as _agent_init_commands,
+    get_container_ip as _get_container_ip,
+    host_user as _host_user,
+    init_entrypoint as _init_entrypoint,
+    parse_env_pairs as _parse_env_pairs,
+    read_claude_stored_token as _read_claude_stored_token,
+    terminal_env_defaults as _terminal_env_defaults,
+    update_container_mapping as _update_container_mapping,
+    write_claude_stored_token as _write_claude_stored_token,
+    x11_volumes_and_env as _x11_volumes_and_env,
+)
 from vibepod.core.session_logger import SessionLogger
 from vibepod.utils.console import error, info, success, warning
 
-CLAUDE_TOKEN_FILENAME = "oauth-token"
-
-
-def _claude_stored_token_path(config_dir: Path) -> Path:
-    return config_dir / CLAUDE_TOKEN_FILENAME
-
-
-def _read_claude_stored_token(config_dir: Path) -> str | None:
-    path = _claude_stored_token_path(config_dir)
-    try:
-        token = path.read_text(encoding="utf-8").strip()
-    except FileNotFoundError:
-        return None
-    except OSError as exc:
-        warning(f"Could not read stored claude token at {path}: {exc}")
-        return None
-    return token or None
-
-
-def _write_claude_stored_token(config_dir: Path, token: str) -> Path:
-    path = _claude_stored_token_path(config_dir)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-    try:
-        # fchmod overrides umask; os.open mode alone is umask-filtered
-        os.fchmod(fd, 0o600)
-    except OSError:
-        warning(f"Could not restrict permissions on {path}; token may be readable by other users")
-    with os.fdopen(fd, "w", encoding="utf-8") as f:
-        f.write(token.strip() + "\n")
-    return path
-
-
-def _parse_env_pairs(values: list[str]) -> dict[str, str]:
-    parsed: dict[str, str] = {}
-    for entry in values:
-        if "=" not in entry:
-            raise typer.BadParameter(f"Invalid --env value '{entry}', expected KEY=VALUE")
-        key, value = entry.split("=", 1)
-        if not key:
-            raise typer.BadParameter("Environment variable key cannot be empty")
-        parsed[key] = value
-    return parsed
-
-
-def _agent_init_commands(agent: str, agent_cfg: dict[str, Any]) -> list[str]:
-    """Read and validate per-agent init commands from config."""
-    raw_init = agent_cfg.get("init", [])
-    if raw_init is None:
-        return []
-
-    if isinstance(raw_init, str):
-        items = [raw_init]
-    elif isinstance(raw_init, list):
-        items = raw_init
-    else:
-        raise typer.BadParameter(
-            f"Invalid agents.{agent}.init value, expected a string or list of strings."
-        )
-
-    commands: list[str] = []
-    for index, item in enumerate(items, start=1):
-        if not isinstance(item, str):
-            raise typer.BadParameter(
-                f"Invalid agents.{agent}.init[{index}] value, expected a string."
-            )
-        command = item.strip()
-        if not command:
-            raise typer.BadParameter(
-                f"Invalid agents.{agent}.init[{index}] value, cannot be empty."
-            )
-        commands.append(command)
-    return commands
-
-
-def _init_entrypoint(init_commands: list[str]) -> list[str]:
-    """Build a shell entrypoint that runs init commands before the agent command."""
-    script = "\n".join(
-        [
-            "set -e",
-            *init_commands,
-            'exec "$@"',
-        ]
-    )
-    return ["/bin/sh", "-lc", script, "--"]
-
-
-def _get_container_ip(container: Any, network: str) -> str | None:
-    """Extract the container's IP address on the given Docker network."""
-    try:
-        network_settings = container.attrs.get("NetworkSettings")
-        if not isinstance(network_settings, dict):
-            return None
-        networks = network_settings.get("Networks")
-        if not isinstance(networks, dict):
-            return None
-        network_data = networks.get(network)
-        if not isinstance(network_data, dict):
-            return None
-        ip = network_data.get("IPAddress")
-        return ip if isinstance(ip, str) and ip else None
-    except AttributeError:
-        return None
-
-
-def _update_container_mapping(
-    mapping_path: Path,
-    ip: str,
-    container_id: str,
-    container_name: str,
-    agent: str,
-) -> bool:
-    """Merge a new IP→container entry into containers.json atomically."""
-    mapping: dict[str, dict[str, str]] = {}
-    try:
-        if mapping_path.exists():
-            try:
-                mapping = json.loads(mapping_path.read_text())
-            except (json.JSONDecodeError, OSError):
-                pass
-
-        mapping[ip] = {
-            "container_id": container_id,
-            "container_name": container_name,
-            "agent": agent,
-            "started_at": datetime.now(timezone.utc).isoformat(),
-        }
-
-        tmp_path = mapping_path.with_suffix(".tmp")
-        tmp_path.write_text(json.dumps(mapping, indent=2))
-        os.replace(tmp_path, mapping_path)
-    except OSError:
-        return False
-    return True
-
-
-def _agent_extra_volumes(agent: str, config_dir: Path) -> list[tuple[str, str, str]]:
-    """Return agent-specific bind mounts as (host_path, container_path, mode)."""
-    if agent == "auggie":
-        host = str(config_dir / ".augment")
-        return [
-            (host, "/root/.augment", "rw"),
-            (host, "/home/node/.augment", "rw"),
-        ]
-    if agent == "copilot":
-        host = str(config_dir / ".copilot")
-        return [
-            (host, "/root/.copilot", "rw"),
-            (host, "/home/node/.copilot", "rw"),
-            (host, "/home/coder/.copilot", "rw"),
-        ]
-    return []
-
-
-def _x11_volumes_and_env(display: str) -> tuple[list[tuple[str, str, str]], dict[str, str]]:
-    """Return X11 socket volumes and DISPLAY env for paste-image support."""
-    volumes: list[tuple[str, str, str]] = [("/tmp/.X11-unix", "/tmp/.X11-unix", "rw")]
-    env: dict[str, str] = {"DISPLAY": display}
-    return volumes, env
-
-
-def _host_user() -> str | None:
-    """Return current user id in uid:gid format when available."""
-    getuid = getattr(os, "getuid", None)
-    getgid = getattr(os, "getgid", None)
-    if not callable(getuid) or not callable(getgid):
-        return None
-    return f"{getuid()}:{getgid()}"
-
-
-def _terminal_env_defaults() -> dict[str, str]:
-    """Return host terminal-related env vars for interactive container apps."""
-    keys = ("TERM", "COLORTERM", "TERM_PROGRAM", "TERM_PROGRAM_VERSION", "LANG")
-    values = {key: value for key in keys if (value := os.environ.get(key))}
-    values.setdefault("TERM", "xterm-256color")
-    return values
-
 
 def _compose_file_present(workspace: Path) -> bool:
     return (workspace / "docker-compose.yml").exists() or (workspace / "compose.yml").exists()