stcode 0.0.1a0__py3-none-any.whl

stcode/core/daemon/main.py

@@ -0,0 +1,126 @@
+"""
+`stcode-daemon` — the daemon as a process. What a container runs, and what the UI
+starts in the background when nothing is listening.
+
+    stcode-daemon [--config PATH] [--transport unix|tcp] [--socket PATH]
+                  [--host HOST] [--port N] [--mode MODE] [--role ROLE] [--team]
+
+Flags apply to this process only and are never written to the config file. It logs to
+stderr and stops on SIGTERM, SIGINT, or a `shutdown` message over the unix socket.
+
+Exit codes: 0 stopped, 1 failed to start, 2 `full-auto` refused (rule 5).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import logging
+import signal
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+from stcode import __version__
+from stcode.core.configs import APPROVAL_MODES, Config, config_path, load_config
+from stcode.core.daemon.autonomy import AutonomyRefused, in_container
+from stcode.core.daemon.server import Daemon
+
+log = logging.getLogger("stcode.daemon")
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="stcode-daemon", description=__doc__.split("\n\n")[0])
+    parser.add_argument("--config", type=Path, help="Config file. Default: $STCODE_CONFIG or ~/.stcode/config.toml.")
+    parser.add_argument("--transport", choices=("unix", "tcp"))
+    parser.add_argument("--socket", help="Unix socket path.")
+    parser.add_argument("--host", help="TCP host to bind.")
+    parser.add_argument("--port", type=int, help="TCP port to bind.")
+    parser.add_argument("--mode", choices=APPROVAL_MODES, help="Default approval mode for new sessions.")
+    parser.add_argument("--role", help="Which agent this is. Does not turn team mode on.")
+    parser.add_argument("--team", action="store_true", default=None, help="Turn team mode on.")
+    parser.add_argument("--version", action="version", version=f"stcode {__version__}")
+    return parser.parse_args(argv)
+
+
+def overrides_from(args: argparse.Namespace) -> dict[str, Any]:
+    """The flags as dotted config keys, unset ones left out."""
+    pairs = {
+        "daemon.transport": args.transport,
+        "daemon.socket": args.socket,
+        "daemon.host": args.host,
+        "daemon.port": args.port,
+        "agent.approval_mode": args.mode,
+        "team.role": args.role,
+        "team.enabled": args.team,
+    }
+    return {key: value for key, value in pairs.items() if value is not None}
+
+
+def startup_report(daemon: Daemon, *, created: Sequence[Path] = ()) -> list[str]:
+    """What this daemon became, one line per fact — a container has no screen, so this
+    is the only place to say it. `created` names what start-up *made*: a config
+    scaffolded because a mount did not happen looks exactly like one that was mounted.
+    """
+    config = daemon.config
+    limit = daemon.max_clients
+    provider, model = daemon.gateway().resolve(config.agent.difficulty)
+    lines = [
+        f"stcode {__version__} — daemon",
+        f"  listening   {config.daemon.transport} {daemon.address}   "
+        + (f"({limit} client{'' if limit == 1 else 's'} max)" if limit else "(no client limit)"),
+        f"  workspace   {config.cwd}",
+        f"  mode        {config.agent.approval_mode}",
+        f"  model       {model or '(library default)'} ({provider})",
+        f"  config      {config.path}",
+        f"  sessions    {config.session.dir}",
+    ]
+    team = config.team
+    lines.append(f"  team        {team.role or '(no role!)'} on {team.shared_dir}" if team.enabled else "  team        off")
+    lines.append(f"  container   {'yes' if in_container() else 'no'}")
+    lines += [f"  created     {path}" for path in created]
+    return lines
+
+
+async def serve(config: Config, overrides: dict[str, Any], created: Sequence[Path]) -> None:
+    daemon = Daemon(config, overrides=overrides)
+    await daemon.start()
+    loop = asyncio.get_running_loop()
+    for signum in (signal.SIGTERM, signal.SIGINT):
+        with contextlib.suppress(NotImplementedError):  # Windows has no signal handlers
+            loop.add_signal_handler(signum, daemon.stop)
+    for line in startup_report(daemon, created=created):
+        print(line, file=sys.stderr)
+    print("ready", file=sys.stderr, flush=True)
+    try:
+        await daemon.serve_forever()
+    finally:
+        await daemon.aclose()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s", stream=sys.stderr)
+    overrides = overrides_from(args)
+    path = (args.config or config_path()).expanduser()
+    created = [] if path.exists() else [path]
+    try:
+        config = load_config(path, overrides=overrides, create_if_missing=True)
+        if not config.session.dir.expanduser().exists():
+            created.append(config.session.dir)
+        asyncio.run(serve(config, overrides, created))
+    except AutonomyRefused as refusal:
+        # Rule 5. The engine refuses; this only turns the refusal into an exit code.
+        print(str(refusal), file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        pass
+    except Exception as exc:  # noqa: BLE001 — a daemon that cannot start says why and exits
+        print(f"stcode-daemon: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stcode/core/daemon/protocol.py

@@ -0,0 +1,499 @@
+"""
+The wire — JSONL, one message per line, same framing on unix and TCP.
+
+Everything crossing a process boundary is shaped here and nowhere else.
+
+* **One line, flushed** — the same discipline as the session file and the REPL worker.
+  Nothing on the wire may hold a raw newline, so the encoder is not optional.
+* **Agent events are not re-wrapped.** `core/agent/events.py` already carries primitives
+  with the right `type`, so a `TextDelta` is dumped as-is plus a `session` field.
+* `turn_finished` carries the **full four-field `Usage`** — the cache counts are the
+  evidence for the prompt-caching claim.
+* `set_mode` and `set_meta` exist, so `/mode`, `/model` and `/effort` reach the live
+  session rather than only later ones.
+* `info` exists because a client cannot answer "which skills are there" for itself —
+  in `--daemonless` the workspace is on the daemon's machine, not the terminal's.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any, Literal, Union
+
+from pydantic import BaseModel, Field, TypeAdapter, ValidationError
+
+from stcode.core.agent.events import AgentEvent
+from stcode.core.configs import ApprovalMode, ReasoningEffort
+from stcode.core.harness.tools.base import ApprovalRequest, Question
+
+
+class ProtocolError(Exception):
+    """A line that is not a message this daemon understands."""
+
+
+# ---- client → daemon ------------------------------------------------------------
+#
+# Every message that acts on a session takes an optional `session` id. A connection
+# remembers the last session it created or attached to and uses that when the field is
+# empty, which is what §11.1's `{"type":"push","text":"…"}` assumes; the field is there
+# because one connection may attach to several sessions at once and then has to say
+# which one it means.
+
+
+class Create(BaseModel):
+    """Start a new session. The daemon replies with `session` and attaches this client."""
+
+    type: Literal["create"] = "create"
+    cwd: str = ""
+    role: str = ""
+    approval_mode: ApprovalMode | None = None
+
+
+class Attach(BaseModel):
+    """Join a session. Several clients may attach to one at the same time.
+
+    An id the daemon is not holding is resumed from disk, which is what makes
+    `stcode --resume` a protocol message rather than a second code path.
+    """
+
+    type: Literal["attach"] = "attach"
+    session: str = ""
+    replay: bool = True
+
+
+class Detach(BaseModel):
+    """Stop receiving this session's events. **Does not stop the agent** — that is the
+    entire reason the daemon exists (§8 point 2)."""
+
+    type: Literal["detach"] = "detach"
+    session: str = ""
+
+
+class Sessions(BaseModel):
+    """What this daemon is holding, plus what is on disk."""
+
+    type: Literal["sessions"] = "sessions"
+    limit: int = 20
+
+
+class Push(BaseModel):
+    """Queue a message. Arriving mid-turn, it waits for the next turn (§8 point 3)."""
+
+    type: Literal["push"] = "push"
+    text: str
+    session: str = ""
+
+
+class Interrupt(BaseModel):
+    """Stop the turn in flight at its next checkpoint."""
+
+    type: Literal["interrupt"] = "interrupt"
+    session: str = ""
+
+
+class Approval(BaseModel):
+    """The answer to an `approval_request`, correlated by `execution_id`."""
+
+    type: Literal["approval"] = "approval"
+    execution_id: str
+    approved: bool = False
+    session: str = ""
+
+
+class Answer(BaseModel):
+    """The answer to a `question`, correlated by `execution_id`."""
+
+    type: Literal["answer"] = "answer"
+    execution_id: str
+    text: str = ""
+    session: str = ""
+
+
+class SetMode(BaseModel):
+    """Change a live session's approval mode."""
+
+    type: Literal["set_mode"] = "set_mode"
+    mode: ApprovalMode
+    session: str = ""
+
+
+class SetMeta(BaseModel):
+    """Change a live session's model, provider or reasoning effort.
+
+    A **patch**: an unset field is left alone, so `/effort` does not have to restate
+    the model. It lands as a `meta` record appended to the session, which is why the
+    change is in the transcript and nothing is rewritten.
+    """
+
+    type: Literal["set_meta"] = "set_meta"
+    model: str | None = None
+    provider: str | None = None
+    reasoning_effort: ReasoningEffort | None = None
+    session: str = ""
+
+    def fields(self) -> dict[str, Any]:
+        """Just the settings that were actually given."""
+        return {
+            key: value
+            for key, value in (
+                ("model", self.model),
+                ("provider", self.provider),
+                ("reasoning_effort", self.reasoning_effort),
+            )
+            if value
+        }
+
+
+class Info(BaseModel):
+    """Ask what this daemon's machine has: skills, MCP servers, tools, paths."""
+
+    type: Literal["info"] = "info"
+    session: str = ""
+
+
+class WorkspaceFiles(BaseModel):
+    """List paths in the attached daemon workspace for client completion."""
+
+    type: Literal["workspace_files"] = "workspace_files"
+    session: str = ""
+    request_id: str
+
+
+class WorkspaceShell(BaseModel):
+    """Run an explicit user command outside the agent and its history."""
+
+    type: Literal["workspace_shell"] = "workspace_shell"
+    session: str = ""
+    request_id: str
+    command: str
+    timeout: float = Field(default=10, allow_inf_nan=False)
+
+
+class GetConfig(BaseModel):
+    """Ask for the daemon's own config, as a `config` frame. Keys are never sent."""
+
+    type: Literal["get_config"] = "get_config"
+
+
+class SetConfig(BaseModel):
+    """Change the daemon's persisted defaults, save them, and reload.
+
+    A patch: an unset field is left alone. `provider` names a `[model.providers]` entry
+    — or a library name, which creates that entry — and becomes the default; `model`
+    and `api_key` apply to that entry. `api_key` is accepted over the unix socket only.
+
+    Answered with a `config` frame, whether or not the change was accepted.
+    """
+
+    type: Literal["set_config"] = "set_config"
+    provider: str | None = None
+    model: str | None = None
+    api_key: str | None = None
+    reasoning_effort: ReasoningEffort | None = None
+    approval_mode: ApprovalMode | None = None
+
+
+class Shutdown(BaseModel):
+    """Stop the daemon. Accepted over the unix socket only."""
+
+    type: Literal["shutdown"] = "shutdown"
+
+
+ClientMessage = Annotated[
+    Union[
+        Create,
+        Attach,
+        Detach,
+        Sessions,
+        Push,
+        Interrupt,
+        Approval,
+        Answer,
+        SetMode,
+        SetMeta,
+        Info,
+        WorkspaceFiles,
+        WorkspaceShell,
+        GetConfig,
+        SetConfig,
+        Shutdown,
+    ],
+    Field(discriminator="type"),
+]
+
+_CLIENT_ADAPTER: TypeAdapter[ClientMessage] = TypeAdapter(ClientMessage)
+
+
+# ---- daemon → client ------------------------------------------------------------
+
+
+class SessionOpened(BaseModel):
+    """Answer to `create`, `attach`, `set_mode` and `set_meta`: what this session now is.
+
+    The settings are the **effective** ones — `meta` merged with any overrides — because
+    a status line showing what a session started as is a status line that lies after the
+    first `/model`. `started` says whether the transcript exists yet: a session can be
+    an id and nothing more until its first message.
+    """
+
+    type: Literal["session"] = "session"
+    id: str
+    cwd: str = ""
+    role: str = ""
+    model: str = ""
+    provider: str = ""
+    reasoning_effort: str = ""
+    approval_mode: str = ""
+    busy: bool = False
+    started: bool = False
+
+
+class SessionList(BaseModel):
+    type: Literal["sessions"] = "sessions"
+    sessions: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class History(BaseModel):
+    """The transcript so far, sent on attach before the live stream is joined.
+
+    Raw session records rather than `Message`s: a re-attaching client wants what the
+    trajectory holds — tool calls, errors, usage — not the folded model history.
+    """
+
+    type: Literal["history"] = "history"
+    session: str = ""
+    records: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class ApprovalRequested(BaseModel):
+    """A tool is waiting on a human. Answer with `approval` carrying this
+    `execution_id`; whoever answers first decides."""
+
+    type: Literal["approval_request"] = "approval_request"
+    session: str = ""
+    execution_id: str
+    tool: str
+    permission: str = ""
+    arguments: dict[str, Any] = Field(default_factory=dict)
+    agent_name: str = "main"
+
+    @classmethod
+    def of(cls, session: str, request: ApprovalRequest) -> "ApprovalRequested":
+        return cls(
+            session=session,
+            execution_id=request.execution_id,
+            tool=request.tool_name,
+            permission=str(request.permission),
+            arguments=request.arguments,
+            agent_name=request.agent_name,
+        )
+
+
+class QuestionAsked(BaseModel):
+    """`ask_user_question` is waiting. Answer with `answer`.
+
+    `execution_id` is minted by the daemon: `Question` has no field for one, unlike
+    `ApprovalRequest`. Same correlation mechanism, one end of it supplied here.
+    """
+
+    type: Literal["question"] = "question"
+    session: str = ""
+    execution_id: str
+    question: str
+    header: str = ""
+    options: list[str] = Field(default_factory=list)
+    multi_select: bool = False
+
+    @classmethod
+    def of(cls, session: str, execution_id: str, question: Question) -> "QuestionAsked":
+        return cls(
+            session=session,
+            execution_id=execution_id,
+            question=question.question,
+            header=question.header,
+            options=question.options,
+            multi_select=question.multi_select,
+        )
+
+
+class InfoReply(BaseModel):
+    """Answer to `info`: what the **daemon's** machine has.
+
+    Every field here is something a client cannot see for itself once the agent is in a
+    container: the workspace, the config file, the skills that were discovered, the MCP
+    servers that answered. In solo mode that distinction is invisible; in
+    `--daemonless` it is the whole reason this message exists.
+    """
+
+    type: Literal["info"] = "info"
+    session: str = ""
+    version: str = ""
+    daemon: str = ""
+    cwd: str = ""
+    role: str = ""
+    config_path: str = ""
+    session_path: str = ""
+    session_dir: str = ""
+    approval_mode: str = ""
+    tools: list[str] = Field(default_factory=list)
+    skills: list[dict[str, str]] = Field(default_factory=list)
+    mcp: list[dict[str, Any]] = Field(default_factory=list)
+    usage: dict[str, int] = Field(default_factory=dict)
+    """This session's token totals, summed from its `usage` records — what `/token`
+    shows. Here rather than as its own message because it is the same question `info`
+    already answers: *what does the daemon know about this session that I cannot see?*
+    """
+
+
+class ConfigReply(BaseModel):
+    """Answer to `get_config` and `set_config`: what this daemon is configured with.
+
+    `path` is the file **on the daemon's disk**. `writable` says whether `set_config`
+    can land at all; `keys_editable` whether it may carry a key (unix socket only).
+    `provider` and `model` are the default entry, which is what `/model` edits.
+
+    `providers` lists the configured entries without their keys — `has_key` says
+    whether one resolves. `libraries` is what a new entry can be: each library's
+    default model and conventional key variable.
+    """
+
+    type: Literal["config"] = "config"
+    path: str = ""
+    writable: bool = True
+    keys_editable: bool = False
+    provider: str = ""
+    model: str = ""
+    reasoning_effort: str = ""
+    approval_mode: str = ""
+    providers: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    libraries: dict[str, dict[str, str]] = Field(default_factory=dict)
+
+
+class Progress(BaseModel):
+    """A line of progress from a long-running tool. Advisory: nothing is recorded."""
+
+    type: Literal["progress"] = "progress"
+    session: str = ""
+    text: str = ""
+
+
+class ErrorMessage(BaseModel):
+    """A protocol- or daemon-level failure. Not `agent_failed`, which is a turn ending
+    badly and is the agent's own event."""
+
+    type: Literal["error"] = "error"
+    session: str = ""
+    message: str
+    level: Literal["error", "warning"] = "error"
+
+
+ServerMessage = Union[
+    SessionOpened,
+    SessionList,
+    History,
+    ApprovalRequested,
+    QuestionAsked,
+    InfoReply,
+    ConfigReply,
+    Progress,
+    ErrorMessage,
+]
+
+
+# ---- framing --------------------------------------------------------------------
+
+STREAM_LIMIT = 64 * 1024 * 1024
+"""How long one line may be, on both ends of every connection.
+
+`asyncio`'s streams default to **64 KiB** per line, and a line over it raises
+`ValueError` out of the read loop rather than arriving. The framing here is one message
+per line, and `history` is one message carrying a whole transcript — so the default cap
+means *a session stops being resumable the moment its file passes 64 KiB*, which is
+about thirty tool calls. The frame is built in memory either way; this only says the
+reader must be willing to receive what the writer was willing to send.
+"""
+
+
+def encode(message: BaseModel | dict[str, Any]) -> bytes:
+    """One message, one line, UTF-8. `default=str` so a stray Path or datetime in a
+    tool's arguments degrades to text instead of killing the connection."""
+    payload = message.model_dump(mode="json") if isinstance(message, BaseModel) else message
+    return (json.dumps(payload, ensure_ascii=False, default=str) + "\n").encode("utf-8")
+
+
+def decode(line: bytes | str) -> dict[str, Any]:
+    """One line back to an object, or `ProtocolError`."""
+    text = line.decode("utf-8", errors="replace") if isinstance(line, bytes) else line
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ProtocolError(f"not JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ProtocolError("a message must be a JSON object")
+    return payload
+
+
+def parse_client_message(payload: dict[str, Any]) -> ClientMessage:
+    """Validate one decoded line as a client message.
+
+    Errors name the `type` the client sent, because "field required" against a model
+    the client has never heard of is not a diagnosis.
+    """
+    try:
+        return _CLIENT_ADAPTER.validate_python(payload)
+    except ValidationError as exc:
+        kind = payload.get("type", "(missing)")
+        detail = "; ".join(
+            f"{'.'.join(str(part) for part in error['loc']) or 'message'}: {error['msg']}"
+            for error in exc.errors()
+        )
+        raise ProtocolError(f"bad {kind!r} message: {detail}") from exc
+
+
+def event_frame(session: str, event: AgentEvent, *, agent: str = "") -> dict[str, Any]:
+    """An agent event as it goes on the wire: itself, plus where it came from.
+
+    `agent` names the **sub-agent** that produced it and is omitted when there is none,
+    so a frame without the field is the session's own agent. One extra field rather
+    than a parallel set of sub-agent message types — the same reason agent events are
+    not re-wrapped in the first place.
+    """
+    frame = {**event.model_dump(mode="json"), "session": session}
+    if agent:
+        frame["agent"] = agent
+    return frame
+
+
+__all__ = [
+    "STREAM_LIMIT",
+    "Answer",
+    "Approval",
+    "ApprovalRequested",
+    "Attach",
+    "ClientMessage",
+    "ConfigReply",
+    "Create",
+    "Detach",
+    "ErrorMessage",
+    "GetConfig",
+    "History",
+    "Info",
+    "InfoReply",
+    "Interrupt",
+    "Progress",
+    "ProtocolError",
+    "Push",
+    "QuestionAsked",
+    "ServerMessage",
+    "SessionList",
+    "SessionOpened",
+    "Sessions",
+    "SetConfig",
+    "SetMeta",
+    "SetMode",
+    "Shutdown",
+    "decode",
+    "encode",
+    "event_frame",
+    "parse_client_message",
+]