dlab-cli 0.1.0__py3-none-any.whl

dlab/local.py

@@ -0,0 +1,269 @@
+"""
+Local execution backend for running opencode without Docker.
+
+Used when --no-sandboxing is passed or Docker is not available.
+Instead of replicating the Docker environment, this copies the docker/
+directory into the work dir as _docker/ and prepends instructions to the
+prompt telling the agent to set up its own environment.
+"""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+def is_docker_available() -> bool:
+    """
+    Check if Docker CLI exists and the daemon is running.
+
+    Returns
+    -------
+    bool
+        True if docker is installed and the daemon responds.
+    """
+    if shutil.which("docker") is None:
+        return False
+    try:
+        result: subprocess.CompletedProcess[str] = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=10,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+def detect_package_manager(config_dir: str) -> str:
+    """
+    Detect package manager from docker/ contents.
+
+    Parameters
+    ----------
+    config_dir : str
+        Path to decision-pack directory.
+
+    Returns
+    -------
+    str
+        One of "conda", "pixi", "pip".
+    """
+    docker_dir: Path = Path(config_dir) / "docker"
+    if (docker_dir / "environment.yml").exists():
+        return "conda"
+    if (docker_dir / "pixi.toml").exists():
+        return "pixi"
+    return "pip"
+
+
+def copy_docker_dir(config_dir: str, work_dir: str) -> None:
+    """
+    Copy the decision-pack's docker/ directory into the work dir as _docker/.
+
+    Parameters
+    ----------
+    config_dir : str
+        Path to decision-pack directory.
+    work_dir : str
+        Session work directory.
+    """
+    docker_src: Path = Path(config_dir) / "docker"
+    docker_dst: Path = Path(work_dir) / "_docker"
+    if docker_src.exists():
+        if docker_dst.exists():
+            shutil.rmtree(docker_dst)
+        shutil.copytree(str(docker_src), str(docker_dst))
+
+
+def build_local_prompt(prompt: str, config: dict[str, Any]) -> str:
+    """
+    Prepend system instructions for unsandboxed local execution.
+
+    Parameters
+    ----------
+    prompt : str
+        Original user prompt.
+    config : dict[str, Any]
+        decision-pack configuration.
+
+    Returns
+    -------
+    str
+        Prompt with system instructions prepended.
+    """
+    pkg_mgr: str = config.get(
+        "package_manager",
+        detect_package_manager(config["config_dir"]),
+    )
+
+    work_dir_abs: str = str(Path(config["config_dir"]).resolve().parent)
+    # Use the actual work dir if available, fall back to config dir parent
+    # (the caller should pass work_dir in config if needed)
+
+    system_instructions: str = (
+        "IMPORTANT --- SYSTEM INSTRUCTIONS (NO-SANDBOXING MODE):\n\n"
+        "You're running locally, NOT inside a Docker container. The decision-pack "
+        f"was designed for a Docker environment with python managed by {pkg_mgr}.\n\n"
+        "## Step 1: Set up the environment\n\n"
+        "Read `_docker/Dockerfile` carefully. It shows:\n"
+        "- Which base image and package manager was intended\n"
+        "- Which dependency file to install from (requirements.txt, environment.yml, pixi.toml)\n"
+        "- Which directories from _docker/ would have been COPY'd into the container "
+        "(e.g., custom Python libraries like `COPY <SUB_DIR>/ /opt/<SUB_DIR>/`)\n\n"
+        f"Use `{pkg_mgr}` to create and install a local environment from the dependency "
+        "file in `_docker/`. For example:\n"
+        "- pip: `python -m venv .venv && .venv/bin/pip install -r _docker/requirements.txt`\n"
+        "- conda: `conda create -p .conda-env --yes && conda env update -p .conda-env -f _docker/environment.yml`\n"
+        "- uv: `uv venv .venv && uv pip install --python .venv/bin/python -r _docker/requirements.txt`\n"
+        "- pixi: `cp _docker/pixi.toml . && pixi install`\n\n"
+        "If the Dockerfile COPY'd any Python libraries from _docker/ into the container, "
+        "you need to make those importable by setting the ABSOLUTE path to _docker/ in "
+        "PYTHONPATH when running scripts:\n"
+        "`PYTHONPATH=/absolute/path/to/workdir/_docker:$PYTHONPATH python my_script.py`\n\n"
+        "## Step 2: Verify the environment works\n\n"
+        "After setting up, run a small test script that imports the key packages from the "
+        "dependency file to confirm everything is installed correctly. Fix any import errors "
+        "before proceeding.\n\n"
+        "## Step 3: Read the hooks\n\n"
+        "Read `_hooks/` — these are scripts that would have run inside the container before "
+        "and after the agent session. Adapt and run pre-run hooks if they make sense locally "
+        "(e.g., skip Modal deployment if not applicable, but run data setup scripts).\n\n"
+        "## Step 4: Subagent environment instructions\n\n"
+        "When you call parallel-agents or task subagents, you MUST include in each prompt:\n"
+        "- The absolute path to the correct python binary (e.g., `/absolute/path/to/.venv/bin/python`)\n"
+        "- The correct PYTHONPATH value (e.g., `PYTHONPATH=/absolute/path/to/workdir/_docker:$PYTHONPATH`)\n"
+        "- Instructions to use this python for all script execution\n\n"
+        "Subagents do NOT inherit your environment setup. They start fresh and need explicit "
+        "instructions on which python to use.\n\n"
+        "---\n\n"
+        "Now follows the User's request:\n"
+    )
+
+    return f"{system_instructions}{prompt}"
+
+
+def build_local_env(env_file: str | None = None) -> dict[str, str]:
+    """
+    Build environment variables dict for local execution.
+
+    Parameters
+    ----------
+    env_file : str | None
+        Optional .env file to parse and include.
+
+    Returns
+    -------
+    dict[str, str]
+        Environment variables.
+    """
+    env: dict[str, str] = dict(os.environ)
+
+    if env_file:
+        for line in Path(env_file).read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            key, _, value = line.partition("=")
+            value = value.strip().strip("'\"")
+            env[key.strip()] = value
+
+    return env
+
+
+def run_local_command(
+    command: list[str],
+    work_dir: str,
+    env: dict[str, str],
+    timeout: int | None = None,
+) -> tuple[int, str, str]:
+    """
+    Run a command locally in the work directory.
+
+    Parameters
+    ----------
+    command : list[str]
+        Command and arguments.
+    work_dir : str
+        Working directory.
+    env : dict[str, str]
+        Environment variables.
+    timeout : int | None
+        Timeout in seconds.
+
+    Returns
+    -------
+    tuple[int, str, str]
+        (exit_code, stdout, stderr).
+    """
+    result: subprocess.CompletedProcess[str] = subprocess.run(
+        command,
+        capture_output=True,
+        text=True,
+        cwd=work_dir,
+        env=env,
+        timeout=timeout,
+    )
+    return result.returncode, result.stdout, result.stderr
+
+
+def run_opencode_local(
+    work_dir: str,
+    prompt: str,
+    model: str,
+    env: dict[str, str],
+    timeout: int | None = None,
+    log_prefix: str = "main",
+) -> tuple[int, str, str]:
+    """
+    Run opencode locally in the work directory.
+
+    Parameters
+    ----------
+    work_dir : str
+        Session work directory.
+    prompt : str
+        Prompt text (already includes system instructions).
+    model : str
+        LLM model identifier.
+    env : dict[str, str]
+        Environment variables.
+    timeout : int | None
+        Timeout in seconds.
+    log_prefix : str
+        Log file prefix.
+
+    Returns
+    -------
+    tuple[int, str, str]
+        (exit_code, stdout, stderr).
+    """
+    work_path: Path = Path(work_dir)
+    logs_dir: Path = work_path / "_opencode_logs"
+
+    # Write prompt to file (avoids shell quoting issues)
+    prompt_file: Path = work_path / ".prompt.txt"
+    prompt_file.write_text(prompt)
+
+    # Build runner script
+    log_path: str = str(logs_dir / f"{log_prefix}.log")
+    runner_script: str = f'''#!/bin/bash
+set -o pipefail
+prompt=$(cat "{prompt_file}")
+opencode run --format json --log-level DEBUG --model "{model}" "$prompt" 2>&1 | tee "{log_path}"
+'''
+    runner_file: Path = work_path / ".run_opencode.sh"
+    runner_file.write_text(runner_script)
+    runner_file.chmod(0o755)
+
+    result: subprocess.CompletedProcess[str] = subprocess.run(
+        ["bash", str(runner_file)],
+        capture_output=True,
+        text=True,
+        cwd=work_dir,
+        env=env,
+        timeout=timeout,
+    )
+
+    return result.returncode, result.stdout, result.stderr

