windcode 0.1.0__py3-none-any.whl

windcode/tools/read_file.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.tools.filesystem import content_sha256, require_workspace_path
+
+
+class ReadFileInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str = Field(min_length=1)
+    offset: int = Field(default=1, ge=1)
+    limit: int = Field(default=500, ge=1, le=2_000)
+
+
+class ReadFileTool:
+    name = "read_file"
+    description = "Read a UTF-8 text file with stable one-based line numbers."
+    input_model = ReadFileInput
+    effects = frozenset({ToolEffect.READ})
+    max_bytes = 2_000_000
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        parsed = cast(ReadFileInput, arguments)
+        path = require_workspace_path(context.workspace, parsed.path)
+        raw = path.read_bytes()
+        if len(raw) > self.max_bytes:
+            return ToolResult(
+                output=f"file is too large: {len(raw)} bytes (limit {self.max_bytes})",
+                is_error=True,
+                data={"error": "file_too_large", "size": len(raw)},
+            )
+        if b"\x00" in raw:
+            return ToolResult(output="binary files are not supported", is_error=True)
+        content = raw.decode("utf-8")
+        lines = content.splitlines()
+        start = parsed.offset - 1
+        selected = lines[start : start + parsed.limit]
+        output = "\n".join(
+            f"{number:>6}\t{line}" for number, line in enumerate(selected, parsed.offset)
+        )
+        truncated = start + len(selected) < len(lines)
+        return ToolResult(
+            output=output,
+            data={
+                "path": str(path.relative_to(context.workspace.resolve())),
+                "sha256": content_sha256(raw),
+                "line_count": len(lines),
+                "truncated": truncated,
+            },
+        )

windcode/tools/registry.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import replace
+from time import monotonic
+from typing import Any, Protocol, cast
+
+import jsonschema
+from pydantic import ValidationError
+
+from windcode.domain.models import ToolSchema
+from windcode.domain.tools import Tool, ToolContext, ToolResult, ValidatedArguments
+
+
+class _RawSchemaTool(Protocol):
+    @property
+    def input_schema(self) -> Mapping[str, Any]: ...
+
+    def validate_arguments(self, arguments: Mapping[str, Any]) -> ValidatedArguments: ...
+
+
+def _input_schema(tool: Tool) -> dict[str, Any]:
+    raw = getattr(tool, "input_schema", None)
+    if isinstance(raw, Mapping):
+        mapping = cast(Mapping[object, object], raw)
+        return {str(key): value for key, value in mapping.items()}
+    return tool.input_model.model_json_schema()
+
+
+def _validate(tool: Tool, arguments: Mapping[str, Any]) -> ValidatedArguments:
+    validator = getattr(tool, "validate_arguments", None)
+    if callable(validator):
+        return cast(_RawSchemaTool, tool).validate_arguments(arguments)
+    schema = getattr(tool, "input_schema", None)
+    if isinstance(schema, Mapping):
+        typed_schema = cast(Mapping[str, Any], schema)
+        validator = jsonschema.Draft202012Validator(typed_schema)
+        validator.validate(arguments)  # pyright: ignore[reportUnknownMemberType]
+        return dict(arguments)
+    return tool.input_model.model_validate(arguments)
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool, *, replace: bool = False) -> None:
+        if tool.name in self._tools and not replace:
+            raise ValueError(f"tool already registered: {tool.name}")
+        self._tools[tool.name] = tool
+
+    def clone(self) -> ToolRegistry:
+        registry = ToolRegistry()
+        registry._tools = self._tools.copy()
+        return registry
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(self._tools)
+
+    def get(self, name: str) -> Tool:
+        try:
+            return self._tools[name]
+        except KeyError as exc:
+            raise KeyError(f"unknown tool: {name}") from exc
+
+    def schemas(self) -> tuple[ToolSchema, ...]:
+        return tuple(
+            ToolSchema(
+                name=tool.name,
+                description=tool.description,
+                parameters=_input_schema(tool),
+            )
+            for tool in self._tools.values()
+        )
+
+    async def execute(
+        self,
+        name: str,
+        context: ToolContext,
+        arguments: Mapping[str, Any],
+    ) -> ToolResult:
+        try:
+            tool = self.get(name)
+        except KeyError as exc:
+            return ToolResult(
+                output=str(exc),
+                is_error=True,
+                data={"error": "unknown_tool", "tool": name},
+            )
+        try:
+            parsed = _validate(tool, arguments)
+        except (ValidationError, jsonschema.ValidationError, jsonschema.SchemaError) as exc:
+            errors: object
+            if isinstance(exc, ValidationError):
+                errors = exc.errors(include_url=False)
+            elif isinstance(exc, jsonschema.ValidationError):
+                path_parts = cast(tuple[object, ...], tuple(exc.absolute_path))
+                path_values: list[str] = [str(part) for part in path_parts]
+                errors = cast(
+                    object,
+                    [{"path": path_values, "message": str(exc.message)}],
+                )
+            else:
+                errors = [{"path": tuple[str, ...](), "message": str(exc)}]
+            return ToolResult(
+                output=json.dumps(errors, ensure_ascii=True),
+                is_error=True,
+                data={"error": "invalid_arguments"},
+            )
+        started = monotonic()
+        try:
+            result = await tool.execute(context, cast(Any, parsed))
+        except (OSError, ValueError, UnicodeError) as exc:
+            result = ToolResult(
+                output=str(exc),
+                is_error=True,
+                data={"error": "execution_failed", "type": type(exc).__name__},
+            )
+        return replace(result, elapsed_seconds=max(0.0, monotonic() - started))

