okstra 0.163.2 → 0.165.0

package/runtime/python/okstra_ctl/domain/provider.py

@@ -0,0 +1,70 @@
+"""Provider and model value objects shared by the registry and adapters."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Mapping, Optional
+
+if TYPE_CHECKING:
+    from okstra_ctl.domain.worker_exec import ExecutionStrategy
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    display: str
+    execution: str
+    pricing: Optional[tuple[float, float, float]] = None
+    in_picker: bool = False
+
+
+@dataclass(frozen=True)
+class LeadLaunchSpec:
+    """How to start a provider CLI as an interactive lead session."""
+
+    executable: str
+    model_flag: str
+    prompt_flag: str = ""
+    start_session_id_flag: str = ""
+    resume_session_id_flag: str = ""
+    sandbox_waiver: tuple[str, ...] = ()
+    sandbox_waiver_note: str = ""
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    provider: str
+    display_label: str
+    models: Mapping[str, ModelSpec]
+    default_models: Mapping[str, str]
+    wrapper: str
+    supported_roles: frozenset[str]
+    lead_launch: Optional[LeadLaunchSpec] = None
+    exec_strategy: Optional["ExecutionStrategy"] = None
+
+
+@dataclass(frozen=True)
+class RunnerResolution:
+    runner: str
+    wrapper: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class LeadProviderAssignment:
+    provider: str
+    runner: str
+    wrapper: str
+    reason: str
+
+
+@dataclass
+class ModelAssignment:
+    display: str
+    execution: str
+
+
+class UnknownModelError(ValueError):
+    """Raised when a provider has no model alias matching a raw value."""
+
+
+class UnknownProviderError(ValueError):
+    """Raised when a requested provider is absent from the registry."""

package/runtime/python/okstra_ctl/domain/wizard/__init__.py

@@ -0,0 +1,19 @@
+"""Wizard interaction domain values and answer normalization."""
+
+from .interaction import (
+    AnswerProtocol,
+    InteractionPlan,
+    WizardAnswerError,
+    WizardOption,
+    WizardPrompt,
+    normalize_planned_answer,
+)
+
+__all__ = [
+    "AnswerProtocol",
+    "InteractionPlan",
+    "WizardAnswerError",
+    "WizardOption",
+    "WizardPrompt",
+    "normalize_planned_answer",
+]

package/runtime/python/okstra_ctl/domain/wizard/interaction.py

@@ -0,0 +1,140 @@
+"""Host-neutral wizard prompts, interaction plans, and answer protocols."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class WizardOption:
+    value: str
+    label: str
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class WizardPrompt:
+    step: str
+    kind: Literal["pick", "text", "pick_group", "done", "aborted"]
+    label: str = ""
+    options: tuple[WizardOption, ...] = ()
+    help: str = ""
+    echo_template: str = ""
+    multi: bool = False
+    questions: tuple["WizardPrompt", ...] = ()
+
+
+@dataclass(frozen=True)
+class AnswerProtocol:
+    kind: Literal["exact-value", "numbered", "group-json", "numbered-group-json"]
+    multi: bool = False
+
+
+@dataclass(frozen=True)
+class InteractionPlan:
+    kind: Literal[
+        "native-single",
+        "native-multi",
+        "native-group",
+        "numbered-single",
+        "numbered-multi",
+        "sequential-group",
+        "plain-text",
+    ]
+    answer_protocol: AnswerProtocol
+
+
+class WizardAnswerError(ValueError):
+    """Raised when an answer violates the interaction plan's protocol."""
+
+
+def _normalize_numbered_item(prompt: WizardPrompt, answer: str) -> str:
+    candidate = (answer or "").strip()
+    exact_values = tuple(
+        option.value for option in prompt.options if option.value == candidate
+    )
+    if exact_values:
+        return exact_values[0]
+    if candidate.isdecimal():
+        number = int(candidate)
+        if 1 <= number <= len(prompt.options):
+            return prompt.options[number - 1].value
+        raise WizardAnswerError(f"numbered-text answer is out of range: {candidate}")
+    label_values = tuple(
+        option.value for option in prompt.options if option.label == candidate
+    )
+    if len(label_values) == 1:
+        return label_values[0]
+    if len(label_values) > 1:
+        raise WizardAnswerError(
+            f"numbered-text answer label is ambiguous: {candidate}"
+        )
+    raise WizardAnswerError(f"numbered-text answer is not an option: {candidate}")
+
+
+def _normalize_numbered_answer(
+    prompt: WizardPrompt,
+    answer: str,
+    *,
+    multi: bool,
+) -> str:
+    if not multi:
+        return _normalize_numbered_item(prompt, answer)
+    if not (answer or "").strip():
+        return ""
+    return ",".join(
+        _normalize_numbered_item(prompt, item)
+        for item in answer.split(",")
+    )
+
+
+def _group_answers(answer: str) -> dict[str, object]:
+    try:
+        answers = json.loads(answer or "{}")
+    except json.JSONDecodeError as exc:
+        raise WizardAnswerError(f"group answer must be a JSON object: {exc}") from exc
+    if not isinstance(answers, dict):
+        raise WizardAnswerError("group answer must be a JSON object")
+    return answers
+
+
+def _normalize_group_answer(
+    prompt: WizardPrompt,
+    answer: str,
+    *,
+    numbered: bool,
+) -> str:
+    answers = _group_answers(answer)
+    if not numbered:
+        return json.dumps(answers, ensure_ascii=False, separators=(",", ":"))
+    questions = {question.step: question for question in prompt.questions}
+    normalized = dict(answers)
+    for step, raw_answer in answers.items():
+        question = questions.get(step)
+        if question is None:
+            continue
+        normalized[step] = _normalize_numbered_answer(
+            question,
+            str(raw_answer or ""),
+            multi=question.multi,
+        )
+    return json.dumps(normalized, ensure_ascii=False, separators=(",", ":"))
+
+
+def normalize_planned_answer(
+    prompt: WizardPrompt,
+    protocol: AnswerProtocol,
+    answer: str,
+) -> str:
+    if protocol.kind == "exact-value":
+        return answer
+    if protocol.kind == "numbered":
+        return _normalize_numbered_answer(prompt, answer, multi=protocol.multi)
+    if protocol.kind in {"group-json", "numbered-group-json"}:
+        return _normalize_group_answer(
+            prompt,
+            answer,
+            numbered=protocol.kind == "numbered-group-json",
+        )
+    raise WizardAnswerError(f"unsupported answer protocol: {protocol.kind}")

