marcus-toolkit 0.1.0__tar.gz

marcus_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Larry Gray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marcus_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: marcus-toolkit
+Version: 0.1.0
+Summary: The run-side toolbox Marcus extensions share: a server under test, seeding, run guards, the cost watchdog, the board sampler, measures, the run record, and a pull-loop agent shell
+License: MIT License
+        
+        Copyright (c) 2025 Larry Gray
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/painted-porch/marcus-toolkit
+Project-URL: Changelog, https://github.com/painted-porch/marcus-toolkit/blob/main/CHANGELOG.md
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest==7.4.3; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: ruff==0.15.5; extra == "dev"
+Requires-Dist: black==26.3.0; extra == "dev"
+Dynamic: license-file
+
+# marcus-toolkit
+
+The run-side toolbox that Marcus extensions share.
+
+## What this is, briefly
+
+[Marcus](https://github.com/painted-porch/marcus) coordinates AI agents through a shared task board: agents pull work from the board over MCP (the Model Context Protocol, the wire protocol for Marcus's tools), do it, and report back with evidence.
+An *extension* is a separate program that seeds a board and runs agents against it for one purpose: verifying citations, verifying a numerical report, coordinating Minecraft agents, refereeing a wargame.
+
+Every extension needs the same scaffolding around a run, and every extension so far rebuilt it.
+This package is that scaffolding, built once (the inventory and the reasoning are in painted-porch/marcus issue #914):
+
+| Module | What it does |
+| --- | --- |
+| `marcus_toolkit.server` | a **server under test**: a private Marcus started for one run with every model-provider key stripped from its environment and the model switched off with an empty key, so the run can spend nothing by construction; refuses a port someone else holds and proves the port's owner is this run's server |
+| `marcus_toolkit.seed` | seeds a project with exactly the tasks named, through `create_project(options.tasks)`, and refuses before the call what the board would mis-handle: an unknown spec key, a `build`-family label, a dependency naming no task, a project name containing "test" |
+| `marcus_toolkit.watchdog` | stops a run the moment its spend reaches the approved line; the line is re-read on every poll when it comes from a file |
+| `marcus_toolkit.pricing`, `marcus_toolkit.usage` | one price table; usage rows read from pi's transcripts or from `<state>/<agent>/usage.jsonl`, one row per model call, which any runtime can write |
+| `marcus_toolkit.sampler` | reads the board from outside every few seconds and applies the drain verdict's claimability rule, so frontier width has a time series |
+| `marcus_toolkit.integrity` | hashes the files that execute, hashes the same files as committed, records a checkout's version |
+| `marcus_toolkit.record` | the run record: `runs/<stamp>/`, `run-config.txt`, JSONL streams, copies |
+| `marcus_toolkit.measure` | pulls and the idle-poll ratio, the kernel's frontier series, the sampler's series, board counts from a copy of `kanban.db` |
+| `marcus_toolkit.client`, `marcus_toolkit.agent` | the MCP client and a pull-loop agent shell in Python |
+| `node/` | the same client in Node: `mcp-http.js` and `board.js` |
+| `marcus_toolkit.livecheck` | the toolbox's own live check against a real Marcus checkout |
+
+Nothing in this package imports Marcus's own code.
+It talks to a server over MCP and reads the files a run leaves behind, which is all an extension may do (`docs/architecture/extension-contract.md` in the Marcus repository).
+
+## Install
+
+```bash
+pip install -e .            # from a checkout
+pip install -e ".[dev]"     # with the test and lint tools
+```
+
+For the Node client, import `node/board.js` and `node/mcp-http.js` directly; they have no dependencies.
+
+## The live check
+
+```bash
+python -m marcus_toolkit.livecheck --checkout ~/dev/marcus --out livecheck-runs
+```
+
+Starts a server under test from that checkout, seeds two tasks (the second depending on the first), runs one scripted agent through register, pull, report, pull, report, drain, reads the board from outside before and after, and writes `livecheck-runs/<stamp>/VERDICT.json`.
+It passes only when every card closed, the agent heard the drain, every reply was read back, and the server log carries no model-provider host.
+CI runs it against the Marcus commit pinned in `.github/workflows/ci.yml`.
+
+## Where it came from
+
+The Minecraft harness's plumbing (`painted-porch/marcus-minecraft`, `plumbing/`), the Marcus experiment runners (`dev-tools/experiments/runners/marcus_client.py`), and the AI-citation verifier's free rehearsal.
+The defects those runs found are fixed here once: a stop line read only at process start, a placeholder key that fired one real call on startup, a task spec whose extra key broke every promotion, a blocked task counted as claimable.
+
+## Versioning
+
+Each release states the Marcus commit it was live-checked against.
+The toolbox depends on Marcus's MCP tool names and reply shapes, not on its code; when those change, this package gets a release, not a patch to the kernel.

marcus_toolkit-0.1.0/README.md

@@ -0,0 +1,57 @@
+# marcus-toolkit
+
+The run-side toolbox that Marcus extensions share.
+
+## What this is, briefly
+
+[Marcus](https://github.com/painted-porch/marcus) coordinates AI agents through a shared task board: agents pull work from the board over MCP (the Model Context Protocol, the wire protocol for Marcus's tools), do it, and report back with evidence.
+An *extension* is a separate program that seeds a board and runs agents against it for one purpose: verifying citations, verifying a numerical report, coordinating Minecraft agents, refereeing a wargame.
+
+Every extension needs the same scaffolding around a run, and every extension so far rebuilt it.
+This package is that scaffolding, built once (the inventory and the reasoning are in painted-porch/marcus issue #914):
+
+| Module | What it does |
+| --- | --- |
+| `marcus_toolkit.server` | a **server under test**: a private Marcus started for one run with every model-provider key stripped from its environment and the model switched off with an empty key, so the run can spend nothing by construction; refuses a port someone else holds and proves the port's owner is this run's server |
+| `marcus_toolkit.seed` | seeds a project with exactly the tasks named, through `create_project(options.tasks)`, and refuses before the call what the board would mis-handle: an unknown spec key, a `build`-family label, a dependency naming no task, a project name containing "test" |
+| `marcus_toolkit.watchdog` | stops a run the moment its spend reaches the approved line; the line is re-read on every poll when it comes from a file |
+| `marcus_toolkit.pricing`, `marcus_toolkit.usage` | one price table; usage rows read from pi's transcripts or from `<state>/<agent>/usage.jsonl`, one row per model call, which any runtime can write |
+| `marcus_toolkit.sampler` | reads the board from outside every few seconds and applies the drain verdict's claimability rule, so frontier width has a time series |
+| `marcus_toolkit.integrity` | hashes the files that execute, hashes the same files as committed, records a checkout's version |
+| `marcus_toolkit.record` | the run record: `runs/<stamp>/`, `run-config.txt`, JSONL streams, copies |
+| `marcus_toolkit.measure` | pulls and the idle-poll ratio, the kernel's frontier series, the sampler's series, board counts from a copy of `kanban.db` |
+| `marcus_toolkit.client`, `marcus_toolkit.agent` | the MCP client and a pull-loop agent shell in Python |
+| `node/` | the same client in Node: `mcp-http.js` and `board.js` |
+| `marcus_toolkit.livecheck` | the toolbox's own live check against a real Marcus checkout |
+
+Nothing in this package imports Marcus's own code.
+It talks to a server over MCP and reads the files a run leaves behind, which is all an extension may do (`docs/architecture/extension-contract.md` in the Marcus repository).
+
+## Install
+
+```bash
+pip install -e .            # from a checkout
+pip install -e ".[dev]"     # with the test and lint tools
+```
+
+For the Node client, import `node/board.js` and `node/mcp-http.js` directly; they have no dependencies.
+
+## The live check
+
+```bash
+python -m marcus_toolkit.livecheck --checkout ~/dev/marcus --out livecheck-runs
+```
+
+Starts a server under test from that checkout, seeds two tasks (the second depending on the first), runs one scripted agent through register, pull, report, pull, report, drain, reads the board from outside before and after, and writes `livecheck-runs/<stamp>/VERDICT.json`.
+It passes only when every card closed, the agent heard the drain, every reply was read back, and the server log carries no model-provider host.
+CI runs it against the Marcus commit pinned in `.github/workflows/ci.yml`.
+
+## Where it came from
+
+The Minecraft harness's plumbing (`painted-porch/marcus-minecraft`, `plumbing/`), the Marcus experiment runners (`dev-tools/experiments/runners/marcus_client.py`), and the AI-citation verifier's free rehearsal.
+The defects those runs found are fixed here once: a stop line read only at process start, a placeholder key that fired one real call on startup, a task spec whose extra key broke every promotion, a blocked task counted as claimable.
+
+## Versioning
+
+Each release states the Marcus commit it was live-checked against.
+The toolbox depends on Marcus's MCP tool names and reply shapes, not on its code; when those change, this package gets a release, not a patch to the kernel.

marcus_toolkit-0.1.0/marcus_toolkit/__init__.py

@@ -0,0 +1,27 @@
+"""
+The run-side toolkit Marcus extensions share (issue #914).
+
+An extension is a program that seeds a Marcus board and runs agents against
+it for one purpose. Every extension so far rebuilt the same scaffolding:
+a private server for the run, seeding, guards, a cost watchdog, a board
+sampler, measures and a run record. This package is that scaffolding,
+lifted from the Minecraft plumbing (``~/marcus-experiments/minecraft-plumbing``)
+with the defects its runs found fixed once.
+
+Nothing here imports Marcus's own code under ``src/``: the toolkit talks to
+a server over MCP and reads its files, the same way an extension must
+(``docs/architecture/extension-contract.md``).
+"""
+
+__all__ = [
+    "client",
+    "pricing",
+    "usage",
+    "watchdog",
+    "sampler",
+    "integrity",
+    "server",
+    "seed",
+    "record",
+    "measure",
+]

marcus_toolkit-0.1.0/marcus_toolkit/agent.py

@@ -0,0 +1,451 @@
+"""
+A pull-loop agent shell in Python: the Node client's ``board.js``, for Python runtimes.
+
+Register with a project (Marcus hands work only to a registered agent), pull,
+absorb "ask again" replies without a model turn, hold the task and its lease
+epoch across a restart, report with the lease epoch and evidence, leave
+markers, record decisions, read the board. Every call is one record with the
+six fields the Minecraft runs measure: ``at``, ``agent``, ``tool``, ``args``,
+``outcome``, ``ms``, ``reply``.
+
+Nothing here talks to another agent. The board is the only channel.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable, Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class ToolClient(Protocol):
+    """What the shell needs from a client: a tool call returning a reply or None."""
+
+    def call_tool(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> dict[str, Any] | None:
+        """Call a tool and return its reply body, or ``None``."""
+
+
+def outcome_of(tool: str, reply: dict[str, Any]) -> str:
+    """
+    Classify a reply the way the Minecraft harness does.
+
+    Parameters
+    ----------
+    tool : str
+        The tool called.
+    reply : Dict[str, Any]
+        The reply body.
+
+    Returns
+    -------
+    str
+        ``transport_error``, ``drained``, ``assigned``, ``retry``, ``failed`` or ``ok``.
+    """
+    if reply.get("transport_error") or reply.get("rpc_error"):
+        return "transport_error"
+    if reply.get("status") == "BOARD_DRAINED":
+        return "drained"
+    if tool == "request_next_task":
+        return "assigned" if reply.get("success") is True else "retry"
+    return "failed" if reply.get("success") is False else "ok"
+
+
+def jsonl_logger(path: Path) -> Callable[[dict[str, Any]], None]:
+    """
+    Append one JSON line per record to ``path``, flushed at once.
+
+    Parameters
+    ----------
+    path : Path
+        ``<state>/<agent>/board-calls.jsonl``; parents are created.
+
+    Returns
+    -------
+    Callable[[Dict[str, Any]], None]
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log(record: dict[str, Any]) -> None:
+        with path.open("a") as handle:
+            handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+    return log
+
+
+class BoardAgent:
+    """
+    One agent's board client.
+
+    Parameters
+    ----------
+    client : ToolClient
+        A connected MCP client.
+    agent_id : str
+        The agent's id on the board.
+    project_id : str
+        The project it registers to.
+    role : str
+        The role string sent on registration (not enforced by the kernel).
+    skills : Sequence[str]
+        The skills sent on registration.
+    project_root : str
+        Where artifacts are written; a directory that is not a repository.
+    log : Optional[Callable[[Dict[str, Any]], None]]
+        Receives one record per board call.
+    hold_path : Optional[Path]
+        Where the held task and its lease epoch persist across a restart.
+    sleep : Callable[[float], None]
+        The sleep used to absorb retries; tests pass a stub.
+    now : Callable[[], float]
+        The clock, in seconds.
+    """
+
+    def __init__(
+        self,
+        client: ToolClient,
+        agent_id: str,
+        project_id: str,
+        *,
+        role: str = "worker",
+        skills: Sequence[str] = ("worker",),
+        project_root: str = "",
+        log: Callable[[dict[str, Any]], None] | None = None,
+        hold_path: Path | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        self.client = client
+        self.agent_id = agent_id
+        self.project_id = project_id
+        self.role = role
+        self.skills = list(skills)
+        self.project_root = project_root
+        self.log = log
+        self.hold_path = hold_path
+        self.sleep = sleep
+        self.now = now
+        self.registered = False
+        self.objective: str | None = None
+        self.task: dict[str, Any] | None = None
+        self.lease_epoch: int | None = None
+        if hold_path is not None and hold_path.is_file():
+            held = json.loads(hold_path.read_text())
+            self.task = held.get("task")
+            self.lease_epoch = held.get("lease_epoch")
+
+    def _remember(self) -> None:
+        if self.hold_path is None:
+            return
+        if self.task:
+            self.hold_path.parent.mkdir(parents=True, exist_ok=True)
+            self.hold_path.write_text(
+                json.dumps({"task": self.task, "lease_epoch": self.lease_epoch})
+            )
+        elif self.hold_path.exists():
+            self.hold_path.unlink()
+
+    def board(self, tool: str, args: dict[str, Any]) -> dict[str, Any]:
+        """
+        Call one tool, timing and logging it.
+
+        Parameters
+        ----------
+        tool : str
+            The tool name.
+        args : Dict[str, Any]
+            The arguments.
+
+        Returns
+        -------
+        Dict[str, Any]
+            The reply body; a missing reply becomes a transport error.
+        """
+        started = self.now()
+        reply = self.client.call_tool(tool, args)
+        if reply is None:
+            reply = {"success": False, "error": "no reply", "transport_error": True}
+        if self.log:
+            self.log(
+                {
+                    "at": datetime.now(UTC).isoformat(),
+                    "agent": self.agent_id,
+                    "tool": tool,
+                    "args": args,
+                    "outcome": outcome_of(tool, reply),
+                    "ms": int((self.now() - started) * 1000),
+                    "reply": reply,
+                }
+            )
+        return reply
+
+    def register(self) -> dict[str, Any]:
+        """Register with the project and read its objective once."""
+        reply = self.board(
+            "register_agent",
+            {
+                "agent_id": self.agent_id,
+                "name": self.agent_id,
+                "role": self.role,
+                "skills": self.skills,
+                "project_id": self.project_id,
+            },
+        )
+        if reply.get("success") is False:
+            return reply
+        self.registered = True
+        primer = self.board(
+            "query_project_history",
+            {
+                "project_id": self.project_id,
+                "query_type": "opinions",
+                "kind": "objective",
+                "limit": 1,
+            },
+        )
+        data = primer.get("data") if primer.get("success") is not False else None
+        try:
+            what = data[0]["opinions"][0]["what"] if data else None
+        except (KeyError, IndexError, TypeError):
+            what = None
+        if isinstance(what, str) and what.strip():
+            self.objective = what.strip()
+        return reply
+
+    def pull(
+        self,
+        absorb: bool = False,
+        max_asks: int | None = None,
+        wait_seconds: float | None = None,
+    ) -> dict[str, Any]:
+        """
+        Ask for work.
+
+        Parameters
+        ----------
+        absorb : bool
+            Wait out "ask again" replies here, one board call per ask.
+        max_asks : Optional[int]
+            Stop absorbing after this many asks.
+        wait_seconds : Optional[float]
+            Override the reply's ``retry_after_seconds``.
+
+        Returns
+        -------
+        Dict[str, Any]
+            ``status`` is ``assigned`` (with ``task``, ``lease_epoch``, ``context``,
+            ``opinions``, maybe ``objective``), ``retry``, ``drained``, ``error`` or
+            ``holding``.
+        """
+        if not self.registered:
+            refused = self.register()
+            if refused.get("success") is False:
+                return {"status": "error", "reply": refused}
+        if self.task:
+            return {"status": "holding", "task": self.task}
+        asks = 0
+        while True:
+            reply = self.board("request_next_task", {"agent_id": self.agent_id})
+            asks += 1
+            task = reply.get("task")
+            if reply.get("success") is True and isinstance(task, dict):
+                self.task = {"id": task.get("id"), "name": task.get("name")}
+                self.lease_epoch = reply.get("lease_epoch")
+                self._remember()
+                context = self.board("get_task_context", {"task_id": task.get("id")})
+                opinions = self.board(
+                    "query_project_history",
+                    {
+                        "project_id": self.project_id,
+                        "query_type": "opinions",
+                        "limit": 20,
+                    },
+                )
+                out: dict[str, Any] = {
+                    "status": "assigned",
+                    "task": task,
+                    "lease_epoch": self.lease_epoch,
+                    "context": context,
+                    "opinions": opinions,
+                }
+                if self.objective:
+                    out["objective"] = self.objective
+                return out
+            if reply.get("status") == "BOARD_DRAINED":
+                return {"status": "drained", "reply": reply}
+            if reply.get("transport_error") or reply.get("rpc_error"):
+                return {"status": "error", "reply": reply}
+            if not absorb or (max_asks is not None and asks >= max_asks):
+                return {"status": "retry", "reply": reply}
+            wait = (
+                wait_seconds
+                if wait_seconds is not None
+                else max(1.0, float(reply.get("retry_after_seconds") or 30))
+            )
+            self.sleep(wait)
+
+    def report(
+        self,
+        status: str,
+        message: str,
+        *,
+        progress: int | None = None,
+        subject: str | None = None,
+        observation: str | None = None,
+        evidence: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Report on the held task; completion or blocking clears the hold.
+
+        Parameters
+        ----------
+        status : str
+            ``in_progress``, ``completed`` or ``blocked``.
+        message : str
+            What was done.
+        progress : Optional[int]
+            Percent; 100 for completed, else 50 by default.
+        subject : Optional[str]
+            A marker subject, so the report is also an opinion.
+        observation : Optional[str]
+            The marker's text.
+        evidence : Optional[Dict[str, Any]]
+            The structured evidence the close carries.
+
+        Returns
+        -------
+        Dict[str, Any]
+        """
+        if not self.task:
+            return {"success": False, "error": "You hold no task."}
+        args: dict[str, Any] = {
+            "agent_id": self.agent_id,
+            "task_id": self.task["id"],
+            "status": status,
+            "progress": (
+                progress
+                if progress is not None
+                else (100 if status == "completed" else 50)
+            ),
+            "message": message,
+        }
+        if subject and subject.strip():
+            args["subject"] = subject.strip()
+        if observation and observation.strip():
+            args["observation"] = observation.strip()
+        if evidence:
+            args["evidence"] = evidence
+        if self.lease_epoch:
+            args["lease_epoch"] = self.lease_epoch
+        reply = self.board("report_task_progress", args)
+        if reply.get("success") is not False and status != "in_progress":
+            self.task = None
+            self.lease_epoch = None
+            self._remember()
+        return reply
+
+    def _registered(self) -> dict[str, Any] | None:
+        """Register first if needed; return the refusal when registration fails."""
+        if self.registered:
+            return None
+        reply = self.register()
+        return reply if reply.get("success") is False else None
+
+    def opinion(
+        self,
+        subject: str,
+        what: str,
+        why: str = "",
+        impact: str = "",
+        about_task: bool = False,
+    ) -> dict[str, Any]:
+        """Leave a marker on the board; registers first when needed (K6)."""
+        refused = self._registered()
+        if refused is not None:
+            return refused
+        args: dict[str, Any] = {
+            "agent_id": self.agent_id,
+            "subject": subject,
+            "what": what,
+            "why": why,
+            "impact": impact,
+        }
+        if about_task and self.task:
+            args["task_id"] = self.task["id"]
+        return self.board("give_opinion", args)
+
+    def decide(
+        self, what: str, why: str, subject: str | None = None, kind: str = "decision"
+    ) -> dict[str, Any]:
+        """Record what the agent did and why; never counted toward a candidate."""
+        refused = self._registered()
+        if refused is not None:
+            return refused
+        mark = "DECISION" if kind == "decision" else "THOUGHT"
+        args: dict[str, Any] = {
+            "agent_id": self.agent_id,
+            "decision": (
+                f"{mark}: {what.strip().rstrip('.')}"
+                f" because {why.strip().rstrip('.')}."
+            ),
+            "task_id": self.task["id"] if self.task else "",
+        }
+        if subject and subject.strip():
+            args["subject"] = subject.strip()
+        return self.board("log_decision", args)
+
+    def artifact(
+        self,
+        filename: str,
+        content: str,
+        description: str = "",
+        artifact_type: str = "world-state",
+    ) -> dict[str, Any]:
+        """Put a file on the board as evidence for the held task."""
+        if not self.task:
+            return {"success": False, "error": "You hold no task."}
+        return self.board(
+            "log_artifact",
+            {
+                "task_id": self.task["id"],
+                "filename": filename,
+                "content": content,
+                "artifact_type": artifact_type,
+                "project_root": self.project_root,
+                "description": description,
+            },
+        )
+
+    def opinions(self, limit: int = 50, kind: str | None = None) -> dict[str, Any]:
+        """Read the board's markers."""
+        args: dict[str, Any] = {
+            "project_id": self.project_id,
+            "query_type": "opinions",
+            "limit": limit,
+        }
+        if kind:
+            args["kind"] = kind
+        return self.board("query_project_history", args)
+
+    def decisions(self, limit: int = 20) -> dict[str, Any]:
+        """Read the board's decisions."""
+        return self.board(
+            "query_project_history",
+            {
+                "project_id": self.project_id,
+                "query_type": "decisions",
+                "kind": "decision",
+                "limit": limit,
+            },
+        )
+
+    def status(self) -> dict[str, Any]:
+        """Read the project's status."""
+        return self.board("get_project_status", {})
+
+
+__all__: list[str] = ["BoardAgent", "ToolClient", "jsonl_logger", "outcome_of"]