whiletrue 0.1.0__py3-none-any.whl

whiletrue/__main__.py

@@ -0,0 +1,3 @@
+from whiletrue.cli.app import entrypoint
+
+entrypoint()

whiletrue/abort.py

@@ -0,0 +1,79 @@
+"""Cooperative cancellation, modelled on the web's AbortSignal."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+
+class AbortSignal:
+    """A one-way flag that can be awaited. Once aborted it stays aborted."""
+
+    def __init__(self) -> None:
+        self._aborted = False
+        self._reason: str | None = None
+        self._event = asyncio.Event()
+        self._callbacks: list[Callable[[], None]] = []
+        self._timer: asyncio.TimerHandle | None = None
+        self._detach: list[Callable[[], None]] = []
+
+    @property
+    def aborted(self) -> bool:
+        return self._aborted
+
+    @property
+    def reason(self) -> str | None:
+        return self._reason
+
+    def abort(self, reason: str = "aborted") -> None:
+        if self._aborted:
+            return
+        self._aborted = True
+        self._reason = reason
+        self._event.set()
+        callbacks, self._callbacks = self._callbacks, []
+        for callback in callbacks:
+            callback()
+
+    async def wait(self) -> None:
+        """Returns once the signal is aborted."""
+        await self._event.wait()
+
+    def on_abort(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Calls `callback` on abort (immediately if already aborted). Returns an unsubscribe."""
+        if self._aborted:
+            callback()
+            return lambda: None
+        self._callbacks.append(callback)
+
+        def remove() -> None:
+            if callback in self._callbacks:
+                self._callbacks.remove(callback)
+
+        return remove
+
+    def dispose(self) -> None:
+        """Releases timers and subscriptions held by a derived signal (timeout / any)."""
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+        for detach in self._detach:
+            detach()
+        self._detach.clear()
+
+    @staticmethod
+    def any(*signals: AbortSignal) -> AbortSignal:
+        """A signal that aborts as soon as any of `signals` does."""
+        derived = AbortSignal()
+        for source in signals:
+            derived._detach.append(source.on_abort(derived.abort))
+        return derived
+
+    @staticmethod
+    def timeout(ms: float) -> AbortSignal:
+        """A signal that aborts after `ms` milliseconds."""
+        derived = AbortSignal()
+        derived._timer = asyncio.get_running_loop().call_later(
+            ms / 1000, lambda: derived.abort("timeout")
+        )
+        return derived

whiletrue/basics/__init__.py

@@ -0,0 +1,99 @@
+"""Built-in modules: shell, gate.*, exec, set, agent, sessions, human.approve, comments."""
+
+from whiletrue.basics.agent import AgentConfig, agent_module
+from whiletrue.basics.comments import (
+    CommentReplies,
+    CommentReply,
+    comments_reply_module,
+    gate_comments_answered_module,
+)
+from whiletrue.basics.diff_size import DiffSizeConfig, diff_size_module
+from whiletrue.basics.exec_ import ExecConfig, exec_module
+from whiletrue.basics.history import (
+    DistillConfig,
+    HistoryConfig,
+    context_history_module,
+    history_distill_module,
+    render_history,
+)
+from whiletrue.basics.human import ApproveConfig, approve_strategy
+from whiletrue.basics.json_source import JsonSource
+from whiletrue.basics.markdown_source import MarkdownTasksSource
+from whiletrue.basics.process import CommandResult, run_command, tail
+from whiletrue.basics.sessions import (
+    SessionEndConfig,
+    context_reset_module,
+    session_end_module,
+)
+from whiletrue.basics.set_ import SetConfig, set_module
+from whiletrue.basics.shell import (
+    GateTestsConfig,
+    ShellConfig,
+    gate_shell_module,
+    gate_tests_module,
+    shell_module,
+)
+from whiletrue.basics.wake import FileExistsWake, TimerWake
+from whiletrue.core import PluginApi, SimplePlugin
+
+
+def _register(api: PluginApi) -> None:
+    api.register_action(shell_module)
+    api.register_action(gate_shell_module)
+    api.register_action(gate_tests_module)
+    api.register_action(diff_size_module)
+    api.register_action(exec_module)
+    api.register_action(set_module)
+    api.register_action(agent_module)
+    api.register_action(session_end_module)
+    api.register_action(context_reset_module)
+    api.register_action(comments_reply_module)
+    api.register_action(context_history_module)
+    api.register_action(history_distill_module)
+    api.register_action(gate_comments_answered_module)
+    api.register_strategy(approve_strategy)
+    api.register_provider("source", "json", JsonSource())
+    api.register_provider("source", "markdown_tasks", MarkdownTasksSource())
+    api.register_provider("wake", "file_exists", FileExistsWake())
+    api.register_provider("wake", "timer", TimerWake())
+    api.register_cap("CommentReplies", CommentReplies)
+
+
+#: Registers the built-in modules through the same public plugin API third parties use.
+basics_plugin = SimplePlugin(name="whiletrue.basics", register=_register)
+
+__all__ = [
+    "AgentConfig",
+    "ApproveConfig",
+    "CommandResult",
+    "CommentReplies",
+    "CommentReply",
+    "DiffSizeConfig",
+    "DistillConfig",
+    "ExecConfig",
+    "GateTestsConfig",
+    "HistoryConfig",
+    "JsonSource",
+    "MarkdownTasksSource",
+    "SessionEndConfig",
+    "SetConfig",
+    "ShellConfig",
+    "agent_module",
+    "approve_strategy",
+    "basics_plugin",
+    "comments_reply_module",
+    "context_history_module",
+    "context_reset_module",
+    "diff_size_module",
+    "exec_module",
+    "gate_comments_answered_module",
+    "gate_shell_module",
+    "gate_tests_module",
+    "history_distill_module",
+    "render_history",
+    "run_command",
+    "session_end_module",
+    "set_module",
+    "shell_module",
+    "tail",
+]

