whiletrue 0.1.0__py3-none-any.whl

whiletrue/core/module.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from whiletrue.core.config import PipelineNode
+    from whiletrue.core.context import CompositeContext, StepContext
+    from whiletrue.core.registry import Registry
+
+#: How a module may touch the world. Drives the safety rules (see architecture.md).
+EFFECTS = ("pure", "deterministic", "agentic", "side-effect")
+Effect = Literal["pure", "deterministic", "agentic", "side-effect"]
+
+#: Values arriving on (or leaving from) a module's ports, keyed by port name.
+PortValues = dict[str, Any]
+
+
+def is_effect(value: object) -> bool:
+    return isinstance(value, str) and value in EFFECTS
+
+
+class EmptyConfig(BaseModel):
+    """Config for modules that take none."""
+
+
+@dataclass(frozen=True)
+class PortSpec:
+    """A named, typed connection point. `cap` names a schema (Issue, Diff, Text, Any, ...)."""
+
+    name: str
+    cap: str
+    optional: bool = False
+
+
+@dataclass
+class Ports:
+    inputs: list[PortSpec] = field(default_factory=lambda: [])
+    outputs: list[PortSpec] = field(default_factory=lambda: [])
+
+
+@dataclass
+class Emit:
+    """Which port fires, and with what. `value=None` means no value."""
+
+    port: str
+    value: Any = None
+
+
+@dataclass(frozen=True)
+class ConfigIssue:
+    """A static-validation finding about a config (never raised at run time)."""
+
+    severity: Literal["error", "warning"]
+    message: str
+
+
+@dataclass
+class ValidateContext:
+    """What static checks may look at (e.g. an agent step loading its prompt file)."""
+
+    cwd: str
+    registry: Registry
+
+
+@dataclass
+class ActionModule[Cfg: BaseModel]:
+    id: str  # e.g. 'gate.tests'
+    config: type[Cfg]
+    ports: Ports
+    effects: Effect
+    run: Callable[[PortValues, StepContext[Cfg]], Awaitable[Emit]]
+    kind: Literal["action"] = "action"
+    capabilities: list[str] = field(default_factory=lambda: [])
+    #: Whether results of `pure`/`deterministic` runs may be cached by input hash. Modules that
+    #: read the workspace (gates, shell) must set this to False.
+    cacheable: bool = True
+    #: Extra static checks beyond the config schema (e.g. agent limits).
+    validate: Callable[[Cfg, ValidateContext], list[ConfigIssue]] | None = None
+    #: Required for `side-effect` modules: a deterministic key so resume never repeats the effect.
+    idempotency_key: Callable[[PortValues, StepContext[Cfg]], str] | None = None
+    #: Record the result under `idempotency_key` so a repeat (resume, a second run) reuses it
+    #: instead of repeating the effect. The key must name the *effect*, not the run.
+    journal: bool = False
+
+
+@dataclass
+class Strategy[Cfg: BaseModel]:
+    id: str  # e.g. 'loop'
+    config: type[Cfg]
+    run: Callable[[list[PipelineNode], PortValues, CompositeContext[Cfg]], Awaitable[Emit]]
+    #: Children are chained: each child's `out` feeds the next child's `in`.
+    chain: bool = False
+    #: Extra static checks beyond the config schema (e.g. loops must be bounded).
+    validate: Callable[[Cfg, ValidateContext], list[ConfigIssue]] | None = None
+    #: Static checks that need the step's children (e.g. `switch` case targets).
+    validate_node: Callable[[Cfg, PipelineNode, ValidateContext], list[ConfigIssue]] | None = None
+
+
+class ModuleDefinitionError(Exception):
+    def __init__(self, module_id: str, problem: str) -> None:
+        super().__init__(f'Invalid module "{module_id}": {problem}')
+
+
+_ID = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$")
+
+
+def _check_id(module_id: str) -> None:
+    if not _ID.match(module_id):
+        raise ModuleDefinitionError(
+            module_id, "id must be lowercase dotted segments, e.g. 'gate.tests'"
+        )
+
+
+def _check_ports(module_id: str, direction: str, ports: list[PortSpec]) -> None:
+    seen: set[str] = set()
+    for port in ports:
+        if port.name in seen:
+            raise ModuleDefinitionError(module_id, f'duplicate {direction} port "{port.name}"')
+        seen.add(port.name)
+
+
+def define_action[Cfg: BaseModel](mod: ActionModule[Cfg]) -> ActionModule[Cfg]:
+    """Validates an action module's static shape at definition time and returns it unchanged."""
+    _check_id(mod.id)
+    if str(mod.kind) != "action":
+        raise ModuleDefinitionError(mod.id, f"kind must be 'action', got '{mod.kind}'")
+    if not is_effect(mod.effects):
+        raise ModuleDefinitionError(mod.id, f"unknown effect '{mod.effects}'")
+    if mod.id.startswith("gate.") and mod.effects != "deterministic":
+        raise ModuleDefinitionError(
+            mod.id, "gates must be deterministic: an agent can never grade itself"
+        )
+    _check_ports(mod.id, "in", mod.ports.inputs)
+    _check_ports(mod.id, "out", mod.ports.outputs)
+    return mod
+
+
+def define_strategy[Cfg: BaseModel](strategy: Strategy[Cfg]) -> Strategy[Cfg]:
+    """Validates a strategy's static shape at definition time and returns it unchanged."""
+    _check_id(strategy.id)
+    return strategy