dlab/model_fallback.py

@@ -0,0 +1,360 @@
+"""
+Model validation and provider fallback for agent configs.
+
+When a decision-pack references model providers whose API keys are not
+in the .env file, this module replaces those model strings with the
+orchestrator's model so users only need a single API key to get started.
+
+Two-phase design:
+1. preflight_check() — runs BEFORE session creation on source dpack files.
+   Catches fatal errors (orchestrator key missing, unknown models) early.
+2. process_opencode_dir() — runs DURING session setup on work-dir copies.
+   Applies fallback replacements for missing provider keys.
+"""
+
+import difflib
+import os
+import re
+from pathlib import Path
+
+from dlab.create_dpack import KNOWN_PROVIDER_ENVS, get_model_list, get_provider_env_vars
+
+
+# Matches provider/model-name patterns (e.g. "anthropic/claude-sonnet-4-5")
+# Negative lookahead (?!/) excludes file paths like "opencode/agents/foo.md"
+_MODEL_PATTERN: re.Pattern[str] = re.compile(
+    r"\b([a-zA-Z0-9_-]+/[a-zA-Z0-9._-]+)\b(?!/)"
+)
+
+
+def parse_env_file(env_file: str | None) -> dict[str, str]:
+    """
+    Parse a .env file into a key-value dict.
+
+    Parameters
+    ----------
+    env_file : str | None
+        Path to .env file, or None.
+
+    Returns
+    -------
+    dict[str, str]
+        Parsed environment variables. Empty dict if env_file is None
+        or file does not exist.
+    """
+    if not env_file:
+        return {}
+    path: Path = Path(env_file)
+    if not path.exists():
+        return {}
+
+    env: dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        key, _, value = line.partition("=")
+        value = value.strip().strip("'\"")
+        env[key.strip()] = value
+    return env
+
+
+def get_available_providers(env_vars: dict[str, str]) -> set[str]:
+    """
+    Return the set of providers whose required API keys are present.
+
+    Parameters
+    ----------
+    env_vars : dict[str, str]
+        Parsed environment variables.
+
+    Returns
+    -------
+    set[str]
+        Provider names (e.g. {"anthropic", "google"}) with all required
+        keys present and non-empty.
+    """
+    available: set[str] = set()
+    for provider, required_keys in KNOWN_PROVIDER_ENVS.items():
+        if all(env_vars.get(k) for k in required_keys):
+            available.add(provider)
+    return available
+
+
+def _strip_comments(text: str) -> str:
+    """Remove comment lines (# ...) from text before scanning for models."""
+    lines: list[str] = []
+    for line in text.splitlines():
+        stripped: str = line.lstrip()
+        if not stripped.startswith("#"):
+            lines.append(line)
+    return "\n".join(lines)
+
+
+def find_model_strings(text: str) -> list[str]:
+    """
+    Extract all provider/model-name strings from non-comment text.
+
+    Parameters
+    ----------
+    text : str
+        File content to scan.
+
+    Returns
+    -------
+    list[str]
+        Deduplicated list of model strings found.
+    """
+    matches: list[str] = _MODEL_PATTERN.findall(_strip_comments(text))
+    # Only keep matches whose provider prefix is a known provider
+    known_prefixes: set[str] = set(KNOWN_PROVIDER_ENVS.keys())
+    models: list[str] = []
+    seen: set[str] = set()
+    for m in matches:
+        provider: str = m.split("/")[0]
+        if provider in known_prefixes and m not in seen:
+            seen.add(m)
+            models.append(m)
+    return models
+
+
+def _collect_models_from_dir(directory: Path) -> list[str]:
+    """Scan all .yaml/.yml/.md files in a directory for model strings."""
+    all_models: list[str] = []
+    config_files: list[Path] = sorted(
+        list(directory.rglob("*.yaml"))
+        + list(directory.rglob("*.yml"))
+        + list(directory.rglob("*.md"))
+    )
+    for f in config_files:
+        all_models.extend(find_model_strings(f.read_text()))
+    return list(dict.fromkeys(all_models))  # deduplicate, preserve order
+
+
+def _format_env_setup_hint(model: str) -> str:
+    """Format a hint showing which env var to set for a model's provider."""
+    env_vars: list[str] = get_provider_env_vars(model)
+    if env_vars:
+        var_str: str = ", ".join(env_vars)
+        return f"Set {var_str} in your .env file"
+    return "Check provider documentation for required API key"
+
+
+def preflight_check(
+    orchestrator_model: str,
+    config_dir: str,
+    env_file: str | None,
+    no_sandboxing: bool = False,
+) -> tuple[list[str], list[str]]:
+    """
+    Validate models before session creation. Runs on source dpack files.
+
+    Returns errors (fatal, abort run) and warnings (informational, continue).
+
+    Parameters
+    ----------
+    orchestrator_model : str
+        The orchestrator's model (from --model or config default_model).
+    config_dir : str
+        Path to the decision-pack config directory.
+    env_file : str | None
+        Path to .env file.
+    no_sandboxing : bool
+        If True, also check os.environ for API keys (local mode inherits
+        the shell environment).
+
+    Returns
+    -------
+    tuple[list[str], list[str]]
+        (errors, warnings). Errors are fatal and should abort the run.
+        Warnings are informational (e.g. fallback will be applied).
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    env_vars: dict[str, str] = {}
+    if no_sandboxing:
+        env_vars.update(os.environ)
+    env_vars.update(parse_env_file(env_file))
+    available: set[str] = get_available_providers(env_vars)
+
+    # Validate orchestrator model name
+    all_known: list[str] = get_model_list()
+    known: set[str] = set(all_known)
+    if orchestrator_model not in known:
+        suggestions: list[str] = sorted(difflib.get_close_matches(
+            orchestrator_model, all_known, n=3, cutoff=0.6,
+        ))
+        if suggestions:
+            alt: str = ", ".join(suggestions)
+            errors.append(
+                f"Unknown model {orchestrator_model} — did you mean: {alt}?"
+            )
+        else:
+            errors.append(f"Unknown model {orchestrator_model}")
+        return errors, warnings
+
+    # Check orchestrator model's provider key
+    orchestrator_provider: str = orchestrator_model.split("/")[0]
+    if orchestrator_provider in KNOWN_PROVIDER_ENVS and orchestrator_provider not in available:
+        env_hint: str = _format_env_setup_hint(orchestrator_model)
+        errors.append(
+            f"Orchestrator model {orchestrator_model} requires an API key "
+            f"that is not set. {env_hint}"
+        )
+        return errors, warnings
+
+    # Scan source opencode/ dir for model strings
+    opencode_dir: Path = Path(config_dir) / "opencode"
+    if not opencode_dir.exists():
+        return errors, warnings
+
+    all_models: list[str] = _collect_models_from_dir(opencode_dir)
+
+    # Validate agent model names exist in known list
+    for model in all_models:
+        if model not in known:
+            suggestions: list[str] = sorted(difflib.get_close_matches(
+                model, all_known, n=3, cutoff=0.6,
+            ))
+            if suggestions:
+                alt: str = ", ".join(suggestions)
+                errors.append(
+                    f"Unknown model {model} — did you mean: {alt}?"
+                )
+            else:
+                errors.append(f"Unknown model {model}")
+
+    # Check which agent models will need fallback
+    unavailable: set[str] = set(KNOWN_PROVIDER_ENVS.keys()) - available
+    models_needing_fallback: list[str] = []
+    for model in all_models:
+        provider: str = model.split("/")[0]
+        if provider in unavailable and model != orchestrator_model:
+            models_needing_fallback.append(model)
+
+    if models_needing_fallback:
+        seen: set[str] = set()
+        for model in models_needing_fallback:
+            if model in seen:
+                continue
+            seen.add(model)
+            env_hint = _format_env_setup_hint(model)
+            warnings.append(
+                f"{model} -> {orchestrator_model} ({env_hint})"
+            )
+
+    return errors, warnings
+
+
+def apply_model_fallback(
+    text: str,
+    orchestrator_model: str,
+    unavailable_providers: set[str],
+) -> tuple[str, list[str]]:
+    """
+    Replace model strings whose providers are unavailable.
+
+    Parameters
+    ----------
+    text : str
+        File content.
+    orchestrator_model : str
+        Model to substitute in place of unavailable ones.
+    unavailable_providers : set[str]
+        Provider names whose API keys are missing.
+
+    Returns
+    -------
+    tuple[str, list[str]]
+        (modified_text, list of replacement descriptions).
+    """
+    if not unavailable_providers:
+        return text, []
+
+    replacements: list[str] = []
+
+    def _replace(match: re.Match[str]) -> str:
+        model_str: str = match.group(1)
+        provider: str = model_str.split("/")[0]
+        if provider in unavailable_providers:
+            replacements.append(f"{model_str} -> {orchestrator_model}")
+            return orchestrator_model
+        return model_str
+
+    # Only replace on non-comment lines
+    new_lines: list[str] = []
+    for line in text.splitlines(keepends=True):
+        if line.lstrip().startswith("#"):
+            new_lines.append(line)
+        else:
+            new_lines.append(_MODEL_PATTERN.sub(_replace, line))
+
+    return "".join(new_lines), replacements
+
+
+def process_opencode_dir(
+    opencode_dir: str,
+    orchestrator_model: str,
+    env_file: str | None,
+    no_sandboxing: bool = False,
+) -> list[str]:
+    """
+    Apply model fallback to all config files in .opencode/ (work-dir copies).
+
+    Assumes preflight_check() has already validated the orchestrator model.
+    Only applies replacements — no validation here.
+
+    Parameters
+    ----------
+    opencode_dir : str
+        Path to the .opencode/ directory in the work dir.
+    orchestrator_model : str
+        The orchestrator's model (fallback target).
+    env_file : str | None
+        Path to .env file.
+    no_sandboxing : bool
+        If True, also check os.environ for API keys.
+
+    Returns
+    -------
+    list[str]
+        Replacement messages (e.g. "parallel_agents/poet.yaml: google/gemini-2.0-flash -> ...").
+    """
+    opencode_path: Path = Path(opencode_dir)
+    if not opencode_path.exists():
+        return []
+
+    env_vars: dict[str, str] = {}
+    if no_sandboxing:
+        env_vars.update(os.environ)
+    env_vars.update(parse_env_file(env_file))
+    available: set[str] = get_available_providers(env_vars)
+
+    orchestrator_provider: str = orchestrator_model.split("/")[0]
+    if orchestrator_provider in KNOWN_PROVIDER_ENVS and orchestrator_provider not in available:
+        return []
+
+    unavailable: set[str] = set(KNOWN_PROVIDER_ENVS.keys()) - available
+    if not unavailable:
+        return []
+
+    messages: list[str] = []
+    config_files: list[Path] = sorted(
+        list(opencode_path.rglob("*.yaml"))
+        + list(opencode_path.rglob("*.yml"))
+        + list(opencode_path.rglob("*.md"))
+    )
+
+    for f in config_files:
+        text: str = f.read_text()
+        new_text, replacements = apply_model_fallback(
+            text, orchestrator_model, unavailable,
+        )
+        if replacements:
+            f.write_text(new_text)
+            rel: str = str(f.relative_to(opencode_path))
+            for r in replacements:
+                messages.append(f"{rel}: {r}")
+
+    return messages

dlab/parallel_tool.py

@@ -0,0 +1,18 @@
+"""
+Template for the parallel-agents.ts tool.
+
+This module loads the parallel-agents TypeScript source from dlab/js/
+and exposes it as PARALLEL_AGENTS_SOURCE for use by session setup.
+
+WARNING: The template contains an evil hack (git init) to work around OpenCode's config
+traversal behavior. See "Git Init Hack" section in CLAUDE.md for details.
+This should be replaced with a proper solution when OpenCode supports
+disabling parent directory config traversal.
+"""
+
+from importlib.resources import files
+
+
+PARALLEL_AGENTS_SOURCE: str = (
+    files("dlab.js").joinpath("parallel-agents.ts").read_text()
+)