windcode 0.1.0__py3-none-any.whl

windcode/sessions/__init__.py

@@ -0,0 +1,23 @@
+from windcode.sessions.artifacts import ArtifactStore
+from windcode.sessions.models import (
+    SCHEMA_VERSION,
+    ArtifactReference,
+    EventRecord,
+    SessionMetadata,
+    SessionStatus,
+)
+from windcode.sessions.store import SessionCorruptionError, SessionStore
+from windcode.sessions.tree import ancestor_chain, create_branch
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "ArtifactReference",
+    "ArtifactStore",
+    "EventRecord",
+    "SessionCorruptionError",
+    "SessionMetadata",
+    "SessionStatus",
+    "SessionStore",
+    "ancestor_chain",
+    "create_branch",
+]

windcode/sessions/artifacts.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from uuid import uuid4
+
+from windcode.sessions.models import ArtifactReference
+
+
+class ArtifactStore:
+    def __init__(self, session_dir: Path) -> None:
+        self.session_dir = session_dir.expanduser().resolve()
+        self.artifacts_dir = self.session_dir / "artifacts"
+        self.artifacts_dir.mkdir(parents=True, exist_ok=True)
+
+    def put(self, content: str, *, preview_chars: int = 240) -> ArtifactReference:
+        encoded = content.encode("utf-8")
+        digest = hashlib.sha256(encoded).hexdigest()
+        relative_path = f"artifacts/{digest}.txt"
+        destination = self.session_dir / relative_path
+        if not destination.exists():
+            temporary = destination.with_suffix(f".tmp-{uuid4().hex}")
+            try:
+                with temporary.open("wb") as stream:
+                    stream.write(encoded)
+                    stream.flush()
+                    os.fsync(stream.fileno())
+                try:
+                    temporary.replace(destination)
+                except FileExistsError:
+                    pass
+            finally:
+                temporary.unlink(missing_ok=True)
+        preview = content[:preview_chars]
+        if len(content) > preview_chars:
+            preview += "..."
+        return ArtifactReference(
+            relative_path=relative_path,
+            sha256=digest,
+            content_length=len(content),
+            preview=preview,
+        )
+
+    def externalize(
+        self,
+        content: str,
+        *,
+        threshold: int,
+    ) -> tuple[str, ArtifactReference | None]:
+        if len(content) <= threshold:
+            return content, None
+        reference = self.put(content)
+        summary = (
+            f"{reference.preview}\n\n"
+            f"[full output: {reference.relative_path}; sha256={reference.sha256}; "
+            f"characters={reference.content_length}]"
+        )
+        return summary, reference
+
+    def read(self, reference: ArtifactReference) -> str:
+        path = (self.session_dir / reference.relative_path).resolve()
+        if not path.is_relative_to(self.artifacts_dir):
+            raise ValueError("artifact reference escapes the artifact directory")
+        content = path.read_text(encoding="utf-8")
+        digest = hashlib.sha256(content.encode("utf-8")).hexdigest()
+        if digest != reference.sha256:
+            raise ValueError("artifact digest mismatch")
+        return content

