windcode 0.1.0__py3-none-any.whl

windcode/extensions/discovery.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from windcode.extensions.models import (
+    ActivationState,
+    CapabilityKind,
+    CapabilityRecord,
+    Diagnostic,
+    DiagnosticSeverity,
+    DiagnosticStage,
+    ExtensionScope,
+    ExtensionSource,
+    PermissionRequirement,
+    capability_id,
+)
+from windcode.extensions.skills.parser import parse_skill_metadata
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryRoot:
+    path: Path
+    scope: ExtensionScope
+    trusted: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryResult:
+    records: tuple[CapabilityRecord, ...]
+    definitions: dict[str, Any]
+    diagnostics: tuple[Diagnostic, ...]
+
+
+def discover_skills(
+    roots: tuple[DiscoveryRoot, ...], *, max_metadata_bytes: int = 65_536
+) -> DiscoveryResult:
+    candidates: list[tuple[CapabilityRecord, Any]] = []
+    diagnostics: list[Diagnostic] = []
+    for root in sorted(roots, key=lambda item: (item.scope.value, str(item.path))):
+        if not root.path.exists():
+            continue
+        for directory in sorted(
+            (path for path in root.path.iterdir() if path.is_dir()), key=lambda path: path.name
+        ):
+            source = ExtensionSource(root.scope, directory)
+            try:
+                metadata = parse_skill_metadata(directory, max_bytes=max_metadata_bytes)
+                stable_id = capability_id(CapabilityKind.SKILL, metadata.name)
+                record = CapabilityRecord(
+                    stable_id,
+                    metadata.name,
+                    CapabilityKind.SKILL,
+                    source,
+                    trusted=root.trusted,
+                    activation=ActivationState.AVAILABLE
+                    if root.trusted
+                    else ActivationState.INACTIVE,
+                    permissions=PermissionRequirement(filesystem_read=True),
+                )
+                candidates.append((record, metadata))
+            except (OSError, ValueError) as exc:
+                diagnostics.append(
+                    Diagnostic(
+                        DiagnosticStage.PARSE,
+                        DiagnosticSeverity.ERROR,
+                        "invalid_skill",
+                        str(exc),
+                        source.source_id,
+                        "Fix the Skill metadata or remove this source.",
+                    )
+                )
+
+    grouped: dict[tuple[CapabilityKind, str], list[tuple[CapabilityRecord, Any]]] = {}
+    for candidate in candidates:
+        record = candidate[0]
+        grouped.setdefault((record.kind, record.public_name), []).append(candidate)
+    records: list[CapabilityRecord] = []
+    definitions: dict[str, Any] = {}
+    for key in sorted(grouped, key=lambda item: (item[0].value, item[1])):
+        items = sorted(grouped[key], key=lambda item: item[0].sort_key)
+        by_scope: dict[ExtensionScope, list[tuple[CapabilityRecord, Any]]] = {}
+        for item in items:
+            by_scope.setdefault(item[0].source.scope, []).append(item)
+        conflicted = {scope for scope, values in by_scope.items() if len(values) > 1}
+        eligible = [item for item in items if item[0].source.scope not in conflicted]
+        winner = eligible[-1] if eligible else None
+        for item in items:
+            record, definition = item
+            if record.source.scope in conflicted:
+                diagnostic = Diagnostic(
+                    DiagnosticStage.MERGE,
+                    DiagnosticSeverity.ERROR,
+                    "same_scope_conflict",
+                    f"duplicate {record.kind.value} named {record.public_name}",
+                    record.source.source_id,
+                    "Remove or rename one same-scope definition.",
+                )
+                diagnostics.append(diagnostic)
+                records.append(
+                    CapabilityRecord(
+                        record.capability_id,
+                        record.public_name,
+                        record.kind,
+                        record.source,
+                        record.enabled,
+                        record.trusted,
+                        record.required,
+                        ActivationState.FAILED,
+                        record.permissions,
+                        None,
+                        (diagnostic,),
+                    )
+                )
+            elif winner is not None and record is not winner[0]:
+                records.append(
+                    CapabilityRecord(
+                        record.capability_id,
+                        record.public_name,
+                        record.kind,
+                        record.source,
+                        record.enabled,
+                        record.trusted,
+                        record.required,
+                        ActivationState.INACTIVE,
+                        record.permissions,
+                        winner[0].source.source_id,
+                        record.diagnostics,
+                    )
+                )
+            else:
+                records.append(record)
+                definitions[record.capability_id] = definition
+    return DiscoveryResult(
+        tuple(sorted(records, key=lambda item: item.sort_key)),
+        definitions,
+        tuple(sorted(diagnostics, key=lambda item: (item.source_id, item.category))),
+    )

