vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/constants/runtime.py

@@ -0,0 +1,186 @@
+"""Canonical values for admission checks and persistent Codex execution.
+
+Commands and the persistence adapter share progress copy; gate checks share reasons.
+Provider credentials and model prompts never belong in this module.
+"""
+
+from enum import IntEnum, StrEnum
+
+
+class AdmissionReason(StrEnum):
+    """Closed vocabulary for local receipt checks, with explicit success."""
+
+    PASSED = "passed"
+    MISSING = "grant_missing"
+    CAPABILITY_MISMATCH = "grant_capability_mismatch"
+    PRICE_MISMATCH = "grant_price_mismatch"
+    LOCATION_OR_ID_INVALID = "grant_location_or_id_invalid"
+    TOKEN_MISSING = "grant_token_missing"
+    TIME_INVALID = "grant_time_invalid"
+    EXPIRED = "grant_expired"
+    TTL_INVALID = "grant_ttl_invalid"
+    VERIFICATION_KEY_MISSING = "grant_verification_key_missing"
+    SIGNATURE_INVALID = "grant_signature_invalid"
+    SIGNED_CLAIMS_MISMATCH = "grant_signed_claims_mismatch"
+    RECEIPT_MISMATCH = "grant_receipt_mismatch"
+
+
+class PersistenceLimit(IntEnum):
+    """Execution bounds independent of the agent's answer content."""
+
+    TURN_TIMEOUT_SECONDS = 3600
+
+
+class AttachmentLimit(IntEnum):
+    """Boundaries for one explicit attachment bundle before an agent starts."""
+
+    MAX_FILES = 50
+    MAX_FILE_BYTES = 1_000_000
+    MAX_TOTAL_BYTES = 8_000_000
+
+
+class AttachmentImageSuffix(StrEnum):
+    """Image suffixes that the Codex adapter can pass as native local-image inputs."""
+
+    GIF = ".gif"
+    JPEG = ".jpeg"
+    JPG = ".jpg"
+    PNG = ".png"
+    WEBP = ".webp"
+
+
+class PersistenceCodexConfig(StrEnum):
+    """Child-only provider configuration; no native login state is changed."""
+
+    PROVIDER = 'model_provider="vidbyte_openai"'
+    NAME = 'model_providers.vidbyte_openai.name="OpenAI"'
+    BASE_URL = 'model_providers.vidbyte_openai.base_url="https://api.openai.com/v1"'
+    ENV_KEY = 'model_providers.vidbyte_openai.env_key="OPENAI_API_KEY"'
+    WIRE_API = 'model_providers.vidbyte_openai.wire_api="responses"'
+
+
+class TaskBoardLimit(IntEnum):
+    """Execution bounds for one ordered task-board invocation."""
+
+    # One board task is a whole unit of agent work, not a chat turn: a decomposed task can
+    # legitimately hold a coding agent for days. Five days is the ceiling that stops a wedged
+    # child process from running forever, not a budget the caller is expected to approach.
+    TURN_TIMEOUT_SECONDS = 5 * 24 * 60 * 60
+    MAX_TASKS = 500
+    # A board task is one whole Markdown task file's worth of instructions, so it shares the
+    # 20,000-character contract every other local runtime task already uses.
+    MAX_TASK_CHARS = 20_000
+    MAX_WINDOW = 25
+    MIN_SUBTASKS = 2
+    MAX_SUBTASKS = 10
+
+
+class TaskBoardCodexConfig(StrEnum):
+    """Child-only provider configuration; no native login state is changed."""
+
+    PROVIDER = 'model_provider="vidbyte_openai"'
+    NAME = 'model_providers.vidbyte_openai.name="OpenAI"'
+    BASE_URL = 'model_providers.vidbyte_openai.base_url="https://api.openai.com/v1"'
+    ENV_KEY = 'model_providers.vidbyte_openai.env_key="OPENAI_API_KEY"'
+    WIRE_API = 'model_providers.vidbyte_openai.wire_api="responses"'
+
+
+class TaskBoardProgress(StrEnum):
+    """Product-facing milestones; task copy describes intent, not observed work."""
+
+    PREPARING = (
+        "Preparing your task board and checking that Codex can run in this working directory."
+    )
+    CREDENTIALS = "Loading your OpenAI credentials to run the board with your own API account."
+    ADMISSION = "Requesting the two-cent Vidbyte admission for this task-board run."
+    VERIFYING = "Verifying your admission receipt before starting work on your board."
+    ADMITTED = "Your admission is verified. Preparing Codex to work through your board."
+    TASK_STARTING = "Working through board tasks in order with Codex."
+    TASK_RETRYING = "Retrying the current board task with the same prior summaries."
+    DAG_PLAN_READY = (
+        "Board dependencies checked. Running each task after the tasks it depends on with Codex."
+    )
+    TASK_SKIPPED = (
+        "Skipping a board task whose dependency did not complete. "
+        "Continuing with tasks that can still run."
+    )
+    TASK_FAILED = (
+        "A board task did not complete after retries. "
+        "Recording what happened and continuing with the remaining tasks."
+    )
+    DECOMPOSE_ISOLATED = (
+        "Decomposition is on: agents see only their own task; window context is off."
+    )
+    COMPLETE = "Codex has worked through the requested board tasks. Returning the summaries."
+
+
+class PersistenceProgress(StrEnum):
+    """Product-facing milestones; continuation copy describes intent, not observed work."""
+
+    PREPARING = "Preparing your task and checking that Codex can run in this working directory."
+    CREDENTIALS = "Loading your OpenAI credentials to run the task with your own API account."
+    ADMISSION = "Requesting the two-cent Vidbyte admission for this persistence session."
+    X402_ADMISSION = "Paying the two-cent admission through x402."
+    VERIFYING = "Verifying your admission payment in Vidbyte before starting work on your task."
+    ADMITTED = "Your admission is verified. Preparing Codex to work on your task."
+    STARTING = "Starting your original task in Codex, with your request preserved exactly."
+    INITIAL_COMPLETE = (
+        "Codex has returned its first response. Continuing in the same conversation "
+        "to give it more opportunities to improve the result."
+    )
+    EARLY = (
+        "Asking Codex to build on its work and look for ways to better satisfy your original task."
+    )
+    MIDDLE = (
+        "Continuing the same task with another request to revisit gaps and strengthen the result."
+    )
+    LATE = "Giving Codex more time to refine its work while keeping your original request in view."
+    FINAL = "Requesting the final improvement pass before returning the result to you."
+    COMPLETE = "Codex has completed the requested persistence passes. Returning its final response."
+
+
+class RuntimePaymentConfig:
+    """Reviewed EVM payment bounds; cents remain separate from provider token usage."""
+
+    PRIVATE_KEY_ENV = "VIDBYTE_X402_PRIVATE_KEY"
+    NETWORK_ENV = "VIDBYTE_X402_NETWORK"
+    DEFAULT_NETWORK = "eip155:8453"
+    NETWORKS = ("eip155:8453", "eip155:84532")
+    MAX_CHALLENGE_CHARACTERS = 16384
+    MAX_AUTHORIZATION_SECONDS = 3600
+    MICROUNITS_PER_CENT = 10000
+    PERSISTENCE_CENTS = 2
+
+
+class StagesLimit(IntEnum):
+    """Execution bounds for the stages primitive."""
+
+    # Review of PR #36 raised this ceiling from 10 to 25: a staged skill such as a design-doc
+    # flow decomposes further than the original estimate, and every stage past the ceiling has
+    # to be split across two paid runs. The admission stays one cent however many stages run.
+    MAX_STAGES = 25
+    TURN_TIMEOUT_SECONDS = 3600
+
+
+class StagesCodexConfig(StrEnum):
+    """Child-only provider configuration; no native login state is changed."""
+
+    PROVIDER = 'model_provider="vidbyte_openai"'
+    NAME = 'model_providers.vidbyte_openai.name="OpenAI"'
+    BASE_URL = 'model_providers.vidbyte_openai.base_url="https://api.openai.com/v1"'
+    ENV_KEY = 'model_providers.vidbyte_openai.env_key="OPENAI_API_KEY"'
+    WIRE_API = 'model_providers.vidbyte_openai.wire_api="responses"'
+
+
+class StagesProgress(StrEnum):
+    """Product-facing milestones for staged local execution."""
+
+    PREPARING = "Preparing your task and checking that Codex can run in this working directory."
+    CREDENTIALS = "Loading your OpenAI credentials to run the stages with your own API account."
+    ADMISSION = "Requesting the one-cent Vidbyte admission for this stages run."
+    VERIFYING = "Verifying your admission receipt before starting the first stage."
+    ADMITTED = "Your admission is verified. Preparing a fresh Codex agent per stage."
+    STAGE_STARTING = "Starting the next stage with its own Codex agent."
+    STAGE_RETRYING = "Retrying the current stage with a fresh Codex agent."
+    STAGE_COMPLETE = "A stage returned its response. Continuing with the next stage."
+    COMPLETE = "Codex has completed every requested stage. Returning the final response."

