stcode 0.0.1a0__py3-none-any.whl

stcode/core/team/mailbox.py

@@ -0,0 +1,249 @@
+"""
+Mailbox — agent-to-agent messaging, with no protocol.
+
+Containers share a volume, so a message is a **file**: sending writes JSON into
+`/team/inbox/<role>/`, receiving is reading your own directory. Joining writes a card
+to `/team/members/<role>.json`, and finding a teammate is reading those.
+
+    /team/members/backend-dev.json                 <- who it is, what it does
+    /team/inbox/backend-dev/01HX…-from-ba.json     <- unread
+    /team/inbox/backend-dev/.read/…                <- drained
+
+No registry service, no routing table, no N² socket mesh. Join, list members and send
+are the three operations a team service would also have to offer — see
+docs/architecture/team.md.
+
+**Messages carry `refs`, not content** — that one convention is what keeps a team's
+token cost from growing with the square of its size. Delivery is a write then a rename,
+so a reader never sees half a message. Nothing here imports the harness.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+from pydantic import BaseModel, Field
+
+# ULID: sorts by time, so an inbox drains oldest-first with no index.
+from stcode.core.common.ids import new_id
+
+DEFAULT_TEAM_DIR = "/team"
+"""Mounted into every container — see docs/architecture/team.md."""
+
+INBOX = "inbox"
+MEMBERS = "members"
+KNOWLEDGE = "knowledge"
+ARTIFACTS = "artifacts"
+READ_DIRNAME = ".read"
+"""Where a drained message goes. Moved, not deleted — "who told it that?" is a question
+you will ask."""
+
+
+class TeamMessage(BaseModel):
+    """One message. Named `TeamMessage` because `Message` is already the provider wire
+    format, and two of those in one codebase is a bug waiting to happen."""
+
+    id: str = ""
+    sender: str = ""
+    to: str = ""
+    subject: str = ""
+    body: str = ""
+    refs: list[str] = Field(default_factory=list)
+    ts: str = ""
+
+    def render(self) -> str:
+        """As the receiving agent reads it."""
+        lines = [f"[message from {self.sender or 'unknown'}] {self.subject}"]
+        if self.body:
+            lines.append(self.body)
+        if self.refs:
+            lines.append("Refs: " + ", ".join(self.refs))
+        return "\n".join(lines)
+
+
+class TeamMember(BaseModel):
+    """One agent's card: who it is and what it does. What `find_teammate` reads."""
+
+    role: str
+    team: str = ""
+    description: str = ""
+    host: str = ""
+    joined: str = ""
+
+    def render(self) -> str:
+        """As a teammate looking for someone reads it."""
+        line = f"{self.role} — {self.description or '(no description)'}"
+        return f"{line} (on {self.host})" if self.host else line
+
+
+class Mailbox:
+    """One role's view of the shared volume: its own inbox, and everyone else's."""
+
+    def __init__(self, root: str | Path = DEFAULT_TEAM_DIR, role: str = "") -> None:
+        self.root = Path(root).expanduser()
+        self.role = role
+
+    # ---- where things are ----
+
+    @property
+    def inbox(self) -> Path:
+        return self.root / INBOX / self.role
+
+    @property
+    def knowledge(self) -> Path:
+        return self.root / KNOWLEDGE
+
+    @property
+    def artifacts(self) -> Path:
+        return self.root / ARTIFACTS
+
+    @property
+    def members_dir(self) -> Path:
+        return self.root / MEMBERS
+
+    def inbox_of(self, role: str) -> Path:
+        return self.root / INBOX / role
+
+    def ensure(self, *roles: str) -> None:
+        """Create the volume layout. Safe to call repeatedly."""
+        for path in (self.knowledge, self.artifacts, self.members_dir, self.root / INBOX):
+            path.mkdir(parents=True, exist_ok=True)
+        for role in (self.role, *roles):
+            if role:
+                self.inbox_of(role).mkdir(parents=True, exist_ok=True)
+
+    # ---- membership ----
+
+    def join(self, description: str = "", team: str = "") -> Path:
+        """Create this role's inbox and write its card. Returns the card's path.
+
+        A restart rewrites the card; stopping leaves it, because the inbox outlives the
+        process and mail sent while a role is down waits for it.
+        """
+        self.ensure()
+        member = TeamMember(
+            role=self.role,
+            team=team,
+            description=description.strip(),
+            host=socket.gethostname(),
+            joined=_now(),
+        )
+        path = self.members_dir / f"{self.role}.json"
+        _write_atomic(path, member.model_dump_json(indent=2))
+        return path
+
+    def members(self) -> list[TeamMember]:
+        """Every card on the volume, by role. One unreadable card is skipped, not fatal:
+        a broken file on a shared volume must not hide the whole team."""
+        if not self.members_dir.is_dir():
+            return []
+        found: list[TeamMember] = []
+        for path in sorted(self.members_dir.glob("*.json")):
+            try:
+                found.append(TeamMember.model_validate_json(path.read_text(encoding="utf-8")))
+            except (OSError, ValueError):
+                continue
+        return found
+
+    # ---- sending ----
+
+    def send(
+        self, to: str, subject: str, body: str = "", refs: list[str] | None = None
+    ) -> Path:
+        """Write one message into `to`'s inbox. Returns the file it landed in.
+
+        Write-then-rename, so a reader draining at the same moment sees either nothing
+        or a complete message.
+        """
+        target = self.inbox_of(to)
+        target.mkdir(parents=True, exist_ok=True)
+
+        message = TeamMessage(
+            id=new_id(),
+            sender=self.role,
+            to=to,
+            subject=subject,
+            body=body,
+            refs=list(refs or []),
+            ts=_now(),
+        )
+        path = target / f"{message.id}-from-{self.role or 'unknown'}.json"
+        _write_atomic(path, message.model_dump_json(indent=2))
+        return path
+
+    # ---- receiving ----
+
+    def pending(self) -> list[Path]:
+        """Unread message files, oldest first. What the daemon's watcher polls."""
+        if not self.inbox.is_dir():
+            return []
+        return sorted(
+            entry
+            for entry in self.inbox.iterdir()
+            if entry.is_file() and entry.suffix == ".json" and not entry.name.startswith(".")
+        )
+
+    def drain(self) -> list[TeamMessage]:
+        """Read every waiting message and mark it read. Called at the top of a turn.
+
+        An unparseable message is moved aside too: leaving it would mean re-draining it
+        every turn forever, a louder failure than losing one malformed file.
+        """
+        read_dir = self.inbox / READ_DIRNAME
+        messages: list[TeamMessage] = []
+        for path in self.pending():
+            try:
+                messages.append(TeamMessage.model_validate_json(path.read_text(encoding="utf-8")))
+            except (OSError, ValueError):
+                pass
+            read_dir.mkdir(parents=True, exist_ok=True)
+            try:
+                os.replace(path, read_dir / path.name)
+            except OSError:
+                continue
+        return messages
+
+    def history(self) -> Iterator[dict[str, Any]]:
+        """Everything this role has already read. For working out what happened."""
+        read_dir = self.inbox / READ_DIRNAME
+        if not read_dir.is_dir():
+            return
+        for path in sorted(read_dir.glob("*.json")):
+            try:
+                yield json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+
+    def __repr__(self) -> str:
+        return f"Mailbox({self.root}, role={self.role!r})"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    """Write-then-rename, so a reader at the same moment sees the old file or the new
+    one, never half of either. The staging name starts with a dot and ends in
+    `.partial`, so no reader's `*.json` matches it."""
+    staging = path.with_name(f".{path.name}.partial")
+    staging.write_text(text, encoding="utf-8")
+    os.replace(staging, path)
+
+
+__all__ = [
+    "ARTIFACTS",
+    "DEFAULT_TEAM_DIR",
+    "INBOX",
+    "KNOWLEDGE",
+    "MEMBERS",
+    "READ_DIRNAME",
+    "Mailbox",
+    "TeamMember",
+    "TeamMessage",
+]