whiletrue/basics/agent.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from whiletrue.abort import AbortSignal
+from whiletrue.core import (
+    ActionModule,
+    AgentDefinition,
+    AgentLimits,
+    AgentRequest,
+    ConfigError,
+    ConfigIssue,
+    Emit,
+    Ports,
+    PortSpec,
+    Registry,
+    RunContext,
+    StepContext,
+    ValidateContext,
+    define_action,
+    load_agent_definition,
+    render_template,
+)
+from whiletrue.core.module import PortValues
+
+
+class AgentConfig(BaseModel):
+    uses: str = Field(min_length=1)
+    runner: str | None = None
+    vars: dict[str, Any] = Field(default_factory=lambda: {})
+
+
+#: Caps that carry no useful JSON Schema constraint for structured output.
+_UNSTRUCTURED = {"Text", "Any"}
+
+
+def _runner_issues(
+    definition: AgentDefinition, runner_id: str, registry: Registry
+) -> list[ConfigIssue]:
+    runner = registry.get_runner(runner_id)
+    if runner is None:
+        return [
+            ConfigIssue(
+                "error",
+                f'Unknown runner "{runner_id}" (e.g. claude-code-headless, opencode)',
+            )
+        ]
+    issues: list[ConfigIssue] = []
+    out_cap = next(iter(definition.outputs.values()), None)
+    if out_cap and out_cap not in _UNSTRUCTURED and not runner.capabilities.structured_output:
+        issues.append(
+            ConfigIssue(
+                "error",
+                f'Agent "{definition.name}" declares structured output ({out_cap}) '
+                f'but runner "{runner_id}" cannot produce it',
+            )
+        )
+    if (
+        definition.limits is not None
+        and definition.limits.budget_usd is not None
+        and not runner.capabilities.budget
+    ):
+        issues.append(
+            ConfigIssue(
+                "error",
+                f'Agent "{definition.name}" sets a budget but runner "{runner_id}" '
+                "cannot enforce one",
+            )
+        )
+    if definition.fork and not runner.capabilities.fork:
+        issues.append(
+            ConfigIssue(
+                "error",
+                f'Agent "{definition.name}" asks to fork a session but runner "{runner_id}" '
+                "cannot fork",
+            )
+        )
+    if definition.bare and runner.capabilities.interactive:
+        issues.append(
+            ConfigIssue(
+                "warning",
+                f'Agent "{definition.name}" sets `bare`, which turns off hooks: runner '
+                f'"{runner_id}" then cannot nudge, enforce limits or detect steering',
+            )
+        )
+    if definition.session != "fresh" and not runner.capabilities.resume:
+        issues.append(
+            ConfigIssue(
+                "error",
+                f'Agent "{definition.name}" asks for session "{definition.session}" '
+                f'but runner "{runner_id}" cannot resume sessions',
+            )
+        )
+    return issues
+
+
+def _validate(config: AgentConfig, vctx: ValidateContext) -> list[ConfigIssue]:
+    try:
+        definition = load_agent_definition(Path(vctx.cwd) / config.uses)
+    except ConfigError as error:
+        return [ConfigIssue("error", str(error))]
+    except OSError as error:
+        return [ConfigIssue("error", f"Cannot read agent file: {error}")]
+    issues: list[ConfigIssue] = []
+    if definition.limits is None:
+        issues.append(
+            ConfigIssue(
+                "error",
+                f'Agent "{definition.name}" needs `limits` (budget_usd, turns, wall): '
+                "agent steps are bounded by default",
+            )
+        )
+    return [*issues, *_runner_issues(definition, config.runner or definition.runner, vctx.registry)]
+
+
+async def _run(input: PortValues, ctx: StepContext[AgentConfig]) -> Emit:
+    definition = load_agent_definition(Path(ctx.cwd) / ctx.config.uses)
+    runner_id = ctx.config.runner or definition.runner
+    runner = ctx.registry.get_runner(runner_id)
+    if runner is None:
+        return Emit("fail", {"error": f'Unknown runner "{runner_id}"'})
+
+    prompt = render_template(
+        definition.prompt,
+        {**ctx.scope.snapshot(), "input": input.get("in"), **ctx.config.vars},
+    )
+
+    out_cap = next(iter(definition.outputs.values()), None)
+    structured = out_cap is not None and out_cap not in _UNSTRUCTURED
+    wall: AbortSignal | None = None
+    signal = ctx.signal
+    if definition.limits is not None and definition.limits.wall_ms is not None:
+        wall = AbortSignal.timeout(definition.limits.wall_ms)
+        signal = AbortSignal.any(ctx.signal, wall)
+
+    sessions: dict[str, str] | None = ctx.scope.get("sessions")
+    shared = definition.session if definition.session != "fresh" and sessions is not None else None
+    existing = sessions.get(shared) if sessions is not None and shared else None
+    new_session = str(uuid.uuid4())
+
+    def path(p: str) -> str:
+        return str(Path(ctx.cwd) / p)
+
+    request = AgentRequest(
+        prompt=prompt,
+        cwd=ctx.cwd,
+        model=definition.model,
+        allowed_tools=definition.tools,
+        permission_mode=definition.permission_mode,
+        output_schema=ctx.registry.caps.to_json_schema(out_cap) if structured and out_cap else None,
+        limits=AgentLimits(
+            budget_usd=definition.limits.budget_usd,
+            turns=definition.limits.turns,
+            wall_ms=definition.limits.wall_ms,
+        )
+        if definition.limits is not None
+        else None,
+        session_id=None if existing else new_session,
+        resume=existing,
+        fork=bool(existing) and definition.fork,
+        add_dirs=[path(d) for d in definition.add_dirs] if definition.add_dirs else None,
+        append_system_prompt_file=path(definition.append_system_prompt_file)
+        if definition.append_system_prompt_file
+        else None,
+        mcp_config=[path(c) for c in definition.mcp_config] if definition.mcp_config else None,
+        bare=definition.bare,
+        on_done=definition.on_done,
+        step_key=ctx.step_key,
+        label=f"{ctx.item_id} {definition.name}",
+        item=ctx.scope.get("item"),
+        output_cap=out_cap,
+        validate_output=(lambda v, cap=out_cap: ctx.registry.caps.validate(cap, v))
+        if structured and out_cap
+        else None,
+    )
+
+    def on_event(event: dict[str, Any]) -> None:
+        if event.get("kind") == "steer" and ctx.store is not None:
+            ctx.store.add_steer(
+                run_id=ctx.run_id,
+                item_id=ctx.item_id,
+                step=ctx.node_id,
+                prompt=str(event.get("prompt", "")),
+                created_at=ctx.now(),
+            )
+        ctx.bus.emit(
+            "agent.event",
+            ctx.run_id,
+            {"node": ctx.node_id, **event},
+            item_id=ctx.item_id,
+        )
+
+    on_event({"kind": "runner", "runner": runner_id})
+    try:
+        if ctx.agent_slots is not None:
+            async with ctx.agent_slots:
+                result = await runner.run(request, RunContext(signal=signal, on_event=on_event))
+        else:
+            result = await runner.run(request, RunContext(signal=signal, on_event=on_event))
+    finally:
+        if wall is not None:
+            wall.dispose()
+            signal.dispose()
+    if shared and sessions is not None and not (existing and definition.fork):
+        # Remember the conversation (even a failed one) so a retry or a later step continues it.
+        sessions[shared] = result.session_id or existing or new_session
+    if result.cost_usd:
+        ctx.record_cost(result.cost_usd)
+    if result.steered_cost_usd is not None:
+        on_event(
+            {
+                "kind": "cost",
+                "agent_usd": (result.cost_usd or 0.0) - result.steered_cost_usd,
+                "steered_usd": result.steered_cost_usd,
+            }
+        )
+    if result.park:
+        return Emit(
+            "needs_human",
+            {"reason": result.park, "detail": result.error, "text": result.text},
+        )
+    if not result.ok:
+        return Emit("fail", {"error": result.error or "agent failed", "text": result.text})
+    value = result.output if result.output is not None else result.text
+    if out_cap:
+        check = ctx.registry.caps.validate(out_cap, value)
+        if not check.ok:
+            return Emit(
+                "fail",
+                {"error": f"Agent output does not match {out_cap}: {'; '.join(check.errors)}"},
+            )
+    return Emit("ok", value)
+
+
+#: Runs a prompt-defined agent (markdown with frontmatter) on a runner.
+agent_module: ActionModule[AgentConfig] = define_action(
+    ActionModule(
+        id="agent",
+        config=AgentConfig,
+        ports=Ports(inputs=[PortSpec("in", "Any")], outputs=[PortSpec("out", "Any")]),
+        effects="agentic",
+        validate=_validate,
+        run=_run,
+    )
+)