whiletrue/core/outcomes.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+#: Every module has these outcome ports in addition to its data ports.
+OUTCOME_PORTS = ("ok", "fail", "needs_human", "skip", "rejected")
+
+ItemState = Literal["pending", "ready", "running", "parked", "done", "failed", "cancelled"]
+
+#: What a composite does with an unwired `fail`.
+OnFail = Literal["park", "drop", "propagate"]
+
+
+@dataclass(frozen=True)
+class OutcomePolicy:
+    on_fail: OnFail = "park"
+
+
+@dataclass(frozen=True)
+class Resolution:
+    action: Literal["continue", "route", "propagate", "exit"]
+    target: str | None = None
+    port: str | None = None
+    state: ItemState | None = None
+
+
+def is_outcome_port(port: str) -> bool:
+    return port in OUTCOME_PORTS
+
+
+def item_state_for(port: str, on_fail: OnFail) -> ItemState:
+    """Terminal item state for an outcome that leaves the pipeline."""
+    match port:
+        case "ok" | "skip":
+            return "done"
+        case "fail":
+            return "parked" if on_fail == "park" else "failed"
+        case _:
+            return "parked"
+
+
+def resolve_outcome(port: str, wires: dict[str, str], policy: OutcomePolicy) -> Resolution:
+    """Decide what happens when a child fires `port`. A wired port always routes to its target.
+
+    Unwired: ok/skip and custom data ports continue; fail/needs_human/rejected follow the policy.
+    """
+    target = wires.get(port)
+    if target is not None:
+        return Resolution("route", target=target)
+    if not is_outcome_port(port) or port in ("ok", "skip"):
+        return Resolution("continue")
+    if policy.on_fail == "propagate":
+        return Resolution("propagate", port=port)
+    return Resolution("exit", port=port, state=item_state_for(port, policy.on_fail))
+
+
+class InvalidTransition(Exception):
+    pass
+
+
+#: Where an item may go next. `done` is final; `failed` and `cancelled` can be rerun.
+_TRANSITIONS: dict[ItemState, frozenset[ItemState]] = {
+    "pending": frozenset({"ready", "cancelled"}),
+    "ready": frozenset({"running", "pending", "cancelled"}),
+    "running": frozenset({"parked", "done", "failed", "cancelled"}),
+    "parked": frozenset({"running", "ready", "cancelled"}),
+    "done": frozenset(),
+    "failed": frozenset({"ready", "cancelled"}),
+    "cancelled": frozenset({"ready"}),
+}
+
+
+def can_transition(old: ItemState, new: ItemState) -> bool:
+    return new in _TRANSITIONS[old]
+
+
+def transition(old: ItemState, new: ItemState) -> ItemState:
+    """`new` if the move is allowed, else InvalidTransition."""
+    if not can_transition(old, new):
+        raise InvalidTransition(f"Invalid item transition {old} -> {new}")
+    return new