windcode/extensions/events.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any
+
+from windcode.domain.events import ExtensionEvent
+
+EXTENSION_ACTIONS = frozenset(
+    {
+        "discovery_completed",
+        "diagnostic",
+        "snapshot_reloaded",
+        "capability_activated",
+        "skill_loaded",
+        "mcp_connecting",
+        "mcp_connected",
+        "mcp_called",
+        "mcp_closed",
+        "hook_started",
+        "hook_finished",
+        "hook_rejected",
+        "plugin_state_changed",
+    }
+)
+
+
+def extension_event(
+    *,
+    event_id: str,
+    session_id: str,
+    run_id: str,
+    turn: int,
+    action: str,
+    snapshot_generation: int,
+    extension_id: str,
+    source_id: str,
+    status: str = "",
+    server_id: str | None = None,
+    hook_id: str | None = None,
+    call_id: str | None = None,
+    details: dict[str, Any] | None = None,
+) -> ExtensionEvent:
+    if action not in EXTENSION_ACTIONS:
+        raise ValueError(f"unknown extension event action: {action}")
+    return ExtensionEvent(
+        event_id=event_id,
+        session_id=session_id,
+        run_id=run_id,
+        turn=turn,
+        action=action,
+        snapshot_generation=snapshot_generation,
+        extension_id=extension_id,
+        source_id=source_id,
+        status=status,
+        server_id=server_id,
+        hook_id=hook_id,
+        call_id=call_id,
+        details={} if details is None else dict(details),
+    )

windcode/extensions/hooks/__init__.py

@@ -0,0 +1,4 @@
+from windcode.extensions.hooks.dispatcher import HookDispatcher
+from windcode.extensions.hooks.models import HookContext, HookDefinition, HookEvent
+
+__all__ = ["HookContext", "HookDefinition", "HookDispatcher", "HookEvent"]

windcode/extensions/hooks/dispatcher.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+from windcode.domain.tools import ToolEffect
+from windcode.extensions.hooks.executor import HookExecutor
+from windcode.extensions.hooks.models import HookContext, HookDefinition, HookOutcome
+
+HookObserver = Callable[[str, HookDefinition, HookContext, HookOutcome | None], Awaitable[None]]
+
+
+class HookDispatcher:
+    def __init__(
+        self,
+        hooks: tuple[HookDefinition, ...],
+        executor: HookExecutor,
+        observer: HookObserver | None = None,
+    ) -> None:
+        self.hooks = tuple(sorted(hooks, key=lambda item: item.sort_key))
+        self.executor = executor
+        self._active_sources: set[str] = set()
+        self._background: set[asyncio.Task[HookOutcome]] = set()
+        self._closed = False
+        self.observer = observer
+
+    async def dispatch(self, context: HookContext, *, background: bool = False) -> HookOutcome:
+        if self._closed:
+            raise RuntimeError("Hook dispatcher is closed")
+        matched = tuple(
+            hook
+            for hook in self.hooks
+            if hook.matcher.matches(context)
+            and context.source_id != f"hook:{hook.source_id}/{hook.hook_id}"
+        )
+        if background:
+            required = tuple(hook for hook in matched if hook.required)
+            for hook in required:
+                try:
+                    await self._run_one(hook, context)
+                except (TimeoutError, RuntimeError, ValueError, OSError) as exc:
+                    raise RuntimeError(
+                        f"required Hook failed: {hook.source_id}/{hook.hook_id}: {exc}"
+                    ) from exc
+            for hook in matched:
+                if hook.required:
+                    continue
+                task = asyncio.create_task(self._run_one(hook, context))
+                self._background.add(task)
+            return HookOutcome()
+        rejected: str | None = None
+        effects: set[ToolEffect] = set()
+        notifications: list[str] = []
+        prompts: list[tuple[str, str]] = []
+        diagnostics: list[str] = []
+        for hook in matched:
+            try:
+                outcome = await self._run_one(hook, context)
+            except (TimeoutError, RuntimeError, ValueError, OSError) as exc:
+                diagnostics.append(f"{hook.source_id}/{hook.hook_id}: {exc}")
+                if hook.required:
+                    raise RuntimeError(
+                        f"required Hook failed: {hook.source_id}/{hook.hook_id}: {exc}"
+                    ) from exc
+                if hook.decision_making:
+                    rejected = rejected or "security Hook failed closed"
+                continue
+            rejected = rejected or outcome.rejected
+            effects.update(outcome.additional_effects)
+            notifications.extend(outcome.notifications)
+            prompts.extend(outcome.sourced_prompts)
+            diagnostics.extend(outcome.diagnostics)
+        return HookOutcome(
+            rejected,
+            frozenset(effects),
+            tuple(notifications),
+            tuple(prompts),
+            tuple(diagnostics),
+        )
+
+    async def _run_one(self, hook: HookDefinition, context: HookContext) -> HookOutcome:
+        recursion_key = f"{hook.source_id}/{hook.hook_id}"
+        if recursion_key in self._active_sources:
+            raise RuntimeError("recursive Hook invocation blocked")
+        self._active_sources.add(recursion_key)
+        try:
+            if self.observer is not None:
+                await self.observer("started", hook, context, None)
+            async with asyncio.timeout(hook.timeout_seconds):
+                outcome = await self.executor.execute(hook, context)
+            if self.observer is not None:
+                await self.observer(
+                    "rejected" if outcome.rejected is not None else "finished",
+                    hook,
+                    context,
+                    outcome,
+                )
+            return outcome
+        finally:
+            self._active_sources.discard(recursion_key)
+
+    async def aclose(self) -> None:
+        self._closed = True
+        tasks = tuple(self._background)
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        self._background.clear()

