monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/prompts/__init__.py

@@ -0,0 +1 @@
+"""System prompt composition and harness text."""

monkeybot/core/prompts/harness_prompt.py

@@ -0,0 +1,197 @@
+"""Runtime-owned harness prompt fragment.
+
+The agent loop appends :func:`harness_fixed_context` after the operator-authored
+base prompt (AGENT.md) so tool/MCP protocol text lives in code, not in the bot file.
+"""
+
+import os
+from collections.abc import Sequence
+
+HARNESS_TOOL_CALL_PROTOCOL = """
+### Tool-call protocol (strict)
+- Invoke tools only through the provider's native function-call channel. Never emit tool invocations as JSON or pseudo-XML inside your assistant text; any such text is treated as a normal message and no tool will run.
+- After tool results are returned to you, your next response MUST be natural-language text that addresses the user's request using those results. Do not return another empty turn.
+- If you have nothing more to do, give a short final answer; do not stay silent.
+- **Evidence rule:** Never produce a substantive answer about content you were supposed to fetch but could not. If every tool path to that content failed or errored, tell the user what blocked you and what they need to supply — do not synthesize, guess, or hallucinate the missing content.
+- **Fulfillment rule:** When the user asks for a file or code change and the relevant tools are available, use them. Do not answer with only pasted code and manual save instructions."""
+
+
+_RUN_COMMAND_EXEC_NOTE_HOST = (
+    "**Execution:** on the **gateway host** under the binary/path allowlist only "
+    "(no OpenSandbox / no extra VM)."
+)
+_RUN_COMMAND_EXEC_NOTE_SANDBOX = (
+    "**Execution:** via **OpenSandbox** (Docker-backed session container). "
+    "The workspace root is bind-mounted at the **same absolute path**; still subject to the allowlist."
+)
+
+_HARNESS_BODY = """## monkeybot harness (fixed)
+
+This block is injected by the host every turn. Prefer the **active tool list** the model receives over any stale summary here.
+
+When workspace tools (`read_file`, `write_file`, `run_command`, …) appear in that list, you **have a writable workspace** — not a read-only chat window. Fulfill file and code requests with tools; do not paste full artifacts and instruct the user to save manually unless they explicitly asked to see code in chat.
+
+### Core built-in tools (when present in the active tool list)
+- `read_file` / `write_file` / `replace_in_file` / `glob` / `grep` / `apply_patch` — paths are **workspace-relative** under the workspace root below. **`glob`** lists matching files (prefer over `run_command` + `ls`). **`grep`** searches file contents with a regex (prefer over `run_command` + `grep`). **`apply_patch`** applies a multi-file Codex-style patch (Add / Update / Delete / Move) fail-closed. Do not substitute a code block in chat for a file deliverable.
+- `search_memory` — keyword search under the configured memory directory; prefer this over shell commands for any memory lookup.
+- `list_skills` — resolves the skills root path for installed skills listed under `## Skills` below; read each skill's `SKILL.md` under that root for procedure.
+- `run_command` — allowlisted shell with optional `timeout` (seconds). {run_command_exec_note} Shell starts in **workspace root**; use the paths listed under Runtime paths below — do NOT guess directory names. `cd` is a shell builtin and cannot be used as a bare command; use `bash -c "cd <dir> && <cmd>"` instead. Pass **`argv` as a list** with the binary first (e.g. `{{"argv": ["ls", "."]}}`); do not pass `{{"command": "ls -R", "args": []}}` — that treats `ls -R` as the binary name.
+- `enable_mcp` / `disable_mcp` — connect or drop a server declared in mcp.json by name (e.g. `browser`). Prefer `enable_mcp` over inventing `add_mcp_server` command/args for known servers. New tools appear on the **next model step this turn**.
+- `add_mcp_server` / `remove_mcp_server` — ad-hoc stdio MCP connect/disconnect when the server is not in mcp.json; same next-step refresh.
+- `mcp_status` — lifecycle status for catalogued/connected/failed/needs_auth/disabled servers.
+- `list_mcp_resources` / `list_mcp_resource_templates` / `read_mcp_resource` — browse and read MCP resources (server must be connected; use `enable_mcp` first when catalogued).
+- `list_mcp_prompts` / `get_mcp_prompt` — list and fetch MCP prompt templates from connected servers.
+{catalog_mcp_line}{web_search_line}{task_line}
+### Workspace deliverables
+- **New file or full rewrite** → `write_file`.
+- **Targeted change to an existing file** → `read_file` then `replace_in_file` (unique match; light fuzzy fallbacks; optional `replace_all`).
+- **Multi-file or multi-hunk edit** → `apply_patch` with a Codex-style `*** Begin Patch` … `*** End Patch` envelope (Add / Update / Delete / Move); fail-closed.
+- Tell the user the workspace-relative path when done.
+- **Do not claim** you lack filesystem access, cannot touch the user's machine, or are limited to "chat-only" output when workspace file tools are in the active tool list.
+- Chat text is for answers and brief excerpts — not a stand-in for a file the user asked you to produce.
+
+### Built-in tool errors (recovery)
+- A tool **failed** whenever its response contains `ok: false` (or `is_error`), even if the call itself "succeeded" (e.g. `run_command` returns `exit_code != 0` with an `ok:false` JSON body in `stdout`). Read the result; do not treat a non-empty response as success.
+- Failed built-in tools often return **JSON** with `ok: false`, `error_kind` (`policy` | `validation` | `runtime`), `message`, and `hint`.
+- If `error_kind` is **policy** (e.g. `run_command` blocked), **do not** retry the identical call; change the command or path per `hint` and the lists in `details`, then retry **once** after a single fix.
+- If `error_kind` is **validation**, fix the argument shape (see `details.example`), then retry once.
+- If `error_kind` is **runtime** (the command/tool ran but failed — e.g. missing config, missing env var, bad exit code, script error), **do not** re-run the identical call. The same inputs will produce the same failure. Either fix the underlying cause if you can act on it, or stop and tell the user exactly what is missing (e.g. an env var, project id, or credential) and what they must set.
+- **No-repeat rule (applies to every tool):** never issue a tool call with the same name and same arguments that already failed this turn. A retry is only allowed after you have changed the command, arguments, or path in response to the error. If you cannot change anything, stop retrying and report the blocker in plain text.
+
+### Runtime paths
+- workspace root: `{workspace_root}`
+- memory storage: `{memory_storage_uri}` — always use `search_memory` to query; only use this URI/path directly in `run_command` for low-level inspection.
+
+### MCP tools
+- Names look like `server__tool` (double underscore).
+- Heavy MCP servers are **on-demand**: call `enable_mcp("name")` before using their `server__*` tools when they are not yet in the active tool list.
+- For server-published context (not callable tools), use `list_mcp_resources` / `read_mcp_resource` and `list_mcp_prompts` / `get_mcp_prompt` after the server is connected. Check `mcp_status` when unsure.
+- MCP tool errors are returned as plain error text (not structured JSON). Any response containing an HTTP error code (4xx / 5xx), "not found", "unauthorized", "forbidden", "permission denied", or similar access/availability signals means the tool **did not return usable data**.
+- When an MCP tool fails: state what failed in one sentence, then stop — do **not** fabricate, infer, or summarize content that the tool was supposed to fetch. If a fallback tool is available and meaningfully different, try it once; otherwise tell the user what is needed to proceed (e.g. correct credentials, a public URL, pasting the content directly).
+
+### Skills
+- Installed skill names are listed under `## Skills` in this prompt. When a task matches one, use `list_skills` to get the skills root, then `read_file` on that skill's `SKILL.md` for procedure before running commands or steps it documents."""
+
+
+_TASK_LINE = (
+    "- `task` — subprocess subagent with the same workspace, memory, and MCP configuration; "
+    "pass `subagent_type` to select a named persona (see Subagent personas below). "
+    "Returns JSON (summary, errors, usage). Nested `task` is disabled inside a subagent.\n"
+)
+
+_WEB_SEARCH_LINE = (
+    "- `web_search` — search the web for current information; "
+    "returns titles, URLs, and text snippets.\n"
+)
+
+
+# Always-on terse-emission guidance (Levers 1-2 of the honey writing style).
+# Trimmed to rules + safety carve-outs; no examples (volume is cost). Lives in
+# the stable harness prefix so it caches, and never overrides the evidence or
+# no-repeat rules above. Opt-in via ``emission_style`` (env MONKEYBOT_EMISSION_STYLE).
+_EMISSION_STYLE_BLOCK = """
+### Emission style (terse)
+
+Volume is cost. Default to terse; add detail only when brevity would drop correctness.
+
+- **Code:** write the minimum that needs to exist. Prefer stdlib and installed deps over new code; edit over add; one line over a block. No speculative params, "might need it later" branches, or single-caller abstractions.
+- **Prose:** answer first. Drop wind-up, hedging, and restating the request. Use fragments/lists over paragraphs when they carry the same info. Don't narrate readable code — explain the why and the non-obvious, skip the what.
+- **Keep exact, never compress:** code blocks verbatim and runnable; identifiers, paths, commands, versions, and error messages quoted exactly.
+
+Never cut (brevity must not break correctness):
+- Input validation at trust boundaries, error handling that prevents data loss, and security/auth checks.
+- The blocker report when every tool path failed — state what failed and what's needed; do not synthesize missing content (see the evidence rule below).
+- Anything the user explicitly asked for.
+
+When editing code, keep function bodies — signatures alone are not enough to edit correctly.
+"""
+
+# Lever 3: dense agent-to-agent handoffs. Only meaningful when the `task` tool
+# is active, so the caller gates this on ``include_task_tool``.
+_EMISSION_AGENT_TO_AGENT_BLOCK = """
+### Subagent handoffs (dense)
+
+When the reader is a subagent or orchestrator (`task` results, not user-facing answers), emit the densest format the receiver parses losslessly:
+- Minified JSON, never pretty-printed.
+- Address records by stable key, not position ("the finding with id X", not "the 37th").
+- Aggregate in code; pass counts, not rows for the receiver to count. Number rows only if positional access is unavoidable.
+- For uniform record arrays, prefer columnar: keys once, then value rows.
+"""
+
+
+def emission_style_terse_from_env() -> bool:
+    """True when ``MONKEYBOT_EMISSION_STYLE`` opts into the terse emission block."""
+    raw = os.environ.get("MONKEYBOT_EMISSION_STYLE", "").strip().lower()
+    return raw in {"terse", "true", "1", "on", "yes"}
+
+
+def _emission_section(*, emission_style: bool, include_task_tool: bool) -> str:
+    """Stable-prefix emission guidance; empty unless terse style is opted in."""
+    if not emission_style:
+        return ""
+    section = _EMISSION_STYLE_BLOCK
+    if include_task_tool:
+        section += _EMISSION_AGENT_TO_AGENT_BLOCK
+    return section
+
+
+def _subagent_personas_block(personas: Sequence[tuple[str, str]]) -> str:
+    if not personas:
+        return ""
+    lines = ["\n### Subagent personas (`task` tool)", ""]
+    for name, description in personas:
+        lines.append(f"- `{name}` — {description}")
+    lines.append(
+        "Pass `subagent_type` on `task` to select a persona. Omit for the default subagent AGENT.md."
+    )
+    return "\n".join(lines) + "\n"
+
+
+def harness_fixed_context(
+    *,
+    include_task_tool: bool,
+    include_web_search: bool = False,
+    workspace_root: str = "(not set)",
+    memory_storage_uri: str = "(not set)",
+    run_command_opensandbox: bool = False,
+    subagent_personas: Sequence[tuple[str, str]] | None = None,
+    emission_style: bool = False,
+    catalog_mcp_servers: Sequence[str] | None = None,
+) -> str:
+    """Runtime-owned description of core tools, paths, MCP naming, and strict tool-call rules.
+
+    ``workspace_root`` and ``memory_storage_uri`` are injected once at
+    context-build time so the model always uses correct paths in shell commands.
+    ``include_web_search`` should be True when a web search backend is active.
+    ``run_command_opensandbox`` should match whether ``run_command`` is routed through
+    OpenSandbox (same signal as ``SandboxConfig.from_env().enabled``).
+    ``subagent_personas`` lists configured named subagent types for the parent orchestrator.
+    ``emission_style`` opts in the terse emission-guidance block (env
+    ``MONKEYBOT_EMISSION_STYLE``); the dense agent-to-agent sub-block is also gated
+    on ``include_task_tool`` so it only appears when the ``task`` tool is active.
+    ``catalog_mcp_servers`` lists mcp.json servers available via ``enable_mcp`` but not
+    connected until the model activates them.
+    """
+    exec_note = _RUN_COMMAND_EXEC_NOTE_SANDBOX if run_command_opensandbox else _RUN_COMMAND_EXEC_NOTE_HOST
+    catalog = [n.strip() for n in (catalog_mcp_servers or ()) if n and str(n).strip()]
+    if catalog:
+        names = ", ".join(f"`{n}`" for n in catalog)
+        catalog_mcp_line = (
+            f"- Configured MCP servers (call `enable_mcp` before use): {names}.\n"
+        )
+    else:
+        catalog_mcp_line = ""
+    body = _HARNESS_BODY.format(
+        run_command_exec_note=exec_note,
+        catalog_mcp_line=catalog_mcp_line,
+        web_search_line=_WEB_SEARCH_LINE if include_web_search else "",
+        task_line=_TASK_LINE if include_task_tool else "",
+        workspace_root=workspace_root,
+        memory_storage_uri=memory_storage_uri,
+    )
+    personas_block = _subagent_personas_block(subagent_personas or ())
+    emission_block = _emission_section(
+        emission_style=emission_style,
+        include_task_tool=include_task_tool,
+    )
+    return body.rstrip() + personas_block + emission_block + HARNESS_TOOL_CALL_PROTOCOL

