vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/commands/research/start.py

@@ -0,0 +1,37 @@
+"""`vidbyte-cli research start <prompt>` — open a new research thread and admit its first run.
+
+Admission returns immediately with durable identifiers rather than blocking: a research run
+outlives a terminal session, and `research watch` is the explicit way to wait for one.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ...lib.runtime.context import ApplicationContext
+from .options import ResearchRunOptions
+from .render import ResearchRenderer
+
+
+class ResearchStartCommand:
+    def register(self, parent: click.Group) -> None:
+        # Options are attached before the group takes the callback, so help lists them in order.
+        options = ResearchRunOptions()
+
+        def _run(context: ApplicationContext, /, **values: object) -> None:
+            self.execute(context, values)
+
+        callback = click.argument("prompt")(click.pass_obj(_run))
+        parent.command(name="start", help="Start a new research thread from a prompt")(
+            options.apply(callback)
+        )
+
+    def execute(self, context: ApplicationContext, values: dict[str, object]) -> None:
+        # Validates the whole request before a credential is resolved, so a malformed
+        # invocation costs neither a keyring lookup nor a round trip.
+        options = ResearchRunOptions()
+        request = options.build(values)
+        key = str(options.key(values))
+        accepted = context.research_endpoints().create_run(request, key)
+        rendered = ResearchRenderer().accepted(accepted, key)
+        context.output().result(rendered.document, rendered.human)

vidbyte_cli/commands/research/status.py

@@ -0,0 +1,32 @@
+"""`vidbyte-cli research status <run_id>` — one run's coarse durable progress.
+
+The published status is deliberately thin: state, phase, continuation count, and a timestamp.
+Live source and artifact counts are a web-product surface, not part of the API-key contract,
+so nothing here estimates or invents them.
+
+This command cannot tell a caller where to add more work. The status route carries only the
+thread's internal identifier, which is rejected by path validation if it were pasted back, so
+the models drop it — `research threads` is where a usable thread ID comes from.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ...lib.runtime.context import ApplicationContext
+from .render import ResearchRenderer
+
+
+class ResearchStatusCommand:
+    def register(self, parent: click.Group) -> None:
+        @parent.command(name="status", help="Show one research run's current status")
+        @click.argument("run_id")
+        @click.pass_obj
+        def _run(context: ApplicationContext, run_id: str) -> None:
+            self.execute(context, run_id)
+
+    def execute(self, context: ApplicationContext, run_id: str) -> None:
+        # Reads the run once; `admitting` and `accepted` are progress, not failures.
+        run = context.research_endpoints().get_run(run_id)
+        rendered = ResearchRenderer().run_status(run)
+        context.output().result(rendered.document, rendered.human)

vidbyte_cli/commands/research/thread.py

@@ -0,0 +1,30 @@
+"""`vidbyte-cli research thread <thread_id>` — one research thread and its rollup counters.
+
+Reads the same thread the portfolio lists, plus the latest run's phase and the favourite flag
+a portfolio row omits. A soft-deleted thread reads as not found, the same as one that never
+existed, because reads are scoped to the caller.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ...lib.runtime.context import ApplicationContext
+from ...types.research import ThreadId
+from .render import ResearchRenderer
+
+
+class ResearchThreadCommand:
+    def register(self, parent: click.Group) -> None:
+        @parent.command(name="thread", help="Show one research thread")
+        @click.argument("thread_id")
+        @click.pass_obj
+        def _run(context: ApplicationContext, thread_id: str) -> None:
+            self.execute(context, thread_id)
+
+    def execute(self, context: ApplicationContext, thread_id: str) -> None:
+        # The ID guard runs first so a mistyped thread never triggers a credential lookup.
+        parsed = ThreadId.parse(thread_id)
+        thread = context.research_endpoints().get_thread(str(parsed))
+        rendered = ResearchRenderer().thread(thread)
+        context.output().result(rendered.document, rendered.human)

vidbyte_cli/commands/research/threads.py

@@ -0,0 +1,35 @@
+"""`vidbyte-cli research threads` — one page of the caller's research threads.
+
+This and `research start` are the only two places a usable thread ID is minted, which is why
+every row leads with it. Paging is cursor-based: an absent `next_cursor` is the end of the
+collection, and the command never loops on the caller's behalf.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ...lib.runtime.context import ApplicationContext
+from .render import ResearchRenderer
+
+_MAXIMUM_PAGE_SIZE = 100
+
+
+class ResearchThreadsCommand:
+    def register(self, parent: click.Group) -> None:
+        @parent.command(name="threads", help="List your research threads")
+        @click.option("--cursor", help="Continue from the cursor a previous page reported.")
+        @click.option(
+            "--limit",
+            type=click.IntRange(1, _MAXIMUM_PAGE_SIZE),
+            help="How many threads to return. The server picks a default when unset.",
+        )
+        @click.pass_obj
+        def _run(context: ApplicationContext, cursor: str | None, limit: int | None) -> None:
+            self.execute(context, cursor, limit)
+
+    def execute(self, context: ApplicationContext, cursor: str | None, limit: int | None) -> None:
+        # Reads exactly one page; the cursor is opaque and is echoed back, never parsed.
+        page = context.research_endpoints().get_portfolio(cursor, limit)
+        rendered = ResearchRenderer().thread_page(page)
+        context.output().result(rendered.document, rendered.human)

