agentworks-cli 0.2.1__py3-none-any.whl

agentworks/sample-config.toml

@@ -0,0 +1,289 @@
+# Agentworks configuration
+# Copy to ~/.config/agentworks/config.toml and edit to match your setup.
+#
+# Required fields are uncommented. Everything else shows the default value
+# commented out -- uncomment and change only what you need.
+#
+# Agentworks ships a built-in catalog of common tools (apt sources, apt
+# packages, system install commands, user install commands). Run
+# `agentworks installer list` to see what is available. You can reference
+# catalog entries by name in templates and define your own entries below
+# to extend or override the catalog.
+
+# =============================================================================
+# Operator identity and platform settings
+# =============================================================================
+
+# --- Operator identity ---
+# These settings identify you (the operator) to agentworks and your VMs.
+
+[operator]
+ssh_public_key = "~/.ssh/id_ed25519.pub"    # required: used to authorize access to VMs
+ssh_private_key = "~/.ssh/id_ed25519"        # required: used for SSH connections to VMs
+# ssh_config = "~/.ssh/config"               # SSH config file for VM host entries
+# ssh_config_dir = true                      # manage VM entries in ~/.ssh/config.d/
+# ssh_host_prefix = "awvm--"                 # prefix for SSH host aliases (e.g. awvm--myvm)
+# extra_ssh_public_keys = [                  # additional public keys for VM authorized_keys
+#     "~/.ssh/other_key.pub",
+# ]
+
+# --- Paths ---
+
+[paths]
+# local_workspaces = "~/workspaces"             # local workspace directory
+# vm_workspaces = "/opt/agentworks/workspaces"  # workspace directory on VMs
+# vscode_workspaces = "~/aw-vscode-workspaces"   # .code-workspace file directory
+# backups = "~/.config/agentworks/backups"       # vm backup directory
+
+# --- Default values for CLI flags ---
+
+[defaults]
+# platform = "lima"                          # lima, azure, or wsl2
+# vm_host = "mac-studio"                     # default VM host for remote Lima
+
+# --- Git credential providers ---
+# Define how to obtain git tokens. Referenced by name in admin.config and
+# agent_templates. Tokens are prompted during VM init (or read from env vars)
+# and stored via git credential-store on the VM.
+
+# [git_credentials.github]
+# type = "github"
+# description = "GitHub full access"               # optional, shown in prompts and logs
+# Token: create at https://github.com/settings/tokens (repo scope)
+
+# [git_credentials.azdo]
+# type = "azdo"
+# org = "my-org"
+# description = "Azure DevOps for my-org"          # optional, shown in prompts and logs
+# Token: create at https://dev.azure.com/{org}/_usersSettings/tokens
+
+# --- Azure settings (only needed for --platform azure) ---
+
+# [azure]
+# subscription_id = "..."                    # required for azure platform
+# resource_group = "agentworks-vms"          # required for azure platform
+# region = "eastus2"                         # required for azure platform
+
+# --- Proxmox settings (only needed for --platform proxmox) ---
+
+# [proxmox]
+# api_url = "https://pve.example.com:8006"   # required: Proxmox API URL
+# node = "pve"                                # required: Proxmox node name
+# token_id = "agentworks@pam!agentworks"      # required: API token ID
+# template_vmid = 9000                        # required: VMID of Debian 12 cloud-init template
+# storage = "local-lvm"                       # target storage for cloned disks
+# bridge = "vmbr0"                            # network bridge
+# pool = "agentworks"                         # Proxmox resource pool for VMs
+# verify_ssl = true                           # verify TLS certificate
+# Token secret: set PROXMOX_TOKEN_SECRET environment variable
+
+# =============================================================================
+# Templates
+# =============================================================================
+#
+# Agentworks uses templates for VMs, workspaces, agents, and tasks. Each
+# template type supports a "default" entry used when --template is not
+# specified. Templates support inheritance via the "inherits" key:
+# child values override parents, depth-first left-to-right.
+
+# --- VM templates ---
+# System-level VM configuration: hardware resources, system packages, and
+# system-wide tools. Selected at vm create time with --template.
+#
+# Agentworks always installs system packages (git, tmux, tmuxinator, acl, jq,
+# unzip) during init, in addition to provisioning packages (openssh-server,
+# curl, sudo, ca-certificates, gnupg) installed at VM create time.
+
+[vm_templates.default]
+# -- Provisioning (set once at create time) --
+# cpus = 4                                   # number of CPUs (Lima)
+# memory = 8                                 # memory in GiB (Lima)
+# azure_vm_size = "Standard_B2s"             # Azure VM size (determines cpu and memory for Azure)
+# disk = 50                                  # disk size in GiB
+# swap = 4                                   # swap file size in GiB (0 to disable)
+# -- System-wide initialization (applied on create and reinit) --
+# apt = [                                    # direct apt packages
+#     "zsh",
+#     "unzip",
+#     "build-essential",
+#     "ripgrep",
+#     "fzf",
+#     "fd-find",
+# ]
+# apt_packages = ["gh", "docker"]            # named apt package sets from catalog
+# snap = []                                  # direct snap packages
+# system_install_commands = ["az-cli"]       # system-level commands from catalog
+# -- Nerf tools --
+# nerf_build_claude_plugin = false             # build Claude Code nerf tools plugin
+# skip_nerf_defaults = false                   # skip built-in nerf catalog
+# nerf_addl_manifests = [                      # additional manifest files to merge in
+#     "~/.config/agentworks/nerf/my-tools/manifest.yaml",
+# ]
+# nerf_home_dir = "/opt/agentworks/nerf"       # root dir for nerf artifacts
+
+# [vm_templates.heavy]
+# inherits = ["default"]
+# cpus = 16
+# memory = 64
+# disk = 200
+
+# --- Admin user configuration ---
+# Per-user settings for the admin (operator) user on VMs. Applied during
+# init/reinit. This is not a template; there is one admin config.
+
+# [admin.config]
+# username = "agentworks"                    # admin username on VMs (default: agentworks)
+# shell = "zsh"                              # admin shell (default: zsh)
+# git_credentials = ["github"]              # git credential providers to configure
+# user_install_commands = ["bun"]             # per-user commands from catalog
+# -- Dotfiles (source refs: local path or git::, see docs/guides/source-refs.md) --
+# dotfiles_source = "git::https://github.com/user/dotfiles"
+# dotfiles_destination = "~/.dotfiles"       # where to put them on the VM
+# dotfiles_install_cmd = "./install.sh"      # command to run after clone/copy
+# -- Mise (see docs/guides/mise.md) --
+# mise_activate = true                       # add mise activate to shell profile
+# mise_packages = ["terraform@1.14.5", "adr-tools@3.0.0"]  # name@version tool declarations
+# mise_lockfile = "~/.config/agentworks/mise.lock"   # source ref (wins over dotfiles)
+# mise_allow_unlocked = false                # install packages not in lockfile (with warning)
+# mise_install_before = "7d"                 # reject versions newer than this
+# mise_prune_on_reinit = true                # remove stale tool versions on reinit
+# -- Git --
+# git_force_safe_directory = true              # set safe.directory '*' for admin and agents
+# -- Nerf tools --
+# nerf_install_claude_plugin = false           # install nerf plugin for this user
+# -- Claude Code (requires claude CLI on PATH, e.g. via user_install_commands) --
+# claude_marketplaces = ["https://github.com/WayfarerLabs/nerftools#1.2.0"]
+# claude_plugins = ["nerftools-default@nerftools"]
+
+# --- Agent templates ---
+# Per-user settings for agent users. Selected at agent create time with
+# --template. Agents default to nothing unless explicitly configured.
+
+# [agent_templates.default]
+# shell = "bash"                             # agent shell (default: bash)
+# git_credentials = []                       # git credential providers (default: none)
+# user_install_commands = []                 # per-user commands from catalog
+# -- Dotfiles --
+# dotfiles_source = "git::https://github.com/user/agent-dotfiles"
+# dotfiles_destination = "~/.dotfiles"
+# dotfiles_install_cmd = "./install.sh"
+# -- Mise --
+# mise_activate = true                       # add mise activate to agent shell profile
+# mise_packages = ["terraform@1.14.5"]              # name@version tool declarations
+# mise_lockfile = "~/.config/agentworks/agent-mise.lock"
+# mise_allow_unlocked = false
+# mise_install_before = "7d"
+# mise_prune_on_reinit = true
+# -- Nerf tools --
+# nerf_install_claude_plugin = false           # install nerf plugin for this agent
+# -- Claude Code (requires claude CLI on PATH, e.g. via user_install_commands) --
+# claude_marketplaces = ["https://github.com/WayfarerLabs/nerftools#1.2.0"]
+# claude_plugins = ["nerftools-default@nerftools"]
+
+# [agent_templates.restricted]
+# inherits = ["default"]
+# user_install_commands = []
+# mise_packages = []
+
+# --- Workspace templates ---
+# Selected at workspace create time with --template. The "default" template
+# is used when --template is not specified.
+#
+# Repo URLs: use HTTPS format. Git credentials configured in admin.config
+# provide authentication via personal access tokens. Public repos work
+# without credentials.
+
+# [workspace_templates.default]
+# repo = "https://github.com/org/repo.git"  # git repo to clone into workspace
+# tmuxinator = true                          # generate tmuxinator config
+# inherits = []                              # list of parent template names
+
+# [workspace_templates.myproject]
+# repo = "https://github.com/org/myproject.git"
+# tmuxinator = false
+# inherits = ["default"]
+
+# --- Session templates ---
+# Define commands that sessions can run. The built-in "default" template runs a
+# login shell. Templates support inheritance via "inherits".
+#
+# Template commands support {{session_name}} and {{workspace_name}} variables,
+# using double-brace syntax consistent with nerftools manifests.
+#
+# Templates may define a restart_command for `session restart`. If omitted,
+# the regular command is used. This is useful for tools like Claude Code
+# where --resume picks up the previous conversation.
+#
+# env maps are merged during inheritance (child wins on key collision).
+
+# [session_templates.default]               # override the built-in default
+# command = "claude --name {{session_name}}"
+# restart_command = "claude --resume {{session_name}}"
+# description = "Claude Code interactive session"
+
+# [session_templates.claude]
+# inherits = ["default"]
+# command = "claude --name {{session_name}}"
+# restart_command = "claude --resume {{session_name}}"
+# description = "Claude Code interactive session"
+
+# [session_templates.custom-tool]
+# command = "my-tool --flag"
+# description = "Custom tool"
+# env = { MY_VAR = "value" }               # environment variables to set
+
+# --- Session configuration ---
+# Non-template session settings.
+
+# [session.config]
+# history_limit = 50000                     # tmux scrollback buffer lines per session
+
+# =============================================================================
+# Catalog extensions
+# =============================================================================
+#
+# Operator-defined entries extend the built-in catalog. Entries with the same name
+# as a built-in entry override it. Run `agentworks installer list` to see all
+# available entries (built-in and operator-defined).
+
+# --- Custom apt sources ---
+# Third-party apt repositories.
+# Use {arch} as a placeholder for the VM architecture (amd64 or arm64).
+
+# [apt_sources.my-repo]
+# description = "My internal apt repository"
+# key_url = "https://apt.example.com/key.gpg"
+# key_path = "/etc/apt/keyrings/my-repo.gpg"
+# source = "deb [arch={arch} signed-by=/etc/apt/keyrings/my-repo.gpg] https://apt.example.com/debian bookworm main"
+# source_file = "my-repo.list"
+
+# --- Custom apt packages ---
+# Named package sets with optional apt source dependencies.
+
+# [apt_packages.my-tool]
+# description = "My internal tool"
+# apt_sources = ["my-repo"]
+# apt = ["my-tool"]
+
+# --- Custom system install commands ---
+# Shell commands that install system-wide tooling (run during vm init/reinit).
+# These may be re-run (e.g. during reinit) so they should be idempotent.
+# Optional checks short-circuit installation if the tool is already present.
+# Use only one of: test_exec, test_file, or test_dir.
+
+# [system_install_commands.my-system-tool]
+# description = "Custom system-wide tool"
+# command = "curl -fsSL https://example.com/install.sh | sudo bash"
+# test_exec = "my-system-tool"            # skip if command is on PATH
+
+# --- Custom user install commands ---
+# Shell commands that install per-user tooling (run for admin and agents).
+# These may be re-run so they should be idempotent.
+# Use only one of: test_exec, test_file, or test_dir.
+# For test_file/test_dir, ~ resolves to the target user's home.
+
+# [user_install_commands.my-tool]
+# description = "Custom per-user tool"
+# command = "curl -fsSL https://example.com/install.sh | bash"
+# path = ["~/.my-tool/bin"]
+# test_exec = "my-tool"                   # skip if command is on PATH

