stcode 0.0.1a0__py3-none-any.whl

stcode/core/agent/events.py

@@ -0,0 +1,97 @@
+"""
+Agent events — what a caller sees while a turn runs.
+
+Deliberately *not* a re-wrapping of the provider's stream: `TextDelta` and
+`ReasoningDelta` are re-exported from `core/providers/types.py` unchanged, since a
+parallel `AgentTextDelta` would be a translation layer whose only job is staying in sync.
+
+What the agent adds is the four events a provider has no concept of — a tool starting,
+a tool finishing, a turn ending, the agent giving up. `daemon/protocol.py` maps them
+one-to-one onto the wire, which is why they carry primitives: a `ToolResult` with a 4 MB
+payload does not belong on a socket, so `ToolFinished` carries a preview.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+from pydantic import BaseModel, Field
+
+from stcode.core.providers.types import ReasoningDelta, TextDelta, Usage
+
+PREVIEW_CHARS = 240
+"""How much of a tool result rides on `ToolFinished`. The full result is in the
+session; `todo_write` also sends its complete result so clients can display the plan."""
+
+
+class ToolStarted(BaseModel):
+    """A tool call was accepted and is running."""
+
+    type: str = "tool_started"
+    id: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolFinished(BaseModel):
+    """A tool call returned. `ok` is False for a tool-level failure — a normal outcome
+    the model reacts to, not an error in the loop."""
+
+    type: str = "tool_finished"
+    id: str
+    name: str
+    ok: bool = True
+    preview: str = ""
+
+
+class SupervisorNudge(BaseModel):
+    """The supervisor spotted a loop and said something.
+
+    An event so a client can show it: the agent is about to change direction and the
+    reason should not be invisible. The nudge reaches the *model* as a `supervisor`
+    record in the session, not through this.
+    """
+
+    type: str = "supervisor"
+    text: str
+    symptom: str = ""
+
+
+class TurnFinished(BaseModel):
+    """The model replied without calling a tool — the only stop condition.
+
+    Not an `answer` dict, not a `ready` flag: models already end a turn by talking.
+    `text` is the assistant's final message.
+    """
+
+    type: str = "turn_finished"
+    text: str = ""
+    usage: Usage = Field(default_factory=Usage)
+    tool_calls: int = 0
+
+
+class AgentFailed(BaseModel):
+    """The turn ended without an answer: the tool-call ceiling, a provider error, or an
+    interrupt. Terminal for this turn only; the agent stays usable."""
+
+    type: str = "agent_failed"
+    message: str
+    recoverable: bool = True
+
+
+AgentEvent = Union[
+    TextDelta, ReasoningDelta, ToolStarted, ToolFinished, SupervisorNudge, TurnFinished, AgentFailed
+]
+
+__all__ = [
+    "PREVIEW_CHARS",
+    "AgentEvent",
+    "AgentFailed",
+    "ReasoningDelta",
+    "SupervisorNudge",
+    "TextDelta",
+    "ToolFinished",
+    "ToolStarted",
+    "TurnFinished",
+    "Usage",
+]

stcode/core/agent/supervisor.py

@@ -0,0 +1,226 @@
+"""
+Supervisor — a second pair of eyes on the trajectory.
+
+The session file is already the trajectory, so this is just a reader.
+
+**Counting first, model second.** Four plain-Python heuristics run at zero token cost;
+only a hit costs one `difficulty="low"` call, and that model may answer NONE. Always on,
+usually free.
+
+Three rules:
+
+* Nudges go into `messages`, never the system prompt — editing the cached prefix would
+  cost a full cache miss per piece of advice.
+* The supervisor has no tools. One that could write is a second agent.
+* It checks *inside* a turn, because that is where a loop happens.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from contextlib import aclosing
+from typing import Any, Sequence
+
+from stcode.core.providers.gateway import Difficulty, LLMGateway
+from stcode.core.providers.types import Message, TextDelta
+
+DEFAULT_EVERY = 8
+"""Iterations between checks. Low enough to catch a loop before it burns the turn's
+budget, high enough not to interrupt a productive stretch."""
+
+DEFAULT_WINDOW = 80
+"""Records the heuristics look at. At ~4 records per iteration (assistant, tool_call,
+tool_result, usage), 80 records represents ~20 iterations — sufficient to observe patterns
+across multiple checks."""
+
+REPEAT_THRESHOLD = 3
+ERROR_RATE_THRESHOLD = 0.5
+SAME_FILE_THRESHOLD = 4
+IDLE_CALLS_THRESHOLD = 8
+"""Calls with no file written before "lots of looking, no doing" counts. High on
+purpose: research legitimately writes nothing, and a supervisor that fires on reading is
+one you switch off."""
+
+WRITING_TOOLS = frozenset({"write", "edit"})
+
+NO_NUDGE = "NONE"
+
+SYSTEM = """\
+You are watching another agent work, and you can see the last few minutes of what it \
+did. Your only question: is it making progress, or is it stuck in a loop?
+
+Reply with exactly the word NONE if it is working normally. Trying something twice, \
+reading before editing, and a failed command followed by a fixed one are all normal.
+
+Otherwise reply with one or two sentences, addressed to the agent, that name what it \
+keeps doing and what to do instead. Be concrete — name the file, the command, or the \
+assumption you think is wrong. No preamble, no praise, no questions."""
+
+
+class Supervisor:
+    """Watches a session and, rarely, says something."""
+
+    def __init__(
+        self,
+        gateway: LLMGateway,
+        *,
+        every: int = DEFAULT_EVERY,
+        window: int = DEFAULT_WINDOW,
+        difficulty: Difficulty = "low",
+    ) -> None:
+        self.gateway = gateway
+        self.every = every
+        self.window = window
+        self.difficulty = difficulty
+        self._last_nudge = ""
+        """The previous nudge. Repeating it is itself a loop, and an agent that ignored
+        the advice once will ignore the repeat."""
+
+    async def check(self, records: Sequence[dict[str, Any]]) -> str | None:
+        """A nudge for the agent, or None. Costs nothing unless a heuristic fires."""
+        recent = list(records)[-self.window :]
+        symptom = self.smell(recent)
+        if symptom is None:
+            return None
+        nudge = await self.diagnose(recent, symptom)
+        if nudge is None or nudge == self._last_nudge:
+            return None
+        self._last_nudge = nudge
+        return nudge
+
+    def due(self, iteration: int) -> bool:
+        """Whether this iteration is a checkpoint. Never the first — no trajectory yet."""
+        return iteration > 0 and iteration % self.every == 0
+
+    # ---- the free half ----
+
+    @staticmethod
+    def smell(records: Sequence[dict[str, Any]]) -> str | None:
+        """Four countable signs of being stuck. No model, no tokens.
+
+        Returns the symptom in plain words: that sentence is what the diagnosis call is
+        given to explain, and a boolean would tell the cheap model nothing.
+        """
+        calls = [r for r in records if r.get("type") == "tool_call"]
+        results = [r for r in records if r.get("type") == "tool_result"]
+
+        repeated = _most_repeated(calls)
+        if repeated and repeated[1] >= REPEAT_THRESHOLD:
+            return f"it called `{repeated[0]}` with identical arguments {repeated[1]} times"
+
+        if len(results) >= 4:
+            failures = sum(1 for r in results if r.get("is_error"))
+            if failures / len(results) > ERROR_RATE_THRESHOLD:
+                return f"{failures} of its last {len(results)} tool calls failed"
+
+        edited = _most_edited(calls)
+        if edited and edited[1] >= SAME_FILE_THRESHOLD:
+            return f"it has written to {edited[0]} {edited[1]} times"
+
+        if len(calls) >= IDLE_CALLS_THRESHOLD and not any(
+            call.get("name") in WRITING_TOOLS for call in calls
+        ):
+            return f"{len(calls)} tool calls in a row without writing a single file"
+
+        return None
+
+    # ---- the cheap half ----
+
+    async def diagnose(self, records: Sequence[dict[str, Any]], symptom: str) -> str | None:
+        """Ask a small model whether the symptom is really stagnation.
+
+        A veto, not a rubber stamp: NONE means a false alarm, which it usually is. A
+        failure returns None — a broken supervisor must never be able to end a turn.
+        """
+        prompt = (
+            f"What the counters noticed: {symptom}.\n\n"
+            f"What the agent has been doing:\n{render_trajectory(records)}\n\n"
+            "Is it stuck? Reply NONE, or one or two sentences of redirection."
+        )
+        try:
+            reply = ""
+            # `aclosing` as everywhere else: an abandoned provider stream stays
+            # suspended holding a connection, possibly past the event loop's close.
+            async with aclosing(
+                self.gateway.stream(
+                    [Message(role="user", content=prompt)],
+                    system=SYSTEM,
+                    difficulty=self.difficulty,
+                )
+            ) as stream:
+                async for event in stream:
+                    if isinstance(event, TextDelta):
+                        reply += event.text
+        except Exception:  # noqa: BLE001 — advice is optional; the turn is not
+            return None
+
+        answer = reply.strip()
+        if not answer or answer.upper().startswith(NO_NUDGE):
+            return None
+        return answer
+
+
+def render_trajectory(records: Sequence[dict[str, Any]]) -> str:
+    """The recent trajectory as a few short lines.
+
+    Deliberately lossy: the supervisor looks for a *shape*, and sending whole file
+    contents would cost more than the loop it is trying to prevent.
+    """
+    lines: list[str] = []
+    for record in records:
+        kind = record.get("type")
+        if kind == "tool_call":
+            lines.append(f"call {record.get('name')}({_short(record.get('arguments'))})")
+        elif kind == "tool_result":
+            mark = "ERROR" if record.get("is_error") else "ok"
+            lines.append(f"  -> {mark}: {_short(record.get('content'), 120)}")
+        elif kind == "assistant" and record.get("content"):
+            lines.append(f"said: {_short(record.get('content'), 160)}")
+        elif kind == "user":
+            lines.append(f"user: {_short(record.get('content'), 160)}")
+    return "\n".join(lines)
+
+
+def _short(value: Any, limit: int = 100) -> str:
+    text = json.dumps(value, default=str) if isinstance(value, (dict, list)) else str(value or "")
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def _signature(call: dict[str, Any]) -> str:
+    return json.dumps(
+        [call.get("name"), call.get("arguments")], sort_keys=True, default=str
+    )
+
+
+def _most_repeated(calls: Sequence[dict[str, Any]]) -> tuple[str, int] | None:
+    """The most-repeated (tool, arguments) pair, by tool name."""
+    if not calls:
+        return None
+    counts = Counter(_signature(call) for call in calls)
+    signature, count = counts.most_common(1)[0]
+    name = json.loads(signature)[0]
+    return (str(name), count)
+
+
+def _most_edited(calls: Sequence[dict[str, Any]]) -> tuple[str, int] | None:
+    """The file written to most often in the window."""
+    paths = Counter(
+        str((call.get("arguments") or {}).get("path", ""))
+        for call in calls
+        if call.get("name") in WRITING_TOOLS
+    )
+    paths.pop("", None)
+    if not paths:
+        return None
+    path, count = paths.most_common(1)[0]
+    return (path, count)
+
+
+__all__ = [
+    "DEFAULT_EVERY",
+    "DEFAULT_WINDOW",
+    "Supervisor",
+    "render_trajectory",
+]

