Python
ocw CLI + team-board MCP server on stdio
Rohit C Prasad36aa1da728a8
diff --git a/coworker/teams/cli.py b/coworker/teams/cli.pynew file mode 100644index 00000000..18dce0cd--- /dev/null+++ b/coworker/teams/cli.py@@ -0,0 +1,467 @@+"""`ocw` — the board and journal from any shell, for any harness.++The board is an open surface (OPE-100): the same role-scoped verbs the in-app+agents get, usable by an external agent CLI, a script, or a human. Point it at a+running OpenWorker server (same machine or remote) or straight at a state dir.++Backing resolution, in order:+1. `--url` + `--token` (or OCW_BOARD_URL / OCW_BOARD_TOKEN) — a remote board.+2. `--db DIR` — direct SQLite in that state dir (headless; you are the only writer).+3. A running local server, discovered via its sidecar token files — the CLI mints+ itself a local user token on first use. This is preferred over direct SQLite+ whenever a server is up: two processes must never write one board file.+4. Direct SQLite on the default state dir (nothing else is running).++`ocw board mcp` serves the same surface as an MCP server on stdio — the way to+hand a board to an external coding agent: point the agent's MCP config at+`ocw board mcp --url … --token … --space …` and ask it to claim a work item.+"""++from __future__ import annotations++import argparse+import json+import os+import sys+from pathlib import Path+from typing import Any, Optional++from .model import BoardError, space_for_workspace+from .store import CLAIM_POLICIES++_STATES = ("open", "in_progress", "blocked", "review", "done", "canceled")+++def main(argv: Optional[list[str]] = None) -> int:+ parser = _parser()+ args = parser.parse_args(argv)+ if not getattr(args, "cmd", None):+ parser.print_help()+ return 2+ try:+ return args.func(args)+ except BoardError as error:+ print(f"error: {error}", file=sys.stderr)+ return 1+++def _parser() -> argparse.ArgumentParser:+ parser = argparse.ArgumentParser(+ prog="ocw", description="OpenWorker team board + journal CLI."+ )+ sub = parser.add_subparsers(dest="group")++ board = sub.add_parser("board", help="work-item board verbs")+ board_sub = board.add_subparsers(dest="cmd")++ def cmd(name: str, func, help: str, parent=board_sub):+ p = parent.add_parser(name, help=help)+ _backing_args(p)+ p.set_defaults(func=func, cmd=name)+ return p++ p = cmd("list", _cmd_list, "list items")+ p.add_argument("--state", choices=_STATES, default="")+ p.add_argument("--assignee", default="")+ p.add_argument("--mine", action="store_true", help="only items assigned to me")++ p = cmd("show", _cmd_show, "one item, with comments")+ p.add_argument("id", type=int)++ p = cmd("create", _cmd_create, "file a new item (open, unassigned)")+ p.add_argument("title")+ p.add_argument("--criteria", required=True, help="acceptance criteria")+ p.add_argument("--description", default="")+ p.add_argument("--parent", type=int, default=None)+ p.add_argument("--case", default="")++ p = cmd("claim", _cmd_claim, "claim an open, unassigned item for yourself")+ p.add_argument("id", type=int)++ p = cmd("move", _cmd_move, "transition an item")+ p.add_argument("id", type=int)+ p.add_argument("to", choices=_STATES[1:] + ("open",))+ p.add_argument("--comment", default="")+ p.add_argument("--ref", action="append", default=[], dest="refs")++ p = cmd("comment", _cmd_comment, "comment on an item")+ p.add_argument("id", type=int)+ p.add_argument("body")+ p.add_argument("--ref", action="append", default=[], dest="refs")++ p = cmd("assign", _cmd_assign, "assign an item (lead/user)")+ p.add_argument("id", type=int)+ p.add_argument("assignee")++ p = cmd("link", _cmd_link, "link two items")+ p.add_argument("src", type=int)+ p.add_argument("kind", choices=("parent", "blocks"))+ p.add_argument("dst", type=int)++ p = cmd("policy", _cmd_policy, "show or set the board's claim policy")+ p.add_argument("--claims", choices=CLAIM_POLICIES, default="")++ p = cmd("pending", _cmd_pending, "my unconsumed deliveries (assignments etc.)")+ p.add_argument("--consume", action="store_true", help="advance my cursor")+ p.add_argument("--limit", type=int, default=50)++ cmd("spaces", _cmd_spaces, "list known board spaces")++ # `token` manages the serving machine's registry file directly — it takes no+ # backing/identity flags of its own (minting is what CREATES identities).+ p = board_sub.add_parser(+ "token", help="mint/list/revoke board join tokens (serving machine)"+ )+ p.add_argument("action", choices=("mint", "list", "revoke"))+ p.add_argument("--actor", default="", help="callname the token binds (mint)")+ p.add_argument(+ "--role", choices=("worker", "lead", "user"), default="worker"+ )+ p.add_argument("--label", default="", help="what this token is for (mint)")+ p.add_argument("--prefix", default="", help="token prefix to revoke")+ p.add_argument("--db", default="", help="state dir holding the registry")+ p.add_argument("--json", action="store_true")+ p.set_defaults(func=_cmd_token, cmd="token")++ p = cmd("mcp", _cmd_mcp, "serve this board over MCP on stdio")++ journal = sub.add_parser("journal", help="journal case verbs")+ journal_sub = journal.add_subparsers(dest="cmd")++ p = cmd("cases", _cmd_cases, "cases I can read", parent=journal_sub)++ p = cmd("read", _cmd_read, "read a case (filtered)", parent=journal_sub)+ p.add_argument("case")+ p.add_argument("--item", type=int, default=None)+ p.add_argument("--author", default="")+ p.add_argument("--kind", default="")+ p.add_argument("--entity", default="")+ p.add_argument("--raw", action="store_true", dest="include_raw")+ p.add_argument("--limit", type=int, default=50)++ p = cmd("append", _cmd_append, "append an entry to a case", parent=journal_sub)+ p.add_argument("case")+ p.add_argument("body")+ p.add_argument(+ "--kind",+ choices=("finding", "evidence", "decision", "note", "raw"),+ default="note",+ )+ p.add_argument("--item", type=int, default=None)+ p.add_argument("--entity", action="append", default=[], dest="entities")+ p.add_argument("--ref", action="append", default=[], dest="refs")++ return parser+++def _backing_args(p: argparse.ArgumentParser) -> None:+ p.add_argument("--url", default=os.environ.get("OCW_BOARD_URL", ""))+ p.add_argument("--token", default=os.environ.get("OCW_BOARD_TOKEN", ""))+ p.add_argument("--db", default="", help="state dir for direct (headless) access")+ p.add_argument("--actor", dest="local_actor", default="user")+ p.add_argument("--role", dest="local_role", default="user")+ p.add_argument(+ "--space",+ default=os.environ.get("OCW_BOARD_SPACE", ""),+ help="board space (default: this directory's workspace)",+ )+ p.add_argument("--json", action="store_true", help="machine-readable output")+++# ------------------------------------------------------------------ backing+++def _space(args) -> str:+ return args.space or space_for_workspace(Path.cwd())+++def _dialect(args):+ from .dialect import RemoteDialect, local_dialect++ if args.url:+ if not args.token:+ raise BoardError("--token (or OCW_BOARD_TOKEN) is required with --url")+ return RemoteDialect(args.url, args.token)+ if args.db:+ return local_dialect(args.db, actor=args.local_actor, role=args.local_role)+ server = _discover_server()+ if server is not None:+ return RemoteDialect(server, _local_cli_token())+ from ..secrets import state_dir++ return local_dialect(state_dir(), actor=args.local_actor, role=args.local_role)+++def _discover_server() -> Optional[str]:+ """A running local server, found via its per-port sidecar token files."""+ import httpx++ from ..secrets import state_dir++ ports = []+ try:+ for path in state_dir().glob("sidecar-*.token"):+ try:+ ports.append(int(path.stem.split("-")[1]))+ except (IndexError, ValueError):+ continue+ except OSError:+ return None+ for port in sorted(ports, reverse=True):+ url = f"http://127.0.0.1:{port}"+ try:+ if httpx.get(f"{url}/v1/health", timeout=1.5).status_code == 200:+ return url+ except httpx.HTTPError:+ continue+ return None+++def _local_cli_token() -> str:+ """The CLI's own user token against the local server. Minted once into the+ shared registry; the plaintext is cached user-only in the state dir — the+ user's own credential on the user's own machine, same pattern as the sidecar+ token file."""+ from ..secrets import state_dir, write_private_text++ from .tokens import BoardTokens++ cache = state_dir() / "ocw-cli.token"+ tokens = BoardTokens(state_dir() / "board-tokens.json")+ try:+ cached = cache.read_text().strip()+ if cached and tokens.resolve(cached) is not None:+ return cached+ except OSError:+ pass+ token = tokens.mint("user", "user", label="local ocw CLI")+ write_private_text(cache, token + "\n")+ return token+++# ------------------------------------------------------------------ board cmds+++def _cmd_list(args) -> int:+ dialect = _dialect(args)+ assignee = args.assignee or (dialect.whoami()["actor"] if args.mine else "")+ items = dialect.list_items(+ _space(args), state=args.state or None, assignee=assignee or None+ )+ if args.json:+ print(json.dumps(items, indent=2))+ return 0+ if not items:+ print("no items")+ return 0+ for item in items:+ who = f" @{item['assignee']}" if item["assignee"] else ""+ print(f"#{item['id']:<4} {item['state']:<12}{who:<14} {item['title']}")+ return 0+++def _cmd_show(args) -> int:+ item = _dialect(args).get_item(_space(args), args.id)+ if args.json:+ print(json.dumps(item, indent=2))+ return 0+ print(f"#{item['id']} {item['title']} [{item['state']}]")+ if item["assignee"]:+ print(f"assignee: {item['assignee']}")+ print(f"created by: {item['creator']}")+ if item["description"]:+ print(f"\n{item['description']}")+ print(f"\nDone when: {item['criteria']}")+ if item.get("refs"):+ print("refs: " + ", ".join(item["refs"]))+ for link in item.get("links") or []:+ print(f"link: {link['kind']} #{link['item']}")+ for comment in item.get("comments") or []:+ print(f"\n[{comment['ts']}] {comment['author']}: {comment['body']}")+ return 0+++def _cmd_create(args) -> int:+ item = _dialect(args).create_item(+ _space(args),+ title=args.title,+ criteria=args.criteria,+ description=args.description,+ parent=args.parent,+ case=args.case or None,+ )+ print(json.dumps(item, indent=2) if args.json else f"created #{item['id']}")+ return 0+++def _cmd_claim(args) -> int:+ item = _dialect(args).claim(_space(args), args.id)+ print(+ json.dumps(item, indent=2)+ if args.json+ else f"claimed #{item['id']} — it's yours; move it to in_progress when you start"+ )+ return 0+++def _cmd_move(args) -> int:+ item = _dialect(args).transition(+ _space(args), args.id, args.to, comment=args.comment, refs=args.refs+ )+ print(json.dumps(item, indent=2) if args.json else f"#{item['id']} → {item['state']}")+ return 0+++def _cmd_comment(args) -> int:+ _dialect(args).comment(_space(args), args.id, args.body, refs=args.refs)+ print("ok" if not args.json else json.dumps({"ok": True}))+ return 0+++def _cmd_assign(args) -> int:+ item = _dialect(args).assign(_space(args), args.id, args.assignee)+ print(+ json.dumps(item, indent=2)+ if args.json+ else f"#{item['id']} → @{item['assignee']}"+ )+ return 0+++def _cmd_link(args) -> int:+ _dialect(args).link(_space(args), args.src, args.kind, args.dst)+ print("ok" if not args.json else json.dumps({"ok": True}))+ return 0+++def _cmd_policy(args) -> int:+ dialect = _dialect(args)+ policy = (+ dialect.set_policy(_space(args), claims=args.claims)+ if args.claims+ else dialect.policy(_space(args))+ )+ print(json.dumps(policy) if args.json else f"claims: {policy['claims']}")+ return 0+++def _cmd_pending(args) -> int:+ dialect = _dialect(args)+ events = dialect.pending(limit=args.limit)+ if args.json:+ print(json.dumps(events, indent=2))+ else:+ for event in events:+ print(f"[{event['seq']}] {event['kind']} #{event.get('item_id')}"+ f" from {event['actor']}: {json.dumps(event['payload'])}")+ if not events:+ print("nothing pending")+ if args.consume and events:+ dialect.consume(events[-1]["seq"])+ return 0+++def _cmd_spaces(args) -> int:+ spaces = _dialect(args).spaces()+ print(json.dumps(spaces) if args.json else "\n".join(spaces) or "no spaces")+ return 0+++def _cmd_token(args) -> int:+ from ..secrets import state_dir++ from .tokens import BoardTokens++ tokens = BoardTokens(+ (Path(args.db).expanduser() if args.db else state_dir()) / "board-tokens.json"+ )+ if args.action == "mint":+ if not args.actor:+ print("error: --actor is required to mint", file=sys.stderr)+ return 1+ token = tokens.mint(args.actor, args.role, label=args.label)+ print(token)+ print(+ f"# binds actor '{args.actor}' as {args.role}; shown once — store it"+ " in the client's config (OCW_BOARD_TOKEN)",+ file=sys.stderr,+ )+ return 0+ if args.action == "revoke":+ removed = tokens.revoke(args.prefix)+ print(f"revoked {removed} token(s)")+ return 0+ entries = tokens.entries()+ if args.json:+ print(json.dumps(entries, indent=2))+ return 0+ for entry in entries:+ label = f" ({entry['label']})" if entry["label"] else ""+ print(f"{entry['prefix']}… {entry['actor']:<16} {entry['role']:<8}{label}")+ if not entries:+ print("no tokens")+ return 0+++def _cmd_mcp(args) -> int:+ from .mcp_server import serve++ serve(_dialect(args), space=_space(args))+ return 0+++# ------------------------------------------------------------------ journal cmds+++def _cmd_cases(args) -> int:+ cases = _dialect(args).journal_overview()+ if args.json:+ print(json.dumps(cases, indent=2))+ return 0+ for case in cases:+ print(+ f"{case.get('case', '?'):<28} {case.get('entries', 0)} entries"+ + (f" (last {case['last_ts']})" if case.get("last_ts") else "")+ )+ if not cases:+ print("no cases")+ return 0+++def _cmd_read(args) -> int:+ entries = _dialect(args).journal_read(+ args.case,+ item=args.item,+ author=args.author or None,+ kind=args.kind or None,+ entity=args.entity or None,+ include_raw=args.include_raw,+ limit=args.limit,+ )+ if args.json:+ print(json.dumps(entries, indent=2))+ return 0+ for entry in entries:+ print(f"[{entry['ts']}] {entry['author']} {entry['kind']}:"+ f" {entry.get('body') or ''}")+ if not entries:+ print("no entries")+ return 0+++def _cmd_append(args) -> int:+ _dialect(args).journal_append(+ args.case,+ args.body,+ kind=args.kind,+ space=_space(args),+ item=args.item,+ entities=args.entities,+ refs=args.refs,+ )+ print("ok" if not args.json else json.dumps({"ok": True}))+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/coworker/teams/mcp_server.py b/coworker/teams/mcp_server.pynew file mode 100644index 00000000..bff7cd90--- /dev/null+++ b/coworker/teams/mcp_server.py@@ -0,0 +1,191 @@+"""`team-board` — the board and journal as an MCP server on stdio.++The way an external coding agent joins a team: its MCP config runs+`ocw board mcp --url … --token … --space …` (or `--db …` headless), it sees the+role-scoped board tools, and the user asks it to claim an item and work. Identity+and authority never live here: the dialect is already bound to one actor (token or+local flags), and every write is judged by the store/server — this file is a thin+adapter, safe to hand to any harness.++Tool results are JSON — raw data for the agent, not prose.+"""++from __future__ import annotations++from typing import Any, Optional++from .model import BoardError+++def build(dialect, *, space: str):+ """Assemble the FastMCP server for one dialect+space. Split from serve() so+ tests can inspect the registered tool set without a transport."""+ from mcp.server.fastmcp import FastMCP++ who = dialect.whoami()+ role = who.get("role", "worker")+ mcp = FastMCP(+ "team-board",+ instructions=(+ f"A shared team work board (you are '{who.get('actor')}', role"+ f" {role}) plus the team journal. Items carry acceptance criteria —"+ " what gets verified before they can be done. Typical worker loop:"+ " board_list → board_claim an open item → board_move to in_progress →"+ " work, journal_append findings as you go → board_move to review with"+ " a hand-off comment and refs. Never mark items done — done is the"+ " verdict after review."+ ),+ )++ def _safe(func, *args, **kwargs) -> Any:+ try:+ return func(*args, **kwargs)+ except (BoardError, ValueError) as error:+ return {"error": str(error)}++ @mcp.tool()+ def board_list(state: str = "", assignee: str = "") -> Any:+ """List work items on the board, optionally filtered by state+ (open/in_progress/blocked/review/done/canceled) or assignee."""+ return _safe(+ dialect.list_items, space, state=state or None, assignee=assignee or None+ )++ @mcp.tool()+ def board_show(item: int) -> Any:+ """One work item in full: description, acceptance criteria, refs, links,+ and every comment."""+ return _safe(dialect.get_item, space, item)++ @mcp.tool()+ def board_create(+ title: str,+ criteria: str,+ description: str = "",+ parent: Optional[int] = None,+ case: str = "",+ ) -> Any:+ """File a new work item (open, unassigned — work starts when it is+ assigned or claimed). `criteria` is the acceptance criteria — what gets+ verified before the item can be done; required."""+ return _safe(+ dialect.create_item,+ space,+ title=title,+ criteria=criteria,+ description=description,+ parent=parent,+ case=case or None,+ )++ @mcp.tool()+ def board_claim(item: int) -> Any:+ """Claim an open, unassigned item for yourself. First claim wins; the+ item becomes your assignment. Only claim work you can start on now."""+ return _safe(dialect.claim, space, item)++ @mcp.tool()+ def board_move(item: int, to: str, comment: str = "", refs: list[str] = []) -> Any:+ """Move a work item: in_progress when you start, blocked with the blocker+ as `comment`, review with a hand-off comment and artifact refs (branch,+ PR, file:line) when finished."""+ return _safe(+ dialect.transition, space, item, to, comment=comment, refs=list(refs or [])+ )++ @mcp.tool()+ def board_comment(item: int, body: str, refs: list[str] = []) -> Any:+ """Comment on a work item — durable and attributed; answers that matter+ belong here. `refs` attach artifact pointers."""+ return _safe(dialect.comment, space, item, body, refs=list(refs or []))++ @mcp.tool()+ def board_pending() -> Any:+ """Your unconsumed deliveries — assignments addressed to you, cancel+ notices. Check at the start of a work session; acknowledge with+ board_consume."""+ return _safe(dialect.pending)++ @mcp.tool()+ def board_consume(upto_seq: int) -> Any:+ """Acknowledge deliveries up to a sequence number (from board_pending),+ so they are not re-delivered."""+ return _safe(lambda: (dialect.consume(upto_seq), {"ok": True})[1])++ if role in ("lead", "user"):++ @mcp.tool()+ def board_assign(item: int, assignee: str) -> Any:+ """Assign a work item to a worker (or to yourself to reserve it)."""+ return _safe(dialect.assign, space, item, assignee)++ @mcp.tool()+ def board_link(src: int, kind: str, dst: int) -> Any:+ """Link two items: `parent` (dst becomes src's parent) or `blocks`+ (src blocks dst)."""+ return _safe(dialect.link, space, src, kind, dst)++ @mcp.tool()+ def board_policy(claims: str = "") -> Any:+ """Show the board's claim policy, or set it: `open` (workers may+ self-claim open items) or `lead-only`."""+ if claims:+ return _safe(dialect.set_policy, space, claims=claims)+ return _safe(dialect.policy, space)++ @mcp.tool()+ def journal_append(+ case: str,+ body: str,+ kind: str = "note",+ item: Optional[int] = None,+ entities: list[str] = [],+ refs: list[str] = [],+ ) -> Any:+ """Append to a journal case as you work: kind is finding, evidence,+ decision, note, or raw (a capture excerpt referencing a file).+ `entities` are the concrete things it is about (paths, resources, ids)."""+ return _safe(+ dialect.journal_append,+ case,+ body,+ kind=kind,+ space=space,+ item=item,+ entities=list(entities or []),+ refs=list(refs or []),+ )++ @mcp.tool()+ def journal_read(+ case: str,+ item: Optional[int] = None,+ author: str = "",+ kind: str = "",+ entity: str = "",+ include_raw: bool = False,+ limit: int = 50,+ ) -> Any:+ """Read a journal case, filtered by item, author, entry kind, or entity.+ Prefer narrow reads; raw captures are skipped unless asked."""+ return _safe(+ dialect.journal_read,+ case,+ item=item,+ author=author or None,+ kind=kind or None,+ entity=entity or None,+ include_raw=include_raw,+ limit=limit,+ )++ @mcp.tool()+ def journal_cases() -> Any:+ """The journal cases you can read, with entry counts."""+ return _safe(dialect.journal_overview)++ return mcp+++def serve(dialect, *, space: str) -> None:+ build(dialect, space=space).run("stdio")diff --git a/pyproject.toml b/pyproject.tomlindex 9561bd91..36b48a75 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -53,6 +53,9 @@ bedrock = ["boto3>=1.34"]openworker = "coworker.cli:main"openworker-server = "coworker.server.run:main"openworker-connectors = "coworker.connectors.cli:main"+# The board as an open surface (OPE-100): `ocw board …` / `ocw journal …`,+# including `ocw board mcp` — the stdio MCP server external harnesses attach to.+ocw = "coworker.teams.cli:main"[tool.setuptools.packages.find]where = ["."]diff --git a/tests/test_team_open_surface.py b/tests/test_team_open_surface.pynew file mode 100644index 00000000..4246bc6f--- /dev/null+++ b/tests/test_team_open_surface.py@@ -0,0 +1,417 @@+"""OPE-100 — the board as an open surface: claim + policy knob, the BoardDialect+seam (local and remote), token-bound identity on `/v1/board`, and the MCP/CLI+front doors."""++import json++import pytest++from coworker.teams import Actor, AuthorityError, BoardError, JournalStore, Role, TeamStore+from coworker.teams.dialect import LocalDialect, RemoteDialect, local_dialect+from coworker.teams.tokens import BoardTokens++USER = Actor(id="user", role=Role.USER)+LEAD = Actor(id="lead-1", role=Role.LEAD, persona="swe-lead")+NIA = Actor(id="nia", role=Role.WORKER, persona="swe-worker")+WEBB = Actor(id="webb", role=Role.WORKER, persona="swe-worker")+++def store(tmp_path):+ journal = JournalStore(tmp_path / "journal.db")+ store = TeamStore(tmp_path / "teams.db", journal=journal)+ yield store+ store.close()+ journal.close()+++def seed(store, space="proj", case=None):+ return store.create_item(+ space, LEAD, title="Build the API", criteria="routes pass tests", case=case+ )+++# ------------------------------------------------------------------ claim verb+++def test_claim_self_assigns_an_open_item(store):+ item = seed(store)+ claimed = store.claim("proj", NIA, item["id"])+ assert claimed["assignee"] == "nia"+ assert claimed["state"] == "open" # claiming is not starting+++def test_second_claim_loses_cleanly(store):+ item = seed(store)+ store.claim("proj", NIA, item["id"])+ with pytest.raises(BoardError, match="already claimed by nia"):+ store.claim("proj", WEBB, item["id"])+++def test_claim_requires_open_and_unassigned(store):+ item = seed(store)+ store.assign("proj", LEAD, item["id"], "nia")+ # an assigned item is not claimable, even while still open+ with pytest.raises(BoardError, match="already claimed by nia"):+ store.claim("proj", WEBB, item["id"])+ store.transition("proj", NIA, item["id"], "in_progress")+ # and a non-open item never is+ with pytest.raises(BoardError, match="only open items"):+ store.claim("proj", WEBB, item["id"])+++def test_lead_only_policy_blocks_worker_claims(store):+ item = seed(store)+ store.set_policy("proj", LEAD, claims="lead-only")+ with pytest.raises(AuthorityError, match="lead-only"):+ store.claim("proj", NIA, item["id"])+ # flipping back re-opens the queue+ store.set_policy("proj", USER, claims="open")+ assert store.claim("proj", NIA, item["id"])["assignee"] == "nia"+++def test_policy_defaults_open_and_validates(store):+ assert store.policy("proj") == {"claims": "open"}+ with pytest.raises(BoardError):+ store.set_policy("proj", LEAD, claims="anarchy")+ with pytest.raises(AuthorityError):+ store.set_policy("proj", NIA, claims="lead-only")+++def test_claim_feeds_the_lead_subscription(store):+ item = seed(store)+ store.claim("proj", NIA, item["id"])+ subs = store.subscribed_events("proj", "lead-1")+ claims = [e for e in subs if e["kind"] == "item_assigned"]+ assert len(claims) == 1+ assert claims[0]["actor"] == "nia"+ assert claims[0]["payload"]["claimed"] is True+++def test_lead_assigns_are_not_subscription_news(store):+ item = seed(store)+ store.assign("proj", USER, item["id"], "nia")+ subs = store.subscribed_events("proj", "lead-1")+ assert not [e for e in subs if e["kind"] == "item_assigned"]+++def test_claim_feeds_journal_grants_like_assignment(store):+ item = seed(store, case="case-alpha")+ store.claim("proj", NIA, item["id"])+ # nia can now read the case it was granted through the claim+ assert "case-alpha" in store.journal.cases(NIA)+++# ------------------------------------------------------------------ dialects+++def test_local_dialect_binds_identity(tmp_path):+ dialect = local_dialect(tmp_path, actor="nia", role="worker")+ assert dialect.whoami() == {"actor": "nia", "role": "worker"}+ with pytest.raises(AuthorityError):+ dialect.assign("proj", 1, "webb") # workers never assign+++def test_local_dialect_full_worker_loop(tmp_path):+ lead = local_dialect(tmp_path, actor="lead-1", role="lead")+ item = lead.create_item(+ "proj", title="Build it", criteria="tests pass", case="case-b"+ )+ worker = LocalDialect(lead.store, lead.journal, NIA)+ claimed = worker.claim("proj", item["id"])+ assert claimed["assignee"] == "nia"+ worker.transition("proj", item["id"], "in_progress")+ worker.journal_append("case-b", "found the flaky fixture", kind="finding")+ worker.transition("proj", item["id"], "review", comment="branch ready")+ shown = worker.get_item("proj", item["id"])+ assert shown["state"] == "review"+ assert [e["body"] for e in worker.journal_read("case-b")] == [+ "found the flaky fixture"+ ]+++# ------------------------------------------------------------- HTTP board API+++def api(tmp_path, monkeypatch):+ """The real FastAPI app over a real manager state dir, driven in-process."""+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))+ monkeypatch.setenv("COWORKER_API_TOKEN", "sidecar-secret")+ from coworker.permissions import Mode+ from coworker.server.app import create_app+ from coworker.server.manager import SessionManager++ manager = SessionManager(+ workspace=None,+ data_dir=tmp_path / "state",+ model="openai:gpt-test",+ mode=Mode("interactive"),+ )+ from fastapi.testclient import TestClient++ app = create_app(manager)+ client = TestClient(app, base_url="http://board.test")+ yield client, manager, app+ client.close()+++def _tokens(manager) -> BoardTokens:+ return manager.board_tokens+++def test_board_api_requires_a_token(api):+ client, _, _ = api+ response = client.get("/v1/board/items", params={"space": "proj"})+ assert response.status_code == 401+ assert "board token" in response.json()["error"]+++def test_board_api_rejects_the_sidecar_token_as_a_board_token(api):+ client, _, _ = api+ response = client.get(+ "/v1/board/whoami",+ headers={"Authorization": "Bearer sidecar-secret"},+ )+ assert response.status_code == 401+++def test_token_binds_identity_and_store_enforces_authority(api):+ client, manager, app = api+ lead_token = _tokens(manager).mint("lead-1", "lead")+ nia_token = _tokens(manager).mint("nia", "worker")+ lead = {"Authorization": f"Bearer {lead_token}"}+ nia = {"Authorization": f"Bearer {nia_token}"}++ assert client.get("/v1/board/whoami", headers=nia).json() == {+ "actor": "nia",+ "role": "worker",+ }++ created = client.post(+ "/v1/board/items",+ headers=lead,+ json={"space": "proj", "title": "Build it", "criteria": "tests pass"},+ )+ assert created.status_code == 200+ item_id = created.json()["id"]++ # a worker token cannot assign — 403 from the store's authority check+ denied = client.post(+ "/v1/board/items/assign",+ headers=nia,+ json={"space": "proj", "id": item_id, "assignee": "nia"},+ )+ assert denied.status_code == 403++ # but it can claim, then work the item+ claimed = client.post(+ "/v1/board/items/claim", headers=nia, json={"space": "proj", "id": item_id}+ )+ assert claimed.status_code == 200+ assert claimed.json()["assignee"] == "nia"++ moved = client.post(+ "/v1/board/items/transition",+ headers=nia,+ json={"space": "proj", "id": item_id, "to": "in_progress"},+ )+ assert moved.status_code == 200++ # bad input is a 400 with the store's message, not a 500+ bad = client.post(+ "/v1/board/items/transition",+ headers=nia,+ json={"space": "proj", "id": item_id, "to": "done"},+ )+ assert bad.status_code == 403 or bad.status_code == 400+++def test_remote_dialect_round_trip(api):+ client, manager, app = api+ lead_token = _tokens(manager).mint("lead-1", "lead")+ nia_token = _tokens(manager).mint("nia", "worker")+ from fastapi.testclient import TestClient++ lead = RemoteDialect(+ "http://board.test",+ lead_token,+ client=TestClient(app, base_url="http://board.test"),+ )+ nia = RemoteDialect(+ "http://board.test",+ nia_token,+ client=TestClient(app, base_url="http://board.test"),+ )++ item = lead.create_item(+ "proj", title="Remote item", criteria="works over the wire", case="case-r"+ )+ assert lead.policy("proj") == {"claims": "open"}+ claimed = nia.claim("proj", item["id"])+ assert claimed["assignee"] == "nia"+ nia.transition("proj", item["id"], "in_progress")+ nia.journal_append("case-r", "wire finding", kind="finding", item=item["id"])+ nia.transition("proj", item["id"], "review", comment="ready", refs=["branch:x"])++ # the lead sees the review, verifies, and closes+ shown = lead.get_item("proj", item["id"])+ assert shown["state"] == "review"+ assert "branch:x" in shown["refs"]+ entries = lead.journal_read("case-r")+ assert entries[0]["body"] == "wire finding"+ done = lead.transition("proj", item["id"], "done")+ assert done["state"] == "done"++ # errors surface as BoardError with the server's message+ with pytest.raises(BoardError, match="only open items"):+ nia.claim("proj", item["id"])++ # policy flip over the wire blocks the next worker claim+ second = lead.create_item("proj", title="Held back", criteria="c")+ lead.set_policy("proj", claims="lead-only")+ with pytest.raises(BoardError, match="lead-only"):+ nia.claim("proj", second["id"])+++def test_pending_and_consume_over_the_wire(api):+ client, manager, app = api+ lead_token = _tokens(manager).mint("lead-1", "lead")+ nia_token = _tokens(manager).mint("nia", "worker")+ from fastapi.testclient import TestClient++ lead = RemoteDialect(+ "http://board.test",+ lead_token,+ client=TestClient(app, base_url="http://board.test"),+ )+ nia = RemoteDialect(+ "http://board.test",+ nia_token,+ client=TestClient(app, base_url="http://board.test"),+ )+ item = lead.create_item("proj", title="Queued", criteria="c")+ lead.assign("proj", item["id"], "nia")+ events = nia.pending()+ assert events and events[-1]["kind"] == "item_assigned"+ nia.consume(events[-1]["seq"])+ assert nia.pending() == []+++# ------------------------------------------------------------------ tokens+++def test_tokens_are_hash_stored_and_revocable(tmp_path):+ tokens = BoardTokens(tmp_path / "board-tokens.json")+ token = tokens.mint("nia", "worker", label="laptop")+ # plaintext never touches disk+ assert token not in (tmp_path / "board-tokens.json").read_text()+ actor = tokens.resolve(token)+ assert (actor.id, actor.role) == ("nia", Role.WORKER)+ assert tokens.resolve("owb_forged") is None+ assert tokens.revoke(token[:12]) == 1+ assert tokens.resolve(token) is None+++def test_token_mint_validates_role(tmp_path):+ tokens = BoardTokens(tmp_path / "board-tokens.json")+ with pytest.raises(ValueError):+ tokens.mint("nia", "admin")+++# ------------------------------------------------------------------ MCP server+++def test_mcp_tool_surface_is_role_scoped(tmp_path):+ import anyio++ from coworker.teams.mcp_server import build++ worker = build(+ local_dialect(tmp_path, actor="nia", role="worker"), space="proj"+ )+ lead = build(+ local_dialect(tmp_path, actor="lead-1", role="lead"), space="proj"+ )++ def names(server):+ return {tool.name for tool in anyio.run(server.list_tools)}++ worker_names = names(worker)+ lead_names = names(lead)+ assert "board_claim" in worker_names+ assert "board_assign" not in worker_names+ assert "board_policy" not in worker_names+ assert {"board_assign", "board_link", "board_policy"} <= lead_names+ assert "journal_append" in worker_names+++def test_mcp_worker_loop_through_call_tool(tmp_path):+ import anyio++ from coworker.teams.mcp_server import build++ lead_dialect = local_dialect(tmp_path, actor="lead-1", role="lead")+ item = lead_dialect.create_item("proj", title="Via MCP", criteria="c")+ worker = build(+ LocalDialect(lead_dialect.store, lead_dialect.journal, NIA), space="proj"+ )++ def call(name, arguments):+ return anyio.run(lambda: worker.call_tool(name, arguments))++ call("board_claim", {"item": item["id"]})+ call("board_move", {"item": item["id"], "to": "in_progress"})+ shown = lead_dialect.get_item("proj", item["id"])+ assert (shown["assignee"], shown["state"]) == ("nia", "in_progress")+++# ------------------------------------------------------------------ CLI+++def test_cli_headless_flow(tmp_path, capsys):+ from coworker.teams.cli import main++ space_args = ["--db", str(tmp_path), "--space", "proj"]+ assert main(+ ["board", "create", "CLI item", "--criteria", "prints", *space_args,+ "--actor", "lead-1", "--role", "lead"]+ ) == 0+ capsys.readouterr()+ assert main(+ ["board", "claim", "1", *space_args, "--actor", "nia", "--role", "worker"]+ ) == 0+ assert "claimed #1" in capsys.readouterr().out+ assert main(["board", "list", *space_args, "--json"]) == 0+ items = json.loads(capsys.readouterr().out)+ assert [(i["id"], i["assignee"]) for i in items] == [(1, "nia")]+ # a losing claim exits 1 with the store's message on stderr+ assert main(+ ["board", "claim", "1", *space_args, "--actor", "webb", "--role", "worker"]+ ) == 1+ assert "already claimed by nia" in capsys.readouterr().err+ # policy knob round-trips+ assert main(["board", "policy", "--claims", "lead-only", *space_args]) == 0+ assert "lead-only" in capsys.readouterr().out+ # journal append + read+ assert main(+ ["journal", "append", "case-cli", "found it", "--kind", "finding",+ *space_args]+ ) == 0+ capsys.readouterr()+ assert main(["journal", "read", "case-cli", *space_args]) == 0+ assert "found it" in capsys.readouterr().out+++def test_cli_token_mint_and_list(tmp_path, capsys):+ from coworker.teams.cli import main++ assert main(+ ["board", "token", "mint", "--actor", "nia", "--role", "worker",+ "--label", "laptop", "--db", str(tmp_path)]+ ) == 0+ token = capsys.readouterr().out.strip()+ assert token.startswith("owb_")+ assert main(["board", "token", "list", "--db", str(tmp_path)]) == 0+ out = capsys.readouterr().out+ assert "nia" in out and "laptop" in out and token not in out