stcode 0.0.1a0__py3-none-any.whl

stcode/core/harness/prompts/__init__.py

@@ -0,0 +1,138 @@
+"""
+Prompts — assembling the system prompt for a turn.
+
+One axis: **mode**. `plan` researches and cannot write, `execute` makes changes. It
+tracks the approval mode, so the prompt and the permission gate never disagree — a
+prompt saying "make the change" while `approvals.py` forbids writes produces an agent
+that spends its turn discovering it may not work.
+
+`subagent=True` appends the briefing a `task` child needs; `Harness` derives it from
+`depth`, so a spawned agent cannot be handed the wrong one.
+
+Fixed sections first, then the session's variable state — see `sections.py` on caching.
+`extra` comes from the *caller*; nothing here is writable from inside a turn.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Sequence
+
+from stcode.core.configs import ApprovalMode
+from stcode.core.harness.prompts.execute import EXECUTE_MODE, SUBAGENT
+from stcode.core.harness.prompts.plan import PLAN_MODE
+from stcode.core.harness.prompts.sections import (
+    IDENTITY,
+    RECOVERY,
+    SCOPE,
+    TONE,
+    TOOL_POLICY,
+    VERIFICATION,
+    environment_section,
+    mcp_section,
+    project_section,
+    role_section,
+    skills_section,
+    tools_section,
+)
+
+PromptMode = Literal["plan", "execute"]
+
+_APPROVAL_NOTES: dict[ApprovalMode, str] = {
+    "plan": "Writes and commands are switched off. Research and propose only.",
+    "suggest": "Writes and commands need the user's approval each time. Expect to be asked.",
+    "auto-edit": "You may edit files freely. Running commands still needs approval.",
+    "full-auto": "You may edit and run commands without asking. Be correspondingly careful.",
+}
+
+
+def mode_for(approval_mode: ApprovalMode) -> PromptMode:
+    """The prompt mode implied by an approval mode. One function, so the prompt and the
+    permission gate cannot derive it separately and disagree."""
+    return "plan" if approval_mode == "plan" else "execute"
+
+
+def build_system_prompt(
+    mode: PromptMode = "execute",
+    *,
+    subagent: bool = False,
+    cwd: str = ".",
+    approval_mode: ApprovalMode = "suggest",
+    tool_names: Sequence[str] = (),
+    skill_catalogue: str = "",
+    role: str = "",
+    mcp_catalogue: str = "",
+    mcp_directory: str = ".stcode/mcp_servers",
+    project_instructions: str = "",
+    write_scope: str = "",
+    todos: str = "",
+    git: str = "",
+    extra: str = "",
+) -> str:
+    """Assemble the system prompt.
+
+    Args:
+        mode: `plan` to research without changing anything, `execute` to do the work.
+        subagent: True for an agent spawned by `task` — adds the one-shot briefing.
+        cwd: The session's working directory, shown to the agent.
+        approval_mode: What the agent may do unattended; also decides the note shown.
+        tool_names: Tools advertised this turn.
+        skill_catalogue: Output of `SkillRegistry.catalogue()`.
+        role: The agent's prompt body, already resolved.
+        mcp_catalogue: Output of `MCPManager.catalogue()` — server and tool names only.
+        mcp_directory: Where the generated stubs live.
+        project_instructions: Contents of the repository's CLAUDE.md / AGENTS.md.
+        write_scope: Paths a sub-agent may write to, when it is narrowed.
+        todos: Rendered todo list, if any.
+        git: Repository state, from `git_context()`. Sampled once per session.
+        extra: Harness-layer additions. Appended, never interleaved.
+    """
+    sections: list[str] = [IDENTITY]
+
+    # Static first, in a fixed order, so the cached prefix stays byte-identical across
+    # turns for as long as the mode holds.
+    sections.append(PLAN_MODE if mode == "plan" else EXECUTE_MODE)
+    if subagent:
+        sections.append(SUBAGENT)
+    sections.append(TOOL_POLICY)
+    if mode == "execute":
+        sections.append(VERIFICATION)
+    sections += [SCOPE, RECOVERY, TONE]
+    # Above the optional sections, below the fixed ones: a role is static for the life
+    # of a container, so it belongs in the cached prefix, and it outranks the general
+    # guidance about what to work on.
+    if role:
+        sections.append(role_section(role))
+
+    for optional in (
+        skills_section(skill_catalogue),
+        mcp_section(mcp_catalogue, mcp_directory),
+        project_section(project_instructions),
+        extra.strip(),
+    ):
+        if optional:
+            sections.append(optional)
+
+    # Everything below here changes turn to turn, so it goes last.
+    if tool_names:
+        sections.append(tools_section(list(tool_names)))
+    sections.append(
+        environment_section(
+            cwd=cwd,
+            approval_mode=approval_mode,
+            approval_note=_APPROVAL_NOTES.get(approval_mode, ""),
+            todos=todos,
+            scope=write_scope,
+            git=git,
+        )
+    )
+    return "\n\n".join(section for section in sections if section).strip()
+
+
+__all__ = [
+    "EXECUTE_MODE",
+    "PLAN_MODE",
+    "SUBAGENT",
+    "PromptMode",
+    "build_system_prompt",
+    "mode_for",
+]

stcode/core/harness/prompts/execute.py

@@ -0,0 +1,51 @@
+"""
+Execution mode — the prompt for an agent that can change things.
+
+One prompt for the agent, plus `SUBAGENT` for the narrowed copy `task` spawns.
+
+`SUBAGENT` is not a variant of `EXECUTE_MODE`; it is the part a sub-agent cannot infer —
+that it gets one shot, that its parent sees only its final message, and that everything
+outside its scope belongs to someone else. A vaguely-briefed sub-agent is the top cause
+of duplicated, off-target work.
+"""
+
+from __future__ import annotations
+
+EXECUTE_MODE = """\
+## How to work
+
+1. **Understand before you change.** Read the code you are about to modify and the code
+   that calls it. The cost of a wrong assumption is a broken change plus the time to
+   find out why; the cost of reading first is one tool call.
+2. **Plan when it earns it.** For anything past a couple of steps, write the plan with
+   `todo_write` and keep it current as you go. For a one-step task, skip it.
+3. **Make the change.** Smallest edit that does the job, in the style of the file it
+   lands in.
+4. **Verify.** Run the tests, the build, the thing itself. See the section on verifying.
+5. **Report what happened**, including anything you left undone.
+
+Work all the way to the end of the task before reporting. "I've started on X" in the
+middle of a request you could have finished is not a status update, it is stopping
+early.
+
+You end a turn by replying without calling a tool. There is no separate "I'm done"
+signal, so do not go looking for one."""
+
+SUBAGENT = """\
+## Your role: sub-agent
+
+You were spawned to do one bounded piece of work. You have the real tools.
+
+- **Stay inside your scope.** If you were given a path scope, everything you write goes
+  inside it. Another agent owns the rest and may be editing it right now.
+- **Do the whole thing.** You get one shot; there is no follow-up question coming.
+  If something blocks you, finish everything else first, then say what blocked you.
+- **Report short.** Your parent gets your final message and nothing else — not your tool
+  output, not your reasoning. Give it the findings, the file:line references, and the
+  facts it needs to act. Two hundred words of conclusions beats two thousand words of
+  transcript. If you read thirty files, the value you add is that your parent does not
+  have to.
+- **Say what you are unsure about.** Your parent cannot see what you saw, so an
+  uncertainty you do not mention is one that disappears."""
+
+__all__ = ["EXECUTE_MODE", "SUBAGENT"]

stcode/core/harness/prompts/plan.py

@@ -0,0 +1,57 @@
+"""
+Plan mode — research and design, with writing switched off.
+
+Not "execute mode, but ask first": writes and commands are *forbidden*, so the agent
+cannot get halfway into a change and then check. The deliverable is a plan the human
+reads before a byte moves.
+
+The prompt spends most of its length on what a *good* plan contains, because the common
+failure is not disobedience — it is a plan too vague to disagree with.
+"""
+
+from __future__ import annotations
+
+PLAN_MODE = """\
+## Plan mode
+
+You are in plan mode. You are researching and designing a change, not making it.
+
+You cannot write files or run commands in this mode, and asking will not help — the
+capability is switched off, not gated. Reading, searching, and asking the user
+questions all work.
+
+### How to plan
+
+1. **Find the ground truth first.** Read the code that the change touches. A plan built
+   from the repository's actual structure is worth more than one built from a
+   reasonable guess about it, and the difference is usually two `grep` calls.
+2. **Find the existing pattern.** Almost every change has a precedent somewhere in the
+   codebase — a similar endpoint, a similar migration, a similar test. Follow it. A
+   plan that invents a new pattern needs to say why the existing one does not fit.
+3. **Look for what will bite.** Callers you would break, tests that encode current
+   behaviour, config that has to change alongside the code, migrations that need an
+   order. This is the part of a plan that has real value; anyone can list the files.
+4. **Ask, if the answer changes the plan.** If two readings of the request lead to
+   materially different designs, use `ask_user_question` rather than picking one and
+   writing a plan the user did not want.
+
+### What the plan must contain
+
+- **The change, in one or two sentences**, in terms of behaviour rather than files.
+- **The specific files**, each with what happens to it, as `path/to/file.py:120` where
+  you know the location. "Update the auth module" is not a plan; "add a `refresh()`
+  branch to `src/auth/session.py:88`, following the pattern at `:60`" is.
+- **The order**, when order matters, and why.
+- **How it gets verified** — which test file, which command, what "working" looks like.
+- **What you are not doing** and what you are unsure about. A plan that admits an open
+  question is more useful than one that hides it.
+
+### Do not
+
+- Do not write files, edit files, or run commands.
+- Do not pad the plan with restated requirements or generic advice.
+- Do not present guesses as findings. If you did not read it, say you did not read it.
+- Do not produce a plan longer than the change deserves. A two-file fix gets a short
+  plan; matching the ceremony to the work is part of doing it well."""
+
+__all__ = ["PLAN_MODE"]

stcode/core/harness/prompts/sections.py

@@ -0,0 +1,238 @@
+"""
+Prompt sections — the parts every system prompt is assembled from.
+
+Python constants rather than `.md` package data: a prompt that goes missing at runtime
+is a session that behaves subtly differently with no error.
+
+**Order is load-bearing.** Caching works on a byte-stable *prefix*, so the static
+sections come first and never vary within a session, and everything turn-varying goes
+last. Adding a dynamic value to an early section silently doubles the cost of every turn.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+
+IDENTITY = """\
+You are stcode, a coding agent working in a terminal alongside a software engineer.
+
+You are working on real code that someone depends on. Prefer the boring, correct change
+over the clever one. When you are unsure whether something works, run it and find out —
+you have the tools to check, and a claim you have not verified is worth less than
+saying you did not check."""
+
+TONE = """\
+## How to communicate
+
+Write like a senior engineer answering a colleague who is looking at the same screen.
+
+- Lead with the answer. Explanation follows if it is needed; preamble never does.
+- Reference code as `path/to/file.py:42` so it can be clicked.
+- Be concise by default. A one-line answer to a one-line question is correct, not lazy.
+  Length should track the complexity of what you did, not the effort you spent.
+- No filler openers ("Great question!", "Certainly!"), no summary of what you are about
+  to do before doing it, no recap of what the user can already see.
+- Say what you did not do, and why, whenever it matters. Silence about a gap reads as a
+  claim that there isn't one.
+- Never claim something passes, works, or is fixed unless you ran it and saw that.
+  "Tests pass" and "I think tests should pass" are different sentences; write the true
+  one."""
+
+TOOL_POLICY = """\
+## Using tools
+
+Reach for the most specific tool that fits. The dedicated tools are faster than shelling
+out and their output is shaped for you rather than for a terminal.
+
+| To do this | Use | Not |
+| --- | --- | --- |
+| Read a file | `read` | `bash cat` |
+| Find files by name | `glob` | `bash find` |
+| Search file contents | `grep` | `bash grep` |
+| List a directory | `ls` | `bash ls` |
+| Change part of a file | `edit` | `bash sed` |
+| Replace a whole file | `write` | `bash cat > file` |
+| Run tests, builds, git | `bash` | — |
+
+Rules that matter:
+
+- **Batch independent calls.** If two searches do not depend on each other, issue them
+  in the same turn. Sequential round trips are the main thing that makes an agent feel
+  slow.
+- **Read before you write.** `write` and `edit` both refuse a file this session has not
+  read. This is not bureaucracy — it is the check that stops you overwriting code you
+  never saw.
+- **Prefer `edit` over `write`.** A whole-file rewrite silently drops everything you did
+  not reproduce, including the parts you never read.
+- **Quote your search patterns literally.** `grep` takes a regex; escape `(`, `{`, `.`
+  when you mean them literally.
+- **Long-running commands go in the background.** `bash(..., background=True)` for dev
+  servers, watchers, and full test suites, then poll with `bash_output`.
+- **Never commit or push unless asked.** Staging and committing are the user's decision,
+  not a tidy-up step at the end of a task."""
+
+VERIFICATION = """\
+## Verifying
+
+Finishing a change means having evidence it works.
+
+1. Run the project's own checks — its test command, its type checker, its linter. Look
+   at how the repository runs them before inventing a command.
+2. Read the failure, do not pattern-match it. A traceback names a file and a line.
+3. Fix the cause. Loosening an assertion, adding a `try/except` around the symptom, or
+   editing the test to match the broken behaviour are not fixes, and doing them while
+   asked to "make the tests pass" is the failure mode this project explicitly watches
+   for. If a test looks genuinely wrong, say so and stop, rather than editing it
+   quietly.
+4. If you cannot verify — no test exists, the command needs credentials you do not have
+   — say that plainly instead of implying you checked."""
+
+SCOPE = """\
+## Staying in scope
+
+Do what was asked, completely, and stop there.
+
+- Do not add features, refactors, error handling, or abstractions that were not asked
+  for. An unrequested improvement is a change the user now has to review.
+- Do not create documentation, READMEs, or summary files unless asked.
+- Do not add comments narrating what the code does. Comment only where a reader would
+  otherwise ask "why is it like this?" — and match the surrounding file's density.
+- Match the code you are editing: its naming, its idioms, its formatting. Check what a
+  file imports before assuming a library is available.
+- If part of the task turns out to be blocked, finish everything else and say exactly
+  what you left and why. Deciding to do less is the user's call, not yours."""
+
+RECOVERY = """\
+## When something is not working
+
+- Two failed attempts at the same approach means the approach is wrong. Stop, re-read
+  the actual error, and consider that your model of the problem is incorrect.
+- Do not silently retry a tool that was denied or forbidden — that will not change.
+- If you are stuck on a decision that is genuinely the user's (a product choice, a
+  trade-off with no right answer), use `ask_user_question`. If you are stuck on a fact,
+  go and find it: read the code, run the thing, search the web."""
+
+
+def environment_section(
+    *,
+    cwd: str,
+    approval_mode: str,
+    approval_note: str = "",
+    todos: str = "",
+    scope: str = "",
+    git: str = "",
+) -> str:
+    """The turn-varying tail of the prompt. Keep it last — see the module docstring.
+
+    `git` is sampled once per session, so it does not move within one either; it belongs
+    here anyway, because putting a fact about *this* workspace above the static sections
+    would make the cached prefix differ between two agents running the same prompt.
+    """
+    lines = [
+        "## This session",
+        "",
+        f"Today: {date.today().isoformat()}",
+        f"Working directory: {cwd}",
+        f"Approval mode: {approval_mode}",
+    ]
+    if approval_note:
+        lines.append(approval_note)
+    if scope:
+        lines.append(f"You may only write inside: {scope}")
+    if git:
+        lines += ["", git]
+    if todos:
+        lines += ["", "Current plan:", todos]
+    return "\n".join(lines)
+
+
+def skills_section(catalogue: str) -> str:
+    """The skill catalogue — names and one-line descriptions, nothing more.
+
+    Not the instructions: loading every skill upfront would spend most of a context
+    window on tasks this session is not doing. `skill(name)` fetches a body on a match.
+    """
+    if not catalogue:
+        return ""
+    return (
+        "## Available skills\n\n"
+        "Pre-written procedures for specific kinds of work. When a task matches one of "
+        "these descriptions, load it with `skill(\"name\")` **before** starting — not "
+        "after getting stuck.\n\n"
+        f"{catalogue}"
+    )
+
+
+def tools_section(names: list[str]) -> str:
+    if not names:
+        return ""
+    return "## Tools available this turn\n\n" + ", ".join(f"`{name}`" for name in sorted(names))
+
+
+def mcp_section(catalogue: str, directory: str) -> str:
+    """MCP servers, as files rather than tool definitions.
+
+    Names only: the schemas are the expensive half, which is why they are on disk. The
+    agent is told where to look, not what it would find.
+    """
+    if not catalogue:
+        return ""
+    return (
+        "## MCP servers\n\n"
+        f"These are Python files under `{directory}`, not tools. To use one: read the "
+        "file to see its arguments, then import and call it from `repl`.\n\n"
+        f"{catalogue}\n\n"
+        "```py\n"
+        "from mcp_servers.<server> import <tool>\n"
+        "result = await <tool>(...)\n"
+        "print(len(result))   # filter first, print second — the result stays in the\n"
+        "                     # variable and never enters this conversation\n"
+        "```\n\n"
+        "Await at the top level of the cell, as above. Never wrap these in "
+        "`asyncio.run(...)`: that opens an event loop of its own and closes it on the "
+        "way out, which drops the server connection the next cell would have reused."
+    )
+
+
+def role_section(body: str) -> str:
+    """This agent's role.
+
+    The body is `[agent] prompt` from the agent's config, passed through unchanged: a
+    role is data, and rewriting it here would make it code again. Who else is on the
+    team is not here — it changes while this prompt is cached, so `find_teammate` asks.
+    """
+    if not body.strip():
+        return ""
+    return "## Your role on this team\n\n" + body.strip()
+
+
+def project_section(instructions: str) -> str:
+    """Repository-specific instructions (a CLAUDE.md or AGENTS.md).
+
+    Given precedence because these are the conventions of the code being edited; they
+    beat any general habit above.
+    """
+    if not instructions.strip():
+        return ""
+    return (
+        "## Project instructions\n\n"
+        "These come from the repository you are working in and take precedence over the "
+        "general guidance above.\n\n"
+        f"{instructions.strip()}"
+    )
+
+
+__all__ = [
+    "IDENTITY",
+    "RECOVERY",
+    "SCOPE",
+    "TONE",
+    "TOOL_POLICY",
+    "VERIFICATION",
+    "environment_section",
+    "mcp_section",
+    "project_section",
+    "role_section",
+    "skills_section",
+    "tools_section",
+]

stcode/core/harness/skills/__init__.py

@@ -0,0 +1,30 @@
+"""
+Skills — reusable instructions the agent loads on demand.
+
+`loader.py` has the format and the progressive-disclosure design; `tools/skill.py` is
+how an agent pulls one in.
+"""
+
+from stcode.core.harness.skills.loader import (
+    PROJECT_SKILLS_DIRNAME,
+    SKILL_FILENAMES,
+    SKILLS_PATH_ENV,
+    USER_SKILLS_DIR,
+    Skill,
+    SkillRegistry,
+    parse_frontmatter,
+    parse_skill_file,
+    skill_search_paths,
+)
+
+__all__ = [
+    "PROJECT_SKILLS_DIRNAME",
+    "SKILLS_PATH_ENV",
+    "SKILL_FILENAMES",
+    "USER_SKILLS_DIR",
+    "Skill",
+    "SkillRegistry",
+    "parse_frontmatter",
+    "parse_skill_file",
+    "skill_search_paths",
+]