delegate-agent-cli 0.11.0__py3-none-any.whl

delegate_agent/inspection_commands.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO
+
+from delegate_agent import command_errors, redaction, run_registry, snapshot_view
+from delegate_agent import rendering as delegate_rendering
+from delegate_agent.json_types import JsonObject
+
+
+@dataclass(frozen=True)
+class SnapshotCommand:
+    handle: str | None
+    latest_harness: str | None = None
+    no_redact: bool = False
+    json_mode: bool = False
+
+
+@dataclass(frozen=True)
+class RunsCommand:
+    active: bool = False
+    running: bool = False
+    stale: bool = False
+    harness: str | None = None
+    group: str | None = None
+    limit: int | None = None
+    json_mode: bool = False
+
+
+class InspectionError(command_errors.CommandError):
+    pass
+
+
+def emit_snapshot(command: SnapshotCommand, *, workspace_path: str, stdout: TextIO) -> int:
+    workspace = Path(workspace_path)
+    registry_root = run_registry.registry_root_if_exists(workspace)
+    if registry_root is None:
+        if command.latest_harness is None and command.handle is None:
+            raise InspectionError("missing_handle", "snapshot requires a run handle or --latest.")
+        registry_root = run_registry.registry_root(workspace)
+    target = run_registry.resolve_run_target(
+        registry_root,
+        handle=command.handle,
+        latest_harness=command.latest_harness,
+    )
+    if isinstance(target, run_registry.RunTargetLookupError):
+        raise InspectionError(target.error, target.message)
+    run_id, alias = target.run_id, target.alias
+    snapshot = run_registry.load_run_snapshot(registry_root, run_id)
+    view = snapshot_view.merge_snapshot_view(
+        registry_root,
+        run_id,
+        snapshot,
+        redact=not command.no_redact,
+    )
+    if target.resolution_kind != "literal":
+        view["requestedHandle"] = target.requested_handle
+        view["resolvedHandle"] = target.resolved_handle or alias or run_id
+        view["resolutionKind"] = target.resolution_kind
+    if command.json_mode:
+        delegate_rendering.print_json(snapshot_view.snapshot_json_payload(view), stdout)
+    else:
+        delegate_rendering.render_snapshot_text(view, stdout)
+    return 0
+
+
+def emit_runs(command: RunsCommand, *, workspace_path: str, stdout: TextIO) -> int:
+    registry_root = run_registry.registry_root_if_exists(Path(workspace_path))
+    limit = command.limit or run_registry.DEFAULT_RUNS_LIMIT
+    if command.running:
+        mode = "running"
+        status_filter = run_registry.STATUS_FILTER_RUNNING
+    elif command.stale:
+        mode = "stale"
+        status_filter = run_registry.STATUS_FILTER_STALE
+    elif command.active:
+        mode = "active"
+        status_filter = None
+    else:
+        mode = "recent"
+        status_filter = None
+    if registry_root is None:
+        summaries: list[JsonObject] = []
+    else:
+        index = run_registry.load_index(registry_root)
+        summaries = run_registry.list_run_summaries(
+            registry_root,
+            index,
+            active=command.active,
+            status_filter=status_filter,
+            harness=command.harness,
+            group=command.group,
+            limit=limit,
+        )
+    summaries = [redaction.redact_value(summary) for summary in summaries]
+    if command.json_mode:
+        delegate_rendering.print_json(
+            delegate_rendering.runs_json_payload(summaries, limit=limit, mode=mode),
+            stdout,
+        )
+    else:
+        delegate_rendering.render_runs_text(summaries, stdout, mode=mode)
+    return 0

delegate_agent/isolation.py