stcode/core/team/tools.py

@@ -0,0 +1,145 @@
+"""
+`find_teammate` and `send_team_message` — the two tools team mode adds.
+
+Everything else already exists: `/team/knowledge/` is a directory, so the ordinary file
+tools work on it. What was missing is a way to find who owns the next step, and to tell
+them something is ready.
+
+Factories rather than module-level `@tool`s, for the same reason as `task`: each closes
+over one role's `Mailbox`, keeping `core/harness` from importing `core/team`.
+
+**The send docstring pushes `refs` over `body`, deliberately** — it is the only place
+that rule can be taught, and a team's cost grows with N² if messages carry documents.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from stcode.core.harness.approvals import ToolPermission
+from stcode.core.harness.context import HarnessContext
+from stcode.core.harness.tools.base import Runtime, Tool, ToolError, tool
+from stcode.core.team.mailbox import Mailbox, TeamMember
+
+MAX_BODY = 2000
+"""Longer than this is a document, not a message. Refused rather than truncated —
+truncating delivers something that reads complete and is not."""
+
+
+def make_find_teammate_tool(mailbox: Mailbox) -> Tool[Any]:
+    """The `find_teammate` tool for one role."""
+
+    @tool(permission=ToolPermission.READ)
+    async def find_teammate(query: str = "") -> str:
+        """Find the teammates who could take a piece of work, before you hand it off.
+
+        Returns each matching teammate's role and what it does. Use the role as `to` in
+        `send_team_message`. Call it again rather than remembering an old answer:
+        teammates join while you work.
+
+        Args:
+            query: Words describing the work, e.g. "api contract" or "deploy". A
+                teammate matches if any word appears in its role or description. Leave
+                empty to list everyone.
+        """
+        others = [member for member in mailbox.members() if member.role != mailbox.role]
+        if not others:
+            return "Nobody else has joined the team yet. Check again later."
+
+        words = [word.lower() for word in query.split()]
+        matches = [member for member in others if _matches(member, words)]
+        if not matches:
+            return (
+                f"No teammate matches {query!r}. Everyone on the team:\n"
+                + "\n".join(member.render() for member in others)
+            )
+        return "\n".join(member.render() for member in matches)
+
+    return find_teammate
+
+
+def make_send_team_message_tool(mailbox: Mailbox) -> Tool[Any]:
+    """The `send_team_message` tool for one role."""
+
+    @tool(permission=ToolPermission.WRITE)
+    async def send_team_message(
+        to: str,
+        subject: str,
+        body: str = "",
+        refs: list[str] | None = None,
+        runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+    ) -> str:
+        """Hand off work to, or ask something of, another agent on this team.
+
+        Use `find_teammate` first to learn which role owns the work.
+
+        Keep `body` short. Anything long belongs in a file under `/team/knowledge/` or
+        `/team/artifacts/` — write it there first, then put the path in `refs`. Do not
+        paste file contents into a message: the recipient can read the path, and every
+        word you paste is paid for again on every turn it stays in their history.
+
+        Send when you have finished something someone is waiting for, when you need a
+        decision only another role can make, or when you have found something that
+        changes their work. Your role prompt says who to report to.
+
+        Args:
+            to: The recipient's role, exactly as `find_teammate` shows it.
+            subject: One line, so the recipient can decide whether to read it now.
+            body: A short note. Say what you need and by when. Leave it empty if the
+                refs speak for themselves.
+            refs: Paths under /team holding the detail. This is the payload; the body
+                is the covering note.
+        """
+        recipient = to.strip()
+        if not recipient:
+            raise ToolError("`to` must name a role. Use `find_teammate` to see who is on the team.")
+        if recipient == mailbox.role:
+            raise ToolError("That is your own inbox. Use a note in /team/knowledge/ instead.")
+
+        # A card, not merely an inbox: a message to a role that never joined would sit
+        # in a directory nobody drains, and the sender would believe it was delivered.
+        known = [member.role for member in mailbox.members() if member.role != mailbox.role]
+        if recipient not in known:
+            raise ToolError(
+                f"There is no {recipient!r} on this team. The roles that have joined are: "
+                f"{', '.join(known) or '(none yet)'}. Use `find_teammate` to find who owns the work."
+            )
+        if len(body) > MAX_BODY:
+            raise ToolError(
+                f"The body is {len(body)} characters, over the {MAX_BODY} limit. Write it "
+                "to /team/knowledge/ or /team/artifacts/ and send the path in `refs`."
+            )
+
+        missing = [ref for ref in (refs or []) if not _ref_exists(mailbox, ref)]
+        if missing:
+            raise ToolError(
+                f"These refs do not exist yet: {', '.join(missing)}. Write the file first — "
+                "a message pointing at nothing wastes the recipient's whole turn."
+            )
+
+        path = mailbox.send(recipient, subject.strip(), body.strip(), list(refs or []))
+        await runtime.progress(f"→ {recipient}: {subject}")
+        return f"Sent to {recipient}. It will be waiting at the start of their next turn ({path.name})."
+
+    return send_team_message
+
+
+def _matches(member: TeamMember, words: list[str]) -> bool:
+    if not words:
+        return True
+    text = f"{member.role} {member.description}".lower()
+    return any(word in text for word in words)
+
+
+def _ref_exists(mailbox: Mailbox, ref: Any) -> bool:
+    """Whether a ref points at something real. Both spellings are accepted — absolute
+    (`/team/knowledge/spec.md`) and relative to the volume (`knowledge/spec.md`)."""
+    text = str(ref)
+    try:
+        return Path(text).exists() or (mailbox.root / text.lstrip("/")).exists()
+    except OSError:
+        return False
+
+
+__all__ = ["MAX_BODY", "make_find_teammate_tool", "make_send_team_message_tool"]

stcode-0.0.1a0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: stcode
+Version: 0.0.1a0
+Summary: A coding agent that lives in a daemon, and a UI that is a client of it.
+Project-URL: Homepage, https://ming-doan.github.io/stcode/
+Project-URL: Documentation, https://ming-doan.github.io/stcode/docs/
+Project-URL: Source, https://github.com/Ming-doan/stcode
+Project-URL: Issues, https://github.com/Ming-doan/stcode/issues
+Author-email: Minh Doan <quangminh57dng@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,coding-agent,daemon,llm,mcp,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.122.0
+Requires-Dist: asyncer>=0.0.18
+Requires-Dist: docstring-parser>=0.18.0
+Requires-Dist: google-genai>=2.18.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp>=2.1.1
+Requires-Dist: openai>=3.0.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: ripgrep>=15.1.0
+Requires-Dist: textual>=8.2.8
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: tomlkit>=0.15.1
+Requires-Dist: typer>=0.27.1
+Description-Content-Type: text/markdown
+
+# stcode
+
+A coding agent for the terminal, built the other way round: **the agent lives in a
+daemon, and the UI is a client of it.**
+
+Closing the window does not stop the work. Several terminals can watch the same session.
+Moving the agent into a container is a config key — `transport = "tcp"` — not a rewrite.
+And because a container is a real boundary, `full-auto` can exist without being a
+foot-gun: the daemon refuses to start in that mode anywhere its blast radius is not
+contained.
+
+---
+
+## Quickstart
+
+```bash
+uv sync                      # Python 3.10+
+uv run stcode                # first run opens a one-time setup screen
+```
+
+Full documentation: `uv run --group docs mkdocs serve`, or read
+[`docs/`](docs/index.md).
+
+Pick a provider, paste an API key (or leave it blank and export `ANTHROPIC_API_KEY` /
+`OPENAI_API_KEY` / `GEMINI_API_KEY`), choose a model, and type.
+
+### The three shapes
+
+```bash
+uv run stcode                # UI + a daemon, started here if none is listening
+uv run stcode --headless     # the daemon alone — what a container runs
+uv run stcode --daemonless   # the UI alone, attached to a daemon elsewhere
+```
+
+`--daemonless` never starts an agent locally: if nothing answers, it asks *which daemon?*
+rather than quietly running the work on your laptop. `/connect` moves a running UI to a
+different one.
+
+### Other commands
+
+```bash
+uv run stcode sessions       # recent sessions, newest first
+uv run stcode --resume 01HX… # attach to one, live or from disk
+uv run stcode config         # where config lives and what it selects
+```
+
+Useful flags: `--cwd`, `--mode` (`plan` | `suggest` | `auto-edit` | `full-auto`),
+`--role` (which agent this is — the prompt comes from `[agent] prompt`), `--restart` (stop the local daemon and
+start a fresh one), `--config` (the file a daemon started here reads), and `--transport` /
+`--socket` / `--host` / `--port` to point at a daemon. The daemon itself is
+`stcode-daemon`; `stcode --headless` runs it.
+
+### In the UI
+
+| | |
+| --- | --- |
+| `shift+tab` | cycle approval mode — takes effect on the live session |
+| `esc` | interrupt the turn in flight |
+| `f2` / `/model` | provider, key, model |
+| `/connect` | point this client at a different daemon |
+| `/mode`, `/clear`, `/help`, `/quit` | |
+
+### Attaching to an agent in a container
+
+```bash
+# in the container
+docker run -e STCODE_SANDBOX=1 -e ANTHROPIC_API_KEY -p 7717:7717 \
+    -v "$PWD:/workspace" stcode          # runs stcode-daemon on tcp:7717
+
+# on your machine
+uv run stcode --daemonless --transport tcp --host <container-ip> --port 7717
+```
+
+---
+
+## What it does differently
+
+Four things, each traceable to a measurement. The full argument, with the numbers, is
+[`CLAUDE.md`](CLAUDE.md) §2.
+
+**MCP tools as code, not tool definitions.** Most agents ship MCP schemas in the prompt
+prefix every turn: 10–30k tokens, forever. stcode writes them to
+`.stcode/mcp_servers/<server>/<tool>.py` and lets the agent `grep` and import what it
+needs. Measured on three servers and twelve tools: **9,869 → 0 chars per turn.**
+
+**A supervisor that watches the trajectory.** The session JSONL is already the trajectory,
+so the supervisor is just a reader. Free counting heuristics run first — the same call
+three times, over half the calls failing, no file written in N turns — and only a firing
+heuristic costs a model call.
+
+**Agent-to-agent messaging with no protocol.** Containers share a volume, so a message is
+a file. No registry, no routing table, no service discovery. Messages carry paths, not
+payloads, which stops team token cost growing with N².
+
+**Daemon-first.** Detach does not kill the agent. Approvals and questions are
+request–response correlated by `execution_id` over the same JSONL framing as everything
+else.
+
+### Honest comparison
+
+| | Claude Code | Cline / Kilo | **stcode** |
+| --- | --- | --- | --- |
+| Tool quality (read/edit/grep/bash) | excellent | good | comparable |
+| MCP cost | tool defs per turn | tool defs per turn | as code, 9.9k → 0 chars/turn |
+| Runs headless in a container | partial | no | **yes** |
+| Multi-agent team across containers | no | no | **yes** |
+| Stagnation detection | no | no | **yes** |
+| Maturity, polish, ecosystem | **far ahead** | ahead | behind, and will stay behind |
+
+We are not competing on polish.
+
+---
+
+## How it fits together
+
+```
+cli  ┄┄ socket + JSONL ┄┄▶  core/daemon ──▶ core/agent ──▶ { core/session, core/harness, core/providers }
+                                                       └──▶ core/team (team mode only)
+core/harness ──▶ core/repl        core/configs, core/common ◀── everyone in core/
+```
+
+`cli/` and `core/` are separate programs that never import each other: the UI starts
+`stcode-daemon` and speaks to it over the socket. Inside `core/`, dependencies point one
+way, always. [`CLAUDE.md`](CLAUDE.md) §3 has the contract for each
+component.
+
+**Approval modes** gate what runs unattended: `plan` reads only, `suggest` asks before
+every write and command, `auto-edit` auto-approves edits, `full-auto` asks nothing — and,
+without an approver, starts only inside a container. That last rule is code
+(`core/daemon/autonomy.py`), not a warning in a document, and there is no override flag.
+
+**Sessions** live at `~/.stcode/sessions/<id>.jsonl`, one append per event, never
+rewritten. Branching a session is `cp`.
+
+---
+
+## Status
+
+All five phases are built: the turn loop, tools, transcript, daemon and TUI client; the
+REPL and MCP-as-code; the stagnation supervisor; multi-container team mode. Each phase has
+a smoke script proving its gate against real processes:
+
+```bash
+uv run python smoke_repl.py         # the REPL, and tool_out
+uv run python smoke_mcp.py          # three MCP servers, prompt prefix unchanged
+uv run python smoke_supervisor.py   # a loop caught and redirected
+uv run python smoke_daemon.py       # detach/re-attach, and the autonomy guard
+uv run python smoke_team.py         # two containers, one volume (needs Docker)
+```
+
+They need a reachable model and are meant to be read as much as run — each is the
+shortest correct example of driving its layer.
+
+**What is not done:** the ~20 team-mode evaluation tasks in
+[`docs/architecture/team.md`](docs/architecture/team.md#the-evaluation-set) are written
+and have not been run. Until they are, whether team mode helps or merely spends 15× the
+tokens is an open question. [`CLAUDE.md`](CLAUDE.md) §7 explains why that is the honest
+thing to say about it.
+
+---
+
+## Development
+
+```bash
+uv run pytest
+```
+
+```bash
+uv run pytest -m live                     # the two tests that call a real provider
+uv run --group docs mkdocs serve          # the documentation site
+```
+
+Conventions: Python 3.10+, `uv` for everything, type hints mandatory in `core/`, tests
+in `tests/`, commit messages `area: what changed`. Every tool has a docstring because
+**the docstring is the prompt the model reads**.
+
+**Before writing code**, read
+[how a change is made](docs/contributing/workflow.md) — spec → question → document →
+test → implement → run → commit. The document comes before the test on purpose: a
+feature whose page is hard to write is a feature whose shape is wrong.
+
+Start with [`CLAUDE.md`](CLAUDE.md) — what the project is, what it bets on, and the
+seven rules — then [`docs/architecture/`](docs/architecture/index.md) for the component
+you are about to change, and [`docs/decisions/`](docs/decisions/index.md) for the
+questions already settled.
+
+## Licence
+
+Apache 2.0 — see [LICENSE](LICENSE).