whiletrue/basics/comments.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from whiletrue.core import (
+    ActionModule,
+    CommentsContext,
+    Emit,
+    EmptyConfig,
+    Ports,
+    PortSpec,
+    StepContext,
+    define_action,
+    with_prefix,
+)
+from whiletrue.core.module import PortValues
+
+COMMENT_KINDS = ("question", "change_request", "nit", "approval", "out_of_scope")
+
+
+class CommentReply(BaseModel):
+    comment_id: int
+    #: How the comment was classified.
+    kind: str = "question"
+    #: What was said back: the answer, "fixed in abc123", or "declined because ...".
+    reply: str = Field(min_length=1)
+
+
+class CommentReplies(BaseModel):
+    """What a responder agent returns: one reply per comment it was given."""
+
+    replies: list[CommentReply]
+
+
+async def _reply(input: PortValues, ctx: StepContext[EmptyConfig]) -> Emit:
+    store = ctx.store
+    if store is None:
+        return Emit("fail", {"error": "comments.reply needs a state store"})
+    payload = CommentReplies.model_validate(input.get("in") or {})
+    known = {c.id: c for c in store.list_comments(ctx.item_id)}
+    item = ctx.scope.get("item") or {"id": ctx.item_id}
+    posted: list[int] = []
+    for reply in payload.replies:
+        comment = known.get(reply.comment_id)
+        if comment is None:
+            return Emit("fail", {"error": f"No comment {reply.comment_id} on {ctx.item_id}"})
+        if comment.answered:
+            continue
+        key = f"reply:{ctx.item_id}:{comment.source}:{comment.external_id}"
+        effect = store.effect_get(key)
+        body = with_prefix(reply.reply)
+        if effect is None:
+            provider = ctx.registry.get_provider("comments", comment.source)
+            store.effect_put(
+                key, run_id=ctx.run_id, status="started", ref=None, created_at=ctx.now()
+            )
+            if provider is not None:
+                ref = await provider.reply(
+                    comment, body, CommentsContext(ctx.cwd, ctx.now, ctx.item_id, item)
+                )
+            else:
+                ref = None  # a local comment: the answer is only recorded
+            store.effect_put(key, run_id=ctx.run_id, status="done", ref=ref, created_at=ctx.now())
+        # A "started" effect with no "done" means a crash mid-post: do not risk a duplicate.
+        store.answer_comment(comment.id, body)
+        ctx.bus.emit(
+            "comment.answered",
+            ctx.run_id,
+            {"comment": comment.id, "source": comment.source, "kind": reply.kind},
+            item_id=ctx.item_id,
+        )
+        posted.append(comment.id)
+    return Emit("ok", {"answered": posted})
+
+
+#: Posts the agent's replies in each comment's own thread (prefixed `[whiletrue]`, once only).
+comments_reply_module: ActionModule[EmptyConfig] = define_action(
+    ActionModule(
+        id="comments.reply",
+        config=EmptyConfig,
+        ports=Ports(inputs=[PortSpec("in", "CommentReplies")], outputs=[PortSpec("out", "Any")]),
+        effects="side-effect",
+        cacheable=False,
+        idempotency_key=lambda _i, ctx: f"comments.reply:{ctx.item_id}:{ctx.node_id}",
+        run=_reply,
+    )
+)
+
+
+async def _answered(_input: PortValues, ctx: StepContext[EmptyConfig]) -> Emit:
+    if ctx.store is None:
+        return Emit("fail", {"error": "gate.comments_answered needs a state store"})
+    open_comments = ctx.store.list_comments(ctx.item_id, unanswered_only=True)
+    if open_comments:
+        ids = ", ".join(f"#{c.id} ({c.author})" for c in open_comments)
+        return Emit(
+            "fail",
+            {"error": f"{len(open_comments)} comment(s) still have no reply: {ids}"},
+        )
+    return Emit("ok", _input.get("in"))
+
+
+#: Fails while any comment on the item (human or reviewer) has no reply.
+gate_comments_answered_module: ActionModule[EmptyConfig] = define_action(
+    ActionModule(
+        id="gate.comments_answered",
+        config=EmptyConfig,
+        ports=Ports(inputs=[PortSpec("in", "Any")], outputs=[PortSpec("out", "Any")]),
+        effects="deterministic",
+        cacheable=False,
+        run=_answered,
+    )
+)

