sennet 0.1.0__py3-none-any.whl

sennet/__init__.py

@@ -0,0 +1,3 @@
+"""Sennet: talk to your coding agents."""
+
+__version__ = "0.1.0"

sennet/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

sennet/access.py

@@ -0,0 +1,121 @@
+"""Paired devices: who may use Sennet (HLD §8, docs/m5-access.md).
+
+There are no accounts. A device pairs once by redeeming a pairing code, and gets a
+token of its own, which it keeps in a cookie until the device is revoked. A pairing
+code comes in two forms, either of which redeems it, once: a long code carried in a
+link (`<url>/pair#<code>`), and a short one to type on a phone that can't scan the
+link's QR code. Codes and tokens are stored only as SHA-256 hashes.
+
+`sennet pair` makes codes straight in the database, so anyone who can run it (the
+user) can always pair a device, with or without the daemon running.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+import secrets
+import time
+from collections import deque
+from dataclasses import dataclass
+
+from .db import Database
+
+COOKIE = "sennet_device"
+COOKIE_MAX_AGE_S = 365 * 24 * 60 * 60
+TERMINAL = "the terminal"
+TERMINAL_TTL_S = 15 * 60       # a code from `sennet pair`
+DEVICE_TTL_S = 5 * 60          # a code another device shows
+# Typed codes leave out characters that are easy to confuse: 0 and O, 1, I and L.
+ALPHABET = "23456789ABCDEFGHJKMNPQRSTUVWXYZ"
+TYPED_LENGTH = 8               # about 40 bits; with expiry and the throttle, enough to type
+SEEN_EVERY_S = 60              # how often a device's last-seen time is written
+NAME_LENGTH = 60
+
+
+@dataclass
+class Pairing:
+    link_code: str
+    typed_code: str              # shown as XXXX-XXXX
+    expires_at: float
+
+    def link(self, base_url: str) -> str:
+        return f"{base_url.rstrip('/')}/pair#{self.link_code}"
+
+
+def _hash(secret: str) -> str:
+    return hashlib.sha256(secret.encode()).hexdigest()
+
+
+def _typed(code: str) -> str:
+    """A typed code as stored: capitals, without the dash or spaces people add."""
+    return re.sub(r"[^0-9A-Z]", "", code.upper())
+
+
+def new_pairing(db: Database, created_by: str, ttl_s: float) -> Pairing:
+    typed = "".join(secrets.choice(ALPHABET) for _ in range(TYPED_LENGTH))
+    pairing = Pairing(secrets.token_urlsafe(16), f"{typed[:4]}-{typed[4:]}", time.time() + ttl_s)
+    db.add_pairing(_hash(pairing.link_code), _hash(typed), created_by, pairing.expires_at)
+    return pairing
+
+
+def redeem(db: Database, code: str, user_agent: str) -> tuple[dict, str] | None:
+    """Pair a device with a code in either form: the new device and its token, or None for a code that
+    is wrong, used or expired."""
+    code = code.strip()
+    if not code or len(code) > 64:
+        return None
+    pairing = db.take_pairing(_hash(code)) or db.take_pairing(_hash(_typed(code)))
+    if pairing is None:
+        return None
+    token = secrets.token_urlsafe(32)
+    device = db.add_device(device_name(user_agent), _hash(token), pairing["created_by"])
+    return device, token
+
+
+def device_for(db: Database, token: str | None) -> dict | None:
+    """The device a cookie's token belongs to, noting that it was seen."""
+    if not token:
+        return None
+    device = db.device_by_token(_hash(token))
+    if device and time.time() - device["last_seen_at"] > SEEN_EVERY_S:
+        device["last_seen_at"] = time.time()
+        db.update_device(device["id"], last_seen_at=device["last_seen_at"])
+    return device
+
+
+def rename(db: Database, device_id: int, name: str) -> dict | None:
+    name = " ".join(name.split())[:NAME_LENGTH]
+    if not name:
+        raise ValueError("a device needs a name")
+    db.update_device(device_id, name=name)
+    return db.device(device_id)
+
+
+def device_name(user_agent: str) -> str:
+    """A name a person recognises, such as "Firefox on Linux", from a browser's user agent."""
+    browser = next((name for pattern, name in (
+        (r"Edg/", "Edge"), (r"OPR/|Opera", "Opera"), (r"Firefox/|FxiOS/", "Firefox"),
+        (r"Chrome/|CriOS/", "Chrome"), (r"Safari/", "Safari")) if re.search(pattern, user_agent)), "Browser")
+    system = next((name for pattern, name in (
+        (r"iPhone", "iPhone"), (r"iPad", "iPad"), (r"Android", "Android"), (r"Mac OS X|Macintosh", "macOS"),
+        (r"Windows", "Windows"), (r"CrOS", "ChromeOS"), (r"Linux", "Linux")) if re.search(pattern, user_agent)), None)
+    return f"{browser} on {system}" if system else browser
+
+
+class Throttle:
+    """Wrong pairing codes, counted across every client: past `limit` a minute, redeeming waits."""
+
+    def __init__(self, limit: int = 10, window_s: float = 60):
+        self.limit = limit
+        self.window_s = window_s
+        self.failures: deque[float] = deque()
+
+    def wait(self) -> float:
+        """Seconds until a code may be tried again; 0 when it may be now."""
+        now = time.monotonic()
+        while self.failures and now - self.failures[0] > self.window_s:
+            self.failures.popleft()
+        return self.failures[0] + self.window_s - now if len(self.failures) >= self.limit else 0
+
+    def failed(self):
+        self.failures.append(time.monotonic())

