merge: merge origin/gamma/refactor and origin/feature/teamhoa/r05-r06 into feature/delta-team/epic-R04

domain/__init__.py

@@ -1 +1,11 @@
-"""domain/ — Quy tắc nghiệp vụ thuần. KHÔNG import PySide6, không chạm đĩa/mạng."""
+"""Domain layer - pure Python entities, value objects and events.
+
+The innermost layer of the 4-tier architecture (see
+``docs/architecture/ADR-001-layered-architecture.md``). Modules here describe
+WHAT the application is about - a turn of conversation, a model candidate, an
+agent event - and depend on nothing but the standard library.
+
+Hard rule (ADR-001 I1/I2, enforced by ``scripts/check_imports.py``): no imports
+of PySide6/PyQt, and no imports from ``application/``, ``infrastructure/``,
+``presentation/`` or the legacy ``core/``/``ui/`` packages.
+"""

domain/agents/__init__.py

@@ -1 +1,51 @@
 """Domain agents package: turn requests, agent events, and role definitions."""
+
+from .agent_event import (
+    NOTICE_INFO,
+    NOTICE_PROGRESS,
+    NOTICE_WARNING,
+    AgentEvent,
+    AssistantMessageCompletedEvent,
+    ErrorEvent,
+    HistoryReadyEvent,
+    NoticeEvent,
+    OutputsAddedEvent,
+    OutputsRemovedEvent,
+    PlanStep,
+    PlanUpdatedEvent,
+    ReasoningChunkEvent,
+    TextChunkEvent,
+    ToolCallFinishedEvent,
+    ToolCallStartedEvent,
+    ToolOutputChunkEvent,
+    ToolPreview,
+    TurnCompletedEvent,
+)
+from .conversation_execution_request import (
+    PREFIX_SEPARATOR,
+    ConversationExecutionRequest,
+)
+
+__all__ = [
+    "NOTICE_INFO",
+    "NOTICE_PROGRESS",
+    "NOTICE_WARNING",
+    "PREFIX_SEPARATOR",
+    "AgentEvent",
+    "AssistantMessageCompletedEvent",
+    "ConversationExecutionRequest",
+    "ErrorEvent",
+    "HistoryReadyEvent",
+    "NoticeEvent",
+    "OutputsAddedEvent",
+    "OutputsRemovedEvent",
+    "PlanStep",
+    "PlanUpdatedEvent",
+    "ReasoningChunkEvent",
+    "TextChunkEvent",
+    "ToolCallFinishedEvent",
+    "ToolCallStartedEvent",
+    "ToolOutputChunkEvent",
+    "ToolPreview",
+    "TurnCompletedEvent",
+]

domain/models/__init__.py

@@ -1 +1,13 @@
 """Domain models package: provider descriptors, model pricing, and routing metadata."""
+
+from .provider_descriptor import (
+    AuthKind,
+    ProviderDescriptor,
+    WireProtocol,
+)
+
+__all__ = [
+    "AuthKind",
+    "ProviderDescriptor",
+    "WireProtocol",
+]

domain/tools/__init__.py

@@ -1 +1,18 @@
-"""Domain tools package: tool descriptors, capability scopes, and registry interfaces."""
+"""Domain entities for tool risk classification and lookup (EPIC R05)."""
+
+from .tool_descriptor import ToolCapability, ToolDescriptor
+from .tool_registry import (
+    BUILT_IN_CAPABILITIES,
+    UNKNOWN_SOURCE_CAPABILITIES,
+    ToolRegistry,
+    default_registry,
+)
+
+__all__ = [
+    "ToolCapability",
+    "ToolDescriptor",
+    "ToolRegistry",
+    "BUILT_IN_CAPABILITIES",
+    "UNKNOWN_SOURCE_CAPABILITIES",
+    "default_registry",
+]

domain/tools/tool_descriptor.py

