skharness 0.3.0__tar.gz

skharness-0.3.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include docker/sandbox *
+include README.md

skharness-0.3.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: skharness
+Version: 0.3.0
+Summary: Sovereign phone-drives-my-agent-swarm harness (execution: sessions + autocode engine)
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"

skharness-0.3.0/README.md

@@ -0,0 +1,73 @@
+# skharness
+
+**Sovereign "phone-drives-my-agent-swarm" harness.**
+
+Run many coding/work agents, each in an **isolated session**, and **drive them from a phone
+over the tailnet** — the feel of Claude Code's remote control, but **self-hosted on SKWorld
+infra with no Big-Tech broker**.
+
+## Why
+Claude Code Remote Control has great UX but routes phone↔laptop through Anthropic's relay —
+it fails the sovereignty test. skharness replicates the *experience*, not the foundation, over
+**Tailscale + capauth**. (Design basis: the 2026-06-13 harness deep-research — pi / cmux /
+OpenCode / web-shells / Claude Code Remote Control. Full spec in
+`docs/superpowers/specs/2026-06-13-skharness-design.md`.)
+
+## Architecture
+A capauth-gated FastAPI over a `SessionManager`:
+
+| Module | Role |
+|---|---|
+| `gateway.py` | FastAPI app; **bind to a Tailscale IP only** (never a public port). `verify_caller` is the auth seam — a real capauth verifier in prod, a fake in tests. |
+| `manager.py` | `SessionManager` — ties registry + spawner; spawn creates an isolated worker. |
+| `spawner.py` | Spawner seam — `FakeSpawner` for CI, `TmuxSpawner` for real sessions. |
+| `registry.py` | `SessionRegistry` — track/persist sessions (JSON now; coord-board / skmem-pg later). |
+| `session.py` | `Session` model — one isolated agent worker. |
+
+Mostly **reuse**: `pi` (MIT, multi-provider incl. local qwen) as orchestrator + the coord
+board / skmem-pg as the session/task registry.
+
+## Run
+```bash
+pip install -e .            # fastapi + pydantic
+# build_app(manager=..., verify_caller=<capauth verifier>) -> FastAPI
+# serve bound to the tailscale IP only; auth every call via capauth.
+```
+
+## Status
+`v0.1.0`, P0 session core (spec + plan under `docs/superpowers/`). Mirror: smilinTux (private).
+
+## skcode-hostd (P0, read-only)
+
+`skcode-hostd` is the read-only remote-control daemon over the unified Harness
+session plane. It owns ONE harness (the claude-code tmux adapter) and exposes
+exactly three capauth-gated data routes plus a self-contained static client. There
+is NO write surface: no spawn, inject, kill, dispatch, rename, archive, or model
+switch. A test (`tests/test_daemon.py::test_no_write_surface`) proves POST/DELETE
+return 405 and `/inject` / `/dispatch` return 404.
+
+Routes:
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/v1/hosts/self` | host + harness identity |
+| GET | `/api/v1/sessions` | list live + historical sessions |
+| GET | `/api/v1/sessions/{sid}` | one session, or 404 |
+| WS | `/api/v1/sessions/{sid}/stream` | typed `SessionEvent` stream (`?token=`) |
+| GET | `/` and `/app` | the static read-only web client |
+
+HTTP routes require a `Bearer` token; the WebSocket takes the token as a
+`?token=` query param (browsers cannot set headers on a WS). The capauth verifier
+in P0 is a fail-closed deny-all placeholder: real verification lands with the
+pairing work (spec 7.6), so the daemon rejects every token until then by design.
+
+Run (Tailscale IP only, never `0.0.0.0`):
+
+```bash
+~/.skenv/bin/python -m skharness --host <your-tailscale-ip> --port 9394 --host-id .158
+```
+
+skcode-hostd defaults to `:9394` (SKWorld platform spec R0.4). Port `:9390` is
+owned by `skcomms.transports.broker_server` (its honest, documented default), so
+the two no longer collide on a shared host. Override with `--port <free>` and
+record it in `~/.skcapstone/docs/PORTS.md` if `:9394` is taken.

skharness-0.3.0/docker/sandbox/build.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Build the SKOS Autopilot sandbox images: the egress proxy sidecar plus one image
+# per harness (claude-code, pi, opencode). Each image is the confined execution
+# environment a harness runs inside (see docs/skos-autopilot-architecture.md §12
+# and docs/skos-autopilot-SOP.md §13). Images are tagged locally so a node can run
+# confined live execution offline; a node missing them fails closed (no unconfined
+# run is ever attempted).
+#
+# Usage:
+#   docker/sandbox/build.sh                 # build all four images
+#   docker/sandbox/build.sh proxy           # build a single image (proxy|claude|pi|opencode)
+#   docker/sandbox/build.sh pi opencode     # build a subset
+#   docker/sandbox/build.sh --no-cache      # force a clean rebuild of all four
+#   docker/sandbox/build.sh -h | --help
+#
+# All four build with plain `docker build` from the repo root (the proxy image
+# COPYs src/skos/autopilot/sandbox_proxy.py). No `--network host` or registry
+# egress is needed: opencode bundles its openai-compatible provider, pi and claude
+# install their CLIs at build time. Next step after a build is the confinement
+# proof: RUN_SANDBOX_IT=1 python -m pytest tests/test_sandbox_confinement_it.py
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."          # repo root (build context)
+D=docker/sandbox
+TAG=1                                # image tag: sandbox-<name>:$TAG
+
+# each entry: <name> <dockerfile-subdir> <in-image verify command | ->
+#   the verify command runs in the freshly built image and prints the baked CLI
+#   version, proving the harness binary is actually present (- = no CLI to check)
+HARNESSES=(
+  "proxy    proxy     -"
+  "claude   claude    claude --version"
+  "pi       pi        pi --version"
+  "opencode opencode  opencode --version"
+)
+
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+
+BUILD_ARGS=()
+WANT=()
+for a in "$@"; do
+  case "$a" in
+    -h|--help) usage 0 ;;
+    --no-cache|--pull) BUILD_ARGS+=("$a") ;;
+    proxy|claude|pi|opencode) WANT+=("$a") ;;
+    *) echo "unknown arg: $a" >&2; usage 1 ;;
+  esac
+done
+
+wanted() {                          # is $1 in the requested set (empty set = all)?
+  [ ${#WANT[@]} -eq 0 ] && return 0
+  local w; for w in "${WANT[@]}"; do [ "$w" = "$1" ] && return 0; done
+  return 1
+}
+
+command -v docker >/dev/null 2>&1 || { echo "docker not found on PATH" >&2; exit 127; }
+
+declare -A RESULT
+for row in "${HARNESSES[@]}"; do
+  read -r name dir verify <<<"$row"
+  wanted "$name" || continue
+  img="sandbox-${name}:${TAG}"
+  echo "== building ${img} =="
+  if docker build "${BUILD_ARGS[@]}" -f "$D/$dir/Dockerfile" -t "$img" .; then
+    RESULT[$name]=ok
+    if [ "$verify" != "-" ]; then
+      ver="$(docker run --rm "$img" sh -c "$verify" 2>/dev/null | head -1 || true)"
+      echo "   ${name} CLI: ${ver:-<version check failed>}"
+    fi
+  else
+    RESULT[$name]=FAIL
+    echo "   ${img} build FAILED" >&2
+  fi
+done
+
+echo "== images =="
+docker image ls --format '{{.Repository}}:{{.Tag}}  {{.Size}}' \
+  | grep -E 'sandbox-(proxy|claude|pi|opencode):'"$TAG" || true
+
+echo "== result =="
+fail=0
+for row in "${HARNESSES[@]}"; do
+  read -r name _ _ <<<"$row"
+  wanted "$name" || continue
+  r="${RESULT[$name]:-skipped}"
+  printf '   %-9s %s\n' "$name" "$r"
+  [ "$r" = "FAIL" ] && fail=1
+done
+
+if [ "$fail" -eq 0 ]; then
+  echo "== all requested images built. next: confinement proof =="
+  echo "   RUN_SANDBOX_IT=1 python -m pytest tests/test_sandbox_confinement_it.py -q"
+fi
+exit "$fail"

skharness-0.3.0/docker/sandbox/claude/Dockerfile

@@ -0,0 +1,20 @@
+# Sandbox image carrying the Claude Code CLI + git + a python test toolchain.
+# The confined harness runs as non-root user `sbx` in /work (the bind-mounted
+# task worktree). No secrets are baked in; auth is bind-mounted read-only at run.
+FROM node:24-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates python3 python3-pip python3-venv curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# pinned harness CLI
+RUN npm install -g @anthropic-ai/claude-code
+
+# repo test toolchain (bookworm python3 is 3.11; adequate for running repo tests
+# inside the sandbox; the confinement proof does not depend on the minor version)
+RUN pip3 install --no-cache-dir --break-system-packages pytest coverage \
+    || pip3 install --no-cache-dir pytest coverage
+
+RUN useradd -u 10001 -m sbx
+WORKDIR /work
+USER sbx

skharness-0.3.0/docker/sandbox/opencode/Dockerfile

@@ -0,0 +1,29 @@
+# Sandbox image carrying the opencode (opencode.ai) CLI + git + python toolchain.
+# Installed sovereign fallback; can target a local model. Confirm the npm package
+# name against opencode.ai; a real `opencode run` output-shape validation is the
+# remaining pre-live step (OpenCodeAdapter._parse is defensive and flagged).
+FROM node:24-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates python3 python3-pip python3-venv curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# harness CLI: the official installer drops a self-contained binary; copy it onto
+# PATH so any uid can run it.
+RUN curl -fsSL https://opencode.ai/install | bash \
+    && cp /root/.opencode/bin/opencode /usr/local/bin/opencode \
+    && chmod 0755 /usr/local/bin/opencode
+
+RUN pip3 install --no-cache-dir --break-system-packages pytest coverage \
+    || pip3 install --no-cache-dir pytest coverage
+
+RUN useradd -u 10001 -m sbx
+WORKDIR /work
+USER sbx
+
+# NO provider pre-fetch is needed. opencode's self-contained binary already BUNDLES
+# the @ai-sdk/openai-compatible provider, so a custom `"npm": "@ai-sdk/openai-compatible"`
+# provider (the injected skgw route to skgateway) resolves against the bundled copy
+# with zero runtime download. Verified: a confined run of this image against
+# skgateway/ornith-tiny returns a correct reply and leaves no @ai-sdk/* on disk
+# anywhere. The confined sandbox therefore needs no npm egress for opencode.

skharness-0.3.0/docker/sandbox/pi/Dockerfile

@@ -0,0 +1,21 @@
+# Sandbox image carrying the pi (pi.dev) CLI + git + python test toolchain.
+# pi is the sovereign target harness: it routes to a local model via skgateway (the
+# skgw provider is injected as /agent/models.json + PI_CODING_AGENT_DIR=/agent by
+# PiAdapter), so all egress stays on-tailnet through the sandbox allowlist proxy.
+# Verified live end-to-end in the confined sandbox against skgateway/ornith-tiny.
+FROM node:24-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates python3 python3-pip python3-venv curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# pinned harness CLI (pi.dev). --ignore-scripts: pi's postinstall is not needed and
+# would pull extra host-specific artifacts; the CLI runs fine without it.
+RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+
+RUN pip3 install --no-cache-dir --break-system-packages pytest coverage \
+    || pip3 install --no-cache-dir pytest coverage
+
+RUN useradd -u 10001 -m sbx
+WORKDIR /work
+USER sbx

skharness-0.3.0/docker/sandbox/proxy/Dockerfile

@@ -0,0 +1,13 @@
+# Sovereign egress allowlist proxy sidecar for the autopilot sandbox.
+# Runs `python -m skharness.autocode.sandbox_proxy <port> <hosts...>` (invoked by
+# Sandbox.spawn). Only the single stdlib-only proxy module is present; a minimal
+# package tree makes the -m import resolve without pulling the skharness deps.
+FROM python:3.12-slim
+
+RUN mkdir -p /app/skharness/autocode \
+    && touch /app/skharness/__init__.py /app/skharness/autocode/__init__.py
+COPY src/skharness/autocode/sandbox_proxy.py /app/skharness/autocode/sandbox_proxy.py
+ENV PYTHONPATH=/app
+WORKDIR /app
+# Command is supplied by Sandbox.spawn:
+#   python -m skharness.autocode.sandbox_proxy <port> <allow-host> <allow-host> ...

skharness-0.3.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skharness"
+version = "0.3.0"
+description = "Sovereign phone-drives-my-agent-swarm harness (execution: sessions + autocode engine)"
+requires-python = ">=3.10"
+dependencies = ["fastapi>=0.110", "pydantic>=2.0", "pyyaml>=6.0", "uvicorn>=0.27", "websockets>=12.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-mock>=3.10", "pytest-asyncio>=0.23", "httpx>=0.27"]
+
+[project.scripts]
+# The skcode-hostd binary Atlas's skcode adapter shells (operator explain|observe|
+# act) and the daemon runner (--host <tailnet-ip>) share one entry point.
+skcode-hostd = "skharness.serve:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# docker/sandbox build contexts live at the repo root (not importable package
+# data); they are shipped in sdists via MANIFEST.in. The autocode engine and its
+# adapters are pure-Python subpackages discovered by find above.
+[tool.setuptools.package-data]
+skharness = ["client/*.html"]
+
+[tool.ruff]
+line-length = 99
+# Cover the whole tree: session primitives, the autocode engine, adapters, tests.
+src = ["src", "tests"]
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# The autocode engine is a byte-identical copy of the skos autopilot engine
+# (Phase A of the extraction). It must not be refactored, so the two rules the
+# verbatim copy trips under skharness's stricter config are scoped-off HERE only:
+#   I001  import-block ordering (skos ships no isort rule; the copy is untouched)
+#   N818  exception naming (UnknownDecision, kept verbatim)
+# New skharness code and the copied tests stay fully linted.
+"src/skharness/autocode/*" = ["I001", "N818"]
+"src/skharness/autocode/**/*" = ["I001", "N818"]
+# The copied autopilot tests are verbatim from skos (only the import PREFIX was
+# rewritten). skos ships no isort rule, so they carry a different import order;
+# scope I001 off for the copied test files so they stay byte-identical. The new
+# tests/test_autocode_gate_conformance.py is authored fresh and stays fully linted.
+"tests/conftest.py" = ["I001"]
+"tests/test_autopilot_*.py" = ["I001"]
+"tests/test_adapter_*.py" = ["I001"]
+"tests/test_sandbox_*.py" = ["I001"]
+"tests/test_harness_registry.py" = ["I001"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    # Autopilot orchestrator tests that exercise the optional skcapstone sibling
+    # (coordination.Board). skcapstone is not a declared skharness dependency; the
+    # tests/conftest.py hook auto-skips these when skcapstone cannot be imported.
+    "needs_skcapstone: requires the optional sibling skcapstone package (auto-skipped when absent)",
+]

skharness-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skharness-0.3.0/src/skharness/__init__.py

@@ -0,0 +1,26 @@
+"""skharness: sovereign orchestration harness. Spawn isolated agent sessions,
+drive them from a phone over the tailnet, no Big-Tech broker. P0 = the CI-testable
+session-manager core. See docs/superpowers/specs/2026-06-13-skharness-design.md.
+
+The unified two-plane Harness contract (Fable Wave 1 "contract hoist") is the
+public seam over both the autocode engine (task plane) and the skcode daemon
+(session plane); see skharness/harness.py.
+"""
+
+from skharness.harness import (
+    HARNESSES,
+    Harness,
+    HarnessCapabilities,
+    build_harness,
+    register_harness,
+    warn_missing_capabilities,
+)
+
+__all__ = [
+    "Harness",
+    "HarnessCapabilities",
+    "HARNESSES",
+    "register_harness",
+    "build_harness",
+    "warn_missing_capabilities",
+]

skharness-0.3.0/src/skharness/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m skharness --host <tailnet-ip>` starts skcode-hostd."""
+
+from skharness.serve import main
+
+if __name__ == "__main__":
+    main()

skharness-0.3.0/src/skharness/auth.py

@@ -0,0 +1,30 @@
+"""Capauth bearer gate, shared by the skharness gateway and skcode-hostd.
+
+`verify_caller` is the auth seam: a real capauth verifier in production, a fake
+in tests. Fail closed on missing or empty tokens BEFORE the verifier runs.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from fastapi import HTTPException
+
+Verifier = Callable[[str], bool]
+
+
+def require_bearer(authorization: str | None, verify_caller: Verifier) -> str:
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(401, "missing bearer token")
+    token = authorization[len("Bearer "):].strip()
+    if not token:
+        raise HTTPException(401, "missing bearer token")
+    if not verify_caller(token):
+        raise HTTPException(403, "unauthorized")
+    return token
+
+
+def check_token(token: str | None, verify_caller: Verifier) -> bool:
+    if not token or not token.strip():
+        return False
+    return bool(verify_caller(token.strip()))

