symphony-code 0.0.1__py3-none-any.whl

coding_agent/run/interrupted.py

@@ -0,0 +1,67 @@
+"""Decide whether the most recent session is an interrupted run worth continuing."""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+from typing import Optional
+
+from core_harness import Checkpoint
+
+from coding_agent.addons.persistence import JsonlPersistence, SessionSummary
+from coding_agent.addons.persistence.artifacts import safe_path
+
+
+async def interrupted_session(persistence: JsonlPersistence) -> Optional[tuple[SessionSummary, Checkpoint]]:
+    """Most recent session, only if its last checkpoint still says ``running``."""
+    sessions = await persistence.list_sessions()
+    if not sessions:
+        return None
+    checkpoint = await persistence.load_checkpoint(session_id=sessions[0].session_id)
+    if checkpoint is None or checkpoint.status != "running":
+        return None
+    return sessions[0], checkpoint
+
+
+def detached_run_pid(persistence: JsonlPersistence, session_id: str) -> Optional[int]:
+    """Pid recorded for a detached run, if run.json has one."""
+    try:
+        path = safe_path(persistence.session_dir(session_id), "run.json")
+    except ValueError:
+        return None
+    if not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    pid = payload.get("pid")
+    if isinstance(pid, bool) or not isinstance(pid, int) or pid <= 1:
+        return None
+    return pid
+
+
+def stop_orphaned_jobs(jobs: object) -> list[str]:
+    """SIGKILL job process groups (own session, so pgid == pid) that outlived the killed run."""
+    stopped = []
+    for job_id, pid in jobs.items() if isinstance(jobs, dict) else []:
+        if not isinstance(pid, int) or pid <= 1:
+            continue
+        try:
+            os.killpg(pid, signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            continue
+        stopped.append(f"{job_id} (pid {pid})")
+    return stopped
+
+
+def resume_note(summary: SessionSummary, checkpoint: Checkpoint, stopped: list[str]) -> str:
+    goal = checkpoint.metadata.get("goal") or summary.first_message
+    return (
+        f"previous run was interrupted at {summary.updated_at}; "
+        f"background jobs {', '.join(stopped) or 'none'} were stopped; "
+        f"continue toward the original task: {goal}"
+    )

coding_agent/run/log_sink.py

@@ -0,0 +1,46 @@
+"""Headless event sink: one log line per notable event, nothing kept in memory."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict
+
+from core_harness import EventSink
+
+LOGGED_EVENTS = frozenset(
+    {
+        "run_started",
+        "tool_execution_started",
+        "auto_decision",
+        "waiting_for_children",
+        "message_injected",
+        "compaction_completed",
+        "run_completed",
+        "run_failed",
+        "run_cancelled",
+        "run_limit_exceeded",
+    }
+)
+QUIET_KEYS = frozenset(
+    {
+        "run_id",
+        "session_id",
+        "seq",
+        "ts",
+        "schema_version",
+        "parent_id",
+        "started_at",
+        "context",
+        "usage",
+    }
+)
+
+
+class LogLineSink(EventSink):
+    async def deliver(self, event_type: str, payload: Dict[str, Any]) -> None:
+        name = event_type
+        if name not in LOGGED_EVENTS:
+            return
+        detail = {key: value for key, value in payload.items() if key not in QUIET_KEYS}
+        print(f"{time.strftime('%H:%M:%S')} {name} {json.dumps(detail, default=str)[:400]}", flush=True)

coding_agent/tools/__init__.py

@@ -0,0 +1,73 @@
+"""Coding-agent tools."""
+
+from pathlib import Path
+from typing import List, Type
+
+from core_harness import Tool
+
+from coding_agent.config import ToolsConfig
+from coding_agent.tools.base import ToolArgsModel, WorkspaceTool
+from coding_agent.tools.ask_user import AskUserArgs, AskUserTool
+from coding_agent.tools.bash import BashArgs, BashTool
+from coding_agent.tools.bash_jobs import BashJobs
+from coding_agent.tools.generate_image import GenerateImageArgs, GenerateImageTool
+from coding_agent.tools.memory import MemoryArgs, MemoryGetTool, MemorySearchTool, MemoryTool
+from coding_agent.tools.patch import PatchArgs, PatchTool
+from coding_agent.tools.read_file import ReadFileArgs, ReadFileTool
+from coding_agent.tools.search import SearchArgs, SearchTool
+from coding_agent.tools.web_search import WebSearchArgs, WebSearchTool
+from coding_agent.tools.write_file import WriteFileArgs, WriteFileTool
+
+TOOL_CLASSES: tuple[Type[WorkspaceTool], ...] = (
+    ReadFileTool,
+    WriteFileTool,
+    GenerateImageTool,
+    MemoryTool,
+    MemorySearchTool,
+    MemoryGetTool,
+    PatchTool,
+    BashTool,
+    SearchTool,
+    WebSearchTool,
+    AskUserTool,
+)
+
+__all__ = [
+    "AskUserArgs", "AskUserTool", "BashArgs", "BashJobs", "BashTool",
+    "GenerateImageArgs", "GenerateImageTool", "MemoryArgs", "MemoryTool", "PatchArgs", "PatchTool",
+    "ReadFileArgs", "ReadFileTool", "SearchArgs", "SearchTool", "TOOL_CLASSES",
+    "ToolArgsModel", "WebSearchArgs", "WebSearchTool", "WorkspaceTool", "WriteFileArgs", "WriteFileTool",
+    "build_tools",
+]
+
+
+def build_tools(
+    workspace: str | Path,
+    *,
+    config: ToolsConfig | None = None,
+    learning_enabled: bool = False,
+    unattended: bool = False,
+    bash_jobs: BashJobs | None = None,
+    learning_store: object | None = None,
+) -> List[Tool]:
+    tools_config = config or ToolsConfig()
+    configured = {
+        AskUserTool: {"unattended": unattended},
+        BashTool: {"config": tools_config.bash, "jobs": bash_jobs},
+        ReadFileTool: {"config": tools_config.read_file},
+        SearchTool: {"config": tools_config.search},
+        WebSearchTool: {"config": tools_config.web_search},
+        MemoryTool: {"store": learning_store},
+        MemorySearchTool: {"store": learning_store},
+        MemoryGetTool: {"store": learning_store},
+    }
+    skipped: set[Type[WorkspaceTool]] = set()
+    if not learning_enabled:
+        skipped |= {MemoryTool, MemorySearchTool, MemoryGetTool}
+    if not tools_config.web_search.enabled:
+        skipped.add(WebSearchTool)
+    classes = tuple(tool for tool in TOOL_CLASSES if tool not in skipped)
+    return [
+        tool_class(workspace, **configured.get(tool_class, {})).as_harness_tool()
+        for tool_class in classes
+    ]

coding_agent/tools/ask_user.py

@@ -0,0 +1,61 @@
+"""Ask the human a clarifying question and wait for an answer."""
+
+from __future__ import annotations
+
+
+from core_harness.events import EventSink
+from pydantic import Field
+
+from coding_agent.tools.base import ToolArgsModel, WorkspaceTool
+
+NO_HUMAN_ANSWER = "no human available; pick the safest reasonable option and continue"
+
+
+class AskUserArgs(ToolArgsModel):
+    question: str = Field(..., min_length=1, description="Clarifying question to show the user.")
+    choices: list[str] = Field(default_factory=list, description="Optional preset answers to present.")
+    default: str = Field(default="", description="Optional suggested answer.")
+
+
+class AskUserTool(WorkspaceTool):
+    name = "ask_user"
+    description = (
+        "Ask the user a clarifying question during an interactive run and return their answer. "
+        "Use when the task is ambiguous or blocked on a human decision. "
+        "Keep the question concise and specific."
+    )
+    args_model = AskUserArgs
+
+    def __init__(self, workspace: str, *, unattended: bool = False) -> None:
+        self.unattended = unattended
+        super().__init__(workspace)
+
+    async def run(
+        self,
+        question: str,
+        choices: list[str] | None = None,
+        default: str = "",
+        sink: EventSink | None = None,
+    ) -> str:
+        question = question.strip()
+        if not question:
+            return "error: question must be a non-empty string"
+
+        if self.unattended:
+            # ApprovalAddon records the auto_decision; never block on a human here.
+            hints = [f"default: {default}"] if default else []
+            hints += [f"choices: {', '.join(choices)}"] if choices else []
+            return "\n".join([NO_HUMAN_ANSWER, *hints])
+
+        if sink is None:
+            return "error: interactive user questions require an interactive control plane"
+
+        answer = await sink.interaction.request_user_input(
+            question=question,
+            choices=list(choices),
+            default=default,
+        )
+        answer = str(answer or "").strip()
+        if not answer and default:
+            return default
+        return answer or ""

coding_agent/tools/base.py

@@ -0,0 +1,136 @@
+"""Tool base: working-directory relative paths, schema generation, validation."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Annotated, Any, ClassVar, Dict, Type
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, ValidationError
+
+from core_harness import Tool
+
+
+def _strip_path(value: str) -> str:
+    stripped = value.strip()
+    if not stripped:
+        raise ValueError("path must be a non-empty string")
+    return stripped
+
+
+# A path argument with surrounding whitespace removed. Use it on models that
+# keep str_strip_whitespace off so file content stays whitespace-exact.
+NonEmptyPath = Annotated[str, AfterValidator(_strip_path)]
+
+
+class WorkspaceTool(Tool, ABC):
+    """File/shell tool. Relative paths start at the working directory."""
+
+    name: str
+    description: str
+    args_model: ClassVar[Type[BaseModel]]
+
+    def __init__(self, workspace: str | Path, *, parallel: bool = False) -> None:
+        """``parallel`` marks a read-only tool the harness may batch with others.
+
+        The harness caps a batch at ``max_parallel_tool_calls``; tools that write
+        or run commands must leave this ``False`` so they stay serial.
+        """
+        self.workspace = Path(workspace).expanduser().resolve()
+        self.workspace.mkdir(parents=True, exist_ok=True)
+        super().__init__(
+            name=type(self).name,
+            description=type(self).description,
+            parameters=self.parameters_schema(),
+            parallel=parallel,
+        )
+
+    def resolve_path(self, path: str) -> Path:
+        """Resolve ``path``. Absolute and ``~`` paths are used as-is; others join the working directory."""
+        if not isinstance(path, str):
+            raise TypeError(f"path must be a string, got {type(path).__name__}")
+        stripped = path.strip()
+        if not stripped:
+            raise ValueError("path must be a non-empty string")
+        candidate = Path(stripped).expanduser()
+        if not candidate.is_absolute():
+            candidate = self.workspace / candidate
+        return candidate.resolve()
+
+    def parameters_schema(self) -> Dict[str, Any]:
+        """JSON Schema for tool arguments, including optional UI activity metadata."""
+        schema = self.args_model.model_json_schema()
+        schema.pop("title", None)
+        schema.setdefault("type", "object")
+        schema.setdefault("additionalProperties", False)
+        properties = schema.setdefault("properties", {})
+        properties["activity"] = {
+            "type": "object",
+            "description": (
+                "Optional UI context as a nested object. Do not put verb, reason, "
+                "goal, or group at the top level of the tool arguments. "
+                "Set activity.verb to a short present-participle label such as "
+                "'Searching' or 'Reading', activity.reason to why this call is "
+                "needed, and activity.group to a stable label shared by related calls."
+            ),
+            "properties": {
+                "verb": {
+                    "type": "string",
+                    "description": "Short present-participle label, e.g. Searching, Reading.",
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "Why this call is needed.",
+                },
+                "group": {
+                    "type": "string",
+                    "description": "Stable label shared by related calls.",
+                },
+            },
+            "additionalProperties": False,
+        }
+        return schema
+
+    def validate_args(self, **kwargs: Any) -> BaseModel:
+        """Validate and coerce tool kwargs with the tool's pydantic args model."""
+        try:
+            return self.args_model.model_validate(kwargs)
+        except ValidationError as exc:
+            raise ValueError(f"invalid {self.name} arguments: {exc}") from exc
+
+    def prepare_args(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Remove presentation-only metadata before schema validation."""
+        prepared = dict(args)
+        for key in ("activity", "verb", "reason", "goal", "group"):
+            prepared.pop(key, None)
+        return prepared
+
+    @abstractmethod
+    def run(self, *args: Any, **kwargs: Any) -> str | list[dict[str, Any]]:
+        """Execute the tool and return a string or multimodal content for the model."""
+
+    async def execute(self, *, sink: Any, args: Dict[str, Any]) -> Any:
+        run_signature = inspect.signature(self.run)
+        accepts_sink = "sink" in run_signature.parameters
+        validated = self.validate_args(**self.prepare_args(args))
+        kwargs = {**validated.model_dump(), **({"sink": sink} if accepts_sink else {})}
+        if self.parallel and not inspect.iscoroutinefunction(self.run):
+            # Parallel tools run off the event loop so a batch actually overlaps.
+            result = await asyncio.to_thread(self.run, **kwargs)
+        else:
+            result = self.run(**kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    def as_harness_tool(self) -> Tool:
+        """Return ``self`` — these tools already are harness tools."""
+        return self
+
+
+class ToolArgsModel(BaseModel):
+    """Strict base for tool argument models."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)

coding_agent/tools/bash.py

@@ -0,0 +1,288 @@
+"""Run a shell command inside the workspace without blocking the event loop."""
+
+from __future__ import annotations
+
+import asyncio
+import codecs
+import contextlib
+import os
+import signal
+from types import TracebackType
+from typing import TYPE_CHECKING, Literal
+
+from core_harness import EventSink
+from core_harness.tools import current_tool_call_id
+from pydantic import Field
+
+from coding_agent.config import BashConfig
+from coding_agent.tools.base import ToolArgsModel, WorkspaceTool
+
+if TYPE_CHECKING:
+    from coding_agent.tools.bash_jobs import BashJobs
+
+DEFAULT_BASH_CONFIG = BashConfig()
+# Live output for UIs (the TUI's running Bash card shows its tail). Chunks are
+# coalesced so a chatty command costs at most one event per interval.
+OUTPUT_EVENT = "tool_execution_output"
+OUTPUT_FLUSH_SECONDS = 0.1
+# Most characters sent per event. A UI shows a tail, so when a burst exceeds
+# this only its newest lines are sent; the tool result is not affected.
+OUTPUT_EVENT_CHARS = 4096
+
+
+class BashArgs(ToolArgsModel):
+    command: str = Field(
+        default="",
+        description=(
+            "Shell command to run with cwd set to the working directory. Pipelines, &&, loops, "
+            "and heredoc scripts are fine (e.g. 'python -m pytest -q 2>&1 | tail -20', "
+            "'rg -l foo | xargs wc -l'). Required for action=run."
+        ),
+    )
+    timeout: int = Field(
+        default=DEFAULT_BASH_CONFIG.default_timeout_seconds,
+        ge=1,
+        description="Seconds to wait before killing the process group.",
+    )
+    background: bool = Field(
+        default=False,
+        description=(
+            "Run detached and return a job id plus log path at once (for long builds or "
+            "test suites). When it exits you are sent its status and output tail "
+            "automatically; do not poll. The run cannot finish while a job is alive."
+        ),
+    )
+    action: Literal["run", "output", "stop"] = Field(
+        default="run",
+        description="run a command; output: tail a background job's log; stop: kill a background job.",
+    )
+    job_id: str = Field(default="", description="Background job id for action=output or stop.")
+
+
+class BashTool(WorkspaceTool):
+    name = "bash"
+    description = (
+        "Run a shell command (bash) in the working directory and return combined stdout/stderr. "
+        "Reach for this early and often: one well-built command usually beats many small tool calls. "
+        "Use pipelines and chaining (rg -n 'TODO' src | head -50, git log --oneline -20 && git status, "
+        "ls -R | wc -l), loops, heredocs, and short inline scripts (python - <<'EOF' ... EOF) to explore, "
+        "count, compare, transform, and verify in a single call. Prefer it for builds, tests, git, "
+        "package managers, codebase surveys, and quick checks; keep read_file for reading a file you "
+        "will edit and patch/write_file for edits. "
+        "Non-zero exits are returned as text (prefixed with exit=N), not as a tool failure. "
+        "Timeouts include captured output. Output is capped to the last bytes, so filter or limit "
+        "noisy output in the command itself. "
+        "Child processes are killed as a group according to the configured limits."
+    )
+    args_model = BashArgs
+
+    def __init__(
+        self, workspace: str, *, config: BashConfig = DEFAULT_BASH_CONFIG, jobs: BashJobs | None = None
+    ) -> None:
+        self.config = config
+        self.jobs = jobs
+        super().__init__(workspace)
+        timeout_schema = self.parameters["properties"]["timeout"]
+        timeout_schema["default"] = config.default_timeout_seconds
+        timeout_schema["maximum"] = config.max_timeout_seconds
+
+    def prepare_args(self, args: dict[str, object]) -> dict[str, object]:
+        prepared = super().prepare_args(args)
+        prepared.setdefault("timeout", self.config.default_timeout_seconds)
+        return prepared
+
+    async def run(
+        self,
+        command: str,
+        timeout: int,
+        background: bool = False,
+        action: str = "run",
+        job_id: str = "",
+        sink: EventSink | None = None,
+    ) -> str:
+        if background or action != "run":
+            return await self.run_job(command, action, job_id)
+        if not isinstance(command, str) or not command.strip():
+            return "error: command must be a non-empty string"
+        timeout = min(max(int(timeout), 1), self.config.max_timeout_seconds)
+
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+                cwd=self.workspace,
+                start_new_session=True,
+            )
+        except OSError as exc:
+            return f"error: failed to run command: {exc}"
+
+        tool_call_id = current_tool_call_id.get()
+        live = OutputStream(sink, tool_call_id) if sink is not None and tool_call_id else None
+        try:
+            async with contextlib.AsyncExitStack() as stack:
+                if live is not None:
+                    await stack.enter_async_context(live)
+                output, truncated, timed_out = await stream_output(
+                    proc,
+                    timeout,
+                    max_output_bytes=self.config.max_output_bytes,
+                    live=live,
+                )
+        except asyncio.CancelledError:
+            await stop_process_group(proc)
+            raise
+
+        text = decode_capped(output, truncated, self.config.max_output_bytes)
+        if timed_out:
+            prefix = f"timed out after {timeout}s"
+            return f"{prefix}\n{text}".rstrip() if text else prefix
+        if proc.returncode not in (0, None):
+            return f"exit={proc.returncode}\n{text}".rstrip() if text else f"exit={proc.returncode}"
+        return text or "(no output)"
+
+    async def run_job(self, command: str, action: str, job_id: str) -> str:
+        if self.jobs is None:
+            return "error: background jobs are not available here"
+        if action == "run":
+            if not command.strip():
+                return "error: command must be a non-empty string"
+            return await self.jobs.start(command, self.workspace)
+        if not job_id:
+            return f"error: job_id is required for action={action}"
+        if action == "output":
+            return self.jobs.output(job_id, self.config.max_output_bytes)
+        return await self.jobs.stop(job_id)
+
+
+def decode_capped(output: bytes, truncated: bool, cap: int) -> str:
+    if truncated:
+        index = 0
+        while index < len(output) and output[index] & 0xC0 == 0x80:
+            index += 1
+        output = output[index:]
+    text = output.decode("utf-8", errors="replace").rstrip()
+    if not truncated:
+        return text
+    notice = f"...[earlier output truncated, showing last {cap} bytes]..."
+    return f"{notice}\n{text}" if text else notice
+
+
+class OutputStream:
+    """Send a running command's output to the sink as ``tool_execution_output``.
+
+    ``feed`` only buffers; while the context is open a pump task emits the
+    buffer every ``OUTPUT_FLUSH_SECONDS``, and leaving the context normally
+    (exit or timeout) sends what is left. A cancelled command sends nothing
+    more. Payload: ``tool_call_id``, ``tool_name`` and the text ``delta``.
+    """
+
+    def __init__(self, sink: EventSink, tool_call_id: str) -> None:
+        self.sink = sink
+        self.tool_call_id = tool_call_id
+        self.decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+        self.pending = ""
+        self.at_line_start = True
+        self.pump: asyncio.Task[None] | None = None
+
+    def feed(self, data: bytes) -> None:
+        self.pending += self.decoder.decode(data)
+
+    async def flush(self) -> None:
+        delta = self.pending
+        self.pending = ""
+        if len(delta) > OUTPUT_EVENT_CHARS:
+            # Keep the newest whole lines; restart the line the UI had open.
+            start = len(delta) - OUTPUT_EVENT_CHARS
+            newline = delta.find("\n", start)
+            delta = delta[newline + 1 :] if 0 <= newline < len(delta) - 1 else delta[start:]
+            if not self.at_line_start:
+                delta = "\n" + delta
+        if not delta:
+            return
+        self.at_line_start = delta.endswith("\n")
+        await self.sink.emit(
+            OUTPUT_EVENT,
+            {"tool_call_id": self.tool_call_id, "tool_name": BashTool.name, "delta": delta},
+        )
+
+    async def run_pump(self) -> None:
+        while True:
+            await asyncio.sleep(OUTPUT_FLUSH_SECONDS)
+            await self.flush()
+
+    async def __aenter__(self) -> OutputStream:
+        self.pump = asyncio.create_task(self.run_pump())
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self.pump is not None:
+            self.pump.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self.pump
+        if exc_type is None:
+            self.pending += self.decoder.decode(b"", final=True)
+            await self.flush()
+
+
+async def stream_output(
+    proc: asyncio.subprocess.Process,
+    timeout: float,
+    *,
+    max_output_bytes: int,
+    live: OutputStream | None = None,
+) -> tuple[bytes, bool, bool]:
+    if proc.stdout is None:
+        return b"", False, False
+
+    buf = bytearray()
+    truncated = False
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+
+    while True:
+        remaining = deadline - loop.time()
+        if remaining <= 0:
+            await stop_process_group(proc)
+            return bytes(buf), truncated, True
+        try:
+            chunk = await asyncio.wait_for(proc.stdout.read(4096), timeout=remaining)
+        except TimeoutError:
+            await stop_process_group(proc)
+            return bytes(buf), truncated, True
+        if not chunk:
+            break
+        if live is not None:
+            live.feed(chunk)
+        buf.extend(chunk)
+        if len(buf) > max_output_bytes:
+            truncated = True
+            del buf[:-max_output_bytes]
+
+    remaining = deadline - loop.time()
+    try:
+        await asyncio.wait_for(proc.wait(), timeout=max(remaining, 0.01))
+    except TimeoutError:
+        await stop_process_group(proc)
+        return bytes(buf), truncated, True
+    return bytes(buf), truncated, False
+
+
+async def stop_process_group(proc: asyncio.subprocess.Process) -> None:
+    if proc.returncode is not None:
+        return
+    for sig in (signal.SIGTERM, signal.SIGKILL):
+        try:
+            os.killpg(proc.pid, sig)
+        except ProcessLookupError:
+            break
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=1.0)
+            return
+        except asyncio.TimeoutError:
+            continue