package/runtime/python/okstra_ctl/domain/worker_exec.py

@@ -0,0 +1,102 @@
+"""Provider-neutral execution contracts shared by the dispatcher and workers.
+
+A worker run is decided along three axes: which terminal surface it lands on,
+which provider CLI runs it, and which role it plays. This module owns the
+provider axis' vocabulary plus the one rule that is identical for every worker
+regardless of provider — see ``ExecutionPolicy``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from .worker_stream import Normalise, no_events
+
+# What ``ExecCommand.stream_format`` may hold. The value decides whether the
+# runner pipes the CLI's output through the stream formatter or forwards it
+# unchanged, so it is part of the contract rather than a display hint.
+STREAM_JSON = "stream-json"
+TEXT = "text"
+
+
+@dataclass(frozen=True)
+class ExecutionPolicy:
+    """How a non-interactive worker is allowed to act.
+
+    Identical for every worker: nobody is at the keyboard to answer an approval
+    prompt, so the gate has to be open and the boundary has to come from a
+    sandbox instead. Declared once here rather than per provider, because a
+    policy that lives in one adapter file per provider drifts into one policy
+    per provider.
+    """
+
+    auto_approve: bool
+    write_scope: tuple[Path, ...]
+
+
+@dataclass(frozen=True)
+class WorkerExecRequest:
+    """One worker dispatch, before any provider has looked at it.
+
+    ``worktree_path`` is the stage tree this run was given, or None for a
+    dispatch that works in the project itself. It is kept apart from
+    ``policy.write_scope`` because the two answer different questions: the scope
+    is what may be written, while this is where the run belongs. Providers
+    disagree on that second answer, so the request carries both and each
+    strategy decides.
+    """
+
+    prompt_text: str
+    model: str
+    project_root: Path
+    worktree_path: Path | None
+    policy: ExecutionPolicy
+    idle_timeout_seconds: int
+
+
+@dataclass(frozen=True)
+class ExecCommand:
+    """One provider invocation, fully resolved.
+
+    ``stdin_text`` is None when the provider takes its prompt as an argument
+    rather than on stdin.
+
+    ``cwd`` is part of the contract because it is not derivable from the argv:
+    some CLIs name their working directory in a flag, others inherit the
+    process's, and the two groups do not choose the same directory. A runner
+    that had to re-derive it would be guessing at what the strategy already
+    decided.
+
+    ``normalise`` is the companion of ``stream_format``: declaring a JSON stream
+    without saying how to read it is what left one provider's pane blank for a
+    whole run. The two are named together so a provider whose events are shaped
+    differently cannot be silently handed a formatter that cannot see them.
+    """
+
+    argv: tuple[str, ...]
+    stdin_text: str | None
+    stream_format: str
+    cwd: Path
+    normalise: Normalise = field(default=no_events)
+
+
+@dataclass(frozen=True)
+class PolicySupport:
+    """Whether a provider CLI can express ``ExecutionPolicy`` at all.
+
+    A provider that cannot must say so rather than quietly accepting the policy
+    and running without it. ``note`` carries the reason and is what the contract
+    test asserts on.
+    """
+
+    can_auto_approve: bool
+    can_bound_write_scope: bool
+    note: str = ""
+
+
+@runtime_checkable
+class ExecutionStrategy(Protocol):
+    def build_command(self, request: WorkerExecRequest) -> ExecCommand: ...
+
+    def policy_support(self) -> PolicySupport: ...

package/runtime/python/okstra_ctl/domain/worker_role.py

@@ -0,0 +1,34 @@
+"""Per-role execution parameters.
+
+Roles differ by value, not by algorithm, so this is a value object rather than
+a strategy. Owning the values here takes the final say back from the shell: the
+dispatcher passed a global idle budget while each wrapper quietly overrode it
+with its own `case "$role"` block.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Implementation executor / verifier dispatches run whole build + test suites
+# that legitimately emit nothing for minutes; the 600s cap reaped them mid-suite
+# (observed: a silent jest + tsc build TERM'd at ~929s). This stays below the
+# 1800s wall-clock polling cap so a genuine hang is still reaped first.
+_BUILD_RUNNING_IDLE_SECONDS = 1500
+_DEFAULT_IDLE_SECONDS = 600
+
+_BUILD_RUNNING_ROLES = frozenset({"executor", "verifier"})
+
+
+@dataclass(frozen=True)
+class WorkerRoleSpec:
+    role: str
+    idle_timeout_seconds: int
+
+
+def role_spec(role: str) -> WorkerRoleSpec:
+    seconds = (
+        _BUILD_RUNNING_IDLE_SECONDS
+        if role in _BUILD_RUNNING_ROLES
+        else _DEFAULT_IDLE_SECONDS
+    )
+    return WorkerRoleSpec(role=role, idle_timeout_seconds=seconds)

