devs-common 5.0.6__tar.gz → 6.0.0__tar.gz

{devs_common-5.0.6 → devs_common-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devs-common
-Version: 5.0.6
+Version: 6.0.0
 Summary: Shared utilities for devs package ecosystem
 Author: Dan Lester
 License-Expression: MIT

devs_common-6.0.0/devs_common/agents.py

@@ -0,0 +1,79 @@
+"""Registry of the AI coding agents devs can run inside a devcontainer.
+
+Adding an agent:
+
+1. Install it in ``templates/Dockerfile`` (and add shell aliases next to the others).
+2. Add an ``AgentSpec`` to ``AGENTS`` below — this gives ``ContainerManager.exec_agent``.
+3. Register its ``devs <name>`` command with ``_add_agent_command`` in the CLI's ``cli.py``.
+"""
+
+from dataclasses import dataclass
+from typing import Dict
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """How to run one coding agent non-interactively in a devs container.
+
+    Attributes:
+        name: Registry key and CLI subcommand (``devs <name> ...``).
+        display_name: Human-readable name used in status messages.
+        description: What gets executed, used in help text ("Execute <description> ...").
+        command: Shell command run from the container workspace after ``~/.zshrc`` is
+            sourced. The prompt is written to its stdin, so the command must read it
+            from there and exit when done.
+    """
+
+    name: str
+    display_name: str
+    description: str
+    command: str
+
+
+AGENTS: Dict[str, AgentSpec] = {
+    spec.name: spec
+    for spec in (
+        AgentSpec(
+            name="claude",
+            display_name="Claude",
+            description="Claude CLI",
+            command="claude --dangerously-skip-permissions -p",
+        ),
+        AgentSpec(
+            name="codex",
+            display_name="Codex",
+            description="OpenAI Codex CLI",
+            # `--full-auto` was removed from the Codex CLI (passing it now aborts with
+            # "unexpected argument"). This is the flag Codex intends for externally
+            # sandboxed environments, which a devcontainer is — and it matches the
+            # `claude --dangerously-skip-permissions` invocation beside it.
+            command="codex --dangerously-bypass-approvals-and-sandbox",
+        ),
+        AgentSpec(
+            name="hermes",
+            display_name="Hermes",
+            description="Hermes Agent (Nous Research)",
+            # `--query-file -` reads the prompt from stdin; `--oneshot` answers and exits
+            # rather than seeding an interactive session. `--yolo` skips dangerous-command
+            # approvals, like the other agents. `hermes chat` ignores HERMES_INFERENCE_MODEL,
+            # so forward it as --model when set; otherwise the model baked into the image's
+            # Hermes config is used. Hermes picks OpenRouter from OPENROUTER_API_KEY.
+            command=(
+                "hermes --yolo chat --oneshot --query-file - "
+                "${HERMES_INFERENCE_MODEL:+--model=$HERMES_INFERENCE_MODEL}"
+            ),
+        ),
+    )
+}
+
+
+def get_agent(name: str) -> AgentSpec:
+    """Look up an agent by name.
+
+    Raises:
+        ValueError: If no agent with that name is registered.
+    """
+    try:
+        return AGENTS[name]
+    except KeyError:
+        raise ValueError(f"Unknown agent '{name}'. Available: {', '.join(AGENTS)}") from None

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common/config.py

@@ -12,6 +12,7 @@ class BaseConfig(ABC):
     # Default directories shared across CLI and webhook
     CLAUDE_CONFIG_DIR = Path.home() / ".devs" / "claudeconfig"
     CODEX_CONFIG_DIR = Path.home() / ".devs" / "codexconfig"
+    HERMES_CONFIG_DIR = Path.home() / ".devs" / "hermesconfig"
 
     def __init__(self) -> None:
         """Initialize base configuration."""
@@ -25,6 +26,13 @@ class BaseConfig(ABC):
         codex_config_env = os.getenv("DEVS_CODEX_CONFIG_DIR")
         self.codex_config_dir = Path(codex_config_env) if codex_config_env else self.CODEX_CONFIG_DIR
 
+        hermes_config_env = os.getenv("DEVS_HERMES_CONFIG_DIR")
+        hermes_config_dir = Path(hermes_config_env) if hermes_config_env else self.HERMES_CONFIG_DIR
+        # Bypass __setattr__: pydantic subclasses reject attributes they don't declare as
+        # fields, and devs-webhook releases from before Hermes support don't declare this
+        # one. Their `devs-common>=` pin lets a newer devs-common be installed alongside.
+        object.__setattr__(self, "hermes_config_dir", hermes_config_dir)
+
     @property
     def workspaces_dir(self) -> Path:
         """Get workspaces directory."""
@@ -100,3 +108,5 @@ class BaseConfig(ABC):
         self.bridge_dir.mkdir(parents=True, exist_ok=True)
         self.claude_config_dir.mkdir(parents=True, exist_ok=True)
         self.codex_config_dir.mkdir(parents=True, exist_ok=True)
+        # Bind-mounted into containers, so it must exist before `devcontainer up`
+        self.hermes_config_dir.mkdir(parents=True, exist_ok=True)

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common/core/container.py

@@ -5,9 +5,10 @@ import re
 import time
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple, Union
 import subprocess
 
+from ..agents import AgentSpec, get_agent
 from ..config import BaseConfig
 
 
@@ -915,13 +916,14 @@ class ContainerManager:
         except (DockerError, subprocess.SubprocessError) as e:
             raise ContainerError(f"Failed to exec command in {dev_name}: {e}")
     
-    def exec_claude(self, dev_name: str, workspace_dir: Path, prompt: str, debug: bool = False, stream: bool = True, live: bool = False, extra_env: Optional[Dict[str, str]] = None) -> tuple[bool, str, str, int]:
-        """Execute Claude CLI in the container.
+    def exec_agent(self, agent: Union[str, AgentSpec], dev_name: str, workspace_dir: Path, prompt: str, debug: bool = False, stream: bool = True, live: bool = False, extra_env: Optional[Dict[str, str]] = None) -> tuple[bool, str, str, int]:
+        """Execute a coding agent (Claude, Codex, Hermes, ...) in the container.
 
         Args:
+            agent: Agent name from ``devs_common.agents.AGENTS``, or an ``AgentSpec``
             dev_name: Development environment name
             workspace_dir: Workspace directory path
-            prompt: Prompt to send to Claude
+            prompt: Prompt to send to the agent (passed on stdin)
             debug: Show debug output for devcontainer operations
             stream: Stream output to console in real-time
             live: Whether the container is in live mode
@@ -931,47 +933,14 @@ class ContainerManager:
             Tuple of (success, stdout, stderr, exit_code)
 
         Raises:
-            ContainerError: If Claude execution fails
+            ValueError: If the agent name is not registered
+            ContainerError: If agent execution fails
         """
-        # Simply delegate to exec_command with the Claude command and prompt as stdin
+        spec = get_agent(agent) if isinstance(agent, str) else agent
         return self.exec_command(
             dev_name=dev_name,
             workspace_dir=workspace_dir,
-            command="claude --dangerously-skip-permissions -p",
-            stdin_input=prompt,
-            debug=debug,
-            stream=stream,
-            live=live,
-            extra_env=extra_env
-        )
-
-    def exec_codex(self, dev_name: str, workspace_dir: Path, prompt: str, debug: bool = False, stream: bool = True, live: bool = False, extra_env: Optional[Dict[str, str]] = None) -> tuple[bool, str, str, int]:
-        """Execute OpenAI Codex CLI in the container.
-
-        Args:
-            dev_name: Development environment name
-            workspace_dir: Workspace directory path
-            prompt: Prompt to send to Codex
-            debug: Show debug output for devcontainer operations
-            stream: Stream output to console in real-time
-            live: Whether the container is in live mode
-            extra_env: Additional environment variables to pass to container
-
-        Returns:
-            Tuple of (success, stdout, stderr, exit_code)
-
-        Raises:
-            ContainerError: If Codex execution fails
-        """
-        # Simply delegate to exec_command with the Codex command and prompt as stdin
-        return self.exec_command(
-            dev_name=dev_name,
-            workspace_dir=workspace_dir,
-            # `--full-auto` was removed from the Codex CLI (passing it now aborts with
-            # "unexpected argument"). This is the flag Codex intends for externally
-            # sandboxed environments, which a devcontainer is — and it matches the
-            # `claude --dangerously-skip-permissions` alias sitting beside it.
-            command="codex --dangerously-bypass-approvals-and-sandbox",
+            command=spec.command,
             stdin_input=prompt,
             debug=debug,
             stream=stream,

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common/templates/Dockerfile

@@ -36,6 +36,7 @@ RUN apt update && apt install -y less \
   nano \
   htop \
   tmux \
+  ripgrep \
   && apt clean \
   && rm -rf /var/lib/apt/lists/*
 
@@ -88,7 +89,7 @@ RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhisto
 ENV DEVCONTAINER=true
 
 # Create workspace and config directories and set permissions
-RUN mkdir -p /workspaces /home/node/claudeconfig /home/node/codexconfig \
+RUN mkdir -p /workspaces /home/node/claudeconfig /home/node/codexconfig /home/node/hermesconfig \
       /home/node/.vscode-server/extensions \
       /home/node/.vscode-server/data/Machine && \
   echo '[]' > /home/node/.vscode-server/extensions/extensions.json && \
@@ -150,6 +151,37 @@ RUN curl -fsSL https://claude.ai/install.sh | bash
 ARG CODEX_CLI_VERSION=0.144.6
 RUN npm install -g "@openai/codex@${CODEX_CLI_VERSION}"
 
+# Install Hermes Agent (Nous Research's open-source coding agent). Pinned to a release
+# tag for the same reason as Codex above; bump HERMES_AGENT_VERSION to upgrade. Setup
+# wizard, browser and computer-use extras are skipped — the agent is driven through
+# OpenRouter: put OPENROUTER_API_KEY in ~/.devs/envs/<project>/.env (or DEVS.yml env_vars).
+#
+# The code goes in /home/node/.hermes-agent and the data dir (HERMES_HOME: sessions,
+# memory, skills, config.yaml) in /home/node/hermesconfig, which devcontainer.json
+# bind-mounts from ~/.devs/hermesconfig so it persists across rebuilds like claudeconfig
+# and codexconfig. The installer's default puts the code *inside* HERMES_HOME, where the
+# mount would hide it. Because config.yaml lives on the host, the default model can't be
+# baked in here: scripts/setup-hermes.sh seeds HERMES_DEFAULT_MODEL into it at container
+# start if no model is configured yet. HERMES_INFERENCE_MODEL overrides it per container.
+ARG HERMES_AGENT_VERSION=v2026.9.14
+ARG HERMES_DEFAULT_MODEL=z-ai/glm-5.3
+ENV HERMES_HOME=/home/node/hermesconfig \
+    HERMES_DEFAULT_MODEL=${HERMES_DEFAULT_MODEL}
+# Download first rather than `curl | bash`: /bin/sh has no pipefail, so a failed
+# download (e.g. a GitHub 429) would otherwise run an empty script and "succeed".
+# The installer also seeds a data dir (~85 MB: its own uv, skills, a sample config.yaml);
+# the mount would hide it anyway, so point that at a scratch dir and delete it. Hermes
+# re-syncs bundled skills into the mounted HERMES_HOME on first run.
+RUN curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors \
+      "https://raw.githubusercontent.com/NousResearch/hermes-agent/${HERMES_AGENT_VERSION}/scripts/install.sh" \
+      -o /tmp/hermes-install.sh && \
+  HERMES_HOME=/tmp/hermes-build-home bash /tmp/hermes-install.sh \
+    --branch "${HERMES_AGENT_VERSION}" --dir /home/node/.hermes-agent \
+    --hermes-home /tmp/hermes-build-home \
+    --non-interactive --skip-setup --skip-browser --skip-computer-use && \
+  HERMES_HOME=/tmp/hermes-build-home /home/node/.local/bin/hermes --version && \
+  rm -rf /tmp/hermes-install.sh /tmp/hermes-build-home
+
 # Install cloudflared for tunnel support (proxies all HTTP methods correctly)
 # Install VS Code CLI for tunnel support (needs root for /usr/local/bin)
 # Using the standalone CLI which supports the 'tunnel' command
@@ -180,14 +212,16 @@ RUN ARCH=$(dpkg --print-architecture) && \
   rm -rf /tmp/tailscale.tgz "/tmp/tailscale_${TAILSCALE_VERSION}_${ARCH}" && \
   chmod +x /usr/local/bin/tailscale /usr/local/bin/tailscaled
 
-# Set up environment variables and aliases for Claude and Codex
+# Set up environment variables and aliases for Claude, Codex and Hermes
 RUN for shell_rc in /home/node/.zshrc /home/node/.bashrc; do \
   echo "export CLAUDE_CONFIG_DIR=\"/home/node/claudeconfig\"" >> "$shell_rc" && \
-  echo "export CODEX_CONFIG_HOME=\"/home/node/codexconfig\"" >> "$shell_rc" && \
+  echo "export CODEX_HOME=\"/home/node/codexconfig\"" >> "$shell_rc" && \
   echo "export PATH=\"/home/node/.local/bin:\$PATH\"" >> "$shell_rc" && \
   echo "alias claude=\"claude --dangerously-skip-permissions\"" >> "$shell_rc" && \
   echo "alias codex=\"/usr/local/share/npm-global/bin/codex -c check_for_update_on_startup=false --dangerously-bypass-approvals-and-sandbox\"" >> "$shell_rc" && \
   echo "alias codex-normal=\"/usr/local/share/npm-global/bin/codex -c check_for_update_on_startup=false\"" >> "$shell_rc" && \
+  echo "alias hermes='/home/node/.local/bin/hermes --yolo \${HERMES_INFERENCE_MODEL:+--model=\$HERMES_INFERENCE_MODEL}'" >> "$shell_rc" && \
+  echo "alias hermes-normal='/home/node/.local/bin/hermes \${HERMES_INFERENCE_MODEL:+--model=\$HERMES_INFERENCE_MODEL}'" >> "$shell_rc" && \
   echo "" >> "$shell_rc" && \
   echo "# Auto-activate Python venv if it exists" >> "$shell_rc" && \
   echo "if [ -f /home/node/.devs-venv/workspace-venv/bin/activate ]; then" >> "$shell_rc" && \

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common/templates/devcontainer.json

@@ -37,6 +37,7 @@
     "source=claude-code-bashhistory,target=/commandhistory,type=volume",
     "source=${localEnv:HOME}/.devs/claudeconfig,target=/home/node/claudeconfig,type=bind",
     "source=${localEnv:HOME}/.devs/codexconfig,target=/home/node/codexconfig,type=bind",
+    "source=${localEnv:HOME}/.devs/hermesconfig,target=/home/node/hermesconfig,type=bind",
     "source=${localEnv:DEVS_ENV_MOUNT_PATH},target=/home/node/.devs-env,type=bind",
     "source=${localEnv:DEVS_BRIDGE_MOUNT_PATH},target=/home/node/bridge,type=bind",
     // Remove the extensions mount to get fresh state each time

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common/templates/scripts/post-start.sh

@@ -16,16 +16,30 @@ if [ -f /home/node/.devs-env/.env ]; then
   set -a; . /home/node/.devs-env/.env; set +a
 fi
 
+# Per-developer start hooks: ~/.devs/envs/<project>/autoexec-start/ on the host.
+# The every-start counterpart of the create-time autoexec/ — for whatever a hook
+# launched that a restart kills along with everything else that isn't PID 1. Same
+# runner; no directory => no-op. Called last on either path below, so a hook that
+# needs tailnet names finds MagicDNS already in place.
+run_start_hooks() {
+  DEVS_AUTOEXEC_DIR=/home/node/.devs-env/autoexec-start /usr/local/bin/run-autoexec.sh \
+    || echo "⚠️  autoexec-start hook failed (continuing)."
+}
+
 # VS Code machine settings (+ optional tmux overlay, off unless DEVS_TMUX=1). Not
 # Tailscale-gated — it configures the editor regardless of how you connect. Must come
 # before the TS_ENABLE gate below, which exits when Tailscale is off.
 /usr/local/bin/setup-vscode-settings.sh || true
 
+# Hermes Agent's default model, seeded into its host-persisted config if none is set yet.
+/usr/local/bin/setup-hermes.sh || true
+
 # Gate on the same master switch as the rest of the Tailscale wiring.
 case "${TS_ENABLE:-}" in
   1|true|yes) ;;
   *)
     echo "ℹ️  Tailscale not enabled (TS_ENABLE=${TS_ENABLE:-unset}) — skipping tailnet setup."
+    run_start_hooks
     exit 0 ;;
 esac
 
@@ -41,3 +55,5 @@ esac
 # container. Must run after the bring-up above (it no-ops unless tailscaled is up),
 # and on every start because Docker regenerates /etc/resolv.conf each time.
 sudo -n /usr/local/bin/setup-magicdns.sh || true
+
+run_start_hooks

devs_common-6.0.0/devs_common/templates/scripts/setup-hermes.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Seed Hermes Agent's default model into its persisted config (runs as the node user from
+# post-start.sh on every container start).
+#
+# HERMES_HOME (/home/node/hermesconfig) is bind-mounted from ~/.devs/hermesconfig on the
+# host, so config.yaml can't be baked into the image. Without a configured model Hermes
+# falls back to its own pick, so write HERMES_DEFAULT_MODEL (a Dockerfile build arg) the
+# first time — but never overwrite a model or provider the user has chosen since, e.g.
+# with `hermes model`. HERMES_INFERENCE_MODEL still overrides per container at run time.
+set -uo pipefail
+
+HERMES=/home/node/.local/bin/hermes
+[ -x "$HERMES" ] || exit 0
+[ -n "${HERMES_DEFAULT_MODEL:-}" ] || exit 0
+
+if [ -n "$("$HERMES" config get model.default 2>/dev/null)" ]; then
+    exit 0
+fi
+
+if [ -z "$("$HERMES" config get model.provider 2>/dev/null)" ]; then
+    "$HERMES" config set model.provider openrouter >/dev/null || exit 0
+fi
+"$HERMES" config set model.default "$HERMES_DEFAULT_MODEL" >/dev/null &&
+    echo "✅ Hermes default model set to $HERMES_DEFAULT_MODEL in $HERMES_HOME/config.yaml"

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common/templates/sudo-scripts/setup-devs-env.sh

@@ -68,24 +68,6 @@ check_github_token_setup() {
         git config --global core.trustctime false
         echo "✅ Git core.trustctime set to false (prevents timezone-related rebase issues)"
         
-        # Ensure it's available in all shell sessions for the node user
-        if ! grep -q "source /home/node/.devs-env/.env" /home/node/.zshrc 2>/dev/null; then
-            echo "# Load devs environment variables" >> /home/node/.zshrc
-            echo "if [ -f /home/node/.devs-env/.env ]; then" >> /home/node/.zshrc
-            echo "    set -a" >> /home/node/.zshrc
-            echo "    source /home/node/.devs-env/.env" >> /home/node/.zshrc
-            echo "    set +a" >> /home/node/.zshrc
-            echo "fi" >> /home/node/.zshrc
-        fi
-        if ! grep -q "source /home/node/.devs-env/.env" /home/node/.bashrc 2>/dev/null; then
-            echo "# Load devs environment variables" >> /home/node/.bashrc
-            echo "if [ -f /home/node/.devs-env/.env ]; then" >> /home/node/.bashrc
-            echo "    set -a" >> /home/node/.bashrc
-            echo "    source /home/node/.devs-env/.env" >> /home/node/.bashrc
-            echo "    set +a" >> /home/node/.bashrc
-            echo "fi" >> /home/node/.bashrc
-        fi
-        
         # Test if gh CLI can authenticate
         if command -v gh >/dev/null 2>&1; then
             if gh auth status >/dev/null 2>&1; then
@@ -104,10 +86,45 @@ check_github_token_setup() {
     fi
 }
 
+# Load the mounted env file in every shell for the node user. This used to happen only
+# when GH_TOKEN was set, which left other keys in the file (e.g. OPENROUTER_API_KEY for
+# Hermes) invisible to interactive shells and to `devs <agent>` execs.
+setup_env_file_sourcing() {
+    local rc
+    for rc in /home/node/.zshrc /home/node/.bashrc; do
+        if ! grep -q "source /home/node/.devs-env/.env" "$rc" 2>/dev/null; then
+            {
+                echo "# Load devs environment variables"
+                echo "if [ -f /home/node/.devs-env/.env ]; then"
+                echo "    set -a"
+                echo "    source /home/node/.devs-env/.env"
+                echo "    set +a"
+                echo "fi"
+            } >> "$rc"
+        fi
+    done
+}
+
+# Report whether Hermes Agent has an inference provider key
+check_hermes_setup() {
+    if [ -n "${OPENROUTER_API_KEY:-}" ]; then
+        echo "✅ OpenRouter API key (OPENROUTER_API_KEY) is available - Hermes Agent is ready"
+    else
+        echo "ℹ️  No OpenRouter API key (OPENROUTER_API_KEY) configured"
+        echo "   To use Hermes Agent, add OPENROUTER_API_KEY=your_key to"
+        echo "   ~/.devs/envs/<project-name>/.env (or ~/.devs/envs/default/.env)"
+    fi
+}
+
 # Check SSH access (configured during build)
 check_ssh_setup
 
 # Check GitHub token access (configured via mounted env files)
 check_github_token_setup
 
+setup_env_file_sourcing
+
+# check_github_token_setup sourced the env file, so OPENROUTER_API_KEY is visible here
+check_hermes_setup
+
 echo "Devs environment setup complete!"

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devs-common
-Version: 5.0.6
+Version: 6.0.0
 Summary: Shared utilities for devs package ecosystem
 Author: Dan Lester
 License-Expression: MIT

{devs_common-5.0.6 → devs_common-6.0.0}/devs_common.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 devs_common/__init__.py
+devs_common/agents.py
 devs_common/config.py
 devs_common/devs_config.py
 devs_common/exceptions.py
@@ -31,6 +32,7 @@ devs_common/templates/scripts/post-start.sh
 devs_common/templates/scripts/python-venv-integration.sh
 devs_common/templates/scripts/run-autoexec.sh
 devs_common/templates/scripts/screenshot-webapp.sh
+devs_common/templates/scripts/setup-hermes.sh
 devs_common/templates/scripts/setup-vscode-settings.sh
 devs_common/templates/scripts/setup-workspace.sh
 devs_common/templates/scripts/start-tailscale.sh

{devs_common-5.0.6 → devs_common-6.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devs-common"
-version = "5.0.6"
+version = "6.0.0"
 description = "Shared utilities for devs package ecosystem"
 authors = [
     {name = "Dan Lester"},