vidbyte_cli/commands/research/watch.py

@@ -0,0 +1,93 @@
+"""`vidbyte-cli research watch <run_id>` — follow one run until it settles.
+
+The interval starts at ten seconds and backs off, which is a rate limit decision rather than
+a taste one. The backend meters API keys on a weighted per-minute budget where starting a run
+costs many times what reading one does, so a tight poll loop can exhaust the same budget the
+caller needs to start their next run.
+
+Only coarse transitions are reported. The status route publishes no live counters, so a
+change is detected by fingerprinting exactly what it does publish.
+"""
+
+from __future__ import annotations
+
+import time
+
+import click
+
+from ...lib.errors.failures import ResearchWatchTimedOut
+from ...lib.runtime.context import ApplicationContext
+from ...types.research import ResearchRunStatus
+from .render import ResearchRenderer
+
+_INITIAL_DELAY_SECONDS = 10.0
+_MAXIMUM_DELAY_SECONDS = 60.0
+_BACKOFF_FACTOR = 1.5
+_MAXIMUM_TIMEOUT_SECONDS = 86_400.0
+
+
+class ResearchWatchCommand:
+    def register(self, parent: click.Group) -> None:
+        @parent.command(name="watch", help="Watch one research run until it finishes")
+        @click.argument("run_id")
+        @click.option(
+            "--timeout",
+            type=click.FloatRange(1.0, _MAXIMUM_TIMEOUT_SECONDS),
+            help="Give up waiting after this many seconds. The run keeps going.",
+        )
+        @click.pass_obj
+        def _run(context: ApplicationContext, run_id: str, timeout: float | None) -> None:
+            self.execute(context, run_id, timeout)
+
+    def execute(self, context: ApplicationContext, run_id: str, timeout: float | None) -> None:
+        # Polls to a terminal status, then emits that final snapshot as the one result.
+        run = self._poll_until_terminal(context, run_id, timeout)
+        rendered = ResearchRenderer().run_status(run)
+        context.output().result(rendered.document, rendered.human)
+
+    def _poll_until_terminal(
+        self,
+        context: ApplicationContext,
+        run_id: str,
+        timeout: float | None,
+    ) -> ResearchRunStatus:
+        # Always fetches once before honouring the deadline, so a tiny timeout still reports.
+        endpoints = context.research_endpoints()
+        renderer = ResearchRenderer()
+        started = time.monotonic()
+        delay = _INITIAL_DELAY_SECONDS
+        last_fingerprint: str | None = None
+        while True:
+            run = endpoints.get_run(run_id)
+            fingerprint = self._fingerprint(run)
+            if fingerprint != last_fingerprint:
+                self._emit_transition(context, renderer, run)
+                last_fingerprint = fingerprint
+            if run.status.is_terminal():
+                return run
+            if self._expired(started, timeout, delay):
+                raise ResearchWatchTimedOut(run_id)
+            time.sleep(delay)
+            delay = self._next_delay(delay)
+
+    def _fingerprint(self, run: ResearchRunStatus) -> str:
+        # The whole of what the status route publishes, so no change can go unnoticed.
+        return f"{run.status.value}:{run.phase}:{run.updated_at.isoformat()}"
+
+    def _emit_transition(
+        self,
+        context: ApplicationContext,
+        renderer: ResearchRenderer,
+        run: ResearchRunStatus,
+    ) -> None:
+        # Progress goes to the transition channel so a single-JSON consumer still sees
+        # exactly one document on stdout at the end.
+        rendered = renderer.transition(run)
+        context.output().transition(rendered.document, rendered.human)
+
+    def _expired(self, started: float, timeout: float | None, delay: float) -> bool:
+        # Checked before sleeping: waiting past the deadline to discover it would be worse.
+        return timeout is not None and (time.monotonic() - started) + delay >= timeout
+
+    def _next_delay(self, delay: float) -> float:
+        return min(delay * _BACKOFF_FACTOR, _MAXIMUM_DELAY_SECONDS)