@@ -0,0 +1,316 @@
+"""Worktree isolation planning and creation helpers.
+
+This module owns effective-isolation resolution, source Git validation,
+persistent worktree creation, and prompt context injection. Worktree removal
+lives in worktree_mgmt.py.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import subprocess  # nosec B404 - isolation helpers intentionally run fixed git argv with shell=False.
+from dataclasses import dataclass
+from pathlib import Path
+
+# Re-export isolation constants from config for convenience
+from delegate_agent.config import (  # noqa: F401  # re-exported
+    ISOLATION_AUTO,
+    ISOLATION_NONE,
+    ISOLATION_WORKTREE,
+    VALID_ISOLATION_VALUES,
+    ConfigError,
+)
+from delegate_agent.constants import KNOWN_ENGINES
+from delegate_agent.git_utils import (
+    GIT_QUICK_TIMEOUT_SECONDS,
+    GIT_TIMEOUT_RETURN_CODE,
+)
+from delegate_agent.git_utils import (
+    run_git as _run_git,
+)
+from delegate_agent.json_types import JsonObject
+from delegate_agent.prompt_instructions import SKILL_REVIEW_PREFIX
+
+
+@dataclass(frozen=True)
+class IsolationContext:
+    """Resolved isolation metadata shared by dry-run output, run metadata, and launch."""
+
+    source_workspace: str
+    effective_isolation: str
+    isolation_mode: str
+    isolation_lifecycle: str
+    preserved_workspace: bool
+    planned_branch: str | None = None
+    planned_execution_cwd: str | None = None
+    source_git_root: str | None = None
+    source_git_common_dir: str | None = None
+    source_head_oid: str | None = None
+    source_head_ref: str | None = None
+    source_branch: str | None = None
+    safe_workspace_method: str | None = None
+    include_dirty: bool = False
+    warnings: tuple[str, ...] = ()
+
+
+def compute_repo_fingerprint_from_common_dir(git_common_dir: str) -> str:
+    """Return a stable 12-char hash of the resolved Git common directory path."""
+    resolved = Path(git_common_dir).resolve(strict=True).as_posix()
+    return hashlib.sha256(resolved.encode("utf-8")).hexdigest()[:12]
+
+
+def _raise_if_git_timed_out(result: subprocess.CompletedProcess[str], action: str) -> None:
+    if result.returncode == GIT_TIMEOUT_RETURN_CODE:
+        raise IsolationExecutionError("git_timeout", f"{action} timed out: {result.stderr}")
+
+
+def short_run_id(run_id: str) -> str:
+    """Return a run-id segment safe for branch and path names."""
+    s = run_id
+    if s.startswith("del_"):
+        s = s[4:]
+    s = "".join(ch if ch.isalnum() or ch in "._-" else "-" for ch in s)
+    return s[:32]
+
+
+def branch_label(engine: str, model_alias: str | None) -> str:
+    """Return the engine/model segment used in Delegate worktree branch names."""
+    if engine == "cursor":
+        return "cursor"
+    if engine == "codex":
+        return "codex"
+    if engine == "kimi":
+        return "kimi"
+    if engine == "claude":
+        return "claude"
+    if engine == "droid":
+        if not model_alias:
+            return "droid"
+        slug = model_alias.lower()
+        slug = re.sub(r"[^a-z0-9-]", "-", slug)
+        slug = re.sub(r"-+", "-", slug)
+        slug = slug.strip("-")
+        return f"droid-{slug}" if slug else "droid"
+    return engine
+
+
+def plan_branch_name(label: str, short_id: str) -> str:
+    return f"delegate/{label}-{short_id}"
+
+
+def plan_worktree_path(data_home: Path, fingerprint: str, label: str, short_id: str) -> Path:
+    return data_home / fingerprint / f"{label}-{short_id}"
+
+
+def worktrees_data_home(config: JsonObject) -> Path:
+    """Return the persistent worktree root, defaulting to ~/.delegate/worktrees."""
+    cfg = config.get("worktrees", {})
+    if not isinstance(cfg, dict):
+        return Path.home() / ".delegate" / "worktrees"
+    data_home = cfg.get("dataHome")
+    if isinstance(data_home, str) and data_home:
+        expanded = Path(data_home).expanduser()
+        if not expanded.is_absolute():
+            raise ConfigError(
+                "invalid_worktrees_config",
+                "worktrees.dataHome must be an absolute path or start with ~/.",
+            )
+        return expanded
+    return Path.home() / ".delegate" / "worktrees"
+
+
+def _map_auto_isolation(engine: str, mode: str) -> str:
+    """Preserve safe-mode isolation for local engines while leaving work mode in-place."""
+    if mode == "safe" and engine in KNOWN_ENGINES:
+        return ISOLATION_WORKTREE
+    return ISOLATION_NONE
+
+
+def _isolation_lifecycle(isolation_mode: str, mode: str) -> str:
+    if isolation_mode == ISOLATION_NONE:
+        return "none"
+    if isolation_mode == ISOLATION_WORKTREE:
+        if mode == "work":
+            return "persistent"
+        return "temporary"
+    return "none"
+
+
+def build_isolation_context(
+    source_workspace: str,
+    resolved_isolation: str,
+    *,
+    engine: str = "",
+    mode: str = "",
+    model_alias: str | None = None,
+    source_git_root: str | None = None,
+    source_git_common_dir: str | None = None,
+    source_head_oid: str | None = None,
+    source_head_ref: str | None = None,
+    source_branch: str | None = None,
+    config: JsonObject | None = None,
+    run_short_id: str | None = None,
+    include_dirty: bool = False,
+) -> IsolationContext:
+    """Resolve isolation into launch metadata and planned persistent-worktree paths."""
+    # isolation_mode preserves the raw resolved value (auto/none/worktree).
+    # effective_isolation is the mapped behavior (none/worktree, never auto).
+    isolation_mode_raw = resolved_isolation
+    if resolved_isolation == ISOLATION_AUTO:
+        effective = _map_auto_isolation(engine, mode)
+    else:
+        effective = resolved_isolation
+
+    lifecycle = _isolation_lifecycle(effective, mode)
+    preserved = lifecycle == "persistent"
+
+    # Compute named paths only for persistent worktree runs. Temporary safe-mode
+    # isolation uses an ephemeral detached worktree or directory copy, not a
+    # Delegate-managed branch under the persistent worktree data home.
+    planned_branch: str | None = None
+    planned_execution_cwd: str | None = None
+    if lifecycle == "persistent" and source_git_common_dir is not None:
+        try:
+            fp = compute_repo_fingerprint_from_common_dir(source_git_common_dir)
+        except (FileNotFoundError, OSError):
+            fp = None
+        if fp is not None:
+            short_id = run_short_id if run_short_id else "<short-run-id-placeholder>"
+            label = branch_label(engine, model_alias)
+            planned_branch = plan_branch_name(label, short_id)
+            dh = worktrees_data_home(config or {})
+            planned_execution_cwd = str(plan_worktree_path(dh, fp, label, short_id))
+
+    return IsolationContext(
+        source_workspace=source_workspace,
+        effective_isolation=effective,
+        isolation_mode=isolation_mode_raw,
+        isolation_lifecycle=lifecycle,
+        preserved_workspace=preserved,
+        planned_branch=planned_branch,
+        planned_execution_cwd=planned_execution_cwd,
+        source_git_root=source_git_root,
+        source_git_common_dir=source_git_common_dir,
+        source_head_oid=source_head_oid,
+        source_head_ref=source_head_ref,
+        source_branch=source_branch,
+        include_dirty=include_dirty,
+    )
+
+
+class IsolationExecutionError(Exception):
+    """Machine-readable isolation failure converted to DelegateError by cli.py."""
+
+    def __init__(self, error: str, message: str) -> None:
+        super().__init__(message)
+        self.error = error
+        self.message = message
+
+
+def require_valid_head(source_git_root: str) -> str:
+    """Return HEAD's OID or raise missing_git_head for an unborn repository."""
+    result = _run_git(
+        source_git_root,
+        ["rev-parse", "--verify", "HEAD"],
+        timeout_seconds=GIT_QUICK_TIMEOUT_SECONDS,
+    )
+    _raise_if_git_timed_out(result, "git rev-parse HEAD")
+    if result.returncode != 0:
+        raise IsolationExecutionError(
+            "missing_git_head",
+            "--isolation worktree requires a Git workspace with at least one commit.",
+        )
+    return result.stdout.strip()
+
+
+def require_clean_source(source_git_root: str) -> None:
+    """Require no staged, unstaged, untracked, or submodule dirtiness."""
+    result = _run_git(
+        source_git_root,
+        ["status", "--porcelain=v1", "--untracked-files=normal", "--ignore-submodules=none"],
+        timeout_seconds=GIT_QUICK_TIMEOUT_SECONDS,
+    )
+    _raise_if_git_timed_out(result, "git status")
+    if result.returncode != 0:
+        raise IsolationExecutionError(
+            "dirty_source_check_failed",
+            f"git status failed with code {result.returncode}: {result.stderr.strip()}",
+        )
+    if result.stdout.strip():
+        raise IsolationExecutionError(
+            "dirty_source_workspace",
+            (
+                "--isolation worktree for work mode requires a clean source workspace. "
+                "Commit/stash/delete local changes, run in-place with --isolation none, "
+                "or relaunch with --include-dirty to copy tracked edits and untracked "
+                "non-ignored files into the new worktree."
+            ),
+        )
+
+
+def create_persistent_worktree(
+    source_git_root: str,
+    branch: str,
+    worktree_path: str,
+    base_oid: str,
+) -> None:
+    """Create a persistent Git worktree on a new branch from base_oid."""
+    branch_probe = _run_git(
+        source_git_root,
+        ["show-ref", "--verify", "--quiet", f"refs/heads/{branch}"],
+        timeout_seconds=GIT_QUICK_TIMEOUT_SECONDS,
+    )
+    _raise_if_git_timed_out(branch_probe, "git branch availability check")
+    if branch_probe.returncode == 0:
+        raise IsolationExecutionError(
+            "branch_collision",
+            f"Branch '{branch}' already exists. This indicates registry corruption or a clock anomaly.",
+        )
+    if branch_probe.returncode != 1:
+        raise IsolationExecutionError(
+            "worktree_create_failed",
+            f"Failed to verify branch availability for '{branch}': {branch_probe.stderr.strip()}",
+        )
+    Path(worktree_path).parent.mkdir(parents=True, exist_ok=True)
+    result = _run_git(
+        source_git_root,
+        ["worktree", "add", "-b", branch, worktree_path, base_oid],
+    )
+    _raise_if_git_timed_out(result, "git worktree add")
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        raise IsolationExecutionError(
+            "worktree_create_failed",
+            f"Failed to create git worktree: {stderr}",
+        )
+
+
+# Keep this text stable; child prompts and tests rely on the exact wording.
+PERSISTENT_WORKTREE_CONTEXT_NOTE = (
+    "You are running in a Delegate-created isolated Git worktree. "
+    "Make changes in this execution workspace only. "
+    "Do not attempt to modify, merge into, or clean the source checkout. "
+    "Do not delete, rename, or `git worktree remove` this workspace; "
+    "the orchestrator manages worktree lifecycle. "
+    "Report changed files, verification, and suggested integration steps. "
+    "Your orchestrator can inspect this run via `delegate worktree show <alias>` "
+    "and retire it via `delegate worktree remove <alias>` "
+    "(refuses on dirty or unmerged), "
+    "`delegate worktree remove <alias> --force-branch` "
+    "(allow unmerged-branch deletion), "
+    "`delegate worktree remove <alias> --discard-uncommitted` "
+    "(DISCARDS uncommitted edits), "
+    "`delegate worktree remove <alias> --force` "
+    "(shorthand for both destructive overrides), "
+    "or `delegate worktree prune --merged` for bulk integrated entries."
+    "\n\n"
+)
+
+
+def prepend_persistent_worktree_context(prompt: str) -> str:
+    """Insert the worktree note after the skill prefix so the user prompt stays last."""
+    if prompt.startswith(SKILL_REVIEW_PREFIX):
+        insert_at = len(SKILL_REVIEW_PREFIX)
+        return prompt[:insert_at] + PERSISTENT_WORKTREE_CONTEXT_NOTE + prompt[insert_at:]
+    return PERSISTENT_WORKTREE_CONTEXT_NOTE + prompt