stcode/core/agent/task.py

@@ -0,0 +1,120 @@
+"""
+`task` — a sub-agent as a tool. Solo mode only.
+
+Here rather than in `core/harness/tools/` because of the dependency arrow: this spawns
+an `Agent`, and a tool inside the harness that did so would point it at its own caller.
+
+**The docstring does two jobs.** No model is trained on this scaffold, so expect `task`
+to be under-used; and a vaguely-described sub-agent is the top cause of duplicated,
+off-target work. So it argues for delegation *and* forces an output format and a scope.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Any
+
+from pydantic import Field
+
+from stcode.core.agent.events import AgentFailed, TurnFinished
+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.providers.gateway import Difficulty
+
+if TYPE_CHECKING:  # pragma: no cover
+    from stcode.core.agent.agent import Agent
+
+MAX_DEPTH = 1
+"""Rule 3. A sub-agent gets neither `task` nor `repl`, so this is belt and
+braces — but recursion plus no budget is a fork bomb, and the cheap check is worth it."""
+
+
+def make_task_tool(parent: "Agent") -> Tool[Any]:
+    """Build the `task` tool bound to `parent`, the agent that spawns from it."""
+
+    @tool(permission=ToolPermission.EXECUTE, timeout=None)
+    async def task(
+        prompt: str,
+        name: str,
+        tools: list[str] | None = None,
+        scope: str | None = None,
+        difficulty: Annotated[Difficulty, Field()] = "medium",
+        runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+    ) -> str:
+        """Hand a bounded piece of work to a sub-agent with its own context.
+
+        Use this whenever answering something would cost you many file reads. The
+        sub-agent reads the twenty files and you get back the paragraph — its tool
+        output never enters your context, only its final message does. If you are about
+        to read more than two or three files to answer one question, delegate instead.
+
+        Not for small things. Spawning costs a full agent's startup, so a question a
+        single `grep` answers is cheaper to answer yourself.
+
+        Write the prompt as a briefing, not a title. It gets no follow-up question and
+        cannot see your conversation, so it must contain:
+
+        - what to do, concretely;
+        - **the output format you want back** — "a table of file:line and the handler
+          name", "three sentences on whether X is safe" — because a sub-agent told only
+          the topic returns a transcript;
+        - what not to touch.
+
+        Run several at once by calling this multiple times in the same turn; they
+        execute in parallel. Give any two that write files **disjoint** `scope`s — two
+        agents that can write the same file is a design error, not a race to manage.
+
+        Args:
+            prompt: The full briefing, including the output format you expect back.
+            name: Short identifier for this sub-agent, e.g. "api-scout". Appears in the
+                trajectory and in its own session file.
+            tools: Tool names it may use. Omit for the standard set; narrow it to
+                ["read", "grep", "glob"] for anything that should only investigate.
+            scope: Directory it may write inside, e.g. "src/api". Omit for read-only
+                work. Two writers must never be given overlapping scopes.
+            difficulty: Model tier. Use "low" for mechanical search and summarising,
+                "high" only for work that needs real reasoning.
+        """
+        from stcode.core.agent.agent import Agent
+
+        if runtime.depth >= MAX_DEPTH:
+            raise ToolError(
+                "Sub-agents cannot spawn sub-agents. Do this one yourself, or report "
+                "back to your parent that it needs splitting."
+            )
+
+        child_harness = parent.harness.for_subagent(name, tools=tools, scope=scope)
+        child_session = parent.session.child(name)
+        child_harness.session_id = child_session.id
+
+        child = Agent(
+            gateway=parent.gateway,  # shared: closing it would kill the parent's stream
+            harness=child_harness,
+            session=child_session,
+            difficulty=difficulty,
+            max_turns=parent.max_turns,
+        )
+        async with child:
+            await runtime.progress(f"{name}: {prompt.splitlines()[0][:80]}")
+            # Every event the child produces goes out to whoever is watching, tagged
+            # with this sub-agent's name. Out the side rather than into the parent's
+            # stream: the parent's events are its turn, each with a record behind it,
+            # and the child's belong to the child's transcript.
+            answer = ""
+            async for event in child.run(prompt):
+                runtime.emit(name, event)
+                if isinstance(event, TurnFinished):
+                    answer = event.text
+                elif isinstance(event, AgentFailed):
+                    # As an error, not as text. A sub-agent that never reached the model
+                    # returns a sentence beginning "the sub-agent did not finish", and a
+                    # parent handed that as a *successful* result reads it as findings
+                    # and writes them up — which is how five failed scouts become a
+                    # confident report about five repositories nobody looked at.
+                    raise ToolError(f"{name} did not finish: {event.message}")
+            return answer
+
+    return task
+
+
+__all__ = ["MAX_DEPTH", "make_task_tool"]

stcode/core/common/__init__.py

@@ -0,0 +1,21 @@
+"""
+Common — vocabulary shared across `core/` subpackages, importing from none of them.
+
+Must stay a leaf. Two tests decide whether something belongs here: it is needed by more
+than one subpackage, *and* its logic is not really about any one of them. A type with a
+single consumer belongs in that consumer — `OutputStore` lived here until it turned out
+only `core/harness/` ever held one.
+"""
+
+from stcode.core.common.ids import new_id
+from stcode.core.common.tools import ToolDefinition, ToolResult
+from stcode.core.common.truncate import DEFAULT_VIEW_LIMIT, NARROW_REQUEST_HINT, elide
+
+__all__ = [
+    "DEFAULT_VIEW_LIMIT",
+    "NARROW_REQUEST_HINT",
+    "ToolDefinition",
+    "ToolResult",
+    "elide",
+    "new_id",
+]

stcode/core/common/compat.py

@@ -0,0 +1,27 @@
+"""
+Compat — the two standard-library names stcode uses that Python 3.10 lacks.
+
+Both arrived in 3.11. Everything else in the codebase already runs on 3.10, so these
+two are the entire cost of supporting it; import them from here, never from the
+standard library directly.
+"""
+
+from __future__ import annotations
+
+import sys
+from enum import Enum
+
+if sys.version_info >= (3, 11):
+    import tomllib
+    from enum import StrEnum
+else:  # pragma: no cover - exercised by the 3.10 CI job
+    import tomli as tomllib
+
+    class StrEnum(str, Enum):
+        """`enum.StrEnum` for 3.10: members are strings and print as their value."""
+
+        def __str__(self) -> str:
+            return str(self.value)
+
+
+__all__ = ["StrEnum", "tomllib"]

stcode/core/common/ids.py

@@ -0,0 +1,43 @@
+"""
+Ids — one generator, for everything that needs a name that sorts by when it was made.
+
+A session file, a team message, anything later. It lived in `core/session/` while
+sessions were the only caller, and `core/team/mailbox.py` reached across for it with a
+function-level import to avoid the dependency. Two callers with nothing else in common
+is the definition of `core/common/`.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_last_id: tuple[int, int] = (0, 0)
+
+
+def new_id() -> str:
+    """A monotonic ULID: 48 bits of ms timestamp, 80 bits of randomness, base32.
+
+    Sortable by creation time as a plain string — the whole reason not to use `uuid4`.
+    `Session.list()` is then a directory listing needing no index and no metadata read,
+    and an inbox drains oldest-first for free.
+
+    Monotonic because "same millisecond" is not hypothetical: spawning three sub-agents
+    in one turn does it, and random suffixes would order them arbitrarily. Within a
+    millisecond the randomness increments, which also covers NTP stepping the clock back.
+    """
+    global _last_id
+    stamp = int(time.time() * 1000)
+    last_stamp, last_random = _last_id
+    if stamp > last_stamp:
+        _last_id = (stamp, secrets.randbits(80))
+    else:
+        _last_id = (last_stamp, last_random + 1)
+    stamp, randomness = _last_id
+    value = (stamp << 80) | (randomness & ((1 << 80) - 1))
+    return "".join(_CROCKFORD[(value >> shift) & 0x1F] for shift in range(125, -1, -5))
+
+
+__all__ = ["new_id"]

