vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/runtime/options.py

@@ -0,0 +1,159 @@
+"""A service-free read of the root-option prefix, before Click parses anything.
+
+`--format` and `--debug` decide how a *parse failure* is rendered, and Click's own syntax
+errors leave through the same ErrorHandler boundary as everything else. So the root prefix is
+scanned once here, cheaply, and the resulting policy is settled before Click runs. Click
+remains the authoritative parser; this scan never renders and never decides an invocation.
+
+Scanning only the prefix is the point: the scan stops at the first positional token, so no
+command name or argument value can be mistaken for a root option. When syntax turns invalid
+after a valid machine-output prefix, that output policy is kept for Click's structured error.
+
+An unpassed option stays `None` rather than taking a default here. These values are the
+top layer of configuration precedence, and a default invented at the parser would outrank
+the profile the user actually stored.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import cast
+
+from ..output.formats import ColorMode, OutputFormat
+
+
+@dataclass(frozen=True)
+class RootOptionValues:
+    """Typed root values, from either this scanner or Click's keyword callback."""
+
+    output_format: str | None
+    as_json: bool
+    profile: str | None
+    no_input: bool
+    color: str | None
+    debug: bool
+
+    @classmethod
+    def from_click(cls, values: Mapping[str, object]) -> RootOptionValues:
+        # Click validates primitive types before this typed reconstruction.
+        return cls(
+            output_format=cast(str | None, values["output_format"]),
+            as_json=cast(bool, values["as_json"]),
+            profile=cast(str | None, values["profile"]),
+            no_input=cast(bool, values["no_input"]),
+            color=cast(str | None, values["color"]),
+            debug=cast(bool, values["debug"]),
+        )
+
+
+@dataclass(frozen=True)
+class RootInspection:
+    """Validated root policy, and whether the invocation exits before any command runs."""
+
+    values: RootOptionValues
+    exits_before_command: bool = False
+
+
+class RootOptionInspector:
+    """One scan of one argv, holding its own cursor and accumulated root values."""
+
+    _FLAGS = frozenset({"--json", "--no-input", "--debug"})
+    _VALUED = frozenset({"--format", "--profile", "--color"})
+
+    def __init__(self, argv: Sequence[str]) -> None:
+        self._tokens = list(argv[1:])
+        self._index = 0
+        self._output_format: str | None = None
+        self._as_json = False
+        self._profile: str | None = None
+        self._no_input = False
+        self._color: str | None = None
+        self._debug = False
+
+    def inspect(self) -> RootInspection | None:
+        # Root flags precede the command, so the first positional token ends the prefix.
+        exits_before_command = False
+        while self._index < len(self._tokens):
+            token = self._tokens[self._index]
+            if token == "--":
+                self._index += 1
+                break
+            if not token.startswith("-"):
+                break
+            name, separator, inline_value = token.partition("=")
+            if name in {"--help", "--version"}:
+                exits_before_command = True
+                break
+            if not self._consume(name, separator, inline_value):
+                return self._invalid()
+            self._index += 1
+        if not self._valid():
+            return None
+        return RootInspection(self._freeze(), exits_before_command)
+
+    def _consume(self, name: str, separator: str, inline_value: str) -> bool:
+        # False means "this is not a root option Click would accept" — never a guess.
+        if name in self._FLAGS:
+            # Click rejects `--flag=value` for boolean flags, so this scanner must too.
+            if separator:
+                return False
+            self._apply_flag(name)
+            return True
+        if name not in self._VALUED:
+            return False
+        value = self._read_value(separator, inline_value)
+        if value is None:
+            return False
+        self._apply_value(name, value)
+        return True
+
+    def _read_value(self, separator: str, inline_value: str) -> str | None:
+        # Both Click spellings are accepted: `--name=value` and `--name value`.
+        if separator:
+            return inline_value
+        if self._index + 1 >= len(self._tokens):
+            return None
+        self._index += 1
+        return self._tokens[self._index]
+
+    def _apply_flag(self, name: str) -> None:
+        if name == "--json":
+            self._as_json = True
+        elif name == "--no-input":
+            self._no_input = True
+        else:
+            self._debug = True
+
+    def _apply_value(self, name: str, value: str) -> None:
+        # Normalize choice values exactly as Click's case-insensitive choices do.
+        if name == "--format":
+            self._output_format = value.lower()
+        elif name == "--profile":
+            self._profile = value
+        else:
+            self._color = value.lower()
+
+    def _valid(self) -> bool:
+        # An invalid choice value stays service-free and is later explained by Click.
+        valid_formats = {None, *(item.value for item in OutputFormat)}
+        valid_colors = {None, *(item.value for item in ColorMode)}
+        return self._output_format in valid_formats and self._color in valid_colors
+
+    def _invalid(self) -> RootInspection | None:
+        # Returning the scanned policy rather than None is what keeps `--format json` in force
+        # for the machine error document Click's rejection is about to produce.
+        if not self._valid():
+            return None
+        return RootInspection(self._freeze())
+
+    def _freeze(self) -> RootOptionValues:
+        # Freeze before policy leaves the parser boundary.
+        return RootOptionValues(
+            self._output_format,
+            self._as_json,
+            self._profile,
+            self._no_input,
+            self._color,
+            self._debug,
+        )