delegate_agent/json_types.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import TypeAlias
+
+JsonScalar: TypeAlias = str | int | float | bool | None
+JsonValue: TypeAlias = JsonScalar | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+
+def is_non_negative_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+
+def first_string(*values: object) -> str | None:
+    for value in values:
+        if isinstance(value, str) and value:
+            return value
+    return None

delegate_agent/log_output.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+RUN_OUTPUT_DEFAULT_MAX_CHARS = 60_000
+
+
+@dataclass(frozen=True)
+class LogOutput:
+    content: str
+    truncated: bool
+
+
+@dataclass(frozen=True)
+class CharCapResult:
+    content: str
+    char_truncated: bool
+    returned_chars: int
+    omitted_chars: int
+
+
+def cap_content_by_chars(content: str, max_chars: int) -> CharCapResult:
+    if max_chars < 1:
+        raise ValueError("max_chars must be at least 1")
+    if len(content) <= max_chars:
+        return CharCapResult(
+            content=content,
+            char_truncated=False,
+            returned_chars=len(content),
+            omitted_chars=0,
+        )
+    omitted = len(content) - max_chars
+    return CharCapResult(
+        content=content[-max_chars:],
+        char_truncated=True,
+        returned_chars=max_chars,
+        omitted_chars=omitted,
+    )
+
+
+def tail_file_output(path: Path, lines: int) -> LogOutput:
+    if lines < 1:
+        raise ValueError("tail lines must be at least 1")
+    if not path.exists():
+        return LogOutput(content="", truncated=False)
+    with path.open("rb") as handle:
+        handle.seek(0, 2)
+        end = handle.tell()
+        if end == 0:
+            return LogOutput(content="", truncated=False)
+        block = 4096
+        chunks: list[bytes] = []
+        position = end
+        newline_count = 0
+        while position > 0 and newline_count <= lines:
+            read_size = min(block, position)
+            position -= read_size
+            handle.seek(position)
+            chunk = handle.read(read_size)
+            chunks.insert(0, chunk)
+            newline_count += chunk.count(b"\n")
+        text = b"".join(chunks).decode("utf-8", errors="replace")
+    split = text.splitlines()
+    content = "\n".join(split[-lines:]) + ("\n" if split else "")
+    return LogOutput(content=content, truncated=position > 0 or len(split) > lines)
+
+
+def read_log_output(path: Path, *, tail: int | None, raw: bool) -> LogOutput:
+    if not path.exists():
+        return LogOutput(content="", truncated=False)
+    if raw:
+        return LogOutput(
+            content=path.read_text(encoding="utf-8", errors="replace"), truncated=False
+        )
+    if tail is None:
+        raise ValueError("add --tail N or --raw to read stdout/stderr log output")
+    return tail_file_output(path, tail)

