windcode 0.1.0__py3-none-any.whl

windcode/domain/messages.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any, cast
+
+
+class Role(StrEnum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+@dataclass(frozen=True, slots=True)
+class TextBlock:
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningBlock:
+    summary: str
+    opaque: dict[str, Any] = field(default_factory=dict[str, Any], repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCallBlock:
+    call_id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResultBlock:
+    call_id: str
+    name: str
+    content: str
+    is_error: bool = False
+    artifact_ref: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AttachmentBlock:
+    media_type: str
+    reference: str
+    description: str | None = None
+
+
+ContentBlock = TextBlock | ReasoningBlock | ToolCallBlock | ToolResultBlock | AttachmentBlock
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    role: Role
+    content: tuple[ContentBlock, ...]
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    provider_metadata: dict[str, Any] = field(default_factory=dict[str, Any], repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class SourcedContextMessage:
+    source_id: str
+    content: str
+    lifecycle: str = "next_model_step"
+
+
+def message_to_dict(message: Message) -> dict[str, Any]:
+    content: list[dict[str, Any]] = []
+    for block in message.content:
+        if isinstance(block, TextBlock):
+            content.append({"type": "text", "text": block.text})
+        elif isinstance(block, ReasoningBlock):
+            content.append({"type": "reasoning", "summary": block.summary, "opaque": block.opaque})
+        elif isinstance(block, ToolCallBlock):
+            content.append(
+                {
+                    "type": "tool_call",
+                    "call_id": block.call_id,
+                    "name": block.name,
+                    "arguments": block.arguments,
+                }
+            )
+        elif isinstance(block, ToolResultBlock):
+            content.append(
+                {
+                    "type": "tool_result",
+                    "call_id": block.call_id,
+                    "name": block.name,
+                    "content": block.content,
+                    "is_error": block.is_error,
+                    "artifact_ref": block.artifact_ref,
+                }
+            )
+        else:
+            content.append(
+                {
+                    "type": "attachment",
+                    "media_type": block.media_type,
+                    "reference": block.reference,
+                    "description": block.description,
+                }
+            )
+    return {
+        "role": message.role.value,
+        "content": content,
+        "created_at": message.created_at.isoformat(),
+        "provider_metadata": message.provider_metadata,
+    }
+
+
+def heal_dangling_tool_calls(messages: tuple[Message, ...]) -> tuple[Message, ...]:
+    """Ensure every assistant tool_call is answered by a tool result.
+
+    A run that is cancelled or fails after the assistant tool_calls message is
+    persisted but before tool results are recorded leaves a dangling tool call.
+    OpenAI-compatible providers reject such transcripts, so synthesize a
+    cancelled tool result for any call id that has no matching result.
+    """
+
+    healed: list[Message] = []
+    index = 0
+    total = len(messages)
+    while index < total:
+        message = messages[index]
+        healed.append(message)
+        call_blocks = [block for block in message.content if isinstance(block, ToolCallBlock)]
+        if message.role is not Role.ASSISTANT or not call_blocks:
+            index += 1
+            continue
+        required = {block.call_id: block.name for block in call_blocks}
+        answered: set[str] = set()
+        cursor = index + 1
+        while cursor < total and messages[cursor].role is Role.TOOL:
+            healed.append(messages[cursor])
+            answered.update(
+                block.call_id
+                for block in messages[cursor].content
+                if isinstance(block, ToolResultBlock)
+            )
+            cursor += 1
+        missing = [call_id for call_id in required if call_id not in answered]
+        if missing:
+            healed.append(
+                Message(
+                    Role.TOOL,
+                    tuple(
+                        ToolResultBlock(
+                            call_id,
+                            required[call_id],
+                            "Tool call was interrupted before it produced a result.",
+                            is_error=True,
+                        )
+                        for call_id in missing
+                    ),
+                )
+            )
+        index = cursor
+    return tuple(healed)
+
+
+def _object_mapping(value: object) -> dict[str, object]:
+    if not isinstance(value, Mapping):
+        raise ValueError("message value must be an object")
+    raw = cast(Mapping[object, object], value)
+    return {str(key): item for key, item in raw.items()}
+
+
+def message_from_dict(value: Mapping[str, object]) -> Message:
+    raw_content = value.get("content")
+    if not isinstance(raw_content, list):
+        raise ValueError("message content must be a list")
+    blocks: list[ContentBlock] = []
+    for raw_block in cast(list[object], raw_content):
+        block = _object_mapping(raw_block)
+        block_type = str(block.get("type", ""))
+        if block_type == "text":
+            blocks.append(TextBlock(str(block.get("text", ""))))
+        elif block_type == "reasoning":
+            blocks.append(
+                ReasoningBlock(
+                    str(block.get("summary", "")),
+                    cast(dict[str, Any], _object_mapping(block.get("opaque", {}))),
+                )
+            )
+        elif block_type == "tool_call":
+            blocks.append(
+                ToolCallBlock(
+                    str(block.get("call_id", "")),
+                    str(block.get("name", "")),
+                    cast(dict[str, Any], _object_mapping(block.get("arguments", {}))),
+                )
+            )
+        elif block_type == "tool_result":
+            artifact = block.get("artifact_ref")
+            blocks.append(
+                ToolResultBlock(
+                    str(block.get("call_id", "")),
+                    str(block.get("name", "")),
+                    str(block.get("content", "")),
+                    bool(block.get("is_error", False)),
+                    None if artifact is None else str(artifact),
+                )
+            )
+        elif block_type == "attachment":
+            description = block.get("description")
+            blocks.append(
+                AttachmentBlock(
+                    str(block.get("media_type", "application/octet-stream")),
+                    str(block.get("reference", "")),
+                    None if description is None else str(description),
+                )
+            )
+        else:
+            raise ValueError(f"unknown content block type: {block_type}")
+    metadata = _object_mapping(value.get("provider_metadata", {}))
+    created = value.get("created_at")
+    return Message(
+        role=Role(str(value["role"])),
+        content=tuple(blocks),
+        created_at=(
+            datetime.fromisoformat(created) if isinstance(created, str) else datetime.now(UTC)
+        ),
+        provider_metadata=cast(dict[str, Any], metadata),
+    )

windcode/domain/models.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from windcode.domain.messages import Message
+
+
+class StopReason(StrEnum):
+    STOP = "stop"
+    TOOL_USE = "tool_use"
+    MAX_TOKENS = "max_tokens"
+    CONTENT_FILTER = "content_filter"
+    CANCELLED = "cancelled"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSchema:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelRequest:
+    model: str
+    messages: tuple[Message, ...]
+    system_prompt: str
+    tools: tuple[ToolSchema, ...] = ()
+    max_output_tokens: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict[str, Any])
+
+
+@dataclass(frozen=True, slots=True)
+class TextDelta:
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningDelta:
+    summary: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCallDelta:
+    call_id: str
+    name: str
+    arguments_delta: str
+
+
+@dataclass(frozen=True, slots=True)
+class ModelUsage:
+    usage: Usage
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCompleted:
+    reason: StopReason
+    usage: Usage = field(default_factory=Usage)
+    opaque: dict[str, Any] = field(default_factory=dict[str, Any], repr=False)
+
+
+ModelEvent = TextDelta | ReasoningDelta | ToolCallDelta | ModelUsage | ModelCompleted

windcode/domain/subagents.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, cast
+
+from windcode.domain.models import Usage
+
+_TASK_NAME = re.compile(r"^[a-z0-9]+(?:_[a-z0-9]+)*$")
+
+
+class SubagentRole(StrEnum):
+    RESEARCHER = "researcher"
+    WORKER = "worker"
+    VERIFIER = "verifier"
+
+
+class SubagentTaskKind(StrEnum):
+    READ = "read"
+    WRITE = "write"
+
+
+class SubagentStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    BLOCKED = "blocked"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    CONFLICT = "conflict"
+    INTEGRATION_FAILED = "integration_failed"
+    INTEGRATED = "integrated"
+
+
+TERMINAL_SUBAGENT_STATUSES = frozenset(
+    {
+        SubagentStatus.BLOCKED,
+        SubagentStatus.FAILED,
+        SubagentStatus.CANCELLED,
+        SubagentStatus.CONFLICT,
+        SubagentStatus.INTEGRATION_FAILED,
+        SubagentStatus.INTEGRATED,
+    }
+)
+
+_ALLOWED_TRANSITIONS: dict[SubagentStatus, frozenset[SubagentStatus]] = {
+    SubagentStatus.QUEUED: frozenset({SubagentStatus.RUNNING, SubagentStatus.CANCELLED}),
+    SubagentStatus.RUNNING: frozenset(
+        {
+            SubagentStatus.BLOCKED,
+            SubagentStatus.COMPLETED,
+            SubagentStatus.FAILED,
+            SubagentStatus.CANCELLED,
+        }
+    ),
+    SubagentStatus.COMPLETED: frozenset(
+        {
+            SubagentStatus.INTEGRATED,
+            SubagentStatus.CONFLICT,
+            SubagentStatus.INTEGRATION_FAILED,
+        }
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class SubagentTaskSpec:
+    task_name: str
+    role: SubagentRole
+    kind: SubagentTaskKind
+    goal: str
+    context: str
+    expected_output: str
+    verification: tuple[str, ...]
+    allowed_tools: frozenset[str] | None = None
+    model: str | None = None
+    requires_network: bool = False
+
+    def __post_init__(self) -> None:
+        if not _TASK_NAME.fullmatch(self.task_name):
+            raise ValueError("task_name must contain lowercase letters, numbers, and underscores")
+        for name, value in (
+            ("goal", self.goal),
+            ("context", self.context),
+            ("expected_output", self.expected_output),
+        ):
+            if not value.strip():
+                raise ValueError(f"{name} must not be empty")
+        if not self.verification or any(not command.strip() for command in self.verification):
+            raise ValueError("verification must contain at least one non-empty requirement")
+        if self.kind is SubagentTaskKind.WRITE and self.role is not SubagentRole.WORKER:
+            raise ValueError(f"role {self.role.value} does not allow write tasks")
+        if self.allowed_tools is not None and any(not name for name in self.allowed_tools):
+            raise ValueError("allowed_tools cannot contain empty names")
+
+
+@dataclass(frozen=True, slots=True)
+class SubagentRecord:
+    subagent_id: str
+    parent_session_id: str
+    parent_run_id: str
+    task_index: int
+    spec: SubagentTaskSpec
+    status: SubagentStatus = SubagentStatus.QUEUED
+    child_session_id: str | None = None
+    base_commit: str | None = None
+    branch: str | None = None
+    worktree_path: Path | None = None
+    commit: str | None = None
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    error_category: str | None = None
+    error_message: str | None = None
+
+
+def transition_subagent(
+    record: SubagentRecord,
+    status: SubagentStatus,
+    *,
+    now: datetime | None = None,
+    error_category: str | None = None,
+    error_message: str | None = None,
+) -> SubagentRecord:
+    if status not in _ALLOWED_TRANSITIONS.get(record.status, frozenset()):
+        raise ValueError(
+            f"invalid subagent status transition: {record.status.value} -> {status.value}"
+        )
+    changed_at = now or datetime.now(UTC)
+    return replace(
+        record,
+        status=status,
+        started_at=changed_at if status is SubagentStatus.RUNNING else record.started_at,
+        finished_at=changed_at
+        if status not in {SubagentStatus.QUEUED, SubagentStatus.RUNNING}
+        else None,
+        error_category=error_category,
+        error_message=error_message,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class VerificationResult:
+    command: str
+    exit_code: int | None
+    output_summary: str
+    passed: bool
+
+
+@dataclass(frozen=True, slots=True)
+class SubagentResult:
+    subagent_id: str
+    task_name: str
+    status: SubagentStatus
+    summary: str
+    changed_files: tuple[str, ...] = ()
+    commit: str | None = None
+    verification: tuple[VerificationResult, ...] = ()
+    usage: Usage = field(default_factory=Usage)
+    error_category: str | None = None
+    error_message: str | None = None
+
+
+def sort_subagent_records(records: tuple[SubagentRecord, ...]) -> tuple[SubagentRecord, ...]:
+    return tuple(sorted(records, key=lambda record: record.task_index))
+
+
+def subagent_record_to_dict(record: SubagentRecord) -> dict[str, Any]:
+    spec = record.spec
+    return {
+        "subagent_id": record.subagent_id,
+        "parent_session_id": record.parent_session_id,
+        "parent_run_id": record.parent_run_id,
+        "child_session_id": record.child_session_id,
+        "task_index": record.task_index,
+        "spec": {
+            "task_name": spec.task_name,
+            "role": spec.role.value,
+            "kind": spec.kind.value,
+            "goal": spec.goal,
+            "context": spec.context,
+            "expected_output": spec.expected_output,
+            "verification": list(spec.verification),
+            "allowed_tools": None if spec.allowed_tools is None else sorted(spec.allowed_tools),
+            "model": spec.model,
+            "requires_network": spec.requires_network,
+        },
+        "status": record.status.value,
+        "base_commit": record.base_commit,
+        "branch": record.branch,
+        "worktree_path": None if record.worktree_path is None else str(record.worktree_path),
+        "commit": record.commit,
+        "created_at": record.created_at.isoformat(),
+        "started_at": None if record.started_at is None else record.started_at.isoformat(),
+        "finished_at": None if record.finished_at is None else record.finished_at.isoformat(),
+        "error_category": record.error_category,
+        "error_message": record.error_message,
+    }
+
+
+def subagent_record_from_dict(value: Mapping[str, object]) -> SubagentRecord:
+    raw_spec = value.get("spec")
+    if not isinstance(raw_spec, Mapping):
+        raise ValueError("subagent record spec must be an object")
+    spec_values = cast(Mapping[str, object], raw_spec)
+    verification_value = spec_values.get("verification", ())
+    allowed_tools = spec_values.get("allowed_tools")
+    if not isinstance(verification_value, (list, tuple)):
+        raise ValueError("subagent verification must be a sequence")
+    if allowed_tools is not None and not isinstance(allowed_tools, (list, tuple, set, frozenset)):
+        raise ValueError("subagent allowed_tools must be a sequence")
+    verification = cast(Sequence[object], verification_value)
+    allowed_tool_values = None if allowed_tools is None else cast(Sequence[object], allowed_tools)
+    spec = SubagentTaskSpec(
+        task_name=str(spec_values["task_name"]),
+        role=SubagentRole(str(spec_values["role"])),
+        kind=SubagentTaskKind(str(spec_values["kind"])),
+        goal=str(spec_values["goal"]),
+        context=str(spec_values["context"]),
+        expected_output=str(spec_values["expected_output"]),
+        verification=tuple(str(item) for item in verification),
+        allowed_tools=(
+            None
+            if allowed_tool_values is None
+            else frozenset(str(item) for item in allowed_tool_values)
+        ),
+        model=None if spec_values.get("model") is None else str(spec_values.get("model")),
+        requires_network=bool(spec_values.get("requires_network", False)),
+    )
+
+    def optional_time(name: str) -> datetime | None:
+        item = value.get(name)
+        return None if item is None else datetime.fromisoformat(str(item))
+
+    path = value.get("worktree_path")
+    return SubagentRecord(
+        subagent_id=str(value["subagent_id"]),
+        parent_session_id=str(value["parent_session_id"]),
+        parent_run_id=str(value["parent_run_id"]),
+        child_session_id=(
+            None if value.get("child_session_id") is None else str(value.get("child_session_id"))
+        ),
+        task_index=int(str(value["task_index"])),
+        spec=spec,
+        status=SubagentStatus(str(value["status"])),
+        base_commit=None if value.get("base_commit") is None else str(value.get("base_commit")),
+        branch=None if value.get("branch") is None else str(value.get("branch")),
+        worktree_path=None if path is None else Path(str(path)),
+        commit=None if value.get("commit") is None else str(value.get("commit")),
+        created_at=datetime.fromisoformat(str(value["created_at"])),
+        started_at=optional_time("started_at"),
+        finished_at=optional_time("finished_at"),
+        error_category=(
+            None if value.get("error_category") is None else str(value.get("error_category"))
+        ),
+        error_message=(
+            None if value.get("error_message") is None else str(value.get("error_message"))
+        ),
+    )

windcode/domain/tools.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Protocol
+
+from pydantic import BaseModel
+
+
+class ToolEffect(StrEnum):
+    READ = "read"
+    WORKSPACE_WRITE = "workspace_write"
+    PROCESS = "process"
+    NETWORK = "network"
+    OUTSIDE_WORKSPACE = "outside_workspace"
+    USER_INTERACTION = "user_interaction"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolContext:
+    workspace: Path
+    run_id: str
+    cancelled: Callable[[], bool]
+    progress: Callable[[str], Awaitable[None]] | None = None
+    request_user: Callable[[object], Awaitable[object]] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResult:
+    output: str
+    is_error: bool = False
+    artifact_ref: str | None = None
+    elapsed_seconds: float = 0.0
+    data: dict[str, Any] = field(default_factory=dict[str, Any])
+
+
+class Tool(Protocol):
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def description(self) -> str: ...
+
+    @property
+    def input_model(self) -> type[BaseModel]: ...
+
+    @property
+    def effects(self) -> frozenset[ToolEffect]: ...
+
+    def execute(self, context: ToolContext, arguments: BaseModel) -> Awaitable[ToolResult]: ...
+
+
+ValidatedArguments = BaseModel | Mapping[str, Any]

windcode/extensions/__init__.py

@@ -0,0 +1,27 @@
+from windcode.extensions.models import (
+    ActivationState,
+    CapabilityKind,
+    CapabilityRecord,
+    Diagnostic,
+    DiagnosticSeverity,
+    DiagnosticStage,
+    ExtensionScope,
+    ExtensionSnapshot,
+    ExtensionSource,
+    ManagementResult,
+    PermissionRequirement,
+)
+
+__all__ = [
+    "ActivationState",
+    "CapabilityKind",
+    "CapabilityRecord",
+    "Diagnostic",
+    "DiagnosticSeverity",
+    "DiagnosticStage",
+    "ExtensionScope",
+    "ExtensionSnapshot",
+    "ExtensionSource",
+    "ManagementResult",
+    "PermissionRequirement",
+]

windcode/extensions/commands.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from windcode.extensions.plugins.manifest import PluginCommand
+
+
+@dataclass(frozen=True, slots=True)
+class CommandRoute:
+    name: str
+    target: str
+    source_id: str
+
+
+def build_command_catalog(
+    commands: tuple[tuple[str, PluginCommand], ...], *, reserved: frozenset[str] = frozenset()
+) -> tuple[CommandRoute, ...]:
+    catalog: dict[str, CommandRoute] = {}
+    for source_id, command in sorted(commands, key=lambda item: (item[1].name, item[0])):
+        if command.name in reserved:
+            raise ValueError(f"plugin command conflicts with built-in command: {command.name}")
+        if command.name in catalog:
+            raise ValueError(f"duplicate plugin command: {command.name}")
+        catalog[command.name] = CommandRoute(command.name, command.target, source_id)
+    return tuple(catalog.values())