vidbyte_cli/lib/runtime/version.py

@@ -0,0 +1,30 @@
+"""One source for the CLI's version: the installed distribution's own metadata.
+
+pyproject.toml stays the release source of truth; nothing here duplicates the release
+number. A raw source checkout has no distribution record, so it reports a dev marker rather
+than impersonating a release.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+_DISTRIBUTION_NAME = "vidbyte-cli"
+# Deliberately not "0.1.0": a source tree must not claim to be the released version.
+_SOURCE_TREE_VERSION = "0.1.0.dev0"
+
+
+class VersionProvider:
+    """Resolves the version of the installed distribution."""
+
+    def current(self) -> str:
+        # Editable/source execution has no metadata; fall back rather than raise.
+        try:
+            return version(_DISTRIBUTION_NAME)
+        except PackageNotFoundError:
+            return _SOURCE_TREE_VERSION
+
+
+def current_version() -> str:
+    # Keeps callers independent of importlib.metadata and the distribution name.
+    return VersionProvider().current()

vidbyte_cli/lib/runtime_primitives/__init__.py

@@ -0,0 +1,28 @@
+"""Local planning boundaries for runtime primitives.
+
+Exports discovery, planning, admission verification, and the guarded executor.
+Each primitive's own algorithm lives in `services/`; only what all of them share is here.
+"""
+
+from .executor import RuntimeExecutor
+from .gate import RuntimeAdmissionGate
+from .hosts import RuntimeHostRegistry
+from .planner import RuntimeLaunchPlanner
+from .stages import StagesCodexSession
+from .task_board import TaskBoardCodexSession, TaskBoardSummarizer
+from .task_board_checkpoints import TaskBoardCheckpointer
+from .task_board_tasks import TaskBoardTaskFiles
+from .verification import RuntimeGrantVerifier
+
+__all__ = [
+    "RuntimeAdmissionGate",
+    "RuntimeExecutor",
+    "RuntimeGrantVerifier",
+    "RuntimeHostRegistry",
+    "RuntimeLaunchPlanner",
+    "StagesCodexSession",
+    "TaskBoardCheckpointer",
+    "TaskBoardCodexSession",
+    "TaskBoardSummarizer",
+    "TaskBoardTaskFiles",
+]

vidbyte_cli/lib/runtime_primitives/executor.py

@@ -0,0 +1,54 @@
+"""Execution boundary for admitted local runtime primitives, and the one verdict policy.
+
+Task-board and stages have implementations; adversarial-team retains its explicit scaffold.
+Every process-launching path requires a matching deterministic admission verdict, which
+`require_verdict` is the single source of. `persistence` and `same-host-ensemble` are
+deliberately absent: they run in `services/persistence/` and `services/ensemble/`, because
+a service may depend on `lib/` while nothing in `lib/` may depend on a service.
+"""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from ...types.runtime import RuntimeAdmissionVerdict as Verdict
+from ...types.runtime import RuntimeLaunchPlan as Plan
+from ...types.runtime import StagesResult as Outcome
+from ...types.runtime import StagesSettings as Tune
+from ...types.runtime import TaskBoardResult as BoardResult
+from ...types.runtime import TaskBoardSettings as BoardSettings
+from ..errors.failures import RuntimeAdmissionNotVerified, RuntimeExecutionNotImplemented
+from .stages import StagesCodexSession as StageHost
+from .task_board import TaskBoardCodexSession as BoardSession
+
+
+class RuntimeExecutor:
+    """Checks admission at the final boundary before an agent can start."""
+
+    def execute_adversarial_team(self, plan: Plan, verdict: Verdict | None = None) -> NoReturn:
+        # Keeps the existing primitive inert after validating its admission.
+        self.require_verdict(plan, verdict)
+        raise RuntimeExecutionNotImplemented()
+
+    def execute_task_board(
+        self, plan: Plan, settings: BoardSettings, host: BoardSession, proof: Verdict
+    ) -> BoardResult:
+        # Runs the ordered board only after its exact admission is verified.
+        self.require_verdict(plan, proof)
+        if plan.capability_id != "runtime.task-board@1" or plan.host.value != "codex":
+            raise RuntimeAdmissionNotVerified("task_board_plan_invalid")
+        return host.run(plan, settings, proof.admission_id)
+
+    def execute_stages(self, plan: Plan, tune: Tune, host: StageHost, proof: Verdict) -> Outcome:
+        # The stages cannot run until the one-cent stages admission is verified.
+        self.require_verdict(plan, proof)
+        if plan.capability_id != "runtime.stages@1" or plan.host.value != "codex":
+            raise RuntimeAdmissionNotVerified("stages_plan_invalid")
+        return host.run(plan, tune, proof.admission_id)
+
+    def require_verdict(self, plan: Plan, verdict: Verdict | None) -> None:
+        # Rejects absent, false, mismatched or empty receipts independently of command checks.
+        if verdict is None or not verdict.admitted:
+            raise RuntimeAdmissionNotVerified()
+        if verdict.capability_id != plan.capability_id or not verdict.admission_id.strip():
+            raise RuntimeAdmissionNotVerified()

vidbyte_cli/lib/runtime_primitives/gate.py

@@ -0,0 +1,105 @@
+"""Deterministic receipt policy shared by offline and authenticated online verification."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+
+from ...types.runtime import RuntimeAdmissionCheck as Check
+from ...types.runtime import RuntimeAdmissionGrant as Grant
+from ...types.runtime import RuntimeAdmissionVerdict as Verdict
+from ...types.runtime import RuntimeLaunchPlan as Plan
+from ..constants.runtime import AdmissionReason as Reason
+from .verification import RuntimeGrantVerifier
+
+_ALLOWED_PRICES = {
+    "runtime.review.adversarial-team@1": 25,
+    "runtime.adversarial-team@1": 25,
+    "runtime.same-host-ensemble@1": 2,
+    "runtime.persistence@1": 2,
+    "runtime.task-board@1": 2,
+    "runtime.stages@1": 1,
+}
+_MAX_TTL_SECONDS = 3600
+Key = str | None
+
+
+class RuntimeAdmissionGate:
+    """Checks local policy after a cryptographic verification boundary."""
+
+    def __init__(self, verifier: RuntimeGrantVerifier | None = None) -> None:
+        # Shares the strict payload decoder with offline verification.
+        self._verifier = verifier or RuntimeGrantVerifier()
+
+    def verify(self, plan: Plan, grant: Grant | None, now: datetime | None, key: Key) -> Verdict:
+        # Offline callers must supply a key; CLI execution uses backend verification.
+        current = now or datetime.now(UTC)
+        check = self._check_policy(plan, grant, current)
+        if check.passed and grant is not None:
+            check = self._check_signature(grant, current, key)
+        return self._verdict(plan, grant, check)
+
+    def verify_online(self, plan: Plan, grant: Grant, verified: Grant) -> Verdict:
+        # The backend confirms signature, ownership and Mongo payment evidence for either method.
+        check = self._check_policy(plan, grant, datetime.now(UTC))
+        if grant != verified:
+            check = Check(Reason.RECEIPT_MISMATCH)
+        return self._verdict(plan, grant, check)
+
+    def _check_policy(self, plan: Plan, grant: Grant | None, now: datetime) -> Check:
+        # Rejects unknown products, price drift and unbounded receipt lifetimes.
+        if grant is None:
+            return Check(Reason.MISSING)
+        if grant.capability_id != plan.capability_id:
+            return Check(Reason.CAPABILITY_MISMATCH)
+        if grant.charged_cents != _ALLOWED_PRICES.get(grant.capability_id):
+            return Check(Reason.PRICE_MISMATCH)
+        if not grant.admission_id.strip() or grant.execution_location != "local":
+            return Check(Reason.LOCATION_OR_ID_INVALID)
+        if not grant.grant_token:
+            return Check(Reason.TOKEN_MISSING)
+        return self._check_time(grant, now)
+
+    def _check_time(self, grant: Grant, now: datetime) -> Check:
+        # Both timestamps must be aware, current and bounded independently of token claims.
+        start, end = grant.admitted_at, grant.expires_at
+        if end is None or start.tzinfo is None or end.tzinfo is None or now.tzinfo is None:
+            return Check(Reason.TIME_INVALID)
+        if end <= now:
+            return Check(Reason.EXPIRED)
+        if start > now or end <= start:
+            return Check(Reason.TIME_INVALID)
+        if (end - start).total_seconds() > _MAX_TTL_SECONDS:
+            return Check(Reason.TTL_INVALID)
+        return Check(Reason.PASSED)
+
+    def _check_signature(self, grant: Grant, now: datetime, key: str | None) -> Check:
+        # A valid token must bind every public signed field to this receipt.
+        if not key or not key.strip():
+            return Check(Reason.VERIFICATION_KEY_MISSING)
+        try:
+            signed = self._verifier.verify(grant.grant_token or "", key, now)
+        except ValueError:
+            return Check(Reason.SIGNATURE_INVALID)
+        matches = (
+            signed.admission_id == grant.admission_id,
+            f"{signed.capability_id}@{signed.version}" == grant.capability_id,
+            signed.charged_cents == grant.charged_cents,
+            signed.admitted_at == grant.admitted_at,
+            signed.expires_at == grant.expires_at,
+        )
+        return Check(Reason.PASSED if all(matches) else Reason.SIGNED_CLAIMS_MISMATCH)
+
+    def _verdict(self, plan: Plan, grant: Grant | None, check: Check) -> Verdict:
+        # Exposes safe policy metadata without the token or caller identity.
+        return Verdict(
+            admitted=check.passed,
+            admission_id=grant.admission_id if grant else "rta_missing",
+            capability_id=plan.capability_id,
+            reason=None if check.passed else check.reason.value,
+        )
+
+    @staticmethod
+    def hash_idempotency_key(key: str) -> str:
+        # Binds the invocation without transmitting its raw key to verification.
+        return hashlib.sha256(key.encode("utf-8")).hexdigest()

