vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/services/ensemble/settings.py

@@ -0,0 +1,60 @@
+"""One run's shared collaborators, and the sandbox policy for each of its four stages.
+
+This is where "exactly one agent may write" is decided, so the invariant is checkable by
+reading a single file: `root`, `proposal`, and `selector` are read-only, `implementer` is not.
+It also carries the run's sdk, prompts, and inputs so the service does not thread them
+everywhere.
+
+Each stage gets a complete system prompt of its own rather than an addition to the previous
+stage's, because a fork inherits its parent's prompt unless it is replaced.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ...types.ensemble import (
+    EnsembleInputs,
+    GeneratedRole,
+    RolePlan,
+    RoleProposal,
+    SelectionRound,
+)
+from .prompts.library import EnsemblePrompts
+from .sdk import EnsembleSdk
+
+
+class EnsembleStages:
+    """Holds one run's collaborators and builds the settings each stage needs."""
+
+    def __init__(self, sdk: EnsembleSdk, inputs: EnsembleInputs, cwd: Path) -> None:
+        # One instance per run, so working directory and caller options cannot drift by stage.
+        self.sdk = sdk
+        self.inputs = inputs
+        self.prompts = EnsemblePrompts()
+        self._cwd = cwd
+
+    def root(self) -> Any:
+        # Stage one designs the roster and only reads, so it gets no write access either.
+        prompt = self.prompts.planner_system_prompt(self.inputs.roles)
+        return self.sdk.root_settings(prompt, RolePlan, self._codex(write=False))
+
+    def proposal(self, role: GeneratedRole) -> Any:
+        # Stage two: read-only, and its structured output is what makes it a proposal.
+        prompt = self.prompts.role_system_prompt(role)
+        return self.sdk.fork_settings(role.name, prompt, RoleProposal, self._codex(write=False))
+
+    def selector(self) -> Any:
+        # Stage three reads the workspace to check a candidate's premise, but never edits it.
+        prompt = self.prompts.selector_system_prompt()
+        return self.sdk.fork_settings("selector", prompt, SelectionRound, self._codex(write=False))
+
+    def implementer(self) -> Any:
+        # Stage four is the only bundle in this file that enables workspace writes.
+        prompt = self.prompts.implementer_system_prompt()
+        return self.sdk.fork_settings("implementer", prompt, None, self._codex(write=True))
+
+    def _codex(self, *, write: bool) -> Any:
+        # Provider settings are built by the sdk module; only the write axis is decided here.
+        return self.sdk.codex_settings(self.inputs, self._cwd, write=write)

vidbyte_cli/services/persistence/__init__.py

@@ -0,0 +1,6 @@
+"""The persistence primitive: one Codex thread driven through a fixed continuation loop.
+
+This module stays free of imports on purpose. `runner` reaches the admission boundary in
+`lib/`, so re-exporting it here would make importing `session` or a prompt drag that along.
+Import the module you actually need.
+"""

vidbyte_cli/services/persistence/prompts/__init__.py

@@ -0,0 +1,6 @@
+"""Both persistence prompts, as Markdown, plus the loader that fills their placeholders.
+
+The `.md` files here are the prompts themselves — authored text, reviewed as prose rather
+than as code. `library.py` holds the only Python in this package. Import it directly; this
+module stays empty so reading a prompt never pulls in the session that sends it.
+"""

vidbyte_cli/services/persistence/prompts/library.py