vidbyte_cli/commands/runtime/__init__.py

@@ -0,0 +1,23 @@
+"""Static commands for locally executed Vidbyte runtime primitives.
+
+This group is distinct from hosted services because execution remains on the user's
+machine and delegates to an installed native coding-agent host.
+"""
+
+from .adversarial_team import AdversarialTeamCommand
+from .doctor import RuntimeDoctorCommand
+from .list import RuntimeListCommand
+from .persistence import PersistenceCommand
+from .same_host_ensemble import SameHostEnsembleCommand
+from .stages import StagesCommand
+from .task_board import TaskBoardCommand
+
+__all__ = [
+    "AdversarialTeamCommand",
+    "PersistenceCommand",
+    "RuntimeDoctorCommand",
+    "RuntimeListCommand",
+    "SameHostEnsembleCommand",
+    "TaskBoardCommand",
+    "StagesCommand",
+]

vidbyte_cli/commands/runtime/adversarial_team.py

@@ -0,0 +1,41 @@
+"""Command shell for the first local adversarial-team runtime primitive.
+
+The command validates host and working-directory context, then reaches the inert executor.
+It cannot request paid admission or spawn agents in this release.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ...lib.runtime.context import ApplicationContext
+from ...types.runtime import RuntimeHost
+
+
+class AdversarialTeamCommand:
+    """Builds a launch plan for the unimplemented adversarial-team executor."""
+
+    def register(self, parent: click.Group) -> None:
+        # Attaches the first primitive with an explicit native host selector.
+        @parent.command(name="adversarial-team", help="Run an adversarial agent team locally")
+        @click.argument("task")
+        @click.option(
+            "--host",
+            type=click.Choice(("auto", *(host.value for host in RuntimeHost))),
+            default="auto",
+            show_default=True,
+        )
+        @click.pass_obj
+        def _run(context: ApplicationContext, task: str, host: str) -> None:
+            # Delegates parsed values to the class-owned execution method.
+            self.execute(context, task, host)
+
+    def execute(self, context: ApplicationContext, task: str, host: str) -> None:
+        # Builds a local plan first; the executor then fails before payment or process launch.
+        requested = None if host == "auto" else RuntimeHost(host)
+        plan = context.runtime_launch_planner().build(
+            task, requested, Path.cwd(), "runtime.adversarial-team@1"
+        )
+        context.runtime_executor().execute_adversarial_team(plan)

vidbyte_cli/commands/runtime/doctor.py

@@ -0,0 +1,44 @@
+"""`vidbyte-cli runtime doctor` inspects local native-agent prerequisites.
+
+It is read-only and offline: executable paths are reported, while host configuration,
+credentials, environment values, and repository contents are not inspected.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from pydantic import JsonValue
+
+from ...lib.output import OutputDocument
+from ...lib.runtime.context import ApplicationContext
+
+
+class RuntimeDoctorCommand:
+    """Reports the working directory and supported host availability."""
+
+    def register(self, parent: click.Group) -> None:
+        # Attaches the local-only diagnostic beneath the runtime group.
+        @parent.command(name="doctor", help="Diagnose local runtime host availability")
+        @click.pass_obj
+        def _run(context: ApplicationContext) -> None:
+            # Delegates command behavior to the class-owned execution method.
+            self.execute(context)
+
+    def execute(self, context: ApplicationContext) -> None:
+        # Presents PATH discovery without resolving credentials or opening the network.
+        statuses = context.runtime_hosts().inspect()
+        working_directory = str(Path.cwd().resolve())
+        rows: list[JsonValue] = [status.model_dump(mode="json") for status in statuses]
+        human_rows = [
+            f"{status.host.value}: {status.executable if status.available else 'not found'}"
+            for status in statuses
+        ]
+        human = "\n".join((f"Working directory: {working_directory}", *human_rows))
+        context.output().result(
+            OutputDocument(
+                kind="runtime.doctor", data={"working_directory": working_directory, "hosts": rows}
+            ),
+            human,
+        )