windcode/sessions/models.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any, cast
+
+SCHEMA_VERSION = 1
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class SessionStatus(StrEnum):
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass(frozen=True, slots=True)
+class SessionMetadata:
+    session_id: str
+    created_at: datetime
+    updated_at: datetime
+    summary: str = ""
+    next_sequence: int = 1
+    head_record_id: str | None = None
+    status: SessionStatus = SessionStatus.ACTIVE
+    schema_version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "session_id": self.session_id,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "summary": self.summary,
+            "next_sequence": self.next_sequence,
+            "head_record_id": self.head_record_id,
+            "status": self.status.value,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> SessionMetadata:
+        return cls(
+            schema_version=int(value["schema_version"]),
+            session_id=str(value["session_id"]),
+            created_at=datetime.fromisoformat(str(value["created_at"])),
+            updated_at=datetime.fromisoformat(str(value["updated_at"])),
+            summary=str(value.get("summary", "")),
+            next_sequence=int(value["next_sequence"]),
+            head_record_id=(
+                None if value.get("head_record_id") is None else str(value["head_record_id"])
+            ),
+            status=SessionStatus(str(value["status"])),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class EventRecord:
+    sequence: int
+    record_id: str
+    parent_id: str | None
+    record_type: str
+    payload: dict[str, Any]
+    created_at: datetime = field(default_factory=utc_now)
+    schema_version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "sequence": self.sequence,
+            "record_id": self.record_id,
+            "parent_id": self.parent_id,
+            "record_type": self.record_type,
+            "payload": self.payload,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> EventRecord:
+        raw_payload = value["payload"]
+        if not isinstance(raw_payload, dict):
+            raise ValueError("event payload must be an object")
+        payload = cast(dict[object, object], raw_payload)
+        return cls(
+            schema_version=int(value["schema_version"]),
+            sequence=int(value["sequence"]),
+            record_id=str(value["record_id"]),
+            parent_id=None if value.get("parent_id") is None else str(value["parent_id"]),
+            record_type=str(value["record_type"]),
+            payload={str(key): item for key, item in payload.items()},
+            created_at=datetime.fromisoformat(str(value["created_at"])),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactReference:
+    relative_path: str
+    sha256: str
+    content_length: int
+    preview: str

windcode/sessions/store.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import json
+import os
+import threading
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, cast
+from uuid import uuid4
+
+from windcode.sessions.models import EventRecord, SessionMetadata, SessionStatus, utc_now
+
+
+class SessionCorruptionError(ValueError):
+    pass
+
+
+class SessionStore:
+    def __init__(self, sessions_root: Path, metadata: SessionMetadata) -> None:
+        self.sessions_root = sessions_root.expanduser().resolve()
+        self.metadata = metadata
+        self.session_dir = self.sessions_root / metadata.session_id
+        self.events_path = self.session_dir / "events.jsonl"
+        self.meta_path = self.session_dir / "meta.json"
+        self._lock = threading.Lock()
+
+    @classmethod
+    def create(cls, sessions_root: Path, session_id: str | None = None) -> SessionStore:
+        now = utc_now()
+        metadata = SessionMetadata(
+            session_id=session_id or uuid4().hex,
+            created_at=now,
+            updated_at=now,
+        )
+        store = cls(sessions_root, metadata)
+        store.session_dir.mkdir(parents=True, exist_ok=False)
+        (store.session_dir / "artifacts").mkdir()
+        store.events_path.touch()
+        store._write_metadata(durable=True)
+        return store
+
+    @classmethod
+    def open(cls, sessions_root: Path, session_id: str) -> SessionStore:
+        meta_path = sessions_root.expanduser().resolve() / session_id / "meta.json"
+        try:
+            raw = json.loads(meta_path.read_text(encoding="utf-8"))
+            if not isinstance(raw, dict):
+                raise ValueError("metadata must be an object")
+            metadata = SessionMetadata.from_dict(cast(dict[str, Any], raw))
+        except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+            raise SessionCorruptionError(f"cannot load {meta_path}: {exc}") from exc
+        return cls(sessions_root, metadata)
+
+    def _write_metadata(self, *, durable: bool) -> None:
+        temporary = self.meta_path.with_suffix(f".tmp-{uuid4().hex}")
+        data = json.dumps(self.metadata.to_dict(), ensure_ascii=True, sort_keys=True) + "\n"
+        try:
+            with temporary.open("w", encoding="utf-8") as stream:
+                stream.write(data)
+                stream.flush()
+                if durable:
+                    os.fsync(stream.fileno())
+            temporary.replace(self.meta_path)
+            if durable:
+                directory_fd = os.open(self.session_dir, os.O_RDONLY)
+                try:
+                    os.fsync(directory_fd)
+                finally:
+                    os.close(directory_fd)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def append(
+        self,
+        record_type: str,
+        payload: dict[str, Any],
+        *,
+        parent_id: str | None = None,
+        durable: bool = False,
+    ) -> EventRecord:
+        with self._lock:
+            record = EventRecord(
+                sequence=self.metadata.next_sequence,
+                record_id=uuid4().hex,
+                parent_id=self.metadata.head_record_id if parent_id is None else parent_id,
+                record_type=record_type,
+                payload=payload,
+            )
+            line = json.dumps(record.to_dict(), ensure_ascii=True, sort_keys=True) + "\n"
+            with self.events_path.open("a", encoding="utf-8") as stream:
+                stream.write(line)
+                stream.flush()
+                if durable:
+                    os.fsync(stream.fileno())
+            self.metadata = replace(
+                self.metadata,
+                updated_at=utc_now(),
+                next_sequence=record.sequence + 1,
+                head_record_id=record.record_id,
+            )
+            self._write_metadata(durable=durable)
+            return record
+
+    def set_status(self, status: SessionStatus, *, durable: bool = True) -> None:
+        with self._lock:
+            self.metadata = replace(self.metadata, status=status, updated_at=utc_now())
+            self._write_metadata(durable=durable)
+
+    def set_summary(self, summary: str, *, durable: bool = True) -> None:
+        with self._lock:
+            self.metadata = replace(self.metadata, summary=summary)
+            self._write_metadata(durable=durable)
+
+    def load_records(self) -> tuple[EventRecord, ...]:
+        try:
+            lines = self.events_path.read_text(encoding="utf-8").splitlines()
+        except OSError as exc:
+            raise SessionCorruptionError(f"cannot read {self.events_path}: {exc}") from exc
+
+        records: list[EventRecord] = []
+        for index, line in enumerate(lines):
+            if not line.strip():
+                continue
+            try:
+                raw = json.loads(line)
+                if not isinstance(raw, dict):
+                    raise ValueError("record must be an object")
+                record = EventRecord.from_dict(cast(dict[str, Any], raw))
+                expected = records[-1].sequence + 1 if records else 1
+                if record.sequence != expected:
+                    raise ValueError(f"expected sequence {expected}, got {record.sequence}")
+                records.append(record)
+            except (json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+                if index == len(lines) - 1:
+                    break
+                raise SessionCorruptionError(
+                    f"invalid event record at line {index + 1}: {exc}"
+                ) from exc
+        return tuple(records)
+
+    def recover_interrupted_side_effects(self) -> tuple[EventRecord, ...]:
+        records = self.load_records()
+        finished = {
+            str(record.payload.get("call_id"))
+            for record in records
+            if record.record_type in {"tool_finished", "tool_interrupted"}
+        }
+        pending = [
+            record
+            for record in records
+            if record.record_type == "tool_started"
+            and record.payload.get("side_effect") is True
+            and str(record.payload.get("call_id")) not in finished
+        ]
+        recovered: list[EventRecord] = []
+        for record in pending:
+            recovered.append(
+                self.append(
+                    "tool_interrupted",
+                    {
+                        "call_id": record.payload.get("call_id"),
+                        "reason": "session ended before a durable result was recorded",
+                    },
+                    durable=True,
+                )
+            )
+        return tuple(recovered)

windcode/sessions/tree.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from windcode.sessions.models import EventRecord
+from windcode.sessions.store import SessionStore
+
+
+def ancestor_chain(records: tuple[EventRecord, ...], record_id: str) -> tuple[EventRecord, ...]:
+    by_id = {record.record_id: record for record in records}
+    chain: list[EventRecord] = []
+    cursor: str | None = record_id
+    visited: set[str] = set()
+    while cursor is not None:
+        if cursor in visited:
+            raise ValueError("session record graph contains a cycle")
+        visited.add(cursor)
+        try:
+            record = by_id[cursor]
+        except KeyError as exc:
+            raise ValueError(f"unknown record id: {cursor}") from exc
+        chain.append(record)
+        cursor = record.parent_id
+    chain.reverse()
+    return tuple(chain)
+
+
+def create_branch(
+    store: SessionStore,
+    parent_id: str,
+    record_type: str,
+    payload: dict[str, Any],
+) -> EventRecord:
+    ancestor_chain(store.load_records(), parent_id)
+    return store.append(record_type, payload, parent_id=parent_id, durable=True)

windcode/tools/__init__.py

@@ -0,0 +1,10 @@
+from windcode.tools.builtins import add_subagent_tools, create_builtin_registry
+from windcode.tools.memory import register_memory_tools
+from windcode.tools.registry import ToolRegistry
+
+__all__ = [
+    "ToolRegistry",
+    "add_subagent_tools",
+    "create_builtin_registry",
+    "register_memory_tools",
+]

windcode/tools/apply_patch.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Literal, cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.tools.filesystem import atomic_write_text, content_sha256, require_workspace_path
+
+_HUNK_HEADER = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?: .*)?(?:\n)?$")
+
+
+@dataclass(frozen=True, slots=True)
+class HunkLine:
+    operation: Literal[" ", "+", "-"]
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class Hunk:
+    old_start: int
+    old_count: int
+    new_start: int
+    new_count: int
+    lines: tuple[HunkLine, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class FilePatch:
+    old_path: str | None
+    new_path: str | None
+    hunks: tuple[Hunk, ...]
+
+
+class PatchParseError(ValueError):
+    pass
+
+
+def _parse_path(header: str, prefix: str) -> str | None:
+    if not header.startswith(prefix):
+        raise PatchParseError(f"expected {prefix.strip()} header")
+    raw = header[len(prefix) :].strip().split("\t", 1)[0]
+    if raw == "/dev/null":
+        return None
+    if raw.startswith(("a/", "b/")):
+        raw = raw[2:]
+    path = PurePosixPath(raw)
+    if path.is_absolute() or ".." in path.parts or not path.parts:
+        raise PatchParseError(f"unsafe patch path: {raw}")
+    return str(path)
+
+
+def parse_unified_diff(text: str) -> tuple[FilePatch, ...]:
+    if "GIT binary patch" in text or "Binary files " in text:
+        raise PatchParseError("binary patches are not supported")
+    lines = text.splitlines(keepends=True)
+    files: list[FilePatch] = []
+    index = 0
+    while index < len(lines):
+        if not lines[index].startswith("--- "):
+            index += 1
+            continue
+        old_path = _parse_path(lines[index], "--- ")
+        index += 1
+        if index >= len(lines):
+            raise PatchParseError("missing new file header")
+        new_path = _parse_path(lines[index], "+++ ")
+        index += 1
+        if old_path is None and new_path is None:
+            raise PatchParseError("both patch paths cannot be /dev/null")
+        hunks: list[Hunk] = []
+        while index < len(lines) and not lines[index].startswith("--- "):
+            if lines[index].startswith(("diff --git ", "index ")):
+                index += 1
+                continue
+            match = _HUNK_HEADER.match(lines[index])
+            if match is None:
+                if lines[index].strip():
+                    raise PatchParseError(f"unexpected patch line: {lines[index].rstrip()}")
+                index += 1
+                continue
+            old_start = int(match.group(1))
+            old_count = int(match.group(2) or "1")
+            new_start = int(match.group(3))
+            new_count = int(match.group(4) or "1")
+            index += 1
+            hunk_lines: list[HunkLine] = []
+            while index < len(lines):
+                line = lines[index]
+                if line.startswith(("@@ ", "--- ")):
+                    break
+                if line.startswith("\"):
+                    if not hunk_lines:
+                        raise PatchParseError("orphan no-newline marker")
+                    previous = hunk_lines[-1]
+                    hunk_lines[-1] = HunkLine(previous.operation, previous.content.rstrip("\r\n"))
+                    index += 1
+                    continue
+                if not line or line[0] not in {" ", "+", "-"}:
+                    raise PatchParseError(f"invalid hunk line: {line.rstrip()}")
+                hunk_lines.append(HunkLine(cast(Literal[" ", "+", "-"], line[0]), line[1:]))
+                index += 1
+            actual_old = sum(item.operation != "+" for item in hunk_lines)
+            actual_new = sum(item.operation != "-" for item in hunk_lines)
+            if (actual_old, actual_new) != (old_count, new_count):
+                raise PatchParseError(
+                    f"hunk count mismatch: expected {old_count}/{new_count}, "
+                    f"found {actual_old}/{actual_new}"
+                )
+            hunks.append(Hunk(old_start, old_count, new_start, new_count, tuple(hunk_lines)))
+        if not hunks:
+            raise PatchParseError("file patch has no hunks")
+        files.append(FilePatch(old_path, new_path, tuple(hunks)))
+    if not files:
+        raise PatchParseError("no unified diff file headers found")
+    return tuple(files)
+
+
+def apply_file_patch(content: str, patch: FilePatch) -> str:
+    source = content.splitlines(keepends=True)
+    output: list[str] = []
+    cursor = 0
+    for hunk in patch.hunks:
+        target = max(hunk.old_start - 1, 0)
+        if target < cursor or target > len(source):
+            raise ValueError("hunks overlap or start beyond the source file")
+        output.extend(source[cursor:target])
+        cursor = target
+        for line in hunk.lines:
+            if line.operation in {" ", "-"}:
+                if cursor >= len(source) or source[cursor] != line.content:
+                    raise ValueError(f"patch context does not match source at line {cursor + 1}")
+                if line.operation == " ":
+                    output.append(source[cursor])
+                cursor += 1
+            else:
+                output.append(line.content)
+    output.extend(source[cursor:])
+    return "".join(output)
+
+
+class ApplyPatchInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    patch: str = Field(min_length=1)
+    expected_sha256: dict[str, str] = Field(default_factory=dict[str, str])
+
+
+class ApplyPatchTool:
+    name = "apply_patch"
+    description = "Preflight and atomically apply a bounded multi-file unified diff."
+    input_model = ApplyPatchInput
+    effects = frozenset({ToolEffect.WORKSPACE_WRITE})
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        parsed = cast(ApplyPatchInput, arguments)
+        patches = parse_unified_diff(parsed.patch)
+        planned: list[tuple[FilePatch, Path, str | None, str]] = []
+        for patch in patches:
+            relative = patch.new_path or patch.old_path
+            if relative is None:
+                raise PatchParseError("patch is missing a usable path")
+            path = require_workspace_path(context.workspace, relative)
+            old_content = "" if patch.old_path is None else path.read_text(encoding="utf-8")
+            expected = parsed.expected_sha256.get(relative)
+            actual = content_sha256(old_content) if patch.old_path is not None else None
+            if expected is not None and expected != actual:
+                return ToolResult(
+                    output=f"{relative}: file changed since patch was prepared",
+                    is_error=True,
+                    data={"error": "stale_content", "path": relative, "actual_sha256": actual},
+                )
+            new_content = apply_file_patch(old_content, patch)
+            planned.append((patch, path, None if patch.new_path is None else new_content, relative))
+
+        changes: list[dict[str, object]] = []
+        for patch, path, new_content, relative in planned:
+            if new_content is None:
+                path.unlink()
+                action = "deleted"
+            else:
+                atomic_write_text(path, new_content)
+                action = "created" if patch.old_path is None else "modified"
+            changes.append({"path": relative, "action": action})
+        return ToolResult(
+            output=f"applied patch to {len(changes)} file(s)",
+            data={"changes": changes},
+        )

windcode/tools/ask_user.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import asyncio
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+
+
+class Question(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: str = Field(min_length=1)
+    prompt: str = Field(min_length=1)
+    options: tuple[str, ...] = Field(min_length=2, max_length=3)
+
+
+class AskUserInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    questions: tuple[Question, ...] = Field(min_length=1, max_length=3)
+
+
+class AskUserTool:
+    name = "ask_user"
+    description = "Ask one to three multiple-choice questions through the active run channel."
+    input_model = AskUserInput
+    effects = frozenset({ToolEffect.USER_INTERACTION})
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        parsed = cast(AskUserInput, arguments)
+        if context.request_user is None:
+            return ToolResult(
+                output="no user response channel is available",
+                is_error=True,
+                data={"error": "interaction_unavailable"},
+            )
+        if context.cancelled():
+            raise asyncio.CancelledError
+        payload = tuple(question.model_dump(mode="json") for question in parsed.questions)
+        response = await context.request_user(payload)
+        if not isinstance(response, dict):
+            return ToolResult(
+                output="user response channel returned an invalid response",
+                is_error=True,
+                data={"error": "invalid_user_response"},
+            )
+        raw_answers = cast(dict[object, object], response)
+        answers = {str(key): str(value) for key, value in raw_answers.items()}
+        expected = {question.id for question in parsed.questions}
+        if set(answers) != expected:
+            return ToolResult(
+                output="user response did not answer every question",
+                is_error=True,
+                data={"error": "incomplete_user_response"},
+            )
+        return ToolResult(output="user answered the questions", data={"answers": answers})