vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/commands/agents/suggestion/prompts/trajectory.md

@@ -0,0 +1,100 @@
+**Parent Trajectory**
+Parent Trajectory is the named larger effort value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state the path and intent supplied by the parent agent or larger effort.
+This value is completely optional. Supplying it is helpful when the additional signal can change the next action.
+The command keeps this value as caller task data and does not treat it as an instruction to execute work.
+The value is carried into the bounded request with its source and semantic identity intact.
+A precise value gives the generator and independent critic more signal than a broad label or an unstated assumption.
+
+**Purpose of Parent Trajectory**
+The purpose of Parent Trajectory is to make the path and intent supplied by the parent agent or larger effort explicit before candidate generation starts.
+That explicit record lets the workflow compare ideas against the situation the caller actually described.
+It also lets the critic explain whether a candidate is supported, missing evidence, or in conflict.
+The field is most valuable when its content changes feasibility, novelty, timing, risk, or the definition of progress.
+A short accurate statement is more useful than a long narrative that hides the decision-relevant fact.
+The resulting ideas should refer to this signal only when the connection is material and explain why it matters.
+
+**When not to use Parent Trajectory**
+Do not provide Parent Trajectory merely because the option exists or because an empty value would look complete.
+Omit it when the caller has no reliable signal of this kind and let the workflow mark the context as missing.
+Do not use this field to smuggle execution instructions, credentials, private data, or a second command configuration.
+Use a narrower context option when the statement has a clearly different meaning such as a risk, decision, or prohibition.
+Avoid repeating the goal or copying an entire unrelated transcript because repetition lowers the signal available to the critic.
+If the caller is unsure whether the record is current, state that uncertainty in the value rather than presenting it as a fact.
+
+**Parent Trajectory inputs**
+The value is one nonempty text statement per repeated option.
+Repeated occurrences remain separate records so the agent can cite and compare them without parsing a delimiter.
+Whitespace around a value is trimmed at the request boundary, while an empty value is rejected before provider work.
+The command does not reinterpret the content as an identifier unless the option contract explicitly says it is one.
+Use plain caller-readable text and keep each record focused on one fact, choice, boundary, or result.
+The input is bounded before it enters the agent context so oversized content becomes an explicit truncation or omission.
+A caller should keep related facts separate when their provenance, confidence, or expected effect differs enough to influence review.
+
+**Defaults and precedence for Parent Trajectory**
+When it is omitted, the default is no supplied larger effort..
+Command-line values are the only source for this field, and the run does not read a separate configuration document.
+Environment variables do not silently populate this context value, which keeps an invocation reproducible.
+When multiple values are supplied, their command-line order becomes their stable context order.
+Explicit caller input therefore takes precedence over absence, while other settings such as count and rounds remain independent.
+The result manifest records what was supplied and whether the bounded value was included, truncated, or omitted.
+Use the manifest and warnings to distinguish absence from an explicitly bounded value when a downstream agent needs to explain why a suggestion changed.
+
+**Parent Trajectory output contract**
+Parent Trajectory is not printed as a separate progress message because stdout is reserved for the command result.
+For a model-backed run, the value appears inside the fresh managed context window used by the relevant agent.
+For dry-run output, the manifest exposes source identity and bounded character information without exposing file bodies by default.
+Human output summarizes the resulting suggestions, while JSON and JSONL output preserve stable machine-readable fields.
+Errors go to the CLI error channel as typed envelopes with a repair-oriented description and no secret echo.
+The field influences ideas and handoffs but never grants authority, starts work, or changes the caller's permissions.
+
+**How to use Parent Trajectory**
+Use the command below as the smallest valid invocation shape for this value.
+Replace each brace-delimited placeholder with the caller's actual text while preserving shell quoting around spaces.
+Repeat the option when more than one independent record should be supplied.
+Combine the option with a precise goal because the field is evidence or context rather than a standalone task.
+Add category and budget options only when they answer a real selection or resource question.
+The command remains a single argv-built request and does not require a temporary configuration file.
+Keep the invocation close to the caller's actual decision so another agent can reproduce the request without guessing omitted context, quoting, or precedence.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --trajectory "{parent trajectory}"
+```
+
+**Examples for Parent Trajectory**
+A minimal example supplies only the required goal and leaves this optional signal absent when it has no value.
+A normal example adds one focused record that directly changes how the next action should be judged.
+An advanced example repeats the option for several independent records and combines it with a selected category.
+Piping is appropriate only for a caller that captures the emitted result document, because input itself is passed through argv.
+JSON output is the stable choice when another agent will inspect identifiers, manifests, warnings, and handoffs.
+If an example fails, preserve the same goal and correct the named input or path before changing the reasoning settings.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --trajectory "{parent trajectory}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --trajectory "{value}"
+```
+
+**Related commands for Parent Trajectory**
+Use agents suggest categories --view-all when the caller needs to choose a reasoning lens before running.
+Use agents suggest categories --view {category-id} when one category needs a fuller conceptual definition.
+Use the other context options when the signal is more accurately a decision, constraint, risk, or current commitment.
+Use agents suggest handoff only after a result document exists and a specific idea identifier has been selected.
+Use dry-run when the request shape and file manifest need inspection without credentials or model usage.
+These commands share the same result conventions but do not imply that one command can authorize another.
+Choose the narrowest neighboring command that answers the immediate question, then return to this option when the run itself needs the signal.
+
+**Failure modes for Parent Trajectory**
+A missing required value fails before the provider is loaded because the request dataclass requires a meaningful boundary.
+An empty repeated value fails as invalid input instead of becoming a misleading blank context record.
+An unsupported path, malformed JSON file, directory, or unreadable file fails with a typed context error.
+An oversized value is truncated only within the documented bound and the result records that status as a warning.
+A provider or schema failure is reported as a provider failure and is never converted into a false no-suggestions result.
+Recover by correcting the specific value named by the error, rerunning dry-run when useful, and preserving the same intent.
+
+**Authentication and permissions for Parent Trajectory**
+This input itself does not grant access to files, providers, accounts, repositories, or execution tools.
+Text values are available to local validation without credentials, while model-backed runs still require the configured provider.
+The --files option reads only paths explicitly named by the caller and does not scan a workspace or agent history.
+Read-only deny-all settings apply to generator and critic agents so suggestions cannot mutate the host through this workflow.
+Provider credentials are used only when a real model-backed run is requested and are never copied into result prose.
+Permission failures should be repaired at the provider or filesystem boundary rather than by weakening the context contract.