windcode/extensions/hooks/executor.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from windcode.domain.messages import SourcedContextMessage
+from windcode.extensions.hooks.models import (
+    HookContext,
+    HookDefinition,
+    HookOutcome,
+    NotifyAction,
+    PromptAction,
+    RejectAction,
+    TightenAction,
+)
+
+CommandRunner = Callable[[str, str, HookContext], Awaitable[str]]
+
+
+class HookExecutor:
+    def __init__(self, command_runner: CommandRunner | None = None) -> None:
+        self.command_runner = command_runner
+        self.notifications: list[tuple[str, str]] = []
+        self.context_messages: list[SourcedContextMessage] = []
+
+    def drain_context(self) -> tuple[SourcedContextMessage, ...]:
+        messages = tuple(self.context_messages)
+        self.context_messages.clear()
+        return messages
+
+    async def execute(self, hook: HookDefinition, context: HookContext) -> HookOutcome:
+        action = hook.action
+        if isinstance(action, NotifyAction):
+            message = action.message[: hook.output_limit]
+            self.notifications.append((hook.source_id, message))
+            return HookOutcome(notifications=(message,))
+        if isinstance(action, PromptAction):
+            content = action.content[: hook.output_limit]
+            self.context_messages.append(SourcedContextMessage(hook.source_id, content))
+            return HookOutcome(sourced_prompts=((hook.source_id, content),))
+        if isinstance(action, RejectAction):
+            return HookOutcome(rejected=action.reason[: hook.output_limit])
+        if isinstance(action, TightenAction):
+            return HookOutcome(additional_effects=action.effects)
+        if self.command_runner is None:
+            raise RuntimeError("Hook command runner is not configured")
+        output = await self.command_runner(
+            action.command, f"hook:{hook.source_id}/{hook.hook_id}", context
+        )
+        return HookOutcome(notifications=(output[: hook.output_limit],))