package/runtime/python/okstra_ctl/domain/worker_stream.py

@@ -0,0 +1,261 @@
+"""Turn a worker's progress into lines a person can read.
+
+Pure transformation: no files, no sockets, no clock. The runner decides where
+the lines go; this module decides what they say.
+
+Providers do not agree on a wire format, and this layer may not name one. So the
+formatter never reads a provider's JSON: it reads the normalised events below,
+and each provider adapter supplies the function that produces them from its own
+wire shape (``ExecCommand.normalise``). One wire shape is shared widely enough
+to be worth a default here — ``content_block_events``, whose events are keyed on
+``type`` and carry ``message.content`` blocks — but it is a schema, not a
+provider, and an adapter that speaks something else says so in its own file.
+
+Screen output folds what the log keeps in full — a tool call becomes one line, a
+tool result becomes an outcome and a size. Thinking is dropped at normalisation,
+which is safe only because worker liveness is measured from stream arrival
+rather than from log writes (see the spec's 7.2).
+
+Three projections of the same stream: ``format_live`` for the pane,
+``format_log`` for the archive, and ``final_text`` for the caller that must
+receive the closing message without the progress that produced it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+# Worker panes sit in a two-column grid whose narrowest allowed pane is the
+# floor named by the placement module (60 columns at the time of writing).
+# Holding a summary to two such lines keeps one tool call from pushing the
+# previous one off the top of a short pane.
+_MAX_SUMMARY = 120
+
+
+@dataclass(frozen=True)
+class Text:
+    """Prose the worker addressed to whoever is reading."""
+
+    body: str
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """A tool the worker invoked, and the argument worth naming on one row."""
+
+    name: str
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """What a tool returned.
+
+    ``size_bytes`` is carried rather than derived from ``body`` because the two
+    answer different questions: the size is how much the tool produced, while
+    the body is what the archive is willing to keep of it.
+
+    ``failed`` is None when the stream closed the tool step without reporting an
+    outcome at all. Reading that absence as success would put a confident "ok"
+    next to a command that failed.
+    """
+
+    body: str
+    size_bytes: int
+    failed: bool | None = None
+
+
+@dataclass(frozen=True)
+class Denial:
+    """A tool call the provider refused before the worker could make it."""
+
+    tool: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class Result:
+    """The worker's closing message. At most one per run."""
+
+    text: str
+
+
+StreamEvent = Text | ToolCall | ToolResult | Denial | Result
+
+# What an adapter hands the runner alongside its stream format: one line of the
+# CLI's output, already parsed, turned into however many normalised events it
+# carries. Returning nothing is how an event is dropped.
+Normalise = Callable[[Mapping[str, Any]], tuple[StreamEvent, ...]]
+
+
+def no_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    """The normaliser for a CLI that emits no events at all.
+
+    A text CLI's output is already what a person reads, so the runner forwards
+    it whole and never calls this. It exists so ``ExecCommand`` can default to
+    a truthful "there is nothing here to normalise" instead of to some
+    provider's schema.
+    """
+    return ()
+
+
+def content_block_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    """Normalise the stream shape keyed on ``type`` with ``message.content``.
+
+    Assistant events carry the worker's prose and its tool calls in the same
+    content list, so one event becomes several normalised ones. Thinking blocks
+    and everything unrecognised are dropped here rather than in the formatter:
+    what is worth reading is a property of the stream, not of the projection.
+    """
+    kind = event.get("type")
+    if kind == "assistant":
+        return tuple(
+            item
+            for block in _content_blocks(event)
+            if (item := _assistant_event(block)) is not None
+        )
+    if kind == "user":
+        return tuple(
+            _tool_result(block)
+            for block in _content_blocks(event)
+            if block.get("type") == "tool_result"
+        )
+    if kind == "system" and event.get("subtype") == "permission_denied":
+        return (
+            Denial(
+                tool=str(event.get("tool_name", "?")),
+                reason=str(event.get("decision_reason", "")).strip(),
+            ),
+        )
+    if kind == "result" and isinstance(event.get("result"), str):
+        return (Result(text=str(event["result"])),)
+    return ()
+
+
+def format_live(event: StreamEvent) -> list[str]:
+    return _rows(event, limit=_MAX_SUMMARY, include_body=False)
+
+
+def format_log(event: StreamEvent) -> list[str]:
+    """What the archive keeps: everything the screen shows, plus the bodies.
+
+    The log is no longer a live window — the worker pane is. It is read after
+    the fact, by a person reconstructing why a worker failed and by
+    ``okstra log-report``.
+    """
+    return _rows(event, limit=None, include_body=True)
+
+
+def final_text(event: StreamEvent) -> str | None:
+    """The worker's closing message, or None for any other event."""
+    return event.text if isinstance(event, Result) else None
+
+
+def _rows(event: StreamEvent, *, limit: int | None, include_body: bool) -> list[str]:
+    if isinstance(event, Text):
+        return _body_rows(event.body)
+    if isinstance(event, ToolCall):
+        head = f"→ {event.name}: {event.detail}" if event.detail else f"→ {event.name}"
+        return [_truncate(head, limit)]
+    if isinstance(event, ToolResult):
+        rows = [f"  ← {_outcome(event.failed)} ({event.size_bytes} bytes)"]
+        if include_body:
+            rows.extend(_body_rows(event.body))
+        return rows
+    if isinstance(event, Denial):
+        return [_truncate(f"!! PERMISSION DENIED — {event.tool}: {event.reason}", limit)]
+    # A Result is printed by the runner at the point the run ends, not woven
+    # into the progress it interrupts.
+    return []
+
+
+def _outcome(failed: bool | None) -> str:
+    if failed is None:
+        return "done"
+    return "error" if failed else "ok"
+
+
+def _body_rows(text: str) -> list[str]:
+    """One screen row per line, with every blank row dropped.
+
+    Blank rows are dropped wherever they sit, not only at the end: a tool that
+    double-spaces its output would otherwise take twice the pane height it
+    earns, and a body that ends in newlines would pad the archive.
+    """
+    return [part for part in text.splitlines() if part.strip()]
+
+
+def _assistant_event(block: Mapping[str, Any]) -> StreamEvent | None:
+    if block.get("type") == "text":
+        return Text(body=str(block.get("text", "")))
+    if block.get("type") == "tool_use":
+        return ToolCall(
+            name=str(block.get("name", "tool")), detail=_tool_detail(block.get("input"))
+        )
+    return None
+
+
+def _tool_detail(payload: Any) -> str:
+    if not isinstance(payload, Mapping):
+        return ""
+    for key in ("command", "file_path", "path", "pattern", "query"):
+        value = payload.get(key)
+        if value:
+            return str(value)
+    return ""
+
+
+def _tool_result(block: Mapping[str, Any]) -> ToolResult:
+    body = block.get("content")
+    return ToolResult(
+        body=_body_text(body),
+        size_bytes=_body_size(body),
+        failed=bool(block.get("is_error")),
+    )
+
+
+def _body_text(body: Any) -> str:
+    """The tool's own output as one string, whatever shape it arrived in."""
+    if isinstance(body, str):
+        return body
+    if isinstance(body, list):
+        return "\n".join(
+            str(block.get("text", "")) for block in body if isinstance(block, Mapping)
+        )
+    return ""
+
+
+def _body_size(body: Any) -> int:
+    """How much a tool returned, in bytes.
+
+    The content arrives either as a plain string or as a list of content
+    blocks. Counting only the string form reports a five-figure result as
+    zero — a confident wrong number, which is worse on a screen than no
+    number. Bytes rather than characters because the figure exists to be
+    compared against the log this run leaves on disk.
+    """
+    if isinstance(body, str):
+        return len(body.encode("utf-8"))
+    if isinstance(body, list):
+        return sum(
+            len(str(block.get("text", "")).encode("utf-8"))
+            for block in body
+            if isinstance(block, Mapping)
+        )
+    return 0
+
+
+def _content_blocks(event: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    message = event.get("message")
+    if not isinstance(message, Mapping):
+        return []
+    content = message.get("content")
+    if not isinstance(content, list):
+        return []
+    return [block for block in content if isinstance(block, Mapping)]
+
+
+def _truncate(line: str, limit: int | None) -> str:
+    if limit is None or len(line) <= limit:
+        return line
+    return line[: limit - 1] + "…"

package/runtime/python/okstra_ctl/entrypoints/__init__.py

@@ -0,0 +1 @@
+"""Internal command entrypoints used by Okstra host integrations."""