aisc-cli 0.1.0__py3-none-any.whl

aisc/application/session.py

@@ -0,0 +1,320 @@
+"""Session application logic for Workbench Phase 0 S0.3.
+
+Implements the business logic behind ``aisc session open/list/terminate``.
+Per docs/gui-planning/05-cli-gui-contract.md §6.
+
+Key design:
+- ``open_session`` is interactive (``docker exec -it``), returns a
+  ``ProcessResult`` whose ``exit_code`` is the agent's exit code.
+- ``list_sessions`` reads in-container session metadata via ``docker exec``
+  (non-interactive, captured stdout).
+- ``terminate_session`` runs the wrapper's ``--terminate`` mode via
+  ``docker exec`` (non-interactive, captured stdout).
+
+The container-side logic (env rebuild, process group management, PID
+identity check, session record) lives in ``container/aisc-session-wrapper``.
+"""
+
+from __future__ import annotations
+
+import math
+
+import json
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from aisc.application.runtime import resolve_running_container, validate_uuid_v4
+from aisc.domain.models import (
+    CliError,
+    RuntimeErrorCode,
+    RuntimeExitCode,
+    SessionAgent,
+)
+
+
+# ---------------------------------------------------------------------------
+# Validation helpers
+# ---------------------------------------------------------------------------
+
+_SESSION_WRAPPER_PATH = "/usr/local/bin/aisc-session-wrapper"
+_SESSIONS_DIR = "/run/aisc/sessions"
+
+# Reuse the same UUID v4 pattern as runtime_id.
+_UUID_V4_RE = re.compile(
+    r'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$',
+    re.IGNORECASE,
+)
+
+
+def validate_session_id(session_id: str) -> bool:
+    """Validate that *session_id* is a strict UUID v4."""
+    return bool(_UUID_V4_RE.match(session_id))
+
+
+def validate_agent(agent: str) -> bool:
+    """Validate that *agent* is one of the four controlled values."""
+    return agent in SessionAgent.ALL
+
+
+# ---------------------------------------------------------------------------
+# Container resolution (shared with provider; implementation in application.runtime)
+# ---------------------------------------------------------------------------
+
+# Kept as a private alias so this module's callers and tests are unaffected by
+# the extraction of ``resolve_running_container`` to application.runtime.
+_resolve_running_container = resolve_running_container
+
+
+# ---------------------------------------------------------------------------
+# Session open (interactive)
+# ---------------------------------------------------------------------------
+
+def build_session_exec(
+    runtime_id: str,
+    session_id: str,
+    agent: str,
+    executor: Any,
+    registry_root: Any,
+    resume_conversation_id: Optional[str] = None,
+) -> Tuple[str, List[str], Optional[Dict[str, str]]]:
+    """Resolve + validate + construct the exec for one interactive session.
+
+    2.1.10 R2 (D-8): the shared middle of session-open — the pipe-mode
+    ``open_session`` and the serve PTY op both call this, then attach their
+    own transports (inherited-fd SDK session vs stream handle).
+
+    Returns ``(container_name, docker_argv, env)``; raises ``CliError`` on
+    validation/resolution failures (identical codes to the one-shot CLI).
+    """
+    if not validate_uuid_v4(runtime_id):
+        raise CliError(
+            message=f"Invalid runtime ID (must be UUID v4): {runtime_id}",
+            exit_code=RuntimeExitCode.INVALID_RUNTIME_ID,
+            error_code=RuntimeErrorCode.INVALID_RUNTIME_ID,
+        )
+
+    if not validate_session_id(session_id):
+        raise CliError(
+            message=f"Invalid session ID (must be UUID v4): {session_id}",
+            exit_code=RuntimeExitCode.USAGE_ERROR,
+            error_code=RuntimeErrorCode.INVALID_SESSION_ID,
+        )
+
+    if not validate_agent(agent):
+        raise CliError(
+            message=f"Invalid agent (must be one of {', '.join(SessionAgent.ALL)}): {agent}",
+            exit_code=RuntimeExitCode.USAGE_ERROR,
+            error_code=RuntimeErrorCode.INVALID_AGENT,
+        )
+
+    container_name = _resolve_running_container(runtime_id, executor, registry_root)
+
+    docker_argv = [
+        _SESSION_WRAPPER_PATH,
+        "open",
+        "--session-id", session_id,
+        "--runtime-id", runtime_id,
+        "--agent", agent,
+    ]
+
+    if resume_conversation_id is not None:
+        from aisc.application.conversation import (
+            ERROR_INVALID_AGENT as _CONV_INVALID_AGENT,
+            is_conversation_uuid,
+        )
+
+        if not is_conversation_uuid(resume_conversation_id):
+            raise CliError(
+                message=f"Invalid conversation ID: {resume_conversation_id}",
+                exit_code=2,
+                error_code="AISC_ERR_CONVERSATION_INVALID_ID",
+            )
+        if agent not in ("claude", "codex"):
+            raise CliError(
+                message=f"agent does not support --resume-id: {agent}",
+                exit_code=2,
+                error_code=_CONV_INVALID_AGENT,
+            )
+        docker_argv += ["--resume-id", resume_conversation_id]
+
+    # v2.1.7 S6: bash sessions import the tutorial `help` function from the
+    # exec environment (bash re-imports BASH_FUNC_* vars at startup; the
+    # wrapper passes its os.environ through). Nothing is written to the
+    # image, any profile, or the user's workspace (A-21766), and non-bash
+    # agents are untouched.
+    env = None
+    if agent == "bash":
+        from aisc.cli.tutorial import help_function_env
+
+        env = help_function_env()
+
+    return container_name, docker_argv, env
+
+
+def open_session(
+    runtime_id: str,
+    session_id: str,
+    agent: str,
+    executor: Any,
+    registry_root: Any,
+    resume_conversation_id: Optional[str] = None,
+) -> Any:
+    """Open an interactive agent session via ``docker exec -it``.
+
+    Per contract §6.1:
+    - Validates runtime_id, session_id (UUID v4) and agent (controlled enum).
+    - Checks runtime exists and is running.
+    - Constructs a controlled argv (no shell=True) to execute the
+      in-container ``aisc-session-wrapper``.
+    - Runs with inherited stdio (interactive TTY); the agent's exit code
+      becomes the process exit code.
+
+    Returns a ``ProcessResult`` from ``executor.run_streaming``.
+    """
+    container_name, docker_argv, env = build_session_exec(
+        runtime_id=runtime_id,
+        session_id=session_id,
+        agent=agent,
+        executor=executor,
+        registry_root=registry_root,
+        resume_conversation_id=resume_conversation_id,
+    )
+    return executor.open_interactive(container_name, docker_argv, env=env)
+
+
+# ---------------------------------------------------------------------------
+# Session list (non-interactive, captured)
+# ---------------------------------------------------------------------------
+
+def list_sessions(
+    runtime_id: str,
+    executor: Any,
+    registry_root: Any,
+) -> List[Dict[str, Any]]:
+    """List sessions for a runtime by reading in-container metadata.
+
+    Per contract §6.2: reads ``/run/aisc/sessions/*.json`` inside the
+    container via ``docker exec`` (non-interactive, captured stdout).
+    Only used for diagnostics and crash cleanup; never claims PTY
+    recoverability.
+    """
+    container_name = _resolve_running_container(runtime_id, executor, registry_root)
+
+    docker_argv = [
+        "exec", container_name,
+        _SESSION_WRAPPER_PATH,
+        "list",
+    ]
+
+    result = executor.run_captured(docker_argv, timeout=15.0)
+
+    if result.exit_code != 0:
+        raise CliError(
+            message=f"Failed to list sessions: {(result.stderr or '').strip()[:200]}",
+            exit_code=RuntimeExitCode.SESSION_FAILED,
+            error_code=RuntimeErrorCode.SESSION_FAILED,
+        )
+
+    stdout = result.stdout.strip()
+    if not stdout:
+        return []
+
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise CliError(
+            message=f"Invalid session list output: {exc}",
+            exit_code=RuntimeExitCode.SESSION_FAILED,
+            error_code=RuntimeErrorCode.SESSION_FAILED,
+        )
+
+    if not isinstance(data, list):
+        raise CliError(
+            message="Session list output is not a JSON array",
+            exit_code=RuntimeExitCode.SESSION_FAILED,
+            error_code=RuntimeErrorCode.SESSION_FAILED,
+        )
+
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Session terminate (non-interactive, captured)
+# ---------------------------------------------------------------------------
+
+def terminate_session(
+    runtime_id: str,
+    session_id: str,
+    executor: Any,
+    registry_root: Any,
+    *,
+    grace_seconds: float = 5.0,
+) -> Dict[str, Any]:
+    """Terminate a session by running the wrapper's ``--terminate`` mode.
+
+    Per contract §6.2:
+    - Sends TERM to the session process group, waits a bounded grace period,
+      then KILL if still alive.
+    - Uses PID/PGID/start-ticks identity check to avoid killing a reused PID.
+    - Idempotent: terminating an already-exited session succeeds.
+    - Returns the terminal session record.
+    """
+    if not validate_uuid_v4(runtime_id):
+        raise CliError(
+            message=f"Invalid runtime ID (must be UUID v4): {runtime_id}",
+            exit_code=RuntimeExitCode.INVALID_RUNTIME_ID,
+            error_code=RuntimeErrorCode.INVALID_RUNTIME_ID,
+        )
+
+    if not validate_session_id(session_id):
+        raise CliError(
+            message=f"Invalid session ID (must be UUID v4): {session_id}",
+            exit_code=RuntimeExitCode.USAGE_ERROR,
+            error_code=RuntimeErrorCode.INVALID_SESSION_ID,
+        )
+
+    # --grace must be finite and in 0..600; reject NaN/Infinity/out-of-range
+    # before any Docker call (05 §4.2).
+    if not isinstance(grace_seconds, (int, float)) or not math.isfinite(grace_seconds) or not 0 <= grace_seconds <= 600:
+        raise CliError(
+            message=f"Invalid --grace {grace_seconds!r}: must be a finite number in 0..600",
+            exit_code=2,
+            error_code="AISC_ERR_USAGE",
+        )
+
+    container_name = _resolve_running_container(runtime_id, executor, registry_root)
+
+    docker_argv = [
+        "exec", container_name,
+        _SESSION_WRAPPER_PATH,
+        "terminate",
+        "--session-id", session_id,
+        "--runtime-id", runtime_id,
+        "--grace", str(grace_seconds),
+    ]
+
+    # Outer transport budget is grace + 1s (05 §4.2): keeps the Workbench
+    # --grace 3 path inside its 5s command budget while leaving TERM->KILL
+    # grace untouched.
+    result = executor.run_captured(docker_argv, timeout=grace_seconds + 1.0)
+
+    if result.exit_code != 0:
+        raise CliError(
+            message=f"Failed to terminate session: {(result.stderr or '').strip()[:200]}",
+            exit_code=RuntimeExitCode.SESSION_FAILED,
+            error_code=RuntimeErrorCode.SESSION_FAILED,
+        )
+
+    stdout = result.stdout.strip()
+    if not stdout:
+        # Wrapper may return empty on success (already exited, record cleaned).
+        return {"session_id": session_id, "state": "exited", "exit_code": None}
+
+    try:
+        data = json.loads(stdout)
+        if isinstance(data, dict):
+            return data
+    except json.JSONDecodeError:
+        pass
+
+    return {"session_id": session_id, "state": "exited", "exit_code": None}