windcode/tools/shell.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+from dataclasses import dataclass
+from time import monotonic
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.sandbox import BubblewrapSandbox
+from windcode.tools.filesystem import require_workspace_path
+
+
+class ShellInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    command: str = Field(min_length=1)
+    cwd: str = "."
+    timeout_seconds: float | None = Field(default=None, gt=0, le=3600)
+    network: bool = False
+
+
+@dataclass(slots=True)
+class _BoundedOutput:
+    limit: int
+    data: bytearray
+    truncated: bool = False
+
+    def append(self, chunk: bytes) -> None:
+        remaining = self.limit - len(self.data)
+        if remaining > 0:
+            self.data.extend(chunk[:remaining])
+        if len(chunk) > remaining:
+            self.truncated = True
+
+
+async def _terminate_process_group(process: asyncio.subprocess.Process) -> None:
+    if process.returncode is not None:
+        return
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    try:
+        await asyncio.wait_for(process.wait(), timeout=0.5)
+    except TimeoutError:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        await process.wait()
+
+
+class ShellTool:
+    name = "shell"
+    description = "Run a bounded shell command with timeout, cancellation, and optional sandboxing."
+    input_model = ShellInput
+    effects = frozenset({ToolEffect.PROCESS})
+
+    def __init__(
+        self,
+        *,
+        sandbox: BubblewrapSandbox | None = None,
+        default_timeout: float = 120.0,
+        output_limit: int = 1_000_000,
+    ) -> None:
+        self.sandbox = sandbox
+        self.default_timeout = default_timeout
+        self.output_limit = output_limit
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        parsed = cast(ShellInput, arguments)
+        cwd = require_workspace_path(context.workspace, parsed.cwd)
+        command = ("bash", "-lc", parsed.command)
+        if self.sandbox is not None:
+            if not self.sandbox.status.available:
+                return ToolResult(
+                    output=self.sandbox.status.warning or "sandbox unavailable",
+                    is_error=True,
+                    data={"error": "sandbox_unavailable"},
+                )
+            command = self.sandbox.wrap(command, cwd=cwd, allow_network=parsed.network)
+
+        started = monotonic()
+        process = await asyncio.create_subprocess_exec(
+            *command,
+            cwd=cwd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            start_new_session=True,
+        )
+        stdout = _BoundedOutput(self.output_limit, bytearray())
+        stderr = _BoundedOutput(self.output_limit, bytearray())
+
+        async def read_stream(
+            stream: asyncio.StreamReader | None, target: _BoundedOutput, label: str
+        ) -> None:
+            if stream is None:
+                return
+            while chunk := await stream.read(4096):
+                target.append(chunk)
+                if context.progress is not None:
+                    await context.progress(f"{label}: {chunk.decode('utf-8', errors='replace')}")
+
+        readers = [
+            asyncio.create_task(read_stream(process.stdout, stdout, "stdout")),
+            asyncio.create_task(read_stream(process.stderr, stderr, "stderr")),
+        ]
+        timeout = parsed.timeout_seconds or self.default_timeout
+        try:
+            async with asyncio.timeout(timeout):
+                while process.returncode is None:
+                    if context.cancelled():
+                        raise asyncio.CancelledError
+                    await asyncio.sleep(0.02)
+                await asyncio.gather(*readers)
+        except TimeoutError:
+            await _terminate_process_group(process)
+            await asyncio.gather(*readers)
+            elapsed = monotonic() - started
+            return ToolResult(
+                output=f"command timed out after {timeout:g} seconds",
+                is_error=True,
+                elapsed_seconds=elapsed,
+                data={"error": "timeout", "exit_code": process.returncode, "timed_out": True},
+            )
+        except asyncio.CancelledError:
+            await _terminate_process_group(process)
+            await asyncio.gather(*readers, return_exceptions=True)
+            raise
+        finally:
+            for reader in readers:
+                if not reader.done():
+                    reader.cancel()
+
+        elapsed = monotonic() - started
+        stdout_text = stdout.data.decode("utf-8", errors="replace")
+        stderr_text = stderr.data.decode("utf-8", errors="replace")
+        output = stdout_text
+        if stderr_text:
+            output += ("\n" if output and not output.endswith("\n") else "") + stderr_text
+        truncated = stdout.truncated or stderr.truncated
+        if truncated:
+            output += "\n[output truncated]"
+        return ToolResult(
+            output=output,
+            is_error=process.returncode != 0,
+            elapsed_seconds=elapsed,
+            data={
+                "exit_code": process.returncode,
+                "stdout": stdout_text,
+                "stderr": stderr_text,
+                "truncated": truncated,
+                "command": parsed.command,
+            },
+        )