vidbyte_cli/lib/errors/__init__.py

@@ -0,0 +1,12 @@
+"""Public typed-error contracts. Importing this pulls in Click and the output layer.
+
+Keep it out of the minimal `import vidbyte_cli` path: the package root resolves a version
+without loading command or presentation dependencies. Concrete failures live in
+`failures.py` and are imported from there directly by the code that raises them.
+"""
+
+from .cli_error import CliError
+from .codes import CliErrorCode, ExitCode
+from .handler import ErrorHandler
+
+__all__ = ["CliError", "CliErrorCode", "ErrorHandler", "ExitCode"]

vidbyte_cli/lib/errors/cli_error.py

@@ -0,0 +1,86 @@
+"""The user-safe exception every command and service raises instead of printing.
+
+A CliError serves two callers at once. A human gets `message` and `hint`; an agent also gets
+the non-sensitive `description`/`trace`/`file_path` triple, which is what lets it repair its
+own invocation without a transcript. Subclasses in `failures.py` own that prose, so a raise
+site stays one line and every failure of a kind reads identically.
+
+`cause` is the one field that may hold backend, credential, or filesystem detail. It is
+private on purpose: no renderer may serialize it, and debug traces show frames only.
+"""
+
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+from types import FrameType
+from typing import ClassVar
+
+from pydantic import JsonValue
+
+from .codes import CliErrorCode, ExitCode
+
+# Frames inside this package are error plumbing, never the site that actually failed.
+_ERRORS_PACKAGE = Path(__file__).resolve().parent
+# `.../vidbyte_cli/lib/errors` -> the directory holding the package, so reported paths are
+# relative and identical whether the CLI runs from a checkout or an installed wheel.
+_PACKAGE_PARENT = _ERRORS_PACKAGE.parents[2]
+
+
+class CliError(Exception):
+    """A classified CLI failure whose message and metadata are safe to display."""
+
+    # Subclasses fix the classification; only Click may override exit_code per instance.
+    code: ClassVar[CliErrorCode] = CliErrorCode.OPERATION_FAILED
+    exit_status: ClassVar[ExitCode] = ExitCode.OPERATIONAL_FAILURE
+    retryable: ClassVar[bool] = False
+
+    def __init__(
+        self,
+        message: str,
+        description: str,
+        trace: str,
+        *,
+        exit_code: int | None = None,
+        hint: str | None = None,
+        request_id: str | None = None,
+        remediation: dict[str, JsonValue] | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.description = description
+        self.trace = trace
+        self.file_path = self._origin_file()
+        self.exit_code = int(self.exit_status if exit_code is None else exit_code)
+        self.hint = hint
+        self.request_id = request_id
+        self.remediation = remediation
+        self.cause = cause
+
+    @property
+    def code_value(self) -> str:
+        # Output protocols depend on a plain string without importing this enum package.
+        return self.code.value
+
+    @staticmethod
+    def _origin_file() -> str:
+        # An agent's next action is opening a file, and a path hand-written per subclass goes
+        # stale the moment code moves. The first frame outside this package is the command or
+        # service that actually failed, so derive it instead of declaring it.
+        frame: FrameType | None = inspect.currentframe()
+        while frame is not None:
+            # Resolve before comparing: a frame's filename may be relative to the cwd.
+            path = Path(frame.f_code.co_filename).resolve()
+            if path.parent != _ERRORS_PACKAGE:
+                return CliError._package_path(path)
+            frame = frame.f_back
+        return CliError._package_path(Path(__file__).resolve())
+
+    @staticmethod
+    def _package_path(path: Path) -> str:
+        # Frames outside the package (Click, the interpreter) have no meaningful repository
+        # location, so report the bare filename rather than an absolute machine path.
+        if not path.is_relative_to(_PACKAGE_PARENT):
+            return path.name
+        return path.relative_to(_PACKAGE_PARENT).as_posix()

vidbyte_cli/lib/errors/codes.py

@@ -0,0 +1,43 @@
+"""The stable error and exit vocabulary the CLI publishes to shells and agents.
+
+Every value here is a public contract: a shipped code string may not be reworded and a
+shipped exit number may not be reassigned. Prose belongs to the `CliError` subclasses in
+`failures.py`, so automation branches on identity while messages keep improving.
+
+Several codes deliberately share one exit status — statuses are coarse shell signals, codes
+are precise machine semantics.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+
+
+class CliErrorCode(StrEnum):
+    """Stable failure identity for users and automation."""
+
+    INVALID_ARGUMENT = "INVALID_ARGUMENT"
+    AUTH_REQUIRED = "AUTH_REQUIRED"
+    CREDIT_EXHAUSTED = "CREDIT_EXHAUSTED"
+    API_UNAVAILABLE = "API_UNAVAILABLE"
+    API_PROTOCOL_ERROR = "API_PROTOCOL_ERROR"
+    CONFIG_INVALID = "CONFIG_INVALID"
+    CONFIG_WRITE_CONFLICT = "CONFIG_WRITE_CONFLICT"
+    CREDENTIAL_STORE_UNAVAILABLE = "CREDENTIAL_STORE_UNAVAILABLE"
+    OPERATION_FAILED = "OPERATION_FAILED"
+    NOT_IMPLEMENTED = "NOT_IMPLEMENTED"
+    INTERRUPTED = "INTERRUPTED"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+class ExitCode(IntEnum):
+    """Stable shell statuses documented by the CLI."""
+
+    SUCCESS = 0
+    OPERATIONAL_FAILURE = 1
+    USAGE = 2
+    PARTIAL_OUTCOME = 3
+    AUTHENTICATION = 4
+    CREDIT_EXHAUSTED = 5
+    SOFTWARE = 70
+    INTERRUPTED = 130