@@ -0,0 +1,86 @@
+"""ToolCapability / ToolDescriptor - the risk-tagged catalogue entry for one
+tool the agent loop can call (R05-T01).
+
+Today a tool is just a name inside ``core/tools.py::TOOL_SPECS`` (a
+``providers.base.ToolSpec`` — name/description/JSON-schema parameters, with
+no notion of risk) plus a hand-written membership test wherever gating is
+needed: ``core/tools.py::WRITE_TOOLS``, ``core/code_agent.py``'s
+``WRITE_TOOLS | MS365_WRITE_TOOLS``, and ``core/chat_agent.py``'s literal
+``name in ("run_command", "install_package")``. Three call sites, three
+independently-maintained lists, and a new tool (or an MCP/connector tool,
+which has no list membership at all - see ``core/mcp_client.py``) is gated
+only if someone remembers to add it everywhere.
+
+``ToolDescriptor`` makes the risk an attribute of the tool itself, declared
+once, so ``application/conversations/tool_policy_gateway.py`` (R05-T03) can
+decide ALLOW/CONFIRM/DENY from data instead of a growing set of literal
+tuples.
+
+Pure domain code: stdlib only, no Qt, no I/O. ``to_spec``/``from_spec`` are
+the only place this module touches something outside domain/, and that
+something (``providers.base.ToolSpec``) is itself a plain dataclass with no
+further dependencies.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Flag, auto
+from typing import Any, Dict
+
+from cowork_local.providers.base import ToolSpec
+
+
+class ToolCapability(Flag):
+    """What calling a tool can do to the machine or the network.
+
+    A ``Flag`` (not a plain ``Enum``) because a single tool can combine risks
+    - ``install_package`` writes to the environment, runs pip as a
+    subprocess, AND needs network access. Composing three separate booleans
+    per call site is exactly the duplication this type replaces.
+    """
+
+    NONE = 0
+    READ = auto()
+    WRITE = auto()
+    EXECUTE = auto()
+    NETWORK = auto()
+
+
+@dataclass(frozen=True)
+class ToolDescriptor:
+    """An immutable description of one callable tool.
+
+    Attributes:
+        name: the identifier the model calls (``ToolSpec.name``).
+        description: shown to the model, unchanged from ``ToolSpec``.
+        parameters: JSON-Schema object for the call's arguments.
+        capabilities: the risk this tool carries - see :class:`ToolCapability`.
+    """
+
+    name: str
+    description: str
+    parameters: Dict[str, Any] = field(default_factory=dict)
+    capabilities: ToolCapability = ToolCapability.NONE
+
+    def has(self, capability: ToolCapability) -> bool:
+        """True when this tool carries (any bit of) ``capability``."""
+        return bool(self.capabilities & capability)
+
+    def to_spec(self) -> ToolSpec:
+        """Project back to the ``ToolSpec`` shape the model-facing catalogue
+        and the provider call actually use - risk tagging is metadata the
+        wire format has no room for."""
+        return ToolSpec(name=self.name, description=self.description,
+                        parameters=self.parameters)
+
+    @classmethod
+    def from_spec(cls, spec: ToolSpec,
+                  capabilities: ToolCapability = ToolCapability.NONE) -> "ToolDescriptor":
+        """Wrap an existing ``ToolSpec`` (built-in, MCP, or connector) with a
+        capability tag. The one place callers attach risk to a spec they did
+        not author themselves."""
+        return cls(name=spec.name, description=spec.description,
+                   parameters=spec.parameters, capabilities=capabilities)
+
+
+__all__ = ["ToolCapability", "ToolDescriptor"]

domain/tools/tool_registry.py

@@ -0,0 +1,125 @@
+"""ToolRegistry - the centralised catalogue every tool source registers into
+(R05-T01).
+
+Built-in file/command/fetch tools (``core/tools.py``), MCP server tools
+(``core/mcp_client.py``) and unified connectors (``core/ext_connectors.py``)
+each produce their own ``List[ToolSpec]`` today, concatenated ad-hoc by
+``core/tools.py::combine_tool_sources``. None of that concatenation carries
+risk information, which is exactly why an MCP tool call reaches
+``core/chat_agent.py`` with no ``ToolDescriptor`` to consult and skips the
+permission gate entirely (the gap R05-T04 closes).
+
+``ToolRegistry`` is the one place a :class:`~domain.tools.tool_descriptor.ToolDescriptor`
+is looked up by name, so a policy gateway - or anything else that needs to ask
+"what can this tool do" - has a single source of truth instead of re-deriving
+it from a spec list.
+
+Pure domain code: stdlib only, no Qt, no I/O.
+"""
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Optional
+
+from cowork_local.providers.base import ToolSpec
+
+from .tool_descriptor import ToolCapability, ToolDescriptor
+
+
+class ToolRegistry:
+    """An in-memory, name-keyed catalogue of :class:`ToolDescriptor`.
+
+    Deliberately mutable and unordered-by-name-only: a turn builds one
+    registry from whichever tool sources it has (built-ins + whatever MCP
+    servers/connectors are enabled), so re-registering the same name simply
+    replaces the previous descriptor rather than raising - the same
+    "last one wins" behaviour ``combine_tool_sources`` already has for
+    duplicate tool names across sources.
+    """
+
+    def __init__(self, descriptors: Optional[Iterable[ToolDescriptor]] = None) -> None:
+        self._by_name: Dict[str, ToolDescriptor] = {}
+        for descriptor in descriptors or ():
+            self.register(descriptor)
+
+    def register(self, descriptor: ToolDescriptor) -> None:
+        self._by_name[descriptor.name] = descriptor
+
+    def get(self, name: str) -> Optional[ToolDescriptor]:
+        return self._by_name.get(name)
+
+    def all(self) -> List[ToolDescriptor]:
+        return list(self._by_name.values())
+
+    def specs(self) -> List[ToolSpec]:
+        """Every registered descriptor, projected back to ``ToolSpec`` - the
+        shape the provider call and the model-facing catalogue need."""
+        return [d.to_spec() for d in self._by_name.values()]
+
+    def capabilities_for(self, name: str) -> ToolCapability:
+        """The capability set for ``name``, or ``NONE`` for an unknown tool.
+
+        Returning ``NONE`` rather than raising lets a policy gateway treat an
+        unregistered tool the same way as one with no declared risk - the
+        gateway's DENY-on-unknown-name rule is a deliberate, separate check,
+        not something this lookup should pre-empt.
+        """
+        descriptor = self._by_name.get(name)
+        return descriptor.capabilities if descriptor is not None else ToolCapability.NONE
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._by_name
+
+    def __len__(self) -> int:
+        return len(self._by_name)
+
+
+# --------------------------------------------------------------------------- #
+# Default capability map for this app's built-in tools (core/tools.py).
+# Kept here, next to the registry, rather than inside core/tools.py itself -
+# core/ is the legacy engine layer being strangled, not where new domain facts
+# should accumulate.
+# --------------------------------------------------------------------------- #
+_CAP = ToolCapability
+BUILT_IN_CAPABILITIES: Dict[str, ToolCapability] = {
+    "read_file": _CAP.READ,
+    "list_dir": _CAP.READ,
+    "write_file": _CAP.WRITE,
+    "edit_file": _CAP.WRITE,
+    "run_command": _CAP.EXECUTE,
+    "install_package": _CAP.WRITE | _CAP.EXECUTE | _CAP.NETWORK,
+    "fetch_url": _CAP.NETWORK,
+    "jira_search": _CAP.NETWORK,
+    "jira_get_issue": _CAP.NETWORK,
+    # Advertised by every engine but has no filesystem/process/network effect
+    # of its own - it only drives the Plan panel (see core/chat_agent.py).
+    "update_plan": _CAP.NONE,
+    "save_file": _CAP.WRITE,
+}
+
+# Tools with no standard, self-declared risk metadata (every MCP server tool,
+# every unified connector) are tagged with this conservative default - see
+# R05-T04. Better to over-gate an unknown remote tool than to silently let it
+# through as READ-only.
+UNKNOWN_SOURCE_CAPABILITIES: ToolCapability = _CAP.WRITE | _CAP.EXECUTE | _CAP.NETWORK
+
+
+def default_registry(specs: Iterable[ToolSpec]) -> ToolRegistry:
+    """Build a registry from ``core/tools.py``'s own ``TOOL_SPECS`` (plus
+    ``save_file``/``update_plan``, which the engines add separately), using
+    :data:`BUILT_IN_CAPABILITIES`. A spec with no entry in that map falls back
+    to :data:`UNKNOWN_SOURCE_CAPABILITIES` - the same conservative default
+    applied to MCP/connector tools, so a built-in nobody has classified yet
+    fails safe instead of silently ungated."""
+    registry = ToolRegistry()
+    for spec in specs:
+        capability = BUILT_IN_CAPABILITIES.get(spec.name, UNKNOWN_SOURCE_CAPABILITIES)
+        registry.register(ToolDescriptor.from_spec(spec, capability))
+    return registry
+
+
+__all__ = [
+    "ToolRegistry",
+    "BUILT_IN_CAPABILITIES",
+    "UNKNOWN_SOURCE_CAPABILITIES",
+    "default_registry",
+]

domain/workspaces/__init__.py

@@ -1 +1,5 @@
-"""Domain workspaces package: immutable WorkspaceSession definitions."""
+"""Domain entities for workspace/project isolation (EPIC R06)."""
+
+from .workspace_session import WorkspaceSession
+
+__all__ = ["WorkspaceSession"]

domain/workspaces/workspace_session.py

@@ -0,0 +1,96 @@
+"""WorkspaceSession - an immutable snapshot of which project a turn belongs
+to and where it may touch the filesystem (R06-T01).
+
+``state.py::AppContext.active_project_id`` is a single mutable field read by
+every background worker thread. ``ui/workspace_tab.py::_load_current`` writes
+it (and the related ``config._project_history_dir``) on the UI thread the
+moment the user switches projects - while a turn already running on a
+worker thread may read either field mid-switch and end up acting on the
+OTHER project's workspace/history for the rest of its run (the race
+R06-T04 fixes).
+
+The fix, same shape as R04's ``ConversationExecutionRequest``: capture the
+workspace facts a turn needs ONCE, on the thread that knows which project is
+selected, into one frozen object. Whatever the user does to the UI afterwards,
+the turn keeps using the workspace it was handed at submit time.
+
+Pure domain code: stdlib only, no Qt, no network. It does touch ``Path`` (not
+plain strings, unlike ``ConversationExecutionRequest``) because its whole job
+is path-containment checking - a snapshot with no room to answer "is this
+path mine" would not replace what ``ToolContext.resolve`` currently does
+inline.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Tuple
+
+
+@dataclass(frozen=True)
+class WorkspaceSession:
+    """Everything a turn needs to know about ITS workspace, fixed at the
+    moment it was submitted.
+
+    Attributes:
+        project_id: the project this turn belongs to (``""`` when no project
+            is selected - e.g. the Code tab, which has no project concept).
+        workspace_root: the project's sandbox root (``Project.workspace_dir()``).
+        sandbox_dir: the ``.scratch`` subtree inside ``workspace_root`` used for
+            generator/helper scripts, never a final deliverable (see
+            ``infrastructure/filesystem/file_tools.py::_flatten_rel``).
+        allowed_paths: every root a tool call may read/write under. Almost
+            always just ``(workspace_root,)``; a project with a custom
+            ``output_dir`` outside the managed workspace tree still resolves
+            to exactly one root - the tuple exists so a future caller (e.g. a
+            step scoped to a shared input folder) can widen it without a
+            shape change.
+    """
+
+    project_id: str
+    workspace_root: Path
+    sandbox_dir: Path
+    allowed_paths: Tuple[Path, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if not self.allowed_paths:
+            object.__setattr__(self, "allowed_paths", (self.workspace_root,))
+
+    @classmethod
+    def from_project(cls, project) -> "WorkspaceSession":
+        """Build a session from a ``core.projects.Project``. ``project`` is
+        typed loosely (not imported) so this module has no dependency on
+        ``core/`` - the caller (``core/projects.py`` itself, or
+        ``application/conversations``) already has the Project in hand."""
+        root = Path(project.workspace_dir())
+        return cls(project_id=project.project_id, workspace_root=root,
+                   sandbox_dir=root / ".scratch", allowed_paths=(root,))
+
+    @classmethod
+    def unscoped(cls, workspace_root: Path) -> "WorkspaceSession":
+        """A session for callers with no project concept (e.g. the Code tab,
+        which sandboxes to a plain folder rather than a ``Project``)."""
+        root = Path(workspace_root)
+        return cls(project_id="", workspace_root=root, sandbox_dir=root / ".scratch")
+
+    def is_allowed(self, path: Path) -> bool:
+        """True when ``path`` resolves inside one of :attr:`allowed_paths`.
+
+        Same containment rule as ``ToolContext.resolve`` (an exact root match
+        or a real descendant), but side-effect-free: it reports the answer
+        instead of raising, so a caller (``FileWorkspaceService``, R06-T05)
+        can decide what "not allowed" means for its own UI instead of
+        catching a ``ToolError``.
+        """
+        try:
+            resolved = Path(path).expanduser().resolve()
+        except OSError:
+            return False
+        for allowed in self.allowed_paths:
+            root = Path(allowed).resolve()
+            if resolved == root or root in resolved.parents:
+                return True
+        return False
+
+
+__all__ = ["WorkspaceSession"]