windcode/extensions/hooks/loader.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import cast
+
+from windcode.domain.tools import ToolEffect
+from windcode.extensions.hooks.models import (
+    DECISION_EVENTS,
+    CommandAction,
+    HookDefinition,
+    HookEvent,
+    HookMatcher,
+    NotifyAction,
+    PromptAction,
+    RejectAction,
+    TightenAction,
+)
+from windcode.extensions.models import normalize_id
+from windcode.extensions.paths import read_bounded
+
+
+def load_hook_definition(
+    root: Path, relative_path: str, *, source_id: str, max_bytes: int = 65_536
+) -> HookDefinition:
+    try:
+        raw = cast(
+            dict[str, object],
+            tomllib.loads(read_bounded(root, relative_path, max_bytes=max_bytes).decode("utf-8")),
+        )
+    except (UnicodeError, tomllib.TOMLDecodeError) as exc:
+        raise ValueError(f"invalid Hook definition: {exc}") from exc
+    allowed = {
+        "id",
+        "event",
+        "tool_id",
+        "status",
+        "priority",
+        "timeout_seconds",
+        "output_limit",
+        "required",
+        "action",
+    }
+    unknown = set(raw) - allowed
+    if unknown:
+        raise ValueError(f"unknown Hook fields: {', '.join(sorted(unknown))}")
+    hook_id = normalize_id(str(raw.get("id", "")))
+    event = HookEvent(str(raw.get("event", "")))
+    action_raw = raw.get("action")
+    if not isinstance(action_raw, dict):
+        raise ValueError("Hook action must be a table")
+    action_data = cast(dict[str, object], action_raw)
+    action_type = str(action_data.get("type", ""))
+    if action_type == "notify" and set(action_data) == {"type", "message"}:
+        action = NotifyAction(str(action_data["message"]))
+    elif action_type == "prompt" and set(action_data) == {"type", "content"}:
+        action = PromptAction(str(action_data["content"]))
+    elif action_type == "command" and set(action_data) == {"type", "command"}:
+        action = CommandAction(str(action_data["command"]))
+    elif action_type == "reject" and set(action_data) == {"type", "reason"}:
+        action = RejectAction(str(action_data["reason"]))
+    elif action_type == "tighten" and set(action_data) == {"type", "effects"}:
+        effects = action_data["effects"]
+        if not isinstance(effects, list):
+            raise ValueError("tighten effects must be an array")
+        effect_values = cast(list[object], effects)
+        action = TightenAction(frozenset(ToolEffect(str(value)) for value in effect_values))
+    else:
+        raise ValueError(f"invalid Hook action: {action_type}")
+    if isinstance(action, (RejectAction, TightenAction)) and event not in DECISION_EVENTS:
+        raise ValueError("reject and tighten actions are only valid before tool policy")
+    return HookDefinition(
+        hook_id,
+        source_id,
+        HookMatcher(
+            event,
+            None if raw.get("tool_id") is None else str(raw["tool_id"]),
+            None if raw.get("status") is None else str(raw["status"]),
+        ),
+        action,
+        _int_field(raw.get("priority"), 100, "priority"),
+        _float_field(raw.get("timeout_seconds"), 10.0, "timeout_seconds"),
+        _int_field(raw.get("output_limit"), 4096, "output_limit"),
+        bool(raw.get("required", False)),
+    )
+
+
+def _int_field(value: object, default: int, name: str) -> int:
+    if value is None:
+        return default
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"Hook {name} must be an integer")
+    return value
+
+
+def _float_field(value: object, default: float, name: str) -> float:
+    if value is None:
+        return default
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise ValueError(f"Hook {name} must be a number")
+    return float(value)