skharness-0.3.0/src/skharness/autocode/__init__.py

@@ -0,0 +1,4 @@
+"""SKOS Autopilot: harness-agnostic assess/plan/swarm/grade/report over the GTD spine."""
+from .ratify import ratify
+
+__all__ = ["ratify"]

skharness-0.3.0/src/skharness/autocode/adapters/__init__.py

@@ -0,0 +1,26 @@
+from ..harness import register_harness
+from .claude_code import ClaudeCodeAdapter
+from .pi import PiAdapter
+from .opencode import OpenCodeAdapter
+from .codex import CodexStubAdapter
+
+__all__ = ["ClaudeCodeAdapter", "PiAdapter", "OpenCodeAdapter", "CodexStubAdapter"]
+
+
+def _g(config, key, default=None):
+    return getattr(config, key, default)
+
+
+register_harness("claude-code", lambda c: ClaudeCodeAdapter(
+    _g(c, "allowed_tools", []) or [], mcp_endpoints=_g(c, "mcp_endpoints"),
+    live_execution=_g(c, "live_execution", False), image=_g(c, "sandbox_image"),
+    model=_g(c, "harness_model") or "sonnet"))
+register_harness("pi", lambda c: PiAdapter(
+    model=_g(c, "harness_model"), base_url=_g(c, "harness_base_url"),
+    egress_hosts=_g(c, "mcp_endpoints") or [], live_execution=_g(c, "live_execution", False),
+    image=_g(c, "sandbox_image"), max_tokens=_g(c, "harness_max_tokens")))
+register_harness("opencode", lambda c: OpenCodeAdapter(
+    model=_g(c, "harness_model"), base_url=_g(c, "harness_base_url"),
+    egress_hosts=_g(c, "mcp_endpoints") or [], live_execution=_g(c, "live_execution", False),
+    image=_g(c, "sandbox_image"), max_tokens=_g(c, "harness_max_tokens")))
+register_harness("codex", lambda c: CodexStubAdapter())