monkeybot/core/prompts/prompt.py

@@ -0,0 +1,215 @@
+"""Compose the full system prompt: user AGENT.md plus runtime injections."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from monkeybot.core.attachments.catalog import AttachmentRecord
+from monkeybot.core.context import TurnContext
+from monkeybot.core.context.memory_prompt import MemoryPromptSelection
+from monkeybot.core.llm.provider import Message
+from monkeybot.core.prompts.harness_prompt import (
+    emission_style_terse_from_env,
+    harness_fixed_context,
+)
+from monkeybot.core.tools.sandbox_executor import SandboxConfig
+from monkeybot.core.types.content_blocks import Text
+
+# Cap injected user text so long pastes do not dominate the context window.
+_MAX_CURRENT_REQUEST_CHARS = 8000
+
+# Volatile-tail section headings, defined once here (where the sections are
+# actually composed) so callers that need to locate the stable/volatile
+# boundary in a flattened prompt string (e.g. Anthropic cache-block splitting
+# in ``providers._utils.split_system_prompt_for_cache``) import these instead
+# of re-declaring the literal strings and risking drift.
+MEMORY_INDEX_HEADING = "\n\n## Memory index\n"
+MEMORY_NUDGE_HEADING = "\n\n## Memory\n"
+SKILLS_HEADING = "\n\n## Skills\n"
+CURRENT_REQUEST_HEADING = "\n\n## Current request\n"
+# Not composed here, but part of the same volatile-tail-heading vocabulary —
+# defined alongside the others so ``providers._utils`` has one import for all.
+RUNTIME_NOTES_HEADING = "\n\n## Runtime notes\n"
+
+
+def _user_text_flat(m: Message) -> str:
+    """Concatenate Text blocks from a user turn (tool results use other block types)."""
+    return "".join(b.text for b in m.content if isinstance(b, Text))
+
+
+def _last_user_content(messages: Sequence[Message]) -> tuple[str, int] | None:
+    """Return (flattened text, index) of the last user message that carries text.
+
+    User rows that contain only tool-result blocks (no Text) are skipped so that
+    the originating user request — not the synthetic tool-response turn — is
+    used as the "Current request" anchor.
+    """
+    last: tuple[str, int] | None = None
+    for i, m in enumerate(messages):
+        if m.role == "user":
+            text = _user_text_flat(m)
+            if text:
+                last = (text, i)
+    return last
+
+
+def latest_user_message_text(messages: Sequence[Message] | None) -> str | None:
+    """Return stripped text of the last user message, or None."""
+    if not messages:
+        return None
+    last = _last_user_content(messages)
+    if last is None:
+        return None
+    t = last[0].strip()
+    return t or None
+
+
+def _current_request_block(chat_messages: Sequence[Message] | None) -> str:
+    """When the transcript continues after the user's last message, restate it in-system.
+
+    Avoids duplicating the latest user row when it is already the final message in
+    ``chat_messages`` (that row is still sent as a normal user message).
+    """
+    if not chat_messages:
+        return ""
+    last_user = _last_user_content(chat_messages)
+    if last_user is None:
+        return ""
+    text, _idx = last_user
+    if not text.strip():
+        return ""
+    last = chat_messages[-1]
+    if last.role == "user" and _user_text_flat(last).strip():
+        return ""
+    clipped = text.strip()
+    if len(clipped) > _MAX_CURRENT_REQUEST_CHARS:
+        clipped = clipped[:_MAX_CURRENT_REQUEST_CHARS].rstrip() + "\n…(truncated)"
+    return (
+        f"{CURRENT_REQUEST_HEADING}"
+        "The conversation has continued with assistant or tool messages since this "
+        "user message; treat it as the active task.\n\n"
+        f"{clipped}"
+    )
+
+
+def _session_attachments_block(catalog: Sequence[AttachmentRecord] | None) -> str:
+    if not catalog:
+        return ""
+    lines = [
+        f"- {r.attachment_id} ({r.filename}, {r.mime_type}): {r.description}"
+        for r in catalog
+    ]
+    return "\n\n## Session attachments\n" + "\n".join(lines)
+
+
+def _memory_block(
+    ctx: TurnContext,
+    memory_selection: MemoryPromptSelection | None,
+) -> str:
+    if memory_selection is not None:
+        mem_lines = list(memory_selection.lines)
+    else:
+        mem_lines = list(ctx.memory_index)
+
+    memory_bullets = "\n".join(f"- {line}" for line in mem_lines) if mem_lines else ""
+    mem_block = f"{MEMORY_INDEX_HEADING}{memory_bullets}" if memory_bullets else ""
+    if memory_selection is not None and memory_selection.nudge_search:
+        shown = len(memory_selection.lines)
+        total = memory_selection.total_lines
+        mem_block += (
+            f"{MEMORY_NUDGE_HEADING}"
+            f"Showing {shown} of {total} index entries "
+            f"(coverage {memory_selection.coverage:.0%}, confidence {memory_selection.confidence:.0%}). "
+            "Use `search_memory` with keywords when the task may depend on older or unstated context."
+        )
+    return mem_block
+
+
+def _skills_section(ctx: TurnContext) -> str:
+    skill_lines = [f"- {s.name}" for s in ctx.skills]
+    skills_block = "\n".join(skill_lines)
+    return f"{SKILLS_HEADING}{skills_block}" if skills_block else ""
+
+
+def _harness_text(ctx: TurnContext) -> str:
+    include_task = any(t.name == "task" for t in ctx.tools)
+    include_web_search = any(t.name == "web_search" for t in ctx.tools)
+    return harness_fixed_context(
+        include_task_tool=include_task,
+        include_web_search=include_web_search,
+        workspace_root=str(ctx.workspace_root) if ctx.workspace_root is not None else "(not set)",
+        memory_storage_uri=ctx.memory.uri if ctx.memory is not None else "(not set)",
+        run_command_opensandbox=SandboxConfig.from_env().enabled,
+        subagent_personas=ctx.subagent_personas,
+        emission_style=emission_style_terse_from_env(),
+        catalog_mcp_servers=ctx.catalog_mcp_servers,
+    )
+
+
+def compose_stable_baseline(
+    ctx: TurnContext,
+    *,
+    attachment_catalog: Sequence[AttachmentRecord] | None = None,
+) -> str:
+    """Cacheable prefix: AGENT.md + harness + session attachments."""
+    harness = _harness_text(ctx)
+    attachments = _session_attachments_block(attachment_catalog)
+    return f"{ctx.agent_md}\n\n{harness}{attachments}"
+
+
+def compose_volatile_tail(
+    ctx: TurnContext,
+    *,
+    chat_messages: Sequence[Message] | None = None,
+    memory_selection: MemoryPromptSelection | None = None,
+) -> str:
+    """Volatile tail: memory index + skills + current-request anchor."""
+    mem_block = _memory_block(ctx, memory_selection)
+    skills_section = _skills_section(ctx)
+    task = _current_request_block(chat_messages)
+    return f"{mem_block}{skills_section}{task}"
+
+
+def compose_volatile_tail_parts(
+    ctx: TurnContext,
+    *,
+    chat_messages: Sequence[Message] | None = None,
+    memory_selection: MemoryPromptSelection | None = None,
+) -> dict[str, str]:
+    """Same sections as :func:`compose_volatile_tail`, individually named.
+
+    Lets callers (e.g. ``ContextEpochTracker``) attribute a mid-epoch volatile
+    change to the specific source that moved — memory, skills, or the
+    current-request anchor — instead of a catch-all "volatile" label.
+    """
+    return {
+        "memory": _memory_block(ctx, memory_selection),
+        "skills": _skills_section(ctx),
+        "current_request": _current_request_block(chat_messages),
+    }
+
+
+def compose_system_prompt(
+    ctx: TurnContext,
+    *,
+    chat_messages: Sequence[Message] | None = None,
+    memory_selection: MemoryPromptSelection | None = None,
+    attachment_catalog: Sequence[AttachmentRecord] | None = None,
+) -> str:
+    """Build the system string: AGENT.md, harness, attachments, then volatile tail.
+
+    ``ctx.agent_md`` is the operator-authored base prompt (typically from AGENT.md).
+    Stable sections (harness, attachments) precede volatile curation (memory, skills,
+    current-request anchor) so implicit and explicit prompt caching can hit a contiguous
+    prefix across turns.
+
+    When ``memory_selection`` is set, its lines (and optional search nudge) are used
+    instead of the full ``ctx.memory_index``. Skill names are always taken from
+    ``ctx.skills`` (zero-cost discovery); use ``list_skills``/``read_file`` for the
+    skills root path and full ``SKILL.md`` procedure.
+    """
+    stable = compose_stable_baseline(ctx, attachment_catalog=attachment_catalog)
+    volatile = compose_volatile_tail(
+        ctx, chat_messages=chat_messages, memory_selection=memory_selection
+    )
+    return f"{stable}{volatile}"

monkeybot/core/runtime/__init__.py

@@ -0,0 +1 @@
+"""Agent turn loop and streaming events."""