stcode/core/common/tools.py

@@ -0,0 +1,50 @@
+"""
+Tool vocabulary shared by the layers that build tools and the layers that ship them.
+
+`core/common/` imports nothing else in `core/`, which is where a type with three
+consumers belongs: `core/harness/` builds `ToolDefinition`s from signatures,
+`core/agent/` selects which a turn advertises, `core/providers/` puts them on the wire.
+
+`ToolResult` travels the other way, and is deliberately *not* `ToolResultBlock`: a block
+is the wire shape, a result is what the tool produced — a rendered view for the model,
+the untruncated payload for `tool_out`, and metadata for the trajectory. The agent loop
+narrows one into the other.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolDefinition(BaseModel):
+    """A tool as the model sees it: a name, the prompt that teaches it, and a JSON
+    Schema for the arguments.
+
+    Keep `input_schema` byte-stable across turns — tool definitions sit in the cached
+    prefix alongside the system prompt, which is the biggest cost lever there is.
+    """
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+
+
+class ToolResult(BaseModel):
+    """What one tool invocation produced.
+
+    `content` is the only field reaching the model, already rendered and already capped.
+    `payload` is the same information untruncated, bound for `tool_out[output_id]` so
+    the agent can slice it later — dropping it turns an elision into a deletion.
+    """
+
+    content: str
+    is_error: bool = False
+    payload: Any = None
+    output_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def error(cls, message: str, **metadata: Any) -> "ToolResult":
+        return cls(content=message, is_error=True, metadata=metadata)