windcode/tools/subagents/__init__.py

@@ -0,0 +1,31 @@
+from windcode.runtime.subagents.coordinator import SubagentCoordinator
+from windcode.tools.registry import ToolRegistry
+from windcode.tools.subagents.cancel import CancelSubagentTool
+from windcode.tools.subagents.integrate import IntegrateSubagentTool
+from windcode.tools.subagents.list import ListSubagentsTool
+from windcode.tools.subagents.spawn import SpawnSubagentsTool
+from windcode.tools.subagents.wait import WaitSubagentsTool
+
+
+def register_subagent_tools(
+    registry: ToolRegistry,
+    coordinator: SubagentCoordinator,
+) -> None:
+    for tool in (
+        SpawnSubagentsTool(coordinator),
+        ListSubagentsTool(coordinator),
+        WaitSubagentsTool(coordinator),
+        CancelSubagentTool(coordinator),
+        IntegrateSubagentTool(coordinator),
+    ):
+        registry.register(tool)
+
+
+__all__ = [
+    "CancelSubagentTool",
+    "IntegrateSubagentTool",
+    "ListSubagentsTool",
+    "SpawnSubagentsTool",
+    "WaitSubagentsTool",
+    "register_subagent_tools",
+]

windcode/tools/subagents/cancel.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.runtime.subagents.coordinator import SubagentCoordinator, SubagentCoordinatorError
+
+
+class CancelSubagentInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    subagent_id: str = Field(min_length=1)
+
+
+class CancelSubagentTool:
+    name = "cancel_subagent"
+    description = "Cancel one queued or running temporary subagent."
+    input_model = CancelSubagentInput
+    effects = frozenset({ToolEffect.PROCESS})
+
+    def __init__(self, coordinator: SubagentCoordinator) -> None:
+        self.coordinator = coordinator
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        del context
+        parsed = cast(CancelSubagentInput, arguments)
+        try:
+            record = await self.coordinator.cancel(parsed.subagent_id)
+        except SubagentCoordinatorError as exc:
+            return ToolResult(output=str(exc), is_error=True, data={"error": exc.category})
+        data = {"subagent_id": record.subagent_id, "status": record.status.value}
+        return ToolResult(json.dumps(data, ensure_ascii=True), data=data)