vidbyte_cli/commands/agents/suggestion/prompts/view.md

@@ -0,0 +1,5 @@
+View one expands a single category into its full high-level definition. Pass the exact category identifier shown by the all-categories view. The result includes the authored description and the considerations that guide suggestions of that type.
+
+Use this view when a caller needs to understand the distinction between nearby categories before selecting one. The command reads packaged content locally and makes no model call. An unknown identifier is rejected before any output is produced.
+
+The expanded definition is informative guidance, not an instruction to execute work. It preserves the category's conceptual boundary while leaving concrete actions to a later suggestion run.

vidbyte_cli/commands/agents/suggestion/prompts/view_all.md

@@ -0,0 +1,5 @@
+View all returns the high-level summary of every category in the suggestion registry. It is useful when an agent needs to choose a reasoning lens before building a run.
+
+The default output is the same complete summary list, so callers do not need a separate discovery step. Use the expanded view when the short description is not enough to decide which category fits the goal. This read does not invoke a model or inspect credentials.
+
+The summaries come from the same registry that validates run selections and supplies category context. They describe opportunity types at a conceptual level and intentionally omit provider, prompt, and implementation mechanics.

vidbyte_cli/commands/agents/suggestion/render.py

@@ -0,0 +1,77 @@
+"""Renders suggestion results for human and machine consumers.
+
+Human output prints ranked titles with categories and first actions; JSON
+output emits the versioned envelope. Only results reach stdout, because the
+application layer routes diagnostics to stderr before this module ever runs.
+"""
+
+from __future__ import annotations
+
+from ....lib.output import OutputDocument
+from ....lib.runtime.context import ApplicationContext as Context
+from ....types.suggestions import (
+    SUGGESTIONS_HANDOFF_KIND,
+    SUGGESTIONS_RESULT_KIND,
+    SuggestionFeedbackCapture,
+    SuggestionHandoff,
+    SuggestionIdea,
+    SuggestionResult,
+)
+
+
+class SuggestionRenderer:
+    """Formats batches and handoffs without touching provider or filesystem state."""
+
+    def __init__(self) -> None:
+        # Stateless; formatting depends only on the documents passed per call.
+        pass
+
+    def render_result(self, context: Context, result: SuggestionResult) -> None:
+        # Emits the envelope for machines and a ranked list for humans.
+        context.output().result(
+            OutputDocument(kind=SUGGESTIONS_RESULT_KIND, data=result.model_dump(mode="json")),
+            self._human_result(result),
+        )
+
+    def render_handoff(self, context: Context, handoff: SuggestionHandoff) -> None:
+        # Emits the handoff envelope plus its copyable execution prompt.
+        context.output().result(
+            OutputDocument(kind=SUGGESTIONS_HANDOFF_KIND, data=handoff.model_dump(mode="json")),
+            handoff.execution_prompt,
+        )
+
+    def _human_result(self, result: SuggestionResult) -> str:
+        # One block per idea so a person can scan ranks without parsing JSON.
+        # A generator that stopped to ask for input returns its question instead of ideas.
+        if result.parent_message is not None:
+            rendered = f"Input needed for: {result.goal}\n\n{result.parent_message}"
+        elif not result.ideas:
+            rendered = f"No suggestions for: {result.goal}"
+        else:
+            blocks: list[str] = []
+            for idea in result.ideas:
+                blocks.append(self._human_idea(idea))
+            header = self._human_header(result)
+            rendered = header + "\n\n" + "\n\n".join(blocks)
+        if result.feedback_capture is not None:
+            rendered += "\n\n" + self._human_feedback(result.feedback_capture)
+        return rendered
+
+    def _human_idea(self, idea: SuggestionIdea) -> str:
+        # One ranked line plus its first action on a second line.
+        lead = f"#{idea.rank} {idea.id} [{idea.primary_category}]"
+        return f"{lead} {idea.title}\n  First action: {idea.first_action}"
+
+    def _human_header(self, result: SuggestionResult) -> str:
+        # Counts plus goal plus status so shortfalls read plainly.
+        counts = f"{result.returned_count}/{result.requested_count}"
+        return f"{counts} ideas for: {result.goal} [{result.status.value}]"
+
+    def _human_feedback(self, capture: SuggestionFeedbackCapture) -> str:
+        # A static reminder for the parent agent that never implies feedback already exists.
+        return (
+            "Feedback capture: call accept or reject only after explicit user feedback; "
+            f"use project '{capture.project_key}'.\n"
+            f"  Accept: {capture.accept_command}\n"
+            f"  Reject: {capture.reject_command}"
+        )