sennet/agents/base.py

@@ -0,0 +1,315 @@
+"""Provider-neutral agent contract.
+
+Adapters translate a CLI's protocol into these events and requests. Nothing here
+knows about Codex, Claude Code or Gemini specifics, and nothing outside an adapter
+sees a provider's own words: statuses, kinds and modes are the vocabularies below,
+and `check_event` holds every adapter to them.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Awaitable, Callable, Literal, Protocol, get_args
+
+if TYPE_CHECKING:
+    from .callbacks import CallbackServer
+
+Decision = Literal["approve", "approve_always", "decline", "cancel"]
+
+# How a turn ended. An adapter maps its provider's words to these.
+TurnStatus = Literal["completed", "cancelled", "failed"]
+# A command or file change: running while in progress, then one of the others.
+ItemStatus = Literal["running", "completed", "failed", "declined"]
+ChangeKind = Literal["add", "delete", "update", "move"]
+StepStatus = Literal["pending", "active", "done"]
+# Who started a turn: the user's message, or the agent itself (see `background_turns`).
+TurnStarter = Literal["user", "agent"]
+
+# What the agent may do without asking (the approval policy, §4.4 of the HLD):
+#   ask:   asks before anything outside the agent's own trusted set
+#   auto:  works freely within its access level, asks only to go beyond it
+#   never: never asks; anything beyond its access level fails
+#   classifier: the agent's own safety classifier allows or blocks each action, nothing asked
+#               up front (Claude Code's auto mode); not a sandbox, so it can reach past `workspace`
+ApprovalMode = Literal["ask", "auto", "never", "classifier"]
+# What the agent may touch: read-only, edit the project directory, or anything.
+Access = Literal["read-only", "workspace", "full"]
+APPROVAL_MODES: tuple[str, ...] = get_args(ApprovalMode)
+ACCESS_LEVELS: tuple[str, ...] = get_args(Access)
+
+# Given to every agent as instructions alongside its own. Its messages are read aloud as they
+# arrive, so it states its plan up front and reports briefly between steps; a long
+# message starts with a version written to be heard; the voice hub speaks it as soon as it is
+# streamed, and the timeline hides it (voice-protocol §9). `{ask_tool}` names the agent's
+# own tool for asking the user, when it has one, because naming it is what stops its use.
+SPOKEN_INSTRUCTIONS = """\
+The user may hear your messages read aloud by a voice interface instead of reading them.
+
+While you work, keep the user in the conversation:
+- Before your first tool call, write one or two sentences saying what you understood them to \
+want and how you'll go about it. State the plan, not the answer. Skip this when you can \
+answer straight away without tools.
+- Between tool calls, when you move on to a new step or find something that changes the \
+plan, write a single short sentence, about ten words, saying what you're doing now or what \
+you found, such as "The test fails on the date parsing, so I'm looking at that next." Never \
+more than one sentence: each update is spoken before the next can be, so a long one falls \
+behind your work. Say it in plain words, without commands, code or paths, and don't repeat \
+what you've already said. Skip it for quick steps that follow on from the last one.
+
+When a message to the user is longer than about three sentences, or reports the outcome of \
+your work, start it with a version written to be heard, inside <spoken></spoken> tags, then \
+write the message as you normally would. The spoken version:
+- comes first, before anything else in the message;
+- talks to the user directly, as "you", in plain sentences, most important first: what was \
+done or found, or what went wrong, then anything they need to know or decide;
+- keeps every point that matters, with numbers and names exactly as in the full message, and \
+adds nothing that isn't in it;
+- never repeats a result your updates during the work already said, since the user has just \
+heard it. If the updates covered the results, the spoken version only says how it ended and \
+anything new, such as "Done: both results are in the report file." The written message below \
+it still has everything;
+- has no markdown, lists, code, URLs or file paths (say a file's name, not its path), and \
+writes symbols as words: "24 dollars", not "$24";
+- is usually one to five sentences: shorter than the message, but not cut to a headline;
+- ends with your question, if the message asks the user something.
+
+Short messages need no spoken version. Use the tags only in your messages to the user, \
+never in files, commands, commit messages or other tool input.
+
+Don't ask the user questions while you are still working, and don't use a tool to ask them\
+{ask_tool}: they can't answer until your turn ends. Work out what you can, then put any \
+questions at the end of your final message, where its spoken version ends with them too."""
+
+
+def spoken_instructions(ask_tool: str | None = None) -> str:
+    """SPOKEN_INSTRUCTIONS for an agent whose tool for asking the user is `ask_tool`."""
+    return SPOKEN_INSTRUCTIONS.format(ask_tool=f" (such as {ask_tool})" if ask_tool else "")
+
+
+@dataclass
+class AgentEvent:
+    """A normalized agent event. `data` holds the kind's fields (see EVENT_FIELDS).
+
+    A turn may send several `message`s (commentary, then the answer); the last
+    `message` before `turn_completed` is the turn's answer, and is what gets spoken.
+
+    An agent with `background_turns` may keep work running after its turn ends
+    (`background` lists it) and start a turn of its own when that work is done:
+    `turn_started` with `by: "agent"`, then the turn's events and `turn_completed`.
+    """
+
+    kind: str
+    data: dict = field(default_factory=dict)
+
+
+# Required fields per event kind, and the vocabulary a field must use, if any.
+EVENT_FIELDS: dict[str, dict[str, tuple | None]] = {
+    "message_delta": {"item_id": None, "delta": None},
+    "message": {"item_id": None, "text": None},
+    "command_started": {"item_id": None, "command": None},
+    "command_finished": {"item_id": None, "command": None, "status": get_args(ItemStatus),
+                         "exit_code": None, "output_tail": None},
+    "file_change": {"item_id": None, "status": get_args(ItemStatus), "changes": None},
+    "plan": {"steps": None},
+    "error": {"message": None},
+    "turn_completed": {"status": get_args(TurnStatus), "error": None},
+    "turn_started": {"by": get_args(TurnStarter)},
+    # The work still running after the turn, each {"id", "description"}; empty once it is done.
+    "background": {"tasks": None},
+    # Tokens the turn used, sent before its `turn_completed`: all input (cached included), the
+    # part of it read from cache, and output (reasoning included).
+    "usage": {"input": None, "cached": None, "output": None},
+    # The account's usage limits as the agent last reported them, each window a LimitWindow's
+    # fields. They belong to the account, not the task; a report may hold only some windows.
+    "limits": {"windows": None},
+}
+# Fields an adapter may add when its provider reports them. Anything else is not the contract's.
+OPTIONAL_FIELDS: dict[str, tuple[str, ...]] = {
+    "command_started": ("cwd",),          # the directory the command runs in
+    "command_finished": ("duration_ms",),
+    "error": ("will_retry",),             # the agent retries on its own, so the turn goes on
+    # The turn failed at a usage limit: {"window": its title, "resets_at"}, either None when unknown.
+    "turn_completed": ("limit",),
+}
+LIMIT_WINDOW_FIELDS = {"id", "title", "used", "resets_at"}
+
+
+def check_event(event: AgentEvent) -> list[str]:
+    """What is wrong with an event, by the contract; empty when it conforms."""
+    fields = EVENT_FIELDS.get(event.kind)
+    if fields is None:
+        return [f"unknown event kind {event.kind!r}"]
+    problems = []
+    for name, allowed in fields.items():
+        if name not in event.data:
+            problems.append(f"{event.kind} has no {name}")
+        elif allowed is not None and event.data[name] not in allowed:
+            problems.append(f"{event.kind}.{name} is {event.data[name]!r}, not one of {allowed}")
+    for name in event.data.keys() - fields.keys() - set(OPTIONAL_FIELDS.get(event.kind, ())):
+        problems.append(f"{event.kind} has a field the contract doesn't define: {name}")
+    if event.kind == "file_change":
+        for change in event.data.get("changes") or []:
+            if change.get("kind") not in get_args(ChangeKind):
+                problems.append(f"file_change kind {change.get('kind')!r} is not one of {get_args(ChangeKind)}")
+    if event.kind == "background":
+        for task in event.data.get("tasks") or []:
+            if set(task) != {"id", "description"}:
+                problems.append(f"background task {task!r} isn't just an id and a description")
+    if event.kind == "limits":
+        for window in event.data.get("windows") or []:
+            if set(window) != LIMIT_WINDOW_FIELDS:
+                problems.append(f"limit window {window!r} doesn't have just {sorted(LIMIT_WINDOW_FIELDS)}")
+    if event.kind == "turn_completed" and (limit := event.data.get("limit")) is not None:
+        if set(limit) != {"window", "resets_at"}:
+            problems.append(f"turn_completed limit {limit!r} isn't just a window and resets_at")
+    if event.kind == "plan":
+        for step in event.data.get("steps") or []:
+            if step.get("status") not in get_args(StepStatus):
+                problems.append(f"plan step status {step.get('status')!r} is not one of {get_args(StepStatus)}")
+    return problems
+
+
+ApprovalKind = Literal["command", "edit", "tool", "access"]
+
+
+@dataclass
+class FileChange:
+    path: str
+    kind: ChangeKind
+    diff: str = ""                     # unified diff, if the agent shows one
+
+
+@dataclass
+class ApprovalRequest:
+    """Something the agent wants to do that needs the user's say.
+
+    command: run `command`. edit: change the files in `changes` (or `paths`, when the
+    agent doesn't show the changes). tool: use any other tool, named in `tool`.
+    access: widen the agent's access, such as network or paths outside the project.
+
+    The engine writes the one-line summary from these fields; adapters don't.
+    """
+
+    kind: ApprovalKind
+    command: str | None = None         # as the user would type it, without shell wrappers
+    read_only: bool | None = None      # the adapter's judgement that the command only reads
+    paths: list[str] = field(default_factory=list)
+    changes: list[FileChange] = field(default_factory=list)
+    tool: str | None = None            # e.g. WebFetch, an MCP tool
+    tool_input: str | None = None      # short and human-readable, e.g. the URL
+    reason: str | None = None          # the agent's explanation, if any
+    network: bool = False
+    title: str | None = None           # the agent's own one-line description, if it gives one
+    extra: dict = field(default_factory=dict)  # provider-only detail: shown raw, never interpreted
+
+
+@dataclass
+class TurnPolicy:
+    """How much the agent may do without asking. Each adapter maps it to its CLI's own modes."""
+
+    mode: ApprovalMode
+    access: Access
+    # Load the project's own agent configuration (hooks, MCP servers), which can run code unasked.
+    project_config: bool = False
+    # The model and reasoning effort, by the ids `Agent.models` lists; None for the agent's own choice.
+    model: str | None = None
+    effort: str | None = None
+
+
+@dataclass(frozen=True)
+class ModelOption:
+    """A model an agent can run, as its CLI names it."""
+
+    id: str                            # what the CLI takes, e.g. "opus" or "gpt-6.1-sol"
+    title: str
+    efforts: tuple[str, ...] = ()      # reasoning effort levels it takes, lowest first
+    default_effort: str | None = None
+    default: bool = False              # the agent's own default model
+
+
+@dataclass(frozen=True)
+class Capabilities:
+    """What an agent really supports. Unsupported behaviour is shown, not faked (HLD §4.1).
+
+    Nothing has a default: each adapter states every capability, so none is claimed by omission.
+    """
+
+    interrupt: bool                    # can stop a turn and keep the session
+    resume: bool                       # can continue a task's conversation in a new process
+    live_approvals: bool               # asks for approval mid-turn, so `ask` mode works
+    approval_modes: tuple[str, ...]    # of APPROVAL_MODES
+    access_levels: tuple[str, ...]     # of ACCESS_LEVELS
+    background_turns: bool             # keeps working after its turn ends, and may start a turn itself
+    project_config: bool               # leaves a project's own configuration out unless the project opts in
+    live_model_change: bool            # changes model and effort between turns; else its process restarts, resuming
+
+
+EventSink = Callable[[AgentEvent], Awaitable[None]]
+ApprovalHandler = Callable[[ApprovalRequest], Awaitable[Decision]]
+
+
+@dataclass(frozen=True)
+class LimitWindow:
+    """One of the account's usage limits, such as the five-hour one, as the agent reports it."""
+
+    id: str                            # stable across reports: "session" (five hours), "weekly", ...
+    title: str                         # as the user knows it, e.g. "5-hour"; read out as "Claude's 5-hour limit"
+    used: int                          # percent of it used, 0 to 100
+    resets_at: float | None            # Unix time
+
+
+@dataclass
+class AgentStatus:
+    installed: bool
+    logged_in: bool | None
+    detail: str
+
+
+class AgentSession(Protocol):
+    # Opaque to everything but the adapter: a thread, session or conversation id that
+    # `Agent.open` takes back to continue the same conversation.
+    resume_token: str
+
+    async def send(self, text: str) -> None:
+        """Start a turn. Events and approval requests arrive through the callbacks
+        until a `turn_completed` event."""
+
+    async def interrupt(self) -> None:
+        """Ask the agent to stop the current turn. Only called when `capabilities.interrupt`."""
+
+    async def set_model(self, model: str | None, effort: str | None) -> None:
+        """Use this model and effort from the next turn (None: the agent's default). Only called
+        when `capabilities.live_model_change`; otherwise the session is reopened with them."""
+
+    async def close(self) -> None:
+        """Stop the agent process. With `capabilities.resume`, the conversation continues
+        later from `resume_token`."""
+
+    @property
+    def alive(self) -> bool: ...
+
+
+class Agent(Protocol):
+    """An adapter, built from the command that starts its CLI (`agents.commands` in the config) and
+    the daemon's MCP endpoint (agents.callbacks), for a CLI that calls back into Sennet."""
+
+    name: str
+    title: str                         # as the user knows it, e.g. "Claude Code"
+    capabilities: Capabilities
+    default_command: list[str]
+
+    def __init__(self, command: list[str], callbacks: CallbackServer | None = None): ...
+
+    async def status(self) -> AgentStatus: ...
+
+    async def models(self) -> list[ModelOption]:
+        """The models the user may pick from, the agent's default marked if it is known."""
+
+    async def limits(self) -> list[LimitWindow] | None:
+        """The account's usage limits, asked for without using any; None when the agent can't say
+        (not logged in, or logged in without a plan that has them)."""
+
+    async def open(self, cwd: Path, resume_token: str | None, policy: TurnPolicy,
+                   on_event: EventSink, on_approval: ApprovalHandler) -> AgentSession:
+        """Start a session. A resumed conversation may keep the model it last used, so with
+        `policy.model` None the adapter asks for the agent's default explicitly when resuming."""

sennet/agents/callbacks.py

@@ -0,0 +1,99 @@
+"""Sennet's own MCP endpoint, for agent CLIs that call back into it.
+
+Claude Code asks a permission prompt tool, an MCP tool, before a tool call that
+needs the user's say. The daemon serves such tools over HTTP at `/mcp/<secret>`,
+with one secret per agent session: the adapter registers its tools when the
+session starts, passes the URL to its CLI, and unregisters when it closes, which
+abandons any call still waiting. Only a live session's secret is answered.
+
+This is the least of MCP's HTTP transport a client needs to call a tool: JSON-RPC
+requests in POST bodies, answered with one JSON response each, and no sessions,
+streams or server-sent requests.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import secrets
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable
+
+from .. import __version__
+
+log = logging.getLogger(__name__)
+
+PROTOCOL_VERSION = "2025-06-18"
+SERVER_NAME = "sennet"
+
+# A tool call: the tool's name and arguments in, its text result out.
+ToolCall = Callable[[str, dict], Awaitable[str]]
+
+
+@dataclass
+class Registration:
+    secret: str
+    url: str
+    tools: list[dict]           # MCP tool definitions: name, description, inputSchema
+    call: ToolCall
+    calls: set[asyncio.Task] = field(default_factory=set)
+
+
+class CallbackServer:
+    def __init__(self, base_url: str = ""):
+        self.base_url = base_url    # where the daemon listens, as its agents reach it
+        self.sessions: dict[str, Registration] = {}
+
+    def register(self, tools: list[dict], call: ToolCall) -> Registration:
+        secret = secrets.token_urlsafe(32)
+        registration = Registration(secret, f"{self.base_url}/mcp/{secret}", tools, call)
+        self.sessions[secret] = registration
+        return registration
+
+    async def unregister(self, registration: Registration):
+        self.sessions.pop(registration.secret, None)
+        for call in list(registration.calls):
+            call.cancel()
+        await asyncio.gather(*registration.calls, return_exceptions=True)
+
+    async def handle(self, secret: str, message: dict) -> dict | None:
+        """The JSON-RPC response to `message`, or None for a notification. LookupError for an unknown secret."""
+        registration = self.sessions.get(secret)
+        if registration is None:
+            raise LookupError("no such session")
+        method, request_id = message.get("method"), message.get("id")
+        if request_id is None:
+            return None
+        params = message.get("params") or {}
+        if method == "initialize":
+            result = {"protocolVersion": params.get("protocolVersion", PROTOCOL_VERSION),
+                      "capabilities": {"tools": {}},
+                      "serverInfo": {"name": SERVER_NAME, "title": "Sennet", "version": __version__}}
+        elif method == "tools/list":
+            result = {"tools": registration.tools}
+        elif method == "tools/call":
+            names = {tool["name"] for tool in registration.tools}
+            if params.get("name") not in names:
+                return _error(request_id, -32602, f"no tool called {params.get('name')!r}")
+            call = asyncio.ensure_future(registration.call(params["name"], params.get("arguments") or {}))
+            registration.calls.add(call)
+            try:
+                text = await call
+            except asyncio.CancelledError:
+                if registration.secret in self.sessions:
+                    raise  # the request itself was cancelled
+                return _error(request_id, -32603, "the session ended")
+            except Exception:
+                log.exception("tool %s failed", params["name"])
+                return _error(request_id, -32603, "internal error")
+            finally:
+                registration.calls.discard(call)
+            result = {"content": [{"type": "text", "text": text}]}
+        elif method in ("ping", "server/discover"):
+            result = {}
+        else:
+            return _error(request_id, -32601, f"method {method!r} isn't supported")
+        return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error(request_id, code: int, message: str) -> dict:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}