windcode/tools/subagents/integrate.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.runtime.subagents.coordinator import SubagentCoordinator, SubagentCoordinatorError
+
+
+class IntegrateSubagentInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    subagent_id: str = Field(min_length=1)
+    verification_commands: tuple[str, ...] = ()
+
+
+class IntegrateSubagentTool:
+    name = "integrate_subagent"
+    description = "Integrate a completed subagent commit and verify it in the parent workspace."
+    input_model = IntegrateSubagentInput
+    effects = frozenset({ToolEffect.WORKSPACE_WRITE, ToolEffect.PROCESS})
+
+    def __init__(self, coordinator: SubagentCoordinator) -> None:
+        self.coordinator = coordinator
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        del context
+        parsed = cast(IntegrateSubagentInput, arguments)
+        try:
+            result = await self.coordinator.integrate(
+                parsed.subagent_id, parsed.verification_commands
+            )
+        except SubagentCoordinatorError as exc:
+            return ToolResult(output=str(exc), is_error=True, data={"error": exc.category})
+        data = {
+            "subagent_id": result.subagent_id,
+            "status": result.status.value,
+            "commit": result.commit,
+            "verification": [
+                {
+                    "command": item.command,
+                    "exit_code": item.exit_code,
+                    "passed": item.passed,
+                    "output_summary": item.output_summary,
+                }
+                for item in result.verification
+            ],
+            "error_category": result.error_category,
+            "error_message": result.error_message,
+        }
+        is_error = result.error_category is not None
+        return ToolResult(json.dumps(data, ensure_ascii=True), is_error=is_error, data=data)

windcode/tools/subagents/list.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+
+from pydantic import BaseModel, ConfigDict
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.runtime.subagents.coordinator import SubagentCoordinator
+
+
+class ListSubagentsInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ListSubagentsTool:
+    name = "list_subagents"
+    description = (
+        "Take a non-blocking subagent status snapshot for explicit inspection. "
+        "Do not poll this tool; use wait_subagents to await completion."
+    )
+    input_model = ListSubagentsInput
+    effects = frozenset({ToolEffect.READ})
+
+    def __init__(self, coordinator: SubagentCoordinator) -> None:
+        self.coordinator = coordinator
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        del context, arguments
+        data = [
+            {
+                "subagent_id": record.subagent_id,
+                "task_index": record.task_index,
+                "task_name": record.spec.task_name,
+                "role": record.spec.role.value,
+                "kind": record.spec.kind.value,
+                "status": record.status.value,
+                "commit": record.commit,
+                "worktree_path": (
+                    None if record.worktree_path is None else str(record.worktree_path)
+                ),
+                "error_category": record.error_category,
+                "error_message": record.error_message,
+            }
+            for record in self.coordinator.list()
+        ]
+        return ToolResult(json.dumps(data, ensure_ascii=True), data={"subagents": data})