vidbyte_cli/lib/runtime_primitives/hosts.py

@@ -0,0 +1,45 @@
+"""PATH-only discovery for supported native coding-agent executables.
+
+Discovery never invokes a host, reads its configuration, or inspects environment values.
+An explicit unavailable host is never silently replaced with a different agent.
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+
+from ...types.runtime import RuntimeHost, RuntimeHostStatus
+from ..errors.failures import RuntimeHostUnavailable
+
+_HOST_ORDER = (RuntimeHost.CODEX, RuntimeHost.CLAUDE, RuntimeHost.OPENCODE)
+
+
+class RuntimeHostRegistry:
+    """Discovers and selects the user's installed native coding-agent hosts."""
+
+    def __init__(self, which: Callable[[str], str | None] = shutil.which) -> None:
+        # Makes PATH resolution injectable while using the operating system by default.
+        self._which = which
+
+    def inspect(self) -> tuple[RuntimeHostStatus, ...]:
+        # Returns stable host order so human and machine output remain predictable.
+        return tuple(self._status(host) for host in _HOST_ORDER)
+
+    def resolve(self, requested: RuntimeHost | None) -> RuntimeHostStatus:
+        # Honors explicit selection; auto mode chooses the first available reviewed host.
+        statuses = self.inspect()
+        if requested is not None:
+            selected = next(status for status in statuses if status.host is requested)
+            if not selected.available:
+                raise RuntimeHostUnavailable(requested.value)
+            return selected
+        automatic = next((status for status in statuses if status.available), None)
+        if automatic is None:
+            raise RuntimeHostUnavailable("codex, claude, or opencode")
+        return automatic
+
+    def _status(self, host: RuntimeHost) -> RuntimeHostStatus:
+        # Records only the resolved executable path, never host configuration or credentials.
+        executable = self._which(host.value)
+        return RuntimeHostStatus(host=host, available=executable is not None, executable=executable)