whiletrue/basics/diff_size.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, PositiveInt
+
+from whiletrue.basics.process import run_command, tail
+from whiletrue.core import (
+    ActionModule,
+    ConfigIssue,
+    Emit,
+    Ports,
+    PortSpec,
+    StepContext,
+    define_action,
+)
+from whiletrue.core.module import PortValues
+
+#: git's well-known empty tree, so `diff` works in a repository without commits.
+_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+
+
+class DiffSizeConfig(BaseModel):
+    max_lines: PositiveInt | None = None
+    max_files: PositiveInt | None = None
+    #: Revision to diff the working tree against. Default: HEAD.
+    base: str = "HEAD"
+
+
+def _validate(config: DiffSizeConfig, _vctx: object) -> list[ConfigIssue]:
+    if config.max_lines is None and config.max_files is None:
+        return [ConfigIssue("error", "`gate.diff_size` needs `max_lines` and/or `max_files`")]
+    return []
+
+
+async def _git(ctx: StepContext[DiffSizeConfig], *args: str):
+    return await run_command("git", list(args), cwd=ctx.cwd, signal=ctx.signal)
+
+
+async def _run(_input: PortValues, ctx: StepContext[DiffSizeConfig]) -> Emit:
+    cfg = ctx.config
+    base = cfg.base
+    if base == "HEAD" and (await _git(ctx, "rev-parse", "--verify", "HEAD")).code != 0:
+        base = _EMPTY_TREE
+    diff = await _git(ctx, "diff", "--numstat", base)
+    if diff.code != 0:
+        return Emit("fail", {"error": "git diff failed", "output": tail(diff.stderr)})
+    untracked = await _git(ctx, "ls-files", "--others", "--exclude-standard")
+    if untracked.code != 0:
+        return Emit("fail", {"error": "git ls-files failed", "output": tail(untracked.stderr)})
+    lines = 0
+    files = 0
+    for row in diff.stdout.splitlines():
+        added, deleted, _name = [*row.split("\t", 2), "", "", ""][:3]
+        files += 1
+        # Binary files show "-" for both counts.
+        lines += (int(added) if added.isdigit() else 0) + (int(deleted) if deleted.isdigit() else 0)
+    files += len([n for n in untracked.stdout.splitlines() if n])
+    stats = {"lines": lines, "files": files}
+    problems: list[str] = []
+    if cfg.max_lines is not None and lines > cfg.max_lines:
+        problems.append(f"{lines} changed lines exceed the limit of {cfg.max_lines}")
+    if cfg.max_files is not None and files > cfg.max_files:
+        problems.append(f"{files} changed files exceed the limit of {cfg.max_files}")
+    if problems:
+        return Emit("fail", {"error": "; ".join(problems), **stats})
+    return Emit("ok", stats)
+
+
+#: A deterministic gate: fails when the working tree differs from `base` by more than the limits
+#: (changed lines and files, untracked files counted as files).
+diff_size_module: ActionModule[DiffSizeConfig] = define_action(
+    ActionModule(
+        id="gate.diff_size",
+        config=DiffSizeConfig,
+        ports=Ports(inputs=[PortSpec("in", "Any")], outputs=[PortSpec("out", "Any")]),
+        effects="deterministic",
+        cacheable=False,
+        validate=_validate,  # pyright: ignore[reportArgumentType]
+        run=_run,
+    )
+)