aisc/application/tool_versions.py

@@ -0,0 +1,210 @@
+"""Tool pin resolution + user-layer overlay (0.1.0 A5, D-9/D-27).
+
+Two-layer truth for the container tool versions:
+
+- FACTORY layer: ``config/versions.env`` inside the resolved root (repo
+  checkout / installed aisc-bundle / pip ``bundles/<ver>/``). Read-only —
+  it is part of the shipped bundle and every update path replaces it.
+- USER layer: ``<data-root>/config/versions.env`` — the ONE place
+  ``aisc update --pin-tool`` writes. Survives CLI updates, NSIS upgrades
+  and bundle fetches by construction (none of them touch the data root's
+  config/). ``AISC_DATA_ROOT`` knob applies via ``shared_root()``.
+
+Resolution: factory values as the base, user layer overrides KEY-WISE
+(only keys the user bumped). The r4 incident (pins silently downgraded by
+a bundle refresh) is structurally impossible under this split.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple
+
+#: Keys a user may pin (claude/codex are npm-driven; cc-switch's resolver
+#: pin is the manual-fallback value only; NODE_IMAGE stays factory — the CN
+#: mirror chain pairs with it and a bare image override would desync them).
+PINNABLE_TOOL_KEYS = ("CLAUDE_CODE_VERSION", "CODEX_VERSION", "CC_SWITCH_VERSION")
+
+
+def _parse_env_file(path: Path) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    if not path.is_file():
+        return out
+    for line in path.read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        if "=" not in s:
+            continue
+        k, v = s.split("=", 1)
+        v = v.split("#", 1)[0].strip()  # strip trailing comments
+        if k.strip() and v:
+            out[k.strip()] = v
+    return out
+
+
+def user_pin_path(data_root: Path) -> Path:
+    return data_root / "config" / "versions.env"
+
+
+def effective_tool_versions(
+    root: Path,
+    data_root: Optional[Path] = None,
+) -> Dict[str, Tuple[str, str]]:
+    """Resolve each factory key with its source: key -> (value, source).
+
+    source is ``"user"`` (user-layer override won) or ``"default"``
+    (factory value). Only keys present in the FACTORY file participate —
+    the user layer cannot invent keys the image build never reads.
+    """
+    factory = _parse_env_file(root / "config" / "versions.env")
+    user: Dict[str, str] = {}
+    if data_root is None:
+        try:
+            from aisc.application.data_root import shared_root
+
+            data_root = shared_root()
+        except Exception:
+            data_root = None
+    if data_root is not None:
+        user = _parse_env_file(user_pin_path(data_root))
+    out: Dict[str, Tuple[str, str]] = {}
+    for key, value in factory.items():
+        if key in user:
+            out[key] = (user[key], "user")
+        else:
+            out[key] = (value, "default")
+    return out
+
+
+def write_user_pins(
+    data_root: Path,
+    pins: Dict[str, str],
+) -> Path:
+    """Merge *pins* into the user-layer versions.env (comment-preserving,
+    atomic tmp+rename). Returns the written path. Validates keys against
+    PINNABLE_TOOL_KEYS (raises ValueError listing the offenders)."""
+    unknown = sorted(k for k in pins if k not in PINNABLE_TOOL_KEYS)
+    if unknown:
+        raise ValueError(
+            f"not pinnable: {', '.join(unknown)} "
+            f"(pinnable: {', '.join(PINNABLE_TOOL_KEYS)})")
+    path = user_pin_path(data_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    lines: List[str] = []
+    if path.is_file():
+        lines = path.read_text(encoding="utf-8").splitlines()
+    # Update in place when the key exists on its own line; collect misses.
+    seen = set()
+    updated: List[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#") and "=" in stripped:
+            k = stripped.split("=", 1)[0].strip()
+            if k in pins:
+                updated.append(f"{k}={pins[k]}")
+                seen.add(k)
+                continue
+        updated.append(line)
+    header_needed = not updated or updated[0].strip() != "# AISC user tool pins (aisc update --pin-tool; overrides the bundle's factory defaults)"
+    if header_needed and not any("AISC user tool pins" in l for l in updated):
+        updated.insert(0, "# AISC user tool pins (aisc update --pin-tool; overrides the bundle's factory defaults)")
+    for k, v in pins.items():
+        if k not in seen:
+            updated.append(f"{k}={v}")
+    fd, tmp_name = tempfile.mkstemp(dir=str(path.parent), prefix=".versions-", suffix=".env")
+    os.close(fd)
+    tmp = Path(tmp_name)
+    try:
+        tmp.write_text("\n".join(updated) + "\n", encoding="utf-8", newline="")
+        os.replace(tmp, path)
+    finally:
+        if tmp.exists():
+            tmp.unlink()
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Latest-available lookups (network-tolerant; injectable for tests)
+# ---------------------------------------------------------------------------
+
+NPM_MIRROR = "https://registry.npmmirror.com"
+NPM_PACKAGES = {
+    "CLAUDE_CODE_VERSION": "@anthropic-ai/claude-code",
+    "CODEX_VERSION": "@openai/codex",
+}
+
+
+def _npm_latest(pkg: str, opener: Callable[[str], dict]) -> Optional[dict]:
+    """One registry metadata read via *opener*(url) -> parsed json dict."""
+    try:
+        d = opener(f"{NPM_MIRROR}/{pkg}")
+    except Exception:
+        return None
+    if not isinstance(d, dict):
+        return None
+    latest = d.get("dist-tags", {}).get("latest")
+    if not latest:
+        return None
+    engines = (d.get("versions", {}) or {}).get(latest, {}).get("engines") or {}
+    return {"latest": latest, "node": engines.get("node") or ""}
+
+
+def default_opener(url: str) -> dict:
+    import json
+    import urllib.request
+
+    req = urllib.request.Request(url, headers={"User-Agent": "aisc-update-check"})
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def tools_check_section(
+    root: Path,
+    data_root: Optional[Path] = None,
+    opener: Callable[[str], dict] = default_opener,
+) -> List[dict]:
+    """The `--check` tools block: effective pin (value + source) and the
+    latest available version per tool. Registry failures degrade to
+    ``latest: null`` — a check must never fail because the network did."""
+    eff = effective_tool_versions(root, data_root)
+    out: List[dict] = []
+    for key, pkg in NPM_PACKAGES.items():
+        value, source = eff.get(key, ("latest", "default"))
+        info = _npm_latest(pkg, opener)
+        out.append({
+            "tool": key,
+            "current": value,
+            "source": source,
+            "latest": info["latest"] if info else None,
+            "node_requirement": info["node"] if info else None,
+        })
+    cc_value, cc_source = eff.get("CC_SWITCH_VERSION", ("latest", "default"))
+    cc_latest = _cached_cc_switch_latest()
+    out.append({
+        "tool": "CC_SWITCH_VERSION",
+        "current": cc_value,
+        "source": cc_source,
+        "latest": cc_latest,
+        "node_requirement": "",
+    })
+    return out
+
+
+def _cached_cc_switch_latest() -> Optional[str]:
+    """Latest stable cc-switch from the resolver cache (offline-tolerant;
+    a cache-less machine reports null — the build-time resolver remains
+    the authoritative live source)."""
+    try:
+        import json
+
+        from aisc.application.data_root import shared_root
+
+        f = shared_root() / "cache" / "cc-switch" / "last-resolved.json"
+        d = json.loads(f.read_text(encoding="utf-8"))
+        return str(d.get("version") or "") or None
+    except Exception:
+        return None

aisc/application/toolchain.py

@@ -0,0 +1,91 @@
+"""Persistent toolchain host-side lifecycle (runtime-lifecycle-ux 3a).
+
+prepare/mount/metadata for the project-scope persistent toolchain
+(host_bind backend, per the Windows spike decision). The toolchain root is
+the frozen data-root layout's sibling of the runtime state dir:
+
+    <data-root>/workspaces/<hash>/toolchain/{bin,npm-global,python,cargo,cache}
+
+The environment baseline marker is seeded host-side once (never
+overwritten — the entrypoint merges container-side facts); a mismatch
+writes a warning file that runtime inspect surfaces as a NON-blocking
+warning (D-RUNTIME-11: no manifest, no gate).
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from aisc.domain.toolchain import (
+    ENVIRONMENT_MARKER,
+    TOOLCHAIN_SUBDIRS,
+    TOOLCHAIN_WARNING_FILE,
+    base_environment_marker,
+    toolchain_bind_argv,
+)
+
+import aisc
+
+
+def toolchain_dir_for(workspace_dir: Path) -> Path:
+    """Toolchain root for a resolved data-root workspace dir
+    (``workspaces/<hash>/toolchain`` — sibling of the state subdirs)."""
+    return workspace_dir / "toolchain"
+
+
+def prepare_toolchain(
+    workspace_dir: Path,
+    *,
+    image_id: str = "",
+) -> Path:
+    """Idempotently create the toolchain skeleton + seed the environment
+    marker (only when absent — never overwrite an existing baseline)."""
+    root = toolchain_dir_for(workspace_dir)
+    root.mkdir(parents=True, exist_ok=True)
+    for sub in TOOLCHAIN_SUBDIRS:
+        (root / sub).mkdir(parents=True, exist_ok=True)
+    marker = root / ENVIRONMENT_MARKER
+    if not marker.exists():
+        version = getattr(aisc, "__version__", "") or "dev"
+        payload = base_environment_marker(
+            source_version=version,
+            image_id=image_id,
+            written_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        )
+        tmp = marker.with_name(marker.name + ".tmp")
+        tmp.write_text(
+            __import__("json").dumps(payload, indent=2) + "\n", encoding="utf-8"
+        )
+        tmp.replace(marker)
+    return root
+
+
+def toolchain_mount_argv(workspace_dir: Path) -> List[str]:
+    """-v argv for the persistent toolchain mount (host_bind)."""
+    return toolchain_bind_argv(str(toolchain_dir_for(workspace_dir)).replace("\\", "/"))
+
+
+def toolchain_health(workspace_dir: Path) -> Dict[str, Any]:
+    """Inspect-time toolchain summary (02 §8.4 shape, host_bind view).
+
+    ``compatibility`` is ``warning`` when the entrypoint wrote the mismatch
+    file, ``unknown`` when no marker exists, else ``compatible``. Never a
+    block; no secrets (paths/ids only).
+    """
+    root = toolchain_dir_for(workspace_dir)
+    marker = root / ENVIRONMENT_MARKER
+    warning = root / TOOLCHAIN_WARNING_FILE
+    if warning.exists():
+        compatibility = "warning"
+    elif marker.exists():
+        compatibility = "compatible"
+    else:
+        compatibility = "unknown"
+    return {
+        "mounted": root.exists(),
+        "storage": "host_bind",
+        "path": str(root),
+        "compatibility": compatibility,
+    }