whiletrue/core/registry.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from whiletrue.core.caps import CapRegistry, create_builtin_caps
+from whiletrue.core.module import ActionModule, Strategy
+from whiletrue.core.runner import Runner
+
+ProviderKind = Literal["source", "store", "workspace", "knowledge", "comments", "wake"]
+
+
+class RegistryError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Resolved:
+    kind: Literal["action", "strategy"]
+    module: Any  # ActionModule[Any] | Strategy[Any]; narrowed by `kind`
+
+
+class PluginApi(Protocol):
+    """The public plugin surface. Built-in modules use exactly this API."""
+
+    def register_action[Cfg: BaseModel](self, module: ActionModule[Cfg]) -> None: ...
+    def register_strategy[Cfg: BaseModel](self, strategy: Strategy[Cfg]) -> None: ...
+    def register_runner(self, runner: Runner) -> None: ...
+    def register_provider(self, kind: ProviderKind, name: str, provider: Any) -> None: ...
+    def register_cap(self, name: str, schema: Any) -> None: ...
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    @property
+    def name(self) -> str: ...
+
+    def register(self, api: PluginApi, /) -> None: ...
+
+
+@dataclass(frozen=True)
+class SimplePlugin:
+    """A plugin made of a name and a registration function."""
+
+    name: str
+    register: Callable[[PluginApi], None]
+
+
+class Registry:
+    def __init__(self, caps: CapRegistry | None = None) -> None:
+        self.caps = caps if caps is not None else create_builtin_caps()
+        self._actions: dict[str, ActionModule[Any]] = {}
+        self._strategies: dict[str, Strategy[Any]] = {}
+        self._runners: dict[str, Runner] = {}
+        self._providers: dict[str, Any] = {}
+        self._plugins: list[str] = []
+        self._plugin_versions: dict[str, str] = {}
+
+    def _assert_free_id(self, module_id: str) -> None:
+        if module_id in self._actions or module_id in self._strategies:
+            raise RegistryError(f'Module or strategy "{module_id}" is already registered')
+
+    def register_action[Cfg: BaseModel](self, module: ActionModule[Cfg]) -> None:
+        self._assert_free_id(module.id)
+        self._actions[module.id] = module
+
+    def register_strategy[Cfg: BaseModel](self, strategy: Strategy[Cfg]) -> None:
+        self._assert_free_id(strategy.id)
+        self._strategies[strategy.id] = strategy
+
+    def register_runner(self, runner: Runner) -> None:
+        if runner.id in self._runners:
+            raise RegistryError(f'Runner "{runner.id}" is already registered')
+        self._runners[runner.id] = runner
+
+    def register_provider(self, kind: ProviderKind, name: str, provider: Any) -> None:
+        key = f"{kind}:{name}"
+        if key in self._providers:
+            raise RegistryError(f'Provider "{key}" is already registered')
+        self._providers[key] = provider
+
+    def register_cap(self, name: str, schema: Any) -> None:
+        self.caps.register(name, schema)
+
+    def resolve(self, module_id: str) -> Resolved | None:
+        action = self._actions.get(module_id)
+        if action is not None:
+            return Resolved("action", action)
+        strategy = self._strategies.get(module_id)
+        if strategy is not None:
+            return Resolved("strategy", strategy)
+        return None
+
+    def get_runner(self, runner_id: str) -> Runner | None:
+        return self._runners.get(runner_id)
+
+    def get_provider(self, kind: ProviderKind, name: str) -> Any:
+        return self._providers.get(f"{kind}:{name}")
+
+    def providers(self, kind: ProviderKind) -> list[tuple[str, Any]]:
+        """All providers of a kind as (name, provider), in registration order."""
+        prefix = f"{kind}:"
+        return [
+            (key[len(prefix) :], provider)
+            for key, provider in self._providers.items()
+            if key.startswith(prefix)
+        ]
+
+    def ids(self) -> list[str]:
+        return sorted([*self._actions, *self._strategies])
+
+    def use(self, plugin: Plugin, version: str | None = None) -> None:
+        """Installs a plugin. `version` (else its `version` attribute) is what the lock pins."""
+        if plugin.name in self._plugins:
+            raise RegistryError(f'Plugin "{plugin.name}" is already installed')
+        plugin.register(self)
+        self._plugins.append(plugin.name)
+        self._plugin_versions[plugin.name] = version or str(
+            getattr(plugin, "version", "unversioned")
+        )
+
+    def plugin_versions(self) -> dict[str, str]:
+        return dict(self._plugin_versions)
+
+    def plugins(self) -> list[str]:
+        return list(self._plugins)

whiletrue/core/replay.py