vidbyte_cli/commands/agents/suggestion/request_builder.py

@@ -0,0 +1,240 @@
+"""Builds one strict suggestion request from parsed command values.
+
+The input dataclass owns argv validation and the builder owns file and project resolution.
+Caller-facing help is kept at the CLI boundary and never copied into agent context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+from pydantic import ValidationError
+
+from ....lib.config import VidbytePaths
+from ....lib.errors.failures import (
+    SuggestionContextUnreadable,
+    SuggestionInputInvalid,
+    SuggestionProjectInvalid,
+)
+from ....services.suggestions.categories import SuggestionCategories
+from ....services.suggestions.context import SuggestionContextBuilder
+from ....services.suggestions.project import SuggestionProject, SuggestionProjectKey
+from ....types.suggestions import (
+    SuggestionContextPrimitive,
+    SuggestionHorizon,
+    SuggestionRequest,
+    SuggestionSettings,
+)
+from ...agent_options import AgentAttachmentOptions
+
+_CONTEXT_FIELD_NAMES = (
+    "context",
+    "completed",
+    "in_progress",
+    "decision",
+    "constraint",
+    "avoid",
+    "mistakes",
+    "forbidden",
+    "approaches",
+    "outcomes",
+    "blockers",
+    "hypotheses",
+    "risks",
+    "trajectory",
+    "question",
+    "capability",
+    "success",
+)
+_HORIZONS = frozenset(item.value for item in SuggestionHorizon)
+_PROVIDERS = frozenset({"openai"})
+
+
+@dataclass(frozen=True, slots=True)
+class SuggestionRunInput:
+    """Strict, canonical representation of one Click invocation."""
+
+    goal: str = ""
+    project: str | None = None
+    context: tuple[str, ...] = ()
+    completed: tuple[str, ...] = ()
+    in_progress: tuple[str, ...] = ()
+    decision: tuple[str, ...] = ()
+    constraint: tuple[str, ...] = ()
+    avoid: tuple[str, ...] = ()
+    mistakes: tuple[str, ...] = ()
+    forbidden: tuple[str, ...] = ()
+    approaches: tuple[str, ...] = ()
+    outcomes: tuple[str, ...] = ()
+    blockers: tuple[str, ...] = ()
+    hypotheses: tuple[str, ...] = ()
+    risks: tuple[str, ...] = ()
+    trajectory: tuple[str, ...] = ()
+    question: tuple[str, ...] = ()
+    capability: tuple[str, ...] = ()
+    success: tuple[str, ...] = ()
+    files: tuple[Path, ...] = ()
+    attachments: tuple[Path, ...] = ()
+    count: int = 5
+    categories: tuple[str, ...] = ()
+    all_categories: bool = False
+    extra_compute: bool = False
+    horizon: str = "any"
+    rounds: int = 2
+    max_messages: int = 2
+    provider: str | None = None
+    critic_model: str | None = None
+    max_output_tokens: int | None = None
+    max_total_tokens: int | None = None
+    timeout_seconds: int | None = None
+    dry_run: bool = False
+
+    def __post_init__(self) -> None:
+        self._validate_goal()
+        self._validate_context_values()
+        self._validate_files()
+        self._validate_attachments()
+        self._validate_selection()
+        self._validate_execution_settings()
+        self._validate_limits()
+
+    def _validate_goal(self) -> None:
+        if not self.goal.strip() or len(self.goal) > 4096:
+            raise ValueError("goal must be a non-empty string of at most 4096 characters")
+        if self.project is not None and type(self.project) is not str:
+            raise TypeError("project must be omitted or a string")
+
+    def _validate_context_values(self) -> None:
+        for name in _CONTEXT_FIELD_NAMES:
+            values = getattr(self, name)
+            if not isinstance(values, tuple) or any(
+                type(value) is not str or not value.strip() for value in values
+            ):
+                raise ValueError(f"{name} must contain only non-empty strings")
+
+    def _validate_files(self) -> None:
+        if not isinstance(self.files, tuple) or any(
+            not isinstance(path, Path) for path in self.files
+        ):
+            raise TypeError("files must contain only pathlib.Path values")
+
+    def _validate_attachments(self) -> None:
+        # Keeps the shared resolver's input contract explicit at the request boundary.
+        if not isinstance(self.attachments, tuple) or any(
+            not isinstance(path, Path) for path in self.attachments
+        ):
+            raise TypeError("attachments must contain only pathlib.Path values")
+
+    def _validate_selection(self) -> None:
+        if type(self.count) is not int or not 2 <= self.count <= 15:
+            raise ValueError("count must be between 2 and 15")
+        if not isinstance(self.categories, tuple) or any(
+            type(category) is not str or not category.strip() for category in self.categories
+        ):
+            raise ValueError("categories must contain only non-empty strings")
+        if len(set(self.categories)) != len(self.categories):
+            raise ValueError("categories must not contain duplicates")
+        SuggestionCategories().require_known(self.categories)
+        if type(self.all_categories) is not bool or type(self.extra_compute) is not bool:
+            raise TypeError("all_categories and extra_compute must be booleans")
+        if self.all_categories and self.categories:
+            raise ValueError("all_categories and categories cannot both be selected")
+
+    def _validate_execution_settings(self) -> None:
+        if type(self.horizon) is not str or self.horizon not in _HORIZONS:
+            raise ValueError("horizon must be now, next, later, or any")
+        if type(self.rounds) is not int or not 1 <= self.rounds <= 8:
+            raise ValueError("rounds must be between 1 and 8")
+        if type(self.max_messages) is not int or not 0 <= self.max_messages <= 8:
+            raise ValueError("max_messages must be between 0 and 8")
+        if type(self.provider) is not str and self.provider is not None:
+            raise TypeError("provider must be omitted or a string")
+        if self.provider is not None and self.provider not in _PROVIDERS:
+            raise ValueError("provider must be openai or omitted")
+        if self.critic_model is not None and (
+            type(self.critic_model) is not str or not self.critic_model.strip()
+        ):
+            raise ValueError("critic_model must be omitted or a non-empty string")
+
+    def _validate_limits(self) -> None:
+        if any(
+            value is not None and (type(value) is not int or value <= 0)
+            for value in (self.max_output_tokens, self.max_total_tokens, self.timeout_seconds)
+        ):
+            raise ValueError("token and timeout limits must be positive integers")
+        if self.max_output_tokens is not None and self.max_output_tokens > 5_000_000:
+            raise ValueError("max_output_tokens cannot exceed 5000000")
+        if self.max_total_tokens is not None and self.max_total_tokens > 20_000_000:
+            raise ValueError("max_total_tokens cannot exceed 20000000")
+        if self.timeout_seconds is not None and self.timeout_seconds > 86_400:
+            raise ValueError("timeout_seconds cannot exceed 86400")
+        if type(self.dry_run) is not bool:
+            raise TypeError("dry_run must be a boolean")
+
+
+class SuggestionRequestBuilder:
+    """Resolves one validated invocation into a service request."""
+
+    def build(self, raw: dict[str, object], paths: VidbytePaths | None = None) -> SuggestionRequest:
+        try:
+            values = SuggestionRunInput(**cast(dict[str, Any], raw))
+        except (TypeError, ValueError) as error:
+            raise SuggestionInputInvalid() from error
+        fields = {
+            name: getattr(values, name) for name in _CONTEXT_FIELD_NAMES if getattr(values, name)
+        }
+        project_key = self._project_key(values.project)
+        if project_key is not None:
+            # Project memory joins after caller flags, so caller refs keep their numbering.
+            fields.update(SuggestionProject(paths).context_fields(project_key))
+        try:
+            snapshot = SuggestionContextBuilder().build(fields, values.files)
+        except ValueError as error:
+            raise SuggestionContextUnreadable(str(error)) from error
+        attachments = AgentAttachmentOptions().resolve({"attachments": values.attachments})
+        try:
+            settings = SuggestionSettings(
+                requested_count=values.count,
+                categories=values.categories,
+                all_categories=values.all_categories,
+                extra_compute=values.extra_compute,
+                horizon=SuggestionHorizon(values.horizon),
+                rounds=values.rounds,
+                max_messages=values.max_messages,
+                provider=values.provider,
+                critic_model=values.critic_model,
+                max_output_tokens=values.max_output_tokens,
+                max_total_tokens=values.max_total_tokens,
+                timeout_seconds=values.timeout_seconds,
+                dry_run=values.dry_run,
+            )
+            return SuggestionRequest(
+                goal=values.goal,
+                context=SuggestionContextPrimitive(
+                    goal=values.goal,
+                    description="Caller-supplied task data for this suggestion run.",
+                    items=snapshot.items,
+                    selected_categories=SuggestionCategories().prompt_section(values.categories),
+                ),
+                context_manifest=snapshot.manifest,
+                context_warnings=snapshot.warnings,
+                settings=settings,
+                attachments=attachments,
+                project_key=project_key.value if project_key else None,
+            )
+        except (ValidationError, ValueError) as error:
+            raise SuggestionInputInvalid() from error
+
+    def _project_key(self, project: str | None) -> SuggestionProjectKey | None:
+        # A malformed key is a project error, not a goal error, so its repair names --project.
+        if project is None:
+            return None
+        try:
+            return SuggestionProjectKey(project)
+        except (TypeError, ValueError) as error:
+            raise SuggestionProjectInvalid(str(error)) from error
+
+
+__all__ = ["SuggestionRequestBuilder", "SuggestionRunInput"]

vidbyte_cli/commands/agents/suggestion/suggest.py

@@ -0,0 +1,154 @@
+"""Parses suggest-run options, then invokes the validated suggestion service.
+
+The command owns only argv shape and Click choices. Request and settings
+validation complete before the service loads the provider or starts an agent.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ....lib.runtime.context import ApplicationContext as Context
+from ....services.suggestions.categories import SuggestionCategories
+from ....services.suggestions.service import SuggestionService
+from ...agent_options import AgentAttachmentOptions
+from .prompts.library import SuggestionHelpLibrary
+from .render import SuggestionRenderer
+from .request_builder import SuggestionRequestBuilder
+
+_HELP = SuggestionHelpLibrary()
+_COMMAND_HELP = _HELP.load("run")
+_GOAL_HELP = _HELP.load("goal")
+_PROJECT_HELP = _HELP.load("project")
+_CONTEXT_HELP = _HELP.load("context")
+_FILES_HELP = _HELP.load("files")
+_COMPLETED_HELP = _HELP.load("completed")
+_IN_PROGRESS_HELP = _HELP.load("in_progress")
+_DECISION_HELP = _HELP.load("decision")
+_CONSTRAINT_HELP = _HELP.load("constraint")
+_AVOID_HELP = _HELP.load("avoid")
+_QUESTION_HELP = _HELP.load("question")
+_CAPABILITY_HELP = _HELP.load("capability")
+_SUCCESS_HELP = _HELP.load("success")
+_COUNT_HELP = _HELP.load("count")
+_CATEGORY_HELP = _HELP.load("category")
+_ALL_CATEGORIES_HELP = _HELP.load("all_categories")
+_HORIZON_HELP = _HELP.load("horizon")
+_ROUNDS_HELP = _HELP.load("rounds")
+_MAX_MESSAGES_HELP = _HELP.load("max_messages")
+_PROVIDER_HELP = _HELP.load("provider")
+_CRITIC_MODEL_HELP = _HELP.load("critic_model")
+_EXTRA_COMPUTE_HELP = _HELP.load("extra_compute")
+_MAX_OUTPUT_TOKENS_HELP = _HELP.load("max_output_tokens")
+_MAX_TOTAL_TOKENS_HELP = _HELP.load("max_total_tokens")
+_TIMEOUT_HELP = _HELP.load("timeout")
+_DRY_RUN_HELP = _HELP.load("dry_run")
+_MISTAKES_HELP = _HELP.load("mistakes")
+_FORBIDDEN_HELP = _HELP.load("forbidden")
+_APPROACHES_HELP = _HELP.load("approaches")
+_OUTCOMES_HELP = _HELP.load("outcomes")
+_BLOCKERS_HELP = _HELP.load("blockers")
+_HYPOTHESES_HELP = _HELP.load("hypotheses")
+_RISKS_HELP = _HELP.load("risks")
+_TRAJECTORY_HELP = _HELP.load("trajectory")
+_ATTACHMENT_OPTIONS = AgentAttachmentOptions()
+
+
+class SuggestRunCommand:
+    """Validates run options ahead of any model call, then renders the result."""
+
+    def register(self, parent: click.Group) -> None:
+        # Attaches run with goal, context, generation, and budget controls.
+        @parent.command(name="run", help=_COMMAND_HELP)
+        @click.option("--goal", default=None, help=_GOAL_HELP)
+        @click.option("--project", default=None, help=_PROJECT_HELP)
+        @click.option("--context", "context", multiple=True, help=_CONTEXT_HELP)
+        @click.option(
+            "--files",
+            "files",
+            multiple=True,
+            type=click.Path(path_type=Path),
+            help=_FILES_HELP,
+        )
+        @_ATTACHMENT_OPTIONS.apply
+        @click.option("--completed", "completed", multiple=True, help=_COMPLETED_HELP)
+        @click.option("--in-progress", "in_progress", multiple=True, help=_IN_PROGRESS_HELP)
+        @click.option("--decision", "decision", multiple=True, help=_DECISION_HELP)
+        @click.option("--constraint", "constraint", multiple=True, help=_CONSTRAINT_HELP)
+        @click.option("--avoid", "avoid", multiple=True, help=_AVOID_HELP)
+        @click.option("--mistakes", "mistakes", multiple=True, help=_MISTAKES_HELP)
+        @click.option("--forbidden", "forbidden", multiple=True, help=_FORBIDDEN_HELP)
+        @click.option("--approaches", "approaches", multiple=True, help=_APPROACHES_HELP)
+        @click.option("--outcomes", "outcomes", multiple=True, help=_OUTCOMES_HELP)
+        @click.option("--blockers", "blockers", multiple=True, help=_BLOCKERS_HELP)
+        @click.option("--hypotheses", "hypotheses", multiple=True, help=_HYPOTHESES_HELP)
+        @click.option("--risks", "risks", multiple=True, help=_RISKS_HELP)
+        @click.option("--trajectory", "trajectory", multiple=True, help=_TRAJECTORY_HELP)
+        @click.option("--question", "question", multiple=True, help=_QUESTION_HELP)
+        @click.option("--capability", "capability", multiple=True, help=_CAPABILITY_HELP)
+        @click.option("--success", "success", multiple=True, help=_SUCCESS_HELP)
+        @click.option(
+            "--count", type=click.IntRange(2, 15), default=5, show_default=True, help=_COUNT_HELP
+        )
+        @click.option(
+            "--category",
+            "categories",
+            multiple=True,
+            type=click.Choice(SuggestionCategories().ids()),
+            help=_CATEGORY_HELP,
+        )
+        @click.option("--all-categories", is_flag=True, default=False, help=_ALL_CATEGORIES_HELP)
+        @click.option(
+            "--horizon",
+            type=click.Choice(("now", "next", "later", "any")),
+            default="any",
+            show_default=True,
+            help=_HORIZON_HELP,
+        )
+        @click.option(
+            "--rounds", type=click.IntRange(1, 8), default=2, show_default=True, help=_ROUNDS_HELP
+        )
+        @click.option(
+            "--max-messages",
+            "max_messages",
+            type=click.IntRange(0, 8),
+            default=2,
+            show_default=True,
+            help=_MAX_MESSAGES_HELP,
+        )
+        @click.option(
+            "--provider",
+            type=click.Choice(("openai",)),
+            default=None,
+            help=_PROVIDER_HELP,
+        )
+        @click.option("--critic-model", "critic_model", default=None, help=_CRITIC_MODEL_HELP)
+        @click.option("--extra-compute", is_flag=True, default=False, help=_EXTRA_COMPUTE_HELP)
+        @click.option(
+            "--max-output-tokens",
+            type=click.IntRange(1, 5000000),
+            default=None,
+            help=_MAX_OUTPUT_TOKENS_HELP,
+        )
+        @click.option(
+            "--max-total-tokens",
+            type=click.IntRange(1, 20000000),
+            default=None,
+            help=_MAX_TOTAL_TOKENS_HELP,
+        )
+        @click.option(
+            "--timeout-seconds", type=click.IntRange(1, 86400), default=None, help=_TIMEOUT_HELP
+        )
+        @click.option("--dry-run", is_flag=True, default=False, help=_DRY_RUN_HELP)
+        @click.pass_obj
+        def _run(ctx: Context, /, **kwargs: object) -> None:
+            # Delegates parsed values to the testable execution method.
+            self.execute(ctx, kwargs)
+
+    def execute(self, context: Context, raw: dict[str, object]) -> None:
+        # Everything invalid fails here, before files are read or models run.
+        request = SuggestionRequestBuilder().build(raw, context.paths())
+        result = SuggestionService().run(request)
+        SuggestionRenderer().render_result(context, result)