@@ -0,0 +1,46 @@
+"""Loads the Markdown prompts in this package and fills their `{{placeholder}}` slots.
+
+No prompt text lives here — every sentence an agent reads is in a `.md` file beside this one,
+so a prompt change is a prose diff. This class only reads those files and substitutes values.
+
+Substitution is a literal replace rather than `str.format`, because a task may contain braces
+that a format string would try to interpret.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+
+# The package the `.md` files sit in, named explicitly so resolution does not depend on how
+# this module was imported. They ship in the wheel via `[tool.setuptools.package-data]`.
+_ANCHOR = "vidbyte_cli.services.persistence.prompts"
+
+
+class PersistencePrompts:
+    """Reads each prompt file once and renders it with the values one run supplies."""
+
+    def __init__(self) -> None:
+        # One cache per session; the files are immutable package data, so reading twice is waste.
+        self._cache: dict[str, str] = {}
+
+    def system_prompt(self) -> str:
+        # The standing instruction the thread keeps across every continuation turn.
+        return self._read("persistence_system")
+
+    def turn_prompt(self, original_task: str) -> str:
+        # Each continuation restates the exact task, so a long loop cannot drift off it.
+        return self._render("persistence_turn", original_task=original_task)
+
+    def _render(self, name: str, **values: str) -> str:
+        # A literal replace, because a task holding braces would break a format string.
+        rendered = self._read(name)
+        for key, value in values.items():
+            rendered = rendered.replace("{{" + key + "}}", value)
+        return rendered
+
+    def _read(self, name: str) -> str:
+        # Read through `importlib.resources` so the prompts resolve from the installed wheel.
+        if name not in self._cache:
+            source = resources.files(_ANCHOR).joinpath(f"{name}.md")
+            self._cache[name] = source.read_text(encoding="utf-8")
+        return self._cache[name]

vidbyte_cli/services/persistence/prompts/persistence_system.md

@@ -0,0 +1 @@
+Work on the user's task using the tools and context available in this session. Preserve the user's intent and constraints throughout subsequent requests to continue or improve the work. Report what you accomplished accurately, including anything that remains unresolved.

vidbyte_cli/services/persistence/prompts/persistence_turn.md

@@ -0,0 +1,3 @@
+Very good job, keep working I think you can do a better job.... Revisit the work you have completed and identify the most useful improvements that still serve the original request. Check your assumptions, look for omissions, and verify the parts that need evidence. Improve the result with concrete work wherever you find a meaningful gap. Keep the original scope and constraints in force, and explain any genuine blocker that prevents further progress.
+
+Here is the original task in case your forgot {{original_task}}

vidbyte_cli/services/persistence/runner.py

@@ -0,0 +1,35 @@
+"""The last gate a persistence run passes before its first paid turn.
+
+The command buys and verifies the admission; this class re-checks the receipt against the
+plan independently, so a caller that skipped verification still cannot start an agent. It
+holds no endpoints and never touches the network.
+"""
+
+from __future__ import annotations
+
+from ...lib.errors.failures import RuntimeAdmissionNotVerified
+from ...lib.runtime_primitives.executor import RuntimeExecutor
+from ...types.runtime import PersistenceResult as Result
+from ...types.runtime import PersistenceSettings as Tier
+from ...types.runtime import RuntimeAdmissionVerdict as Verdict
+from ...types.runtime import RuntimeLaunchPlan as Plan
+from .session import PersistentCodexSession as Session
+
+
+class PersistenceRunner:
+    """Checks admission at the final boundary before the Codex session can start."""
+
+    def __init__(self, executor: RuntimeExecutor | None = None) -> None:
+        # Shares one verdict policy with every other primitive rather than restating it.
+        self._executor = executor or RuntimeExecutor()
+
+    def run(self, plan: Plan, settings: Tier, session: Session, verdict: Verdict) -> Result:
+        # The session cannot run until the exact requested capability has been admitted.
+        self._executor.require_verdict(plan, verdict)
+        self._require_persistence_plan(plan)
+        return session.run(plan, settings)
+
+    def _require_persistence_plan(self, plan: Plan) -> None:
+        # A genuine receipt bought for another product must not open this execution path.
+        if plan.capability_id != "runtime.persistence@1" or plan.host.value != "codex":
+            raise RuntimeAdmissionNotVerified("persistence_plan_invalid")

vidbyte_cli/services/persistence/session.py

@@ -0,0 +1,116 @@
+"""Runs a fixed continuation loop through the SDK's CodexHarnessAgent.
+
+The SDK owns transport and thread resumption. This adapter owns exact task input,
+turn limits, progress, and rejection of incomplete or changed-thread results.
+Every sentence a model reads comes from `prompts/`, never from a string literal here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING
+
+from ...lib.constants.runtime import PersistenceCodexConfig, PersistenceLimit
+from ...lib.constants.runtime import PersistenceProgress as Progress
+from ...lib.errors.failures import PersistenceHostFailed
+from ...types.runtime import PersistenceResult, PersistenceSettings
+from ...types.runtime import RuntimeLaunchPlan as Plan
+from .prompts.library import PersistencePrompts
+
+if TYPE_CHECKING:
+    from vidbyte.agents.codex import CodexHarnessAgent
+    from vidbyte.agents.types import AgentMessage
+
+
+class PersistentCodexSession:
+    """One invocation's environment and SDK agent, prepared before paid admission."""
+
+    def __init__(self, environment: Mapping[str, str], progress: Callable[[str], None]) -> None:
+        self._environment = dict(environment)
+        self._progress = progress
+        self._prompts = PersistencePrompts()
+        self._agent: CodexHarnessAgent | None = None
+
+    def prepare(self, plan: Plan) -> None:
+        # Construction validates local SDK settings without starting a paid model turn.
+        from vidbyte.agents.codex import CodexHarnessAgent
+        from vidbyte.lib.dataclasses.codex import (
+            CodexAgentSettings,
+            CodexClientSettings,
+            CodexHarnessAgentSettings,
+            CodexThreadSettings,
+        )
+        from vidbyte.lib.enums.codex import CodexSandbox
+
+        client = CodexClientSettings(
+            codex_bin=str(plan.executable),
+            cwd=str(plan.working_directory),
+            env=self._environment,
+            config_overrides=tuple(setting.value for setting in PersistenceCodexConfig),
+        )
+        self._agent = CodexHarnessAgent(
+            CodexHarnessAgentSettings(
+                name="persistence",
+                system_prompt=self._prompts.system_prompt(),
+                codex=CodexAgentSettings(
+                    client=client,
+                    thread=CodexThreadSettings(sandbox=CodexSandbox.WORKSPACE_WRITE),
+                ),
+            )
+        )
+
+    def run(self, plan: Plan, settings: PersistenceSettings) -> PersistenceResult:
+        from vidbyte.lib.errors import CodexAgentError
+
+        if self._agent is None:
+            raise PersistenceHostFailed()
+        try:
+            return asyncio.run(self._run(plan, settings))
+        except (CodexAgentError, TimeoutError) as error:
+            # SDK diagnostics may carry task content; only the static CLI failure is public.
+            raise PersistenceHostFailed() from error
+
+    async def _run(self, plan: Plan, settings: PersistenceSettings) -> PersistenceResult:
+        continuation = self._prompts.turn_prompt(plan.task)
+        self._progress(Progress.STARTING)
+        reply = await self._turn(plan.task)
+        session_id = self._session_id(reply, "")
+        self._progress(Progress.INITIAL_COMPLETE)
+        # The chosen strength, not a model's claim of completion, controls the loop.
+        for index in range(settings.repeat_count):
+            self._progress(self._continuation_progress(index, settings.repeat_count))
+            reply = await self._turn(continuation)
+            self._session_id(reply, session_id)
+        self._progress(Progress.COMPLETE)
+        return PersistenceResult(
+            session_id=session_id, continuation_turns=settings.repeat_count, text=reply.content
+        )
+
+    async def _turn(self, prompt: str) -> AgentMessage:
+        from vidbyte.lib.dataclasses.codex import CodexRunInput
+
+        if self._agent is None:
+            raise PersistenceHostFailed()
+        # Timeout cancels arun so the SDK's async client unwinds before the loop can continue.
+        async with asyncio.timeout(PersistenceLimit.TURN_TIMEOUT_SECONDS):
+            return await self._agent.arun(CodexRunInput.text(prompt))
+
+    def _session_id(self, reply: AgentMessage, previous: str) -> str:
+        data = reply.codex
+        if data is None or data.status != "completed" or not data.final_response:
+            raise PersistenceHostFailed()
+        if not data.thread_id.strip() or (previous and data.thread_id != previous):
+            raise PersistenceHostFailed()
+        if self._agent is None or self._agent.thread_id != data.thread_id:
+            raise PersistenceHostFailed()
+        return str(data.thread_id)
+
+    def _continuation_progress(self, index: int, count: int) -> Progress:
+        if index == count - 1:
+            return Progress.FINAL
+        if index * 3 < count:
+            return Progress.EARLY
+        if index * 3 < count * 2:
+            return Progress.MIDDLE
+        return Progress.LATE

