markov-agent 1.4.0__tar.gz

markov_agent-1.4.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: markov-agent
+Version: 1.4.0
+Summary: A coding agent following SKILL.state paper principles.
+Author: Nacho Llorca
+Author-email: Nacho Llorca <nllorca@proton.me>
+License: MIT
+Requires-Dist: lmdk>=2.10.3
+Requires-Dist: textual>=6.0.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# markov-agent
+
+A coding agent following the principles defined in the [SKILL.state](docs/paper.md) paper:
+
+> Runtime architecture that replaces append-only conversational history with an explicit, mutable execution state. At each execution step, the model receives only the immutable skill specification, the current structured execution state, and the latest observation. Intermediate reasoning is discarded immediately after **producing a validated state update**, preventing prompt growth with execution history.
+
+![Figure](docs/figure.png)
+
+Hence, the context given to the agent is modeled similar to a Markov process: the next state depends only on the current one and the (observed result of the) action taken.
+
+## Overview
+
+Although the paper specifies tasks like inventory management or CTF, I wanted to use it for a coding agent and test it in tasks I normally throw at [Pi](https://github.com/earendil-works/pi) and see what happens.
+
+The action space is: **bash**. Nothing more and nothing less. While most coding agents have some specially guardrailed tools (`read`, `patch`, etc.), [there is research proving that powerful LMs can do better without](https://arxiv.org/pdf/2609.20804):
+
+> Predefined tools improve performance for models with weaker bash proficiency, whereas bash-capable models can operate effectively with a bash-only interface and achieve substantially lower cost, especially on command-line-centric tasks.
+
+## Installation
+
+```bash
+uv add markov-agent
+```
+
+## Usage
+
+### TUI
+
+```bash
+uv tool install markov-agent
+markov  # --model defaults to mistral:mistral-large-4
+```
+
+### As a library
+
+[`skill_state.py`](src/markov_agent/skill_state.py) is the whole implementation of the paper. Define your
+state as a pydantic model plus an immutable instruction block, then consume the `StepEvent`s of
+`run()`. [`agent.py`](src/markov_agent/agent.py) is a small coding-agent domain to copy from.
+
+If you only want the core and not the terminal UI (nor its `textual` dependency), copy
+`skill_state.py` and `prompt_template.jinja` into your project: they import nothing else from this
+package, and `lmdk` + `jinja2` are their only requirements.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/), [just](https://just.systems/) and [prek](https://github.com/j178/prek).
+
+See [justfile](justfile) for pre-built commands used along pre-commit hooks and CI.
+
+_Made with [`mold`](https://github.com/nachollorca/mold) template_
+
+## References
+
+```
+@misc{badhe2026skillstatescalablelonghorizonagent,
+      title={SKILL.state: Scalable Long-Horizon Agent Skills},
+      author={Sanket Badhe and Priyanka Tiwari and Jonghyun Chung},
+      year={2026},
+      eprint={2608.26263},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2608.26263},
+}
+```

markov_agent-1.4.0/README.md

@@ -0,0 +1,64 @@
+# markov-agent
+
+A coding agent following the principles defined in the [SKILL.state](docs/paper.md) paper:
+
+> Runtime architecture that replaces append-only conversational history with an explicit, mutable execution state. At each execution step, the model receives only the immutable skill specification, the current structured execution state, and the latest observation. Intermediate reasoning is discarded immediately after **producing a validated state update**, preventing prompt growth with execution history.
+
+![Figure](docs/figure.png)
+
+Hence, the context given to the agent is modeled similar to a Markov process: the next state depends only on the current one and the (observed result of the) action taken.
+
+## Overview
+
+Although the paper specifies tasks like inventory management or CTF, I wanted to use it for a coding agent and test it in tasks I normally throw at [Pi](https://github.com/earendil-works/pi) and see what happens.
+
+The action space is: **bash**. Nothing more and nothing less. While most coding agents have some specially guardrailed tools (`read`, `patch`, etc.), [there is research proving that powerful LMs can do better without](https://arxiv.org/pdf/2609.20804):
+
+> Predefined tools improve performance for models with weaker bash proficiency, whereas bash-capable models can operate effectively with a bash-only interface and achieve substantially lower cost, especially on command-line-centric tasks.
+
+## Installation
+
+```bash
+uv add markov-agent
+```
+
+## Usage
+
+### TUI
+
+```bash
+uv tool install markov-agent
+markov  # --model defaults to mistral:mistral-large-4
+```
+
+### As a library
+
+[`skill_state.py`](src/markov_agent/skill_state.py) is the whole implementation of the paper. Define your
+state as a pydantic model plus an immutable instruction block, then consume the `StepEvent`s of
+`run()`. [`agent.py`](src/markov_agent/agent.py) is a small coding-agent domain to copy from.
+
+If you only want the core and not the terminal UI (nor its `textual` dependency), copy
+`skill_state.py` and `prompt_template.jinja` into your project: they import nothing else from this
+package, and `lmdk` + `jinja2` are their only requirements.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/), [just](https://just.systems/) and [prek](https://github.com/j178/prek).
+
+See [justfile](justfile) for pre-built commands used along pre-commit hooks and CI.
+
+_Made with [`mold`](https://github.com/nachollorca/mold) template_
+
+## References
+
+```
+@misc{badhe2026skillstatescalablelonghorizonagent,
+      title={SKILL.state: Scalable Long-Horizon Agent Skills},
+      author={Sanket Badhe and Priyanka Tiwari and Jonghyun Chung},
+      year={2026},
+      eprint={2608.26263},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2608.26263},
+}
+```

markov_agent-1.4.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "markov-agent"
+version = "1.4.0"
+description = "A coding agent following SKILL.state paper principles."
+requires-python = ">=3.13"
+readme = "README.md"
+dependencies = [
+    "lmdk>=2.10.3",
+    "textual>=6.0.0",
+]
+
+[project.license]
+text = "MIT"
+
+[[project.authors]]
+name = "Nacho Llorca"
+email = "nllorca@proton.me"
+
+[project.scripts]
+markov = "markov_agent.tui:main"
+
+[dependency-groups]
+dev = [
+    "logfire",
+    "complexipy",
+    "pytest-cov",
+    "ruff",
+    "ty",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.1,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+fix = true
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "D",
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+ignore = [
+    "D105",
+    "D107",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+build_command = ""
+commit_message = "chore: release {version}"
+commit_parser = "conventional"
+tag_format = "v{version}"
+changelog_file = false
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false

markov_agent-1.4.0/pyproject.toml.orig

@@ -0,0 +1,64 @@
+# Project metadata ------------------------------------------------------------
+[project]
+name = "markov-agent"
+version = "1.4.0"
+description = "A coding agent following SKILL.state paper principles."
+requires-python = ">=3.13"
+license = { text = "MIT" }
+readme = "README.md"
+authors = [{ name = "Nacho Llorca", email = "nllorca@proton.me" }]
+dependencies = [
+    "lmdk>=2.10.3",
+    "textual>=6.0.0",
+]
+
+[project.scripts]
+markov = "markov_agent.tui:main"
+
+# Dev / optional dependencies -------------------------------------------------
+[dependency-groups]
+dev = [
+    "logfire",
+    "complexipy",
+    "pytest-cov",
+    "ruff",
+    "ty",
+]
+
+# Build backend ---------------------------------------------------------------
+[build-system]
+requires = ["uv_build>=0.11.1,<0.12.0"]
+build-backend = "uv_build"
+
+# Ruff (lint + format) --------------------------------------------------------
+[tool.ruff]
+fix = true
+line-length = 100
+
+[tool.ruff.lint]
+select = ["D", "E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["D105", "D107"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+# Semantic release (automated versioning from conventional commits) -----------
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+build_command = ""  # We do this using uv in the CI verify.yaml workflow
+commit_message = "chore: release {version}"
+commit_parser = "conventional"
+tag_format = "v{version}"
+changelog_file = false
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+# Spelling --------------------------------------------------------------------
+# [tool.codespell]
+# skip = ["", ""]  # Comma separated list of regex strings to ignore files for the spelling check
+# ignore-words-list = "firstword,secondword"  # Specific strings to accept

markov_agent-1.4.0/src/markov_agent/__init__.py

@@ -0,0 +1 @@
+"""markov_agent."""

markov_agent-1.4.0/src/markov_agent/agent.py

@@ -0,0 +1,35 @@
+"""Domain definition for a small coding agent on top of `skill_state.run`."""
+
+from pydantic import BaseModel, Field
+
+DEFAULT_MODEL = "mistral:mistral-large-4"
+
+INSTRUCTIONS = """\
+You are a coding agent: you search and edit files in a project, and prove the change works.
+
+- Look before you change: read the relevant files (ls, grep, sed -n) before editing.
+- Read narrowly: grep / sed -n over whole files, the output is the observation you pay for.
+- Minimal diffs: sed / python one-liners / patches; never rewrite a whole file to change one line.
+- Verified means executed: run the tests or the code itself and keep its output as proof.
+"""
+
+
+class CodingAgentState(BaseModel):
+    """State of the coding agent."""
+
+    task: str = Field(description="The user's goal, restated in your words.")
+    plan: str = Field(
+        description="Remaining steps, next first. "
+        "A markdown task list: one `- [ ]` item per step, `- [X]` when done.",
+    )
+    facts: str = Field(
+        description="Everything learned from command output that you will need later: "
+        "file paths, error messages, line numbers, output values. As a markdown list."
+    )
+    failed_approaches: str = Field(description="Commands or fixes that did not work, and why.")
+    edits: str = Field(
+        description="Files changed so far, and why. A markdown list, one entry per line."
+    )
+    verification: str = Field(
+        description="Output of the run that proves the task is done.",
+    )

markov_agent-1.4.0/src/markov_agent/prompt_template.jinja

@@ -0,0 +1,48 @@
+You are an agent running in a loop inside a Unix shell.
+At each step you see only:
+- The instructions below
+- The request that started this session
+- The current state
+- Your last action, if there was one
+- The latest observation, produced by your last action or by your reply to the user
+
+Instructions:
+```
+{{instructions}}
+```
+
+Original Request:
+```
+{{request}}
+```
+
+Current execution state (step {{t}} of this turn):
+```json
+{{state}}
+```
+{% if last_action %}
+Your last action:
+```bash
+{{last_action}}
+```
+{% endif %}
+Latest observation:
+```
+{{observation}}
+```
+
+How to work:
+- One action or one reply per step. Don't cram the whole task into one action: the loop will show its result.
+- Both fields produce the next observation: a command's output, or the user's answer.
+- The state is your only memory: the observation is never shown again and your reasoning is discarded, so anything you will need later must be in the state after this step.
+- The observation wins over the state: if they disagree, the world changed or the state was wrong.
+- Never redo work whose result is already in the state.
+- Record failures, not just successes, so you don't retry what already failed.
+- Every step must move the task forward: learn a missing fact, make a change, verify one, or ask the user.
+- Only say the task is done when the state itself shows it is satisfied and verified.
+
+How to update the state (the `patch` field only):
+- Every state field appears in the patch, and each is required: set the ones you change to their new value, everything else to "unchanged" or "unset".
+- Update: setting a field replaces its whole current value. To add to a field, rewrite it in full: its current content first, then what you are adding.
+- Keep: set a field to "unchanged" to keep its current value.
+- Delete: set a field to "unset" to clear it (uninitialized fields start as "unset").

markov_agent-1.4.0/src/markov_agent/skill_state.py

@@ -0,0 +1,180 @@
+"""SKILL.state (arXiv:2608.26263) core implementation.
+
+Prompt stays O(1) instead of growing with the conversation.
+At each step t, the model sees only three things:
+    1. P: The immutable skill spec
+    2. Σₜ: The current state in the given per-domain structure
+    3. Oₜ: The latest observation
+
+It returns:
+    - A state update (patch) that produces Σₜ₊₁
+    - And either an action that will produce Oₜ₊₁, or a reply that ends the turn
+      and hands control back to the user
+"""
+
+import json
+import subprocess
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any, Literal
+
+from lmdk import complete, render_template
+from pydantic import BaseModel, Field, create_model
+
+PROMPT_TEMPLATE = Path(__file__).parent / "prompt_template.jinja"  # ships with the package
+BASH_TIMEOUT = 100  # seconds to wait for the bash
+MAX_BASH_OUTPUT = 100_000  # maximum chars of observation shown to the model
+
+
+def yolo_bash(command: str) -> str:
+    """Run a bash command and return its exit code, stdout and stderr."""
+    # ! Probably needs a white/black- list and / or a sandbox
+    proc = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=BASH_TIMEOUT)
+    output = (proc.stdout + proc.stderr).strip() or "(no output)"
+    truncated = ""
+    if len(output) > MAX_BASH_OUTPUT:
+        truncated = f"\n[The output has been truncated at the maximum {MAX_BASH_OUTPUT} characters]"
+    return f"(exit {proc.returncode})\n{output[:MAX_BASH_OUTPUT]}{truncated}"
+
+
+def update_state(state: dict, patch: dict) -> dict:
+    """Recursively merge *patch* (the state change made by the agent) into *state*."""
+    merged = dict(state)
+    for key, value in patch.items():
+        if value == "unchanged":
+            continue
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = update_state(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def derive_patch_schema(state_schema: type[BaseModel]) -> type[BaseModel]:
+    """Derive from the domain-defined schema a patch schema the model can emit.
+
+    Adds to each field the possibility to be "unchanged" (default) or "unset".
+    """
+    fields: dict[str, Any] = {}
+    for name, field in state_schema.model_fields.items():
+        ann = field.annotation
+        if isinstance(ann, type) and issubclass(ann, BaseModel):
+            ann = derive_patch_schema(ann)
+        patch_ann = ann | Literal["unchanged", "unset"]
+        fields[name] = (patch_ann, Field(default="unchanged", description=field.description))
+    return create_model(f"Patch_{state_schema.__name__}", **fields)
+
+
+def derive_schema(state_schema: type[BaseModel]) -> type[BaseModel]:
+    """Combine the patch schema with the action-or-reply decision the model answers with.
+
+    The patch comes first so the model records what it learned before deciding what to do.
+    The decision is one `kind` plus one `content`, so strict decoding can only produce exactly
+    one of action or reply (two optional fields got the patch's "unchanged" or both filled).
+    """
+    return create_model(
+        f"Step{state_schema.__name__}",
+        __doc__="One step of the loop: mutate the state, then either act or hand the turn back.",
+        patch=(
+            derive_patch_schema(state_schema),
+            Field(description="State changes only, never `kind` or `content`."),
+        ),
+        kind=(
+            Literal["action", "reply"],
+            Field(
+                description="`action`: run a shell command yourself, when the step is yours to "
+                "execute. `reply`: hand the turn to the user, with the result, a question or a "
+                "blocker, when only they can decide or when the task is done."
+            ),
+        ),
+        content=(
+            str,
+            Field(
+                description="The shell command if `kind` is action, the text for the user if "
+                "reply. Its output, or the user's answer, becomes the next observation."
+            ),
+        ),
+    )
+
+
+def initial_state(state_schema: type[BaseModel], state: dict | None = None) -> dict:
+    """Seed the state: required fields start as "unset", optional fields at their default."""
+    defaults = {
+        name: ("unset" if field.is_required() else field.get_default(call_default_factory=True))
+        for name, field in state_schema.model_fields.items()
+    }
+    return {**defaults, **(state or {})}
+
+
+class StepEvent(BaseModel):
+    """Representation of model state, action and observation at time t."""
+
+    t: int
+    state: dict
+    patch: dict
+    action: str | None
+    reply: str | None = None
+    observation: str | None = None
+
+
+def run(
+    model: str,
+    instructions: str,
+    request: str,
+    state_schema: type[BaseModel],
+    state: dict | None = None,
+    observation: str = "none",
+    max_steps: int = 50,
+) -> Iterator[StepEvent]:
+    """Execute one turn, until the model replies to the user or *max_steps* is hit.
+
+    Args:
+        model: Provider-prefixed model identifier, as in ``lmdk.complete``.
+        instructions: The immutable procedural specification (P in the paper).
+        state_schema: Domain-defined structure of the state (Σ in the paper) for this task.
+        request: The request that started the session. Stable across turns.
+        state: Initial execution state (Σ₀). Empty by default, can be used to start from checkpoint.
+        observation: The observation the turn starts from (O₀): the user's reply to the previous
+            turn, or "none" on the first one.
+        max_steps: Horizon cap, so a looping model cannot burn tokens forever.
+
+    Yields:
+        One ``StepEvent`` per step, carrying the post-patch state, the patch itself,
+        the action proposed and the observation it was conditioned on. The final
+        event carries the ``reply`` handed back to the user, or ``reply=None`` when
+        *max_steps* ran out. Call ``run`` again with the final state and the user's
+        next message to continue.
+    """
+    state = initial_state(state_schema, state)
+    schema = derive_schema(state_schema)
+    last_action = None  # the model never sees its own previous action otherwise
+    for t in range(max_steps):
+        prompt = render_template(
+            path=PROMPT_TEMPLATE,
+            instructions=instructions,
+            request=request,
+            state=json.dumps(state, separators=(",", ":")),
+            observation=observation,
+            last_action=last_action,
+            t=t,
+        )
+        response = complete(
+            model=model, prompt=prompt, output_schema=schema, thinking_effort="high"
+        )
+        assert response.output is not None
+        step = response.output.model_dump()
+        patch = step["patch"]
+        state = update_state(state, patch)
+        replied = step["kind"] == "reply"
+        yield StepEvent(
+            t=t,
+            state=state,
+            patch=patch,
+            action=None if replied else step["content"],
+            reply=step["content"] if replied else None,
+            observation=observation,
+        )
+        if replied:  # turn handed back to the user
+            break
+        last_action = step["content"]
+        observation = yolo_bash(last_action)

markov_agent-1.4.0/src/markov_agent/tui.py

@@ -0,0 +1,238 @@
+"""Terminal UI for SKILL.state agents: watch the state get patched step by step.
+
+The screen mirrors what the model sees at step t: the state Σₜ on the left, where each field
+shows the diff the patch makes to produce Σₜ₊₁, and on the right the observation Oₜ plus the
+action or reply the model answered with. A timeline scrubs through past steps and the input
+opens the session (the request) and continues it (the reply to each of the agent's replies).
+"""
+
+import argparse
+import difflib
+import json
+import os
+from typing import Any
+
+from pydantic import BaseModel
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.widgets import Collapsible, Footer, Header, Input, Static
+from textual.worker import get_current_worker
+
+from .agent import DEFAULT_MODEL, INSTRUCTIONS, CodingAgentState
+from .skill_state import StepEvent, initial_state, run
+
+_SUB = str.maketrans("0123456789", "₀₁₂₃₄₅₆₇₈₉")
+_DIFF_STYLES = {"+": "green", "-": "red", " ": ""}
+
+
+def _lines(value: Any) -> list[str]:
+    if value == "unset":
+        return []
+    return (value if isinstance(value, str) else json.dumps(value, indent=2)).splitlines()
+
+
+def field_diff(old: Any, new: Any) -> Text:
+    """Line diff of one state field: removed lines red, added lines green."""
+    lines = difflib.ndiff(_lines(old), _lines(new))
+    # ndiff also emits "?" hint lines, which only make sense in monospace side by side
+    return Text("\n").join(Text(line, _DIFF_STYLES[line[0]]) for line in lines if line[0] != "?")
+
+
+class MarkovApp(App):
+    """Run a SKILL.state agent one turn at a time, showing each step as state + patch."""
+
+    CSS = """
+    #main { height: 1fr; margin-top: 1; }
+    #state, #step { width: 1fr; }
+    #state { border: round $primary; }
+    #observation { height: 2fr; border: round $secondary; }
+    #cause { color: $accent; text-style: bold; border-bottom: solid $secondary; display: none; }
+    #output { height: 1fr; border: round $accent; }
+    #output.reply { border: heavy $success; }
+    Collapsible { padding-bottom: 0; }
+    Collapsible Contents { padding-top: 0; }
+    Collapsible.patched { border-left: thick $warning; }
+    #timeline { height: auto; max-height: 3; padding: 0 1; }
+    Input { margin-bottom: 1; }
+    """
+    BINDINGS = [  # noqa: RUF012 (textual's own convention)
+        # priority: pageup/pagedown must scrub even while typing in the input
+        Binding("pageup", "scrub(-1)", "Previous step", priority=True),
+        Binding("pagedown", "scrub(1)", "Next step", priority=True),
+    ]
+
+    def __init__(
+        self,
+        model: str,
+        instructions: str,
+        state_schema: type[BaseModel],
+        state: dict | None = None,
+    ):
+        super().__init__()
+        self.model = model
+        self.instructions = instructions
+        self.state_schema = state_schema
+        self.state = initial_state(state_schema, state)
+        self.request = ""
+        self.turn = 0
+        self.steps: list[tuple[int, dict, StepEvent]] = []  # (turn, state before the step, step)
+        self.selected = -1  # selected step; following live while it is the last one
+        self.status = "type your request below"
+
+    def compose(self) -> ComposeResult:
+        """Lay out a fixed panel per state field, so nothing moves between steps."""
+        yield Header()
+        with Horizontal(id="main"):
+            with VerticalScroll(id="state"):
+                with Collapsible(title="instructions (P)"):
+                    yield Static(self.instructions, markup=False)
+                for name in self.state_schema.model_fields:
+                    with Collapsible(title=name, id=f"field-{name}"):
+                        yield Static(id=f"value-{name}", markup=False)
+            with Vertical(id="step"):
+                with Vertical(id="observation"):
+                    yield Static(id="cause", markup=False)  # the action whose output this is
+                    with VerticalScroll():
+                        yield Static(id="obs", markup=False)
+                with VerticalScroll(id="output"):
+                    yield Static(id="out", markup=False)
+        yield Static(id="timeline")
+        yield Input(placeholder="Your request…")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Show the initial state Σ₀ before anything ran."""
+        self.title = f"markov · {self.model}"
+        self._show_state(self.state, self.state, "STATE Σ₀")
+        self._show_timeline()
+        self.query_one(Input).focus()
+
+    def on_input_submitted(self, message: Input.Submitted) -> None:
+        """The first message is the request, every later one is the next turn's observation."""
+        text = message.value.strip()
+        if not text:
+            return
+        message.input.clear()
+        observation = text
+        if not self.request:
+            self.request, observation = text, "none"
+            self.sub_title = text
+            message.input.placeholder = "Your reply…"
+        self.turn += 1
+        self._set_busy("working…", busy=True)
+        self._run_turn(observation)
+
+    @work(thread=True, exclusive=True)
+    def _run_turn(self, observation: str) -> None:
+        """Consume `run` off the UI thread and hand every step to the UI as it arrives."""
+        worker = get_current_worker()
+        status = "step limit reached, reply to continue"
+        try:
+            for event in run(
+                model=self.model,
+                instructions=self.instructions,
+                request=self.request,
+                state_schema=self.state_schema,
+                state=self.state,
+                observation=observation,
+            ):
+                if worker.is_cancelled:  # app is quitting
+                    return
+                self.call_from_thread(self._add_step, event)
+                if event.reply:
+                    status = "your turn"
+        except Exception as error:  # keep the session: the state survives, the user can retry
+            status = f"error: {error}"
+        if not worker.is_cancelled:
+            self.call_from_thread(self._set_busy, status, busy=False)
+
+    def _add_step(self, event: StepEvent) -> None:
+        following = self.selected == len(self.steps) - 1
+        self.steps.append((self.turn, self.state, event))
+        self.state = event.state
+        if following:
+            self.selected = len(self.steps) - 1
+        self._show_step()
+
+    def _set_busy(self, status: str, busy: bool) -> None:
+        self.status = status
+        box = self.query_one(Input)
+        box.disabled = busy
+        if not busy:
+            box.focus()
+        self._show_timeline()
+
+    def action_scrub(self, delta: int) -> None:
+        """Move the selection through past steps; reaching the last one follows live again."""
+        if self.steps:
+            self.selected = max(0, min(len(self.steps) - 1, self.selected + delta))
+            self._show_step()
+
+    def _show_step(self) -> None:
+        _, before, event = self.steps[self.selected]
+        t, t1 = str(event.t).translate(_SUB), str(event.t + 1).translate(_SUB)
+        self._show_state(before, event.state, f"STATE Σ{t} → Σ{t1}")
+        # Oₜ is the output of the previous step's action, or the user's message at a turn start
+        cause = self.steps[self.selected - 1][2].action if event.t else None
+        source = f"a{str(event.t - 1).translate(_SUB)}" if cause else "user"
+        self.query_one("#observation").border_title = f"OBSERVATION O{t} ← {source}"
+        cause_box = self.query_one("#cause", Static)
+        cause_box.display = bool(cause)
+        cause_box.update(f"$ {cause}")
+        self.query_one("#obs", Static).update(event.observation or "none")
+        output = self.query_one("#output")
+        output.set_class(bool(event.reply), "reply")
+        output.border_title = "REPLY" if event.reply else f"ACTION a{t}"
+        self.query_one("#out", Static).update(event.reply or event.action or "")
+        self._show_timeline()
+
+    def _show_state(self, before: dict, after: dict, title: str) -> None:
+        self.query_one("#state").border_title = title
+        for name in self.state_schema.model_fields:
+            old, new = before.get(name), after.get(name)
+            changed = old != new
+            label = "patched" if changed else "unset" if new == "unset" else "unchanged"
+            box = self.query_one(f"#field-{name}", Collapsible)
+            box.title = f"{name} · {label}"
+            box.collapsed = not changed
+            box.set_class(changed, "patched")
+            value = field_diff(old, new) if changed else Text("\n".join(_lines(new)), "dim")
+            self.query_one(f"#value-{name}", Static).update(value)
+
+    def _show_timeline(self) -> None:
+        # shortcut: one glyph per step wraps after ~3 lines of steps, upgrade to a scrolling strip
+        line = Text()
+        for i, (_, _, event) in enumerate(self.steps):
+            if event.t == 0 and i:
+                line.append("│", "dim")
+            line.append("◉" if i == self.selected else "○", "bold" if i == self.selected else "dim")
+        if self.steps:
+            turn, _, event = self.steps[self.selected]
+            line.append(f"  turn {turn} · step {event.t}")
+        line.append(f"   {self.status}", "italic")
+        self.query_one("#timeline", Static).update(line)
+
+
+def main() -> None:
+    """Entry point of the ``markov`` command."""
+    parser = argparse.ArgumentParser(description="Run the coding agent in a terminal UI.")
+    parser.add_argument("--model", default=DEFAULT_MODEL, help="Language model to use.")
+    parser.add_argument("--working-dir", default=os.getcwd(), help="Project directory.")
+    args = parser.parse_args()
+
+    if os.getenv("LMDK_TELEMETRY"):
+        import logfire
+
+        logfire.configure(
+            token=os.environ["LOGFIRE_TOKEN"],
+            service_name="skill-state-coding-agent",
+            scrubbing=False,
+            send_to_logfire=True,
+            console=False,  # console output would draw over the TUI
+        )
+
+    os.chdir(args.working_dir)  # commands run in a shell that inherits this cwd
+    MarkovApp(args.model, INSTRUCTIONS, CodingAgentState).run()