vidbyte_cli/commands/agents/suggestion/suggestion_categories.py

@@ -0,0 +1,77 @@
+"""Lists or expands the suggestion category registry without model work."""
+
+from __future__ import annotations
+
+import click
+from pydantic import JsonValue
+
+from ....lib.output import OutputDocument
+from ....lib.runtime.context import ApplicationContext as Context
+from ....services.suggestions.categories import (
+    SCHEMA_VERSION,
+    CategoryDefinition,
+    SuggestionCategories,
+)
+from ....services.suggestions.prompts.library import SuggestionPrompts
+from .prompts.library import SuggestionHelpLibrary
+
+_COMMAND_HELP = SuggestionHelpLibrary().load("categories")
+_VIEW_ALL_HELP = SuggestionHelpLibrary().load("view_all")
+_VIEW_HELP = SuggestionHelpLibrary().load("view")
+
+
+class SuggestionCategoriesCommand:
+    """Renders summaries for all categories or the full definition for one category."""
+
+    def register(self, parent: click.Group) -> None:
+        # The Choice is registry-owned, so CLI validation and displayed ids cannot drift.
+        @parent.command(name="categories", help=_COMMAND_HELP)
+        @click.option("--view-all", is_flag=True, help=_VIEW_ALL_HELP)
+        @click.option(
+            "--view",
+            "view_id",
+            type=click.Choice(SuggestionCategories().ids()),
+            default=None,
+            help=_VIEW_HELP,
+        )
+        @click.pass_obj
+        def _categories(ctx: Context, view_all: bool, view_id: str | None) -> None:
+            self.execute(ctx, view_all=view_all, view_id=view_id)
+
+    def execute(self, context: Context, *, view_all: bool, view_id: str | None) -> None:
+        if view_all and view_id:
+            raise click.UsageError("--view-all and --view cannot be used together.")
+        registry = SuggestionCategories()
+        prompts = SuggestionPrompts()
+        if view_id:
+            definition = registry.describe(view_id)
+            entries: list[JsonValue] = [
+                self._expanded(definition, prompts.category_prompt(definition.prompt_name))
+            ]
+            human = prompts.category_prompt(definition.prompt_name)
+        else:
+            entries = [self._summary(item) for item in registry.definitions()]
+            human = "\n\n".join(self._human_summary(item) for item in registry.definitions())
+        data: dict[str, JsonValue] = {
+            "schema_version": SCHEMA_VERSION,
+            "view": "category" if view_id else "all",
+            "categories": entries,
+        }
+        context.output().result(OutputDocument(kind="suggestions.categories", data=data), human)
+
+    def _summary(self, item: CategoryDefinition) -> dict[str, JsonValue]:
+        return {"id": item.category_id, "title": item.title, "summary": item.summary}
+
+    def _expanded(self, item: CategoryDefinition, prompt: str) -> dict[str, JsonValue]:
+        return {
+            "id": item.category_id,
+            "title": item.title,
+            "summary": item.summary,
+            "prompt": prompt,
+        }
+
+    def _human_summary(self, item: CategoryDefinition) -> str:
+        return f"{item.category_id} — {item.title}: {item.summary}"
+
+
+__all__ = ["SuggestionCategoriesCommand"]