vidbyte_cli/services/suggestions/__init__.py

@@ -0,0 +1,7 @@
+"""Package marker for the suggestion service."""
+
+from __future__ import annotations
+
+from .service import SuggestionService
+
+__all__ = ["SuggestionService"]

vidbyte_cli/services/suggestions/categories.py

@@ -0,0 +1,270 @@
+"""Owns the single versioned vocabulary of suggestion categories.
+
+The registry maps each accepted identifier to exactly one authored prompt asset.
+Commands, agent context, and result validation all consume this same mapping.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True, slots=True)
+class CategoryDefinition:
+    """One category identifier and its high-level caller-facing summary."""
+
+    category_id: str
+    title: str
+    summary: str
+    prompt_name: str
+
+    @property
+    def description(self) -> str:
+        """Keep the public description name readable to existing consumers."""
+        return self.summary
+
+
+class SuggestionCategories:
+    """Provides the ordered category registry and one-to-one prompt mapping."""
+
+    def __init__(self) -> None:
+        self._definitions = (
+            CategoryDefinition(
+                "continuation",
+                "Continuation",
+                "Advance an accepted plan with its next bounded step.",
+                "continuation",
+            ),
+            CategoryDefinition(
+                "prerequisite",
+                "Prerequisite",
+                "Create or secure a condition required by intended work.",
+                "prerequisite",
+            ),
+            CategoryDefinition(
+                "completion",
+                "Completion",
+                "Close a specific unfinished obligation in the current task.",
+                "completion",
+            ),
+            CategoryDefinition(
+                "bottleneck",
+                "Bottleneck",
+                "Relieve the constraint that limits useful progress.",
+                "bottleneck",
+            ),
+            CategoryDefinition(
+                "verification",
+                "Verification",
+                "Test a consequential claim before relying on it.",
+                "verification",
+            ),
+            CategoryDefinition(
+                "experiment",
+                "Experiment",
+                "Run a bounded test that can change a decision.",
+                "experiment",
+            ),
+            CategoryDefinition(
+                "investigation",
+                "Investigation",
+                "Gather the smallest reliable evidence needed for a decision.",
+                "investigation",
+            ),
+            CategoryDefinition(
+                "alternative",
+                "Alternative",
+                "Compare a materially different route to the same goal.",
+                "alternative",
+            ),
+            CategoryDefinition(
+                "simplification",
+                "Simplification",
+                "Remove complexity while preserving essential value.",
+                "simplification",
+            ),
+            CategoryDefinition(
+                "stop_or_defer",
+                "Stop or Defer",
+                "Stop or postpone work whose present value is insufficient.",
+                "stop_or_defer",
+            ),
+            CategoryDefinition(
+                "risk_prevention",
+                "Risk Prevention",
+                "Prevent a plausible failure with a proportionate guard.",
+                "risk_prevention",
+            ),
+            CategoryDefinition(
+                "leverage",
+                "Leverage",
+                "Create one asset that benefits several credible future tasks.",
+                "leverage",
+            ),
+            CategoryDefinition(
+                "strategy",
+                "Strategy",
+                "Choose a broader direction that coordinates several actions.",
+                "strategy",
+            ),
+            CategoryDefinition(
+                "adjacent_opportunity",
+                "Adjacent Opportunity",
+                "Capture nearby value enabled by current work.",
+                "adjacent_opportunity",
+            ),
+            CategoryDefinition(
+                "cross_domain",
+                "Cross-Domain",
+                "Transfer a useful mechanism from another field.",
+                "cross_domain",
+            ),
+            CategoryDefinition(
+                "preparation",
+                "Preparation",
+                "Build readiness for an anticipated event or demand.",
+                "preparation",
+            ),
+            CategoryDefinition(
+                "coordination",
+                "Coordination",
+                "Resolve ownership, sequencing, or dependency alignment.",
+                "coordination",
+            ),
+            CategoryDefinition(
+                "goal_clarification",
+                "Goal Clarification",
+                "Define the intended outcome and how success will be recognized.",
+                "goal_clarification",
+            ),
+            CategoryDefinition(
+                "creative_exploration",
+                "Creative Exploration",
+                "Generate concrete possibilities outside current assumptions.",
+                "creative_exploration",
+            ),
+            CategoryDefinition(
+                "delegation",
+                "Delegation",
+                "Move work to the person or agent best placed to carry it.",
+                "delegation",
+            ),
+            CategoryDefinition(
+                "learning",
+                "Learning",
+                "Build the smallest useful skill or knowledge for an upcoming task.",
+                "learning",
+            ),
+            CategoryDefinition(
+                "feedback",
+                "Feedback",
+                "Seek a specific reaction that could change the work.",
+                "feedback",
+            ),
+            CategoryDefinition(
+                "reframing",
+                "Reframing",
+                "Interpret the problem differently to unlock a better next move.",
+                "reframing",
+            ),
+            CategoryDefinition(
+                "prioritization",
+                "Prioritization",
+                "Choose what deserves attention among competing commitments.",
+                "prioritization",
+            ),
+            CategoryDefinition(
+                "immediate_next_steps",
+                "Immediate Next Steps",
+                "Identify what can be acted on now from the current state.",
+                "immediate_next_steps",
+            ),
+            CategoryDefinition(
+                "quick_wins",
+                "Quick Wins",
+                "Find a small, inexpensive action with useful near-term payoff.",
+                "quick_wins",
+            ),
+            CategoryDefinition(
+                "long_term_directions",
+                "Long-Term Directions",
+                "Consider capabilities or directions worth pursuing over time.",
+                "long_term_directions",
+            ),
+            CategoryDefinition(
+                "big_bets",
+                "Big Bets",
+                "Examine ambitious changes with high upside and meaningful uncertainty.",
+                "big_bets",
+            ),
+            CategoryDefinition(
+                "business_growth",
+                "Business and Growth",
+                "Improve reach, sustainability, revenue, or customer value.",
+                "business_growth",
+            ),
+            CategoryDefinition(
+                "product_experience",
+                "Product and Experience",
+                "Improve what people can use and how it feels to use it.",
+                "product_experience",
+            ),
+            CategoryDefinition(
+                "technical_possibilities",
+                "Technical Possibilities",
+                "Explore what technology could make materially better or possible.",
+                "technical_possibilities",
+            ),
+        )
+        self._by_id = {item.category_id: item for item in self._definitions}
+
+    def ids(self) -> tuple[str, ...]:
+        """Return identifiers in stable display and selection order."""
+        return tuple(item.category_id for item in self._definitions)
+
+    def definitions(self) -> tuple[CategoryDefinition, ...]:
+        """Return the immutable registry entries."""
+        return self._definitions
+
+    def is_known(self, category_id: str) -> bool:
+        """Accept only exact registry identifiers."""
+        return category_id in self._by_id
+
+    def require_known(self, category_ids: tuple[str, ...]) -> tuple[str, ...]:
+        """Validate selected identifiers without adding inferred categories."""
+        unknown = [item for item in category_ids if item not in self._by_id]
+        if unknown:
+            raise ValueError(f"unknown suggestion categories: {', '.join(sorted(unknown))}")
+        if len(set(category_ids)) != len(category_ids):
+            raise ValueError("suggestion categories must not contain duplicates")
+        return category_ids
+
+    def describe(self, category_id: str) -> CategoryDefinition:
+        """Return one already-validated category definition."""
+        return self._by_id[category_id]
+
+    def category_prompt_exists(self, prompt_name: str) -> bool:
+        """Check that one registry entry resolves to a packaged prompt asset."""
+        from .prompts.library import SuggestionPrompts
+
+        try:
+            return bool(SuggestionPrompts().category_prompt(prompt_name))
+        except (FileNotFoundError, OSError):
+            return False
+
+    def prompt_section(self, category_ids: tuple[str, ...] | None = None) -> str:
+        """Render exactly the selected prompt assets in the selected order."""
+        from .prompts.library import SuggestionPrompts
+
+        selected = (
+            self._definitions
+            if not category_ids
+            else tuple(self._by_id[item] for item in category_ids)
+        )
+        prompts = SuggestionPrompts()
+        return "\n\n".join(prompts.category_prompt(item.prompt_name) for item in selected)
+
+
+__all__ = ["SCHEMA_VERSION", "CategoryDefinition", "SuggestionCategories"]