vidbyte_cli/commands/runtime/list.py

@@ -0,0 +1,47 @@
+"""`vidbyte-cli runtime list` renders locally executable runtime products.
+
+The catalog comes from Vidbyte so price and supported host metadata stay aligned with the
+paid admission route rather than becoming hard-coded command policy.
+"""
+
+from __future__ import annotations
+
+import click
+from pydantic import JsonValue
+
+from ...lib.output import OutputDocument
+from ...lib.runtime.context import ApplicationContext
+
+
+class RuntimeListCommand:
+    """Lists the backend's runtime-only capability catalog."""
+
+    def register(self, parent: click.Group) -> None:
+        # Attaches the authenticated catalog read beneath the runtime group.
+        @parent.command(name="list", help="List local runtime primitives and prices")
+        @click.pass_obj
+        def _run(context: ApplicationContext) -> None:
+            # Delegates command behavior to the class-owned execution method.
+            self.execute(context)
+
+    def execute(self, context: ApplicationContext) -> None:
+        # Fetches one bounded catalog and renders only its typed public fields.
+        catalog = context.runtime_endpoints().list_capabilities()
+        rows: list[JsonValue] = [
+            capability.model_dump(mode="json") for capability in catalog.capabilities
+        ]
+        human_rows = []
+        for item in catalog.capabilities:
+            hosts = ", ".join(host.value for host in item.supported_hosts)
+            price = item.admission_price_cents / 100
+            human_rows.append(
+                f"{item.capability_id}@{item.version}: ${price:.2f} per local launch ({hosts})"
+            )
+        human = "\n".join(human_rows)
+        context.output().result(
+            OutputDocument(
+                kind="runtime.catalog",
+                data={"capabilities": rows, "topup_path": catalog.topup_path},
+            ),
+            human or "No local runtime primitives are available.",
+        )

vidbyte_cli/commands/runtime/persistence.py