windcode/extensions/hooks/models.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from windcode.domain.tools import ToolEffect
+
+
+class HookEvent(StrEnum):
+    SESSION_START = "session_start"
+    SESSION_END = "session_end"
+    USER_SUBMIT = "user_submit"
+    RUN_START = "run_start"
+    RUN_END = "run_end"
+    RUN_ERROR = "run_error"
+    TOOL_BEFORE_POLICY = "tool_before_policy"
+    TOOL_AFTER = "tool_after"
+    PERMISSION_REQUEST = "permission_request"
+    COMPACT_BEFORE = "compact_before"
+    COMPACT_AFTER = "compact_after"
+    SUBAGENT_START = "subagent_start"
+    SUBAGENT_END = "subagent_end"
+
+
+DECISION_EVENTS = frozenset({HookEvent.TOOL_BEFORE_POLICY})
+
+
+@dataclass(frozen=True, slots=True)
+class HookContext:
+    version: int
+    event: HookEvent
+    session_id: str
+    run_id: str
+    correlation_id: str
+    source_id: str = "windcode"
+    tool_id: str | None = None
+    status: str | None = None
+    fields: tuple[tuple[str, str | int | float | bool | None], ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class HookMatcher:
+    event: HookEvent
+    tool_id: str | None = None
+    status: str | None = None
+
+    def matches(self, context: HookContext) -> bool:
+        return (
+            context.event is self.event
+            and (self.tool_id is None or self.tool_id == context.tool_id)
+            and (self.status is None or self.status == context.status)
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class NotifyAction:
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class PromptAction:
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class CommandAction:
+    command: str
+
+
+@dataclass(frozen=True, slots=True)
+class RejectAction:
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class TightenAction:
+    effects: frozenset[ToolEffect]
+
+
+HookAction = NotifyAction | PromptAction | CommandAction | RejectAction | TightenAction
+
+
+@dataclass(frozen=True, slots=True)
+class HookDefinition:
+    hook_id: str
+    source_id: str
+    matcher: HookMatcher
+    action: HookAction
+    priority: int = 100
+    timeout_seconds: float = 10.0
+    output_limit: int = 4096
+    required: bool = False
+
+    @property
+    def decision_making(self) -> bool:
+        return isinstance(self.action, (RejectAction, TightenAction))
+
+    @property
+    def sort_key(self) -> tuple[int, str, str]:
+        return (self.priority, self.source_id, self.hook_id)
+
+
+@dataclass(frozen=True, slots=True)
+class HookOutcome:
+    rejected: str | None = None
+    additional_effects: frozenset[ToolEffect] = frozenset()
+    notifications: tuple[str, ...] = ()
+    sourced_prompts: tuple[tuple[str, str], ...] = ()
+    diagnostics: tuple[str, ...] = ()

windcode/extensions/mcp/__init__.py

@@ -0,0 +1,10 @@
+from windcode.extensions.mcp.client import McpClient, ResolvedHttpServer, ResolvedStdioServer
+from windcode.extensions.mcp.runtime import McpRuntime, McpServerState
+
+__all__ = [
+    "McpClient",
+    "McpRuntime",
+    "McpServerState",
+    "ResolvedHttpServer",
+    "ResolvedStdioServer",
+]

windcode/extensions/mcp/adapter.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any, cast
+
+import jsonschema
+from mcp.types import AudioContent, ImageContent, TextContent
+from pydantic import BaseModel, RootModel
+
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.extensions.mcp.catalog import McpToolDefinition, mcp_tool_wire_name
+from windcode.extensions.mcp.runtime import McpRuntime
+from windcode.sessions.artifacts import ArtifactStore
+
+
+class McpArguments(RootModel[dict[str, Any]]):
+    pass
+
+
+class McpToolAdapter:
+    def __init__(
+        self,
+        definition: McpToolDefinition,
+        runtime: McpRuntime,
+        *,
+        artifact_store: ArtifactStore | None = None,
+        output_limit: int = 20_000,
+    ) -> None:
+        self.definition = definition
+        self.runtime = runtime
+        self.artifact_store = artifact_store
+        self.output_limit = output_limit
+
+    @property
+    def name(self) -> str:
+        return mcp_tool_wire_name(self.definition.server_id, self.definition.name)
+
+    @property
+    def description(self) -> str:
+        return self.definition.description or f"MCP tool from {self.definition.server_id}"
+
+    @property
+    def input_model(self) -> type[BaseModel]:
+        return McpArguments
+
+    @property
+    def input_schema(self) -> Mapping[str, Any]:
+        return self.definition.input_schema
+
+    @property
+    def effects(self) -> frozenset[ToolEffect]:
+        return frozenset({ToolEffect.PROCESS, ToolEffect.NETWORK})
+
+    def validate_arguments(self, arguments: Mapping[str, Any]) -> McpArguments:
+        jsonschema.Draft202012Validator(self.definition.input_schema).validate(arguments)  # pyright: ignore[reportUnknownMemberType]
+        return McpArguments(dict(arguments))
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        if context.cancelled():
+            return ToolResult("MCP call cancelled", True, data={"error": "cancelled"})
+        parsed = cast(McpArguments, arguments)
+        result = await self.runtime.call(
+            self.definition.server_id,
+            lambda client: client.call_tool(
+                self.definition.name, cast(dict[str, object], parsed.root)
+            ),
+        )
+        from mcp.types import CallToolResult
+
+        if not isinstance(result, CallToolResult):
+            raise ValueError("invalid MCP call result")
+        parts: list[str] = []
+        for item in result.content:
+            if isinstance(item, TextContent):
+                parts.append(item.text)
+            elif isinstance(item, (ImageContent, AudioContent)):
+                parts.append(f"[{item.type}: {item.mimeType}; base64={item.data}]")
+            else:
+                parts.append(json.dumps(item.model_dump(mode="json"), sort_keys=True))
+        # MCP servers commonly mirror structuredContent into text content for
+        # backwards-compatible clients. Prefer the canonical content when present.
+        if not parts and result.structuredContent is not None:
+            parts.append(json.dumps(result.structuredContent, sort_keys=True))
+        output = "\n".join(parts)
+        artifact_ref: str | None = None
+        if self.artifact_store is not None:
+            output, reference = self.artifact_store.externalize(output, threshold=self.output_limit)
+            artifact_ref = None if reference is None else reference.relative_path
+        elif len(output) > self.output_limit:
+            output = output[: self.output_limit] + "..."
+        return ToolResult(
+            output,
+            is_error=result.isError,
+            artifact_ref=artifact_ref,
+            data={
+                "source": self.definition.server_id,
+                "tool": self.definition.stable_id,
+                "error": "remote_error" if result.isError else None,
+            },
+        )