delegate_agent/private_io.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import json
+import os
+import secrets
+from contextlib import suppress
+from pathlib import Path
+
+from delegate_agent.json_types import JsonObject, JsonValue
+
+PRIVATE_DIR_MODE = 0o700
+PRIVATE_FILE_MODE = 0o600
+
+
+class RegistryJsonError(ValueError):
+    """Raised when an existing registry JSON file cannot be trusted."""
+
+
+def supports_private_modes() -> bool:
+    """Return whether chmod-style private mode hardening is available."""
+    return os.name == "posix"
+
+
+def ensure_private_dir(path: Path) -> None:
+    """Create a registry directory and make it owner-only on POSIX."""
+    path.mkdir(parents=True, exist_ok=True)
+    if supports_private_modes():
+        os.chmod(path, PRIVATE_DIR_MODE)
+
+
+def ensure_private_file(path: Path) -> None:
+    """Make an existing registry file owner-read/write on POSIX."""
+    if supports_private_modes():
+        os.chmod(path, PRIVATE_FILE_MODE)
+
+
+def write_private_text(path: Path, text: str, *, encoding: str = "utf-8") -> None:
+    """Create/truncate a registry text file with owner-only permissions."""
+    ensure_private_dir(path.parent)
+    fd = os.open(path, os.O_CREAT | os.O_TRUNC | os.O_WRONLY, PRIVATE_FILE_MODE)
+    with os.fdopen(fd, "w", encoding=encoding) as handle:
+        handle.write(text)
+    ensure_private_file(path)
+
+
+def write_private_bytes(path: Path, payload: bytes) -> None:
+    """Create/truncate a registry byte file with owner-only permissions."""
+    ensure_private_dir(path.parent)
+    fd = os.open(path, os.O_CREAT | os.O_TRUNC | os.O_WRONLY, PRIVATE_FILE_MODE)
+    with os.fdopen(fd, "wb") as handle:
+        handle.write(payload)
+    ensure_private_file(path)
+
+
+def write_text_atomic(path: Path, text: str, *, encoding: str = "utf-8") -> None:
+    """Atomically replace a non-private text file while preserving existing mode."""
+    temp = path.with_name(f".{path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp")
+    existing_mode: int | None = None
+    try:
+        existing_mode = path.stat().st_mode & 0o777
+    except OSError:
+        existing_mode = None
+    fd = os.open(temp, os.O_CREAT | os.O_TRUNC | os.O_WRONLY, existing_mode or 0o666)
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as handle:
+            handle.write(text)
+        if existing_mode is not None:
+            os.chmod(temp, existing_mode)
+        os.replace(temp, path)
+    except OSError:
+        with suppress(OSError):
+            os.unlink(temp)
+        raise
+
+
+def write_json_atomic(path: Path, payload: JsonObject) -> None:
+    temp = path.with_name(f".{path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp")
+    try:
+        write_private_text(
+            temp,
+            json.dumps(payload, indent=2, sort_keys=True) + "\n",
+        )
+        os.replace(temp, path)
+        ensure_private_file(path)
+    except OSError:
+        with suppress(OSError):
+            os.unlink(temp)
+        raise
+
+
+def read_json_object(path: Path) -> JsonObject | None:
+    if not path.exists():
+        return None
+    try:
+        data: JsonValue = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RegistryJsonError(f"invalid JSON in {path}: {exc}") from exc
+    except OSError as exc:
+        raise RegistryJsonError(f"could not read JSON file {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise RegistryJsonError(f"{path} root must be a JSON object")
+    return data
+
+
+def read_json_object_or_none(path: Path) -> JsonObject | None:
+    try:
+        return read_json_object(path)
+    except RegistryJsonError:
+        return None

delegate_agent/profile_commands.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TextIO
+
+from delegate_agent import redaction, rendering
+from delegate_agent.json_types import JsonObject
+from delegate_agent.profiles import ProfileResolution
+
+
+@dataclass(frozen=True)
+class ProfilesCommand:
+    json_mode: bool = False
+
+
+def emit(
+    command: ProfilesCommand,
+    *,
+    resolution: ProfileResolution,
+    config_source: str,
+    stdout: TextIO,
+) -> int:
+    env = redaction.redact_env_map(resolution.env)
+    payload: JsonObject = {
+        "ok": True,
+        "profile": resolution.name,
+        "source": resolution.source,
+        "envKeys": sorted(env),
+        "env": env,
+        "warnings": list(resolution.warnings),
+        "configSource": config_source,
+    }
+    if command.json_mode:
+        rendering.print_json(payload, stdout)
+    else:
+        print(f"profile: {resolution.name or '(none)'}", file=stdout)
+        print(f"source: {resolution.source or '(none)'}", file=stdout)
+        keys = ", ".join(payload["envKeys"]) if payload["envKeys"] else "(none)"
+        print(f"envKeys: {keys}", file=stdout)
+        for warning in resolution.warnings:
+            print(f"warning: {warning}", file=stdout)
+    return 0