agentworks/sessions/console.py

@@ -0,0 +1,164 @@
+"""VM console management.
+
+The console is a VM-level tmux session that provides a unified view of all
+sessions running on the VM. It has full tmux controls (the operator can split
+panes, create windows, rearrange layout). Each session appears as a window
+that attaches to the session's locked-down tmux session.
+"""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from typing import TYPE_CHECKING
+
+from agentworks import output
+from agentworks.sessions.tmux import tmux_cmd
+
+if TYPE_CHECKING:
+    from agentworks.config import Config
+    from agentworks.db import Database, SessionRow, VMRow
+    from agentworks.sessions.tmux import RunCommand
+
+CONSOLE_SESSION_NAME = "vm-console"
+
+
+def console_exists(*, run_command: RunCommand) -> bool:
+    """Check if the console tmux session exists on the VM."""
+    result = run_command(f"tmux has-session -t {CONSOLE_SESSION_NAME} 2>/dev/null", check=False)
+    return getattr(result, "ok", False)
+
+
+def create_console(
+    sessions: list[SessionRow],
+    *,
+    run_command: RunCommand,
+    admin_username: str,
+    recreate: bool = False,
+) -> None:
+    """Create the VM console session with one window per session.
+
+    When *recreate* is True, kills any existing console session first.
+    """
+    if recreate:
+        run_command(f"tmux kill-session -t {CONSOLE_SESSION_NAME}", check=False)
+
+    # Create the session with a login shell as the initial window
+    run_command(
+        f"tmux new-session -d -s {CONSOLE_SESSION_NAME} "
+        f"-n admin-shell "
+        f"{shlex.quote('exec sudo su --login ' + shlex.quote(admin_username))}"
+    )
+
+    # Keep windows open when attached session command exits
+    run_command(f"tmux set -t {CONSOLE_SESSION_NAME} remain-on-exit on", check=False)
+
+    # Add a window for each session (wrapper loop handles ended sessions)
+    output.info(f"Adding {len(sessions)} session(s) to console...")
+    for session in sessions:
+        _add_session_window(
+            session.name,
+            run_command=run_command,
+            socket_path=session.socket_path,
+        )
+
+
+def _add_session_window(
+    session_name: str,
+    *,
+    run_command: RunCommand,
+    socket_path: str | None = None,
+) -> None:
+    """Add a single session window to the console."""
+    q_session = shlex.quote(session_name)
+    # Unset TMUX to allow nesting (console -> session), then loop
+    # re-attach while the session is alive.
+    has_cmd = tmux_cmd(f"has-session -t {q_session}", socket_path)
+    attach_cmd = tmux_cmd(f"attach -t {q_session}", socket_path)
+    wrapper = (
+        f"unset TMUX; "
+        f"while {has_cmd} 2>/dev/null; do "
+        f"{attach_cmd}; "
+        f"sleep 0.5; "
+        f"done; "
+        f"echo 'Session {q_session} has ended. Press enter to close.'; "
+        f"read"
+    )
+    result = run_command(
+        f"tmux new-window -t {CONSOLE_SESSION_NAME} -n {q_session} {shlex.quote(wrapper)}",
+        check=False,
+    )
+    ok = getattr(result, "ok", True)
+    stderr = getattr(result, "stderr", "")
+    if not ok:
+        output.warn(f"failed to add window for '{session_name}': {stderr}")
+
+
+def add_session_to_console(
+    session_name: str,
+    *,
+    run_command: RunCommand,
+    socket_path: str | None = None,
+) -> None:
+    """Add a session window to an existing console (best-effort)."""
+    if not console_exists(run_command=run_command):
+        return
+
+    _add_session_window(session_name, run_command=run_command, socket_path=socket_path)
+
+
+def attach_console(
+    db: Database,
+    config: Config,
+    *,
+    vm_name: str,
+    recreate: bool = False,
+    allow_nesting: bool = False,
+) -> None:
+    """Attach to (or create) the VM console."""
+    import os
+
+    if os.environ.get("TMUX") and not allow_nesting:
+        raise output.SessionError(
+            "already inside a tmux session.\n"
+            "Nesting is not recommended (prefix key conflicts,\n"
+            "confusing detach behavior).\n"
+            "Pass --allow-nesting to override."
+        )
+
+    vm = db.get_vm(vm_name)
+    if vm is None:
+        raise output.VMError(f"VM '{vm_name}' not found")
+
+    from agentworks.workspaces.manager import _ensure_vm_running
+
+    _ensure_vm_running(db, config, vm)
+
+    if vm.tailscale_host is None:
+        raise output.VMError(f"VM '{vm_name}' has no Tailscale address")
+
+    from agentworks.ssh import admin_exec_target, interactive
+
+    target = admin_exec_target(vm, config)
+
+    # Get sessions for this VM (console wrapper handles dead sessions)
+    vm_sessions = _get_sessions_for_vm(db, vm)
+
+    if recreate or not console_exists(run_command=target.run):
+        create_console(
+            vm_sessions,
+            run_command=target.run,
+            admin_username=vm.admin_username,
+            recreate=recreate,
+        )
+
+    sys.exit(interactive(target, f"tmux attach -t {CONSOLE_SESSION_NAME}"))
+
+
+def _get_sessions_for_vm(db: Database, vm: VMRow) -> list[SessionRow]:
+    """Get all sessions across all workspaces on a VM."""
+    workspaces = db.list_workspaces(vm_name=vm.name)
+    sessions: list[SessionRow] = []
+    for ws in workspaces:
+        sessions.extend(db.list_sessions(workspace_name=ws.name))
+    return sessions