@@ -0,0 +1,58 @@
+"""Replay: re-run a recorded run's logic without running any module that has effects.
+
+Every step's port and output is already recorded. A replay serves those recordings for all
+modules except `pure` ones, so control flow, expressions and wiring run for real while agents,
+shells and gates are not executed again.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from whiletrue.core.runtime import RunItem
+from whiletrue.core.store import StateStore
+
+#: (item id, node path, attempt) -> recorded (port, output)
+ReplayData = dict[tuple[str, str, int], tuple[str, Any]]
+
+
+@dataclass
+class Recording:
+    run_id: str
+    status: str
+    pipeline_hash: str
+    items: list[RunItem]
+    #: Recorded terminal state per item id.
+    item_states: dict[str, str]
+    steps: ReplayData
+    #: The chain of resumes this run belongs to (its own id for a fresh run).
+    lineage: str = ""
+
+
+class ReplayError(Exception):
+    pass
+
+
+def load_recording(store: StateStore, run_id: str) -> Recording:
+    run = store.get_run(run_id)
+    if run is None:
+        raise ReplayError(f'No run "{run_id}"')
+    records = store.list_items(run_id)
+    steps: ReplayData = {
+        (s.item_id, s.node_path, s.attempt): (s.port, s.output)
+        for s in store.list_steps(run_id)
+        # A step that parked for a person must run again when its run is resumed.
+        if s.port is not None and s.port != "needs_human"
+    }
+    started = store.list_events(run_id, type="run.started")
+    lineage = str(started[0].data.get("lineage", run_id)) if started else run_id
+    return Recording(
+        run_id=run.id,
+        status=run.status,
+        pipeline_hash=run.pipeline_hash,
+        items=[RunItem(i.id, i.payload) for i in records],
+        item_states={i.id: i.state for i in records},
+        steps=steps,
+        lineage=lineage,
+    )

whiletrue/core/runner.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol
+
+from whiletrue.abort import AbortSignal
+from whiletrue.core.caps import CapValidation
+
+
+@dataclass(frozen=True)
+class RunnerCapabilities:
+    """What a runner can do; `validate` rejects steps that ask for more."""
+
+    interactive: bool
+    structured_output: bool
+    resume: bool
+    fork: bool
+    budget: bool
+
+
+@dataclass(frozen=True)
+class AgentLimits:
+    #: Max spend in USD (hard where the runner supports it, an estimate otherwise).
+    budget_usd: float | None = None
+    turns: int | None = None
+    #: Wall-clock limit in milliseconds.
+    wall_ms: int | None = None
+
+
+@dataclass
+class AgentRequest:
+    prompt: str
+    cwd: str
+    model: str | None = None
+    tools: list[str] | None = None
+    allowed_tools: list[str] | None = None
+    disallowed_tools: list[str] | None = None
+    permission_mode: str | None = None
+    system_prompt_append: str | None = None
+    #: JSON Schema the final structured output must satisfy.
+    output_schema: dict[str, Any] | None = None
+    limits: AgentLimits | None = None
+    #: New session id to use (fresh sessions).
+    session_id: str | None = None
+    #: Existing session to resume.
+    resume: str | None = None
+    #: With `resume`: branch into a new session instead of continuing the old one.
+    fork: bool = False
+    add_dirs: list[str] | None = None
+    append_system_prompt_file: str | None = None
+    mcp_config: list[str] | None = None
+    #: Reproducible mode: skip hooks, plugins, memory and auto-discovery (`claude --bare`).
+    bare: bool = False
+    #: Interactive runners: what happens to the pane when the step ends.
+    on_done: Literal["close", "keep"] = "close"
+    #: Identity of the step execution, for tying a live session back to it.
+    step_key: str | None = None
+    #: A short title for the pane, e.g. `#7 implement`.
+    label: str | None = None
+    #: The item's payload (what `whiletrue_context` returns to the agent).
+    item: dict[str, Any] | None = None
+    #: Name of the output cap and a validator for it (interactive runners check `whiletrue_submit`).
+    output_cap: str | None = None
+    validate_output: Callable[[Any], CapValidation] | None = None
+
+
+@dataclass
+class AgentResult:
+    ok: bool
+    #: Final text answer.
+    text: str
+    #: Structured output when the request carried an output schema.
+    output: Any = None
+    session_id: str | None = None
+    cost_usd: float | None = None
+    turns: int | None = None
+    error: str | None = None
+    #: Why the step needs a person instead of failing: `needs_human`, `budget_exceeded`, ...
+    park: str | None = None
+    #: A person typed into the session, which lifts the step's limits.
+    steered: bool = False
+    #: The part of `cost_usd` spent after the steer.
+    steered_cost_usd: float | None = None
+
+
+@dataclass
+class RunContext:
+    signal: AbortSignal
+    #: Raw runner events (tool calls, messages) for the event log.
+    on_event: Callable[[dict[str, Any]], None] | None = None
+
+
+class Runner(Protocol):
+    id: str
+    capabilities: RunnerCapabilities
+
+    async def run(self, request: AgentRequest, ctx: RunContext) -> AgentResult: ...