windcode/tools/subagents/spawn.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.subagents import SubagentRole, SubagentTaskKind, SubagentTaskSpec
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.runtime.subagents.coordinator import SubagentCoordinator, SubagentCoordinatorError
+
+
+class SubagentTaskInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    task_name: str = Field(pattern=r"^[a-z0-9]+(?:_[a-z0-9]+)*$")
+    role: SubagentRole
+    kind: SubagentTaskKind
+    goal: str = Field(min_length=1)
+    context: str = Field(min_length=1)
+    expected_output: str = Field(min_length=1)
+    verification: tuple[str, ...] = Field(min_length=1)
+    allowed_tools: frozenset[str] | None = None
+    model: str | None = None
+    requires_network: bool = Field(
+        default=False,
+        description="Whether the task requires external network access.",
+    )
+
+    def to_spec(self) -> SubagentTaskSpec:
+        return SubagentTaskSpec(
+            self.task_name,
+            self.role,
+            self.kind,
+            self.goal,
+            self.context,
+            self.expected_output,
+            self.verification,
+            self.allowed_tools,
+            self.model,
+            self.requires_network,
+        )
+
+
+class SpawnSubagentsInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tasks: tuple[SubagentTaskInput, ...] = Field(min_length=1, max_length=16)
+
+
+class SpawnSubagentsTool:
+    name = "spawn_subagents"
+    description = (
+        "Create bounded temporary subagents. Declare requires_network for network-dependent "
+        "tasks; network access follows the parent run's network policy and permission workflow."
+    )
+    input_model = SpawnSubagentsInput
+    effects = frozenset({ToolEffect.PROCESS, ToolEffect.WORKSPACE_WRITE})
+
+    def __init__(self, coordinator: SubagentCoordinator) -> None:
+        self.coordinator = coordinator
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        del context
+        parsed = cast(SpawnSubagentsInput, arguments)
+        try:
+            records = await self.coordinator.spawn(tuple(item.to_spec() for item in parsed.tasks))
+        except (SubagentCoordinatorError, ValueError) as exc:
+            category = getattr(exc, "category", "invalid_task")
+            return ToolResult(
+                output=str(exc),
+                is_error=True,
+                data={"error": str(category)},
+            )
+        data = [
+            {
+                "subagent_id": record.subagent_id,
+                "task_index": record.task_index,
+                "task_name": record.spec.task_name,
+                "role": record.spec.role.value,
+                "kind": record.spec.kind.value,
+                "status": record.status.value,
+            }
+            for record in records
+        ]
+        return ToolResult(json.dumps(data, ensure_ascii=True), data={"subagents": data})

windcode/tools/subagents/wait.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.subagents import SubagentResult
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.runtime.subagents.coordinator import SubagentCoordinator, SubagentCoordinatorError
+
+
+class WaitSubagentsInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    subagent_ids: tuple[str, ...] = Field(min_length=1, max_length=16)
+    timeout_seconds: float = Field(default=300.0, gt=0, le=900.0)
+
+
+def _result_data(result: SubagentResult) -> dict[str, object]:
+    return {
+        "subagent_id": result.subagent_id,
+        "task_name": result.task_name,
+        "status": result.status.value,
+        "summary": result.summary,
+        "changed_files": list(result.changed_files),
+        "commit": result.commit,
+        "usage": {
+            "input_tokens": result.usage.input_tokens,
+            "output_tokens": result.usage.output_tokens,
+            "cache_read_tokens": result.usage.cache_read_tokens,
+            "cache_write_tokens": result.usage.cache_write_tokens,
+        },
+        "error_category": result.error_category,
+        "error_message": result.error_message,
+    }
+
+
+class WaitSubagentsTool:
+    name = "wait_subagents"
+    description = (
+        "Wait once for temporary subagents to reach terminal results. Use this after spawning; "
+        "do not poll list_subagents."
+    )
+    input_model = WaitSubagentsInput
+    effects = frozenset({ToolEffect.READ})
+
+    def __init__(self, coordinator: SubagentCoordinator) -> None:
+        self.coordinator = coordinator
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        del context
+        parsed = cast(WaitSubagentsInput, arguments)
+        try:
+            async with asyncio.timeout(parsed.timeout_seconds):
+                results = await asyncio.gather(
+                    *(self.coordinator.wait(subagent_id) for subagent_id in parsed.subagent_ids)
+                )
+        except TimeoutError:
+            data = {
+                "error": "wait_timeout",
+                "subagent_ids": list(parsed.subagent_ids),
+                "statuses": {
+                    record.subagent_id: record.status.value
+                    for record in self.coordinator.list()
+                    if record.subagent_id in parsed.subagent_ids
+                },
+            }
+            return ToolResult(json.dumps(data, ensure_ascii=True), is_error=True, data=data)
+        except SubagentCoordinatorError as exc:
+            return ToolResult(output=str(exc), is_error=True, data={"error": exc.category})
+        data = [_result_data(result) for result in results]
+        return ToolResult(json.dumps(data, ensure_ascii=True), data={"subagents": data})