@@ -0,0 +1,141 @@
+"""Validates and admits one fixed-loop local Codex persistence invocation."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from uuid import uuid4
+
+import click
+
+from ...lib.constants.runtime import PersistenceProgress as Progress
+from ...lib.constants.runtime import RuntimePaymentConfig as PaymentConfig
+from ...lib.errors.failures import RuntimeAdmissionNotVerified
+from ...lib.output import OutputDocument
+from ...lib.runtime.context import ApplicationContext as Context
+from ...lib.runtime_primitives.gate import RuntimeAdmissionGate
+from ...services.persistence.runner import PersistenceRunner
+from ...services.persistence.session import PersistentCodexSession
+from ...types.provider import PROVIDER_ENV_VARS, Provider
+from ...types.runtime import (
+    PersistenceSettings,
+    PersistenceStrength,
+    RuntimeAdmissionRequest,
+    RuntimeGrantVerificationRequest,
+    RuntimeHost,
+    RuntimeX402AdmissionRequest,
+)
+
+_WITH_X402_PAYMENT_HELP = (
+    "Pay the two-cent admission charge with an x402 on-chain transfer instead of debiting "
+    "your Vidbyte API balance. The default is the API-balance path, because it needs no "
+    "wallet and additionally verifies the exact usage-ledger debit before Codex starts. "
+    "Pass this flag when the account holding the work has no Vidbyte balance, or when you "
+    "would rather settle admission from a funded wallet. It requires "
+    "VIDBYTE_X402_PRIVATE_KEY in the environment and a wallet already holding USDC on "
+    "VIDBYTE_X402_NETWORK, which defaults to Base; the CLI never funds the wallet and never "
+    "switches payment methods on its own. This changes only how admission is settled: a "
+    "Vidbyte API key with runtime:write still establishes ownership, and every model call "
+    "is still billed to your own OpenAI credentials."
+)
+
+
+class PersistenceCommand:
+    """Keeps validation and provider credentials ahead of paid admission."""
+
+    def register(self, parent: click.Group) -> None:
+        # The host selector rejects unsupported execution modes before charging.
+        @parent.command(name="persistence", help="Persistently drive one local Codex session")
+        @click.argument("task")
+        @click.option(
+            "--host", type=click.Choice(("auto", "codex")), default="codex", expose_value=False
+        )
+        @click.option("--strength", type=click.IntRange(1, 6), default=1, show_default=True)
+        @click.option(
+            "--idempotency-key", "key", default=None, help="Reuse only to recover admission."
+        )
+        @click.option(
+            "--with-x402-payment",
+            is_flag=True,
+            help=_WITH_X402_PAYMENT_HELP,
+        )
+        @click.pass_obj
+        def _run(
+            context: Context,
+            task: str,
+            strength: int,
+            key: str | None,
+            with_x402_payment: bool,
+        ) -> None:
+            # Delegates without normalizing or wrapping the original task.
+            self.execute(context, task, strength, key, with_x402_payment)
+
+    def execute(
+        self,
+        context: Context,
+        task: str,
+        strength: int,
+        key: str | None,
+        with_x402_payment: bool = False,
+    ) -> None:
+        # Resolve local prerequisites before any wallet admission, then verify before execution.
+        progress = context.output().diagnostic
+        progress(Progress.PREPARING)
+        key = key or str(uuid4())
+        if re.fullmatch(r"[A-Za-z0-9._:-]{8,128}", key) is None:
+            raise click.BadParameter(
+                "Use 8–128 letters, digits, dots, underscores, colons or hyphens."
+            )
+        plan = context.runtime_launch_planner().build(
+            task, RuntimeHost.CODEX, Path.cwd(), "runtime.persistence@1"
+        )
+        settings = PersistenceSettings(strength=PersistenceStrength(strength))
+        progress(Progress.CREDENTIALS)
+        session = self._session(context)
+        session.prepare(plan)
+        endpoints = context.runtime_endpoints()
+        progress(f"Admission recovery key: {key}")
+        if with_x402_payment:
+            from ...lib.api.runtime_payment import RuntimePayment
+
+            payer = RuntimePayment(context.environment, PaymentConfig.PERSISTENCE_CENTS)
+            progress(Progress.X402_ADMISSION)
+            request = RuntimeX402AdmissionRequest(host=plan.host)
+            grant = endpoints.admit_persistence_x402(request, key, payer)
+        else:
+            progress(Progress.ADMISSION)
+            grant = endpoints.admit_persistence(RuntimeAdmissionRequest(host=plan.host), key)
+        if grant.grant_token is None:
+            raise RuntimeAdmissionNotVerified("grant_token_missing")
+        progress(Progress.VERIFYING)
+        verified = endpoints.verify_grant(
+            RuntimeGrantVerificationRequest(
+                grant_token=grant.grant_token,
+                idempotency_key_hash=RuntimeAdmissionGate.hash_idempotency_key(key),
+            )
+        )
+        verdict = RuntimeAdmissionGate().verify_online(plan, grant, verified)
+        if not verdict.admitted:
+            raise RuntimeAdmissionNotVerified(verdict.reason)
+        progress(Progress.ADMITTED)
+        result = PersistenceRunner().run(plan, settings, session, verdict)
+        context.output().result(
+            OutputDocument(kind="runtime.persistence", data=result.model_dump(mode="json")),
+            result.text,
+        )
+
+    def _session(self, context: Context) -> PersistentCodexSession:
+        # The SDK merges env with the parent: empty overrides prevent secret reinheritance.
+        credentials = context.require_provider_credentials(Provider.OPENAI)
+        environment = dict(context.environment)
+        for name in (
+            *PROVIDER_ENV_VARS.values(),
+            "GOOGLE_API_KEY",
+            "VIDBYTE_API_KEY",
+            "RUNTIME_ADMISSION_SIGNING_KEY",
+            "CODEX_API_KEY",
+            PaymentConfig.PRIVATE_KEY_ENV,
+        ):
+            environment[name] = ""
+        environment["OPENAI_API_KEY"] = credentials.secret_value()
+        return PersistentCodexSession(environment, context.output().diagnostic)