vidbyte_cli/lib/runtime_primitives/planner.py

@@ -0,0 +1,79 @@
+"""Builds the local-only handoff for a future runtime executor.
+
+The plan retains task and filesystem context in process memory. Nothing here contacts the
+backend, serializes the environment, or launches an agent.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from ...types.runtime import RuntimeHost as Host
+from ...types.runtime import RuntimeLaunchPlan as Plan
+from ..constants.runtime import TaskBoardLimit
+from ..errors.failures import (
+    RuntimeHostUnavailable,
+    RuntimeTaskInvalid,
+    RuntimeWorkingDirectoryInvalid,
+)
+from .hosts import RuntimeHostRegistry
+
+Product = Literal[
+    "runtime.review.adversarial-team@1",
+    "runtime.adversarial-team@1",
+    "runtime.same-host-ensemble@1",
+    "runtime.persistence@1",
+    "runtime.task-board@1",
+    "runtime.stages@1",
+]
+
+
+class RuntimeLaunchPlanner:
+    """Validates local prerequisites and creates an inert launch plan."""
+
+    def __init__(self, hosts: RuntimeHostRegistry) -> None:
+        # Uses one registry so doctor and execution selection share host semantics.
+        self._hosts = hosts
+
+    def build(self, task: str, host: Host | None, cwd: Path, capability_id: Product) -> Plan:
+        # Validates everything needed before a future paid admission can be requested.
+        normalized_task = task.strip()
+        if not normalized_task or len(task) > 20_000:
+            raise RuntimeTaskInvalid()
+        resolved_directory = cwd.resolve()
+        if not resolved_directory.is_dir():
+            raise RuntimeWorkingDirectoryInvalid()
+        selected = self._hosts.resolve(host)
+        if selected.executable is None:
+            raise RuntimeHostUnavailable(selected.host.value)
+        return Plan(
+            capability_id=capability_id,
+            host=selected.host,
+            executable=Path(selected.executable),
+            working_directory=resolved_directory,
+            task=task,
+        )
+
+    def build_task_board(self, tasks: tuple[str, ...], host: Host | None, cwd: Path) -> Plan:
+        # Validates board count and chars against the shared bounds, then builds a label-only
+        # plan; the bounds live in TaskBoardLimit so the settings model cannot drift from here.
+        if not tasks or len(tasks) > TaskBoardLimit.MAX_TASKS:
+            raise RuntimeTaskInvalid()
+        for task in tasks:
+            if not task.strip() or len(task) > TaskBoardLimit.MAX_TASK_CHARS:
+                raise RuntimeTaskInvalid()
+        resolved_directory = cwd.resolve()
+        if not resolved_directory.is_dir():
+            raise RuntimeWorkingDirectoryInvalid()
+        selected = self._hosts.resolve(host)
+        if selected.executable is None:
+            raise RuntimeHostUnavailable(selected.host.value)
+        label = tasks[0][:200] if len(tasks[0]) > 200 else tasks[0]
+        return Plan(
+            capability_id="runtime.task-board@1",
+            host=selected.host,
+            executable=Path(selected.executable),
+            working_directory=resolved_directory,
+            task=f"Task board with {len(tasks)} tasks starting with: {label}",
+        )