mycode-coding-agent 0.1.0__py3-none-any.whl

mycode/application/__init__.py

@@ -0,0 +1,38 @@
+"""Application-layer runtime assembly and single-turn use cases."""
+
+from mycode.application.agent_session import (
+    AgentApplicationSession,
+    CompactResult,
+    ContextStatus,
+    start_agent_application_session,
+)
+from mycode.application.events import RuntimeEvent, RuntimeEventType
+from mycode.application.runtime import (
+    build_agent_runner,
+    context_budget_from_config,
+    run_agent_turn,
+)
+from mycode.application.sessions import (
+    ActiveProjectSession,
+    SessionStartRequest,
+    delete_project_session,
+    list_project_sessions,
+    start_project_session,
+)
+
+__all__ = [
+    "ActiveProjectSession",
+    "AgentApplicationSession",
+    "CompactResult",
+    "ContextStatus",
+    "RuntimeEvent",
+    "RuntimeEventType",
+    "SessionStartRequest",
+    "build_agent_runner",
+    "context_budget_from_config",
+    "delete_project_session",
+    "list_project_sessions",
+    "run_agent_turn",
+    "start_agent_application_session",
+    "start_project_session",
+]

mycode/application/agent_session.py

@@ -0,0 +1,367 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from typing import Literal
+
+from mycode.agent.events import AgentEvent
+from mycode.agent.outcome import AgentRunOutcome
+from mycode.agent.runner import AgentRunner
+from mycode.application.events import RuntimeEvent
+from mycode.application.runtime import build_agent_runner, run_agent_turn
+from mycode.context.budget import ModelContext
+from mycode.error_handling import error_summary
+from mycode.application.sessions import (
+    ActiveProjectSession,
+    SessionStartRequest,
+    start_project_session,
+)
+from mycode.config import LLMConfig
+from mycode.mcp import MCPConfig, MCPManager
+from mycode.observability import ObservationSink
+from mycode.permissions import Confirmer
+from mycode.persistence.session_store import SessionStore
+from mycode.project import ProjectIdentity
+from mycode.subagents.observability import CompositeSubAgentObserver, SubAgentObserver
+from mycode.subagents.persistence import SessionSubAgentObserver
+
+
+RuntimeEventHandler = Callable[[RuntimeEvent], None]
+CompactResultStatus = Literal["compacted", "skipped", "failed"]
+
+
+@dataclass(frozen=True)
+class ContextStatus:
+    """Content-free, serializable inspection of the current context."""
+
+    estimated_input_tokens: int
+    context_window_tokens: int
+    max_input_tokens: int
+    reserved_output_tokens: int
+    safety_margin_tokens: int
+    estimate_source: str
+    last_provider_prompt_tokens: int | None
+    source_message_count: int
+    model_visible_message_count: int
+    memory_entry_count: int
+    memory_estimated_tokens: int
+    compact_status: str
+    compact_covered_message_count: int
+    compressed_tool_result_count: int
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "estimated": True,
+            "estimated_input_tokens": self.estimated_input_tokens,
+            "context_window_tokens": self.context_window_tokens,
+            "max_input_tokens": self.max_input_tokens,
+            "reserved_output_tokens": self.reserved_output_tokens,
+            "safety_margin_tokens": self.safety_margin_tokens,
+            "estimate_source": self.estimate_source,
+            "last_provider_prompt_tokens": self.last_provider_prompt_tokens,
+            "source_message_count": self.source_message_count,
+            "model_visible_message_count": self.model_visible_message_count,
+            "memory_entry_count": self.memory_entry_count,
+            "memory_estimated_tokens": self.memory_estimated_tokens,
+            "compact_status": self.compact_status,
+            "compact_covered_message_count": self.compact_covered_message_count,
+            "compressed_tool_result_count": self.compressed_tool_result_count,
+        }
+
+
+@dataclass(frozen=True)
+class CompactResult:
+    status: CompactResultStatus
+    reason: str | None
+    before: ContextStatus | None
+    after: ContextStatus | None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "status": self.status,
+            "reason": self.reason,
+            "before": None if self.before is None else self.before.to_dict(),
+            "after": None if self.after is None else self.after.to_dict(),
+        }
+
+
+def _context_status(
+    context: ModelContext,
+    *,
+    context_window_tokens: int,
+    reserved_output_tokens: int,
+    safety_margin_tokens: int,
+    last_provider_prompt_tokens: int | None,
+) -> ContextStatus:
+    memory = context.memory_stats
+    compact = context.compact_stats
+    if compact is None or compact.boundary_id is None:
+        compact_status = "none"
+        compact_covered_message_count = 0
+    elif compact.summary_visible:
+        compact_status = "active"
+        compact_covered_message_count = compact.compacted_message_count
+    else:
+        compact_status = compact.status
+        compact_covered_message_count = compact.compacted_message_count
+    return ContextStatus(
+        estimated_input_tokens=context.estimate.estimated_input_tokens,
+        context_window_tokens=context_window_tokens,
+        max_input_tokens=context.estimate.max_input_tokens,
+        reserved_output_tokens=reserved_output_tokens,
+        safety_margin_tokens=safety_margin_tokens,
+        estimate_source=context.estimate.token_estimate_source,
+        last_provider_prompt_tokens=last_provider_prompt_tokens,
+        source_message_count=context.source_message_count,
+        model_visible_message_count=context.selected_message_count,
+        memory_entry_count=(0 if memory is None else memory.included_entry_count),
+        memory_estimated_tokens=(0 if memory is None else memory.estimated_tokens),
+        compact_status=compact_status,
+        compact_covered_message_count=compact_covered_message_count,
+        compressed_tool_result_count=context.compressed_tool_result_count,
+    )
+
+
+@dataclass
+class AgentApplicationSession:
+    runner: AgentRunner
+    active_project_session: ActiveProjectSession
+    mcp_manager: MCPManager
+    _cleaned_up: bool = field(default=False, init=False, repr=False)
+
+    @property
+    def compact_state_recovered(self) -> bool:
+        return self.active_project_session.compact_state_recovered
+
+    @property
+    def mcp_statuses(self):
+        return self.mcp_manager.statuses
+
+    def get_context_status(self) -> ContextStatus:
+        """Recompute current Context statistics without invoking an LLM."""
+        self._ensure_active()
+        context = self.runner.inspect_context()
+        return _context_status(
+            context,
+            context_window_tokens=self.runner.context_budget.context_window_tokens,
+            reserved_output_tokens=self.runner.context_budget.reserved_output_tokens,
+            safety_margin_tokens=self.runner.context_budget.safety_margin_tokens,
+            last_provider_prompt_tokens=(
+                None
+                if self.runner.last_token_usage is None
+                else self.runner.last_token_usage.prompt_tokens
+            ),
+        )
+
+    def compact_context(self) -> CompactResult:
+        """Run one manual Compact and return a safe structured outcome."""
+        self._ensure_active()
+        before: ContextStatus | None = None
+        try:
+            before = self.get_context_status()
+            context = self.runner.compact_context()
+            compact = context.compact_stats
+            if compact is None:
+                raise RuntimeError("Compact returned no statistics.")
+            operation_status = compact.status
+            if operation_status == "compacted":
+                result_status: CompactResultStatus = "compacted"
+                reason = None
+            elif operation_status in {
+                "insufficient_history",
+                "cooldown",
+                "circuit_open",
+            }:
+                result_status = "skipped"
+                reason = operation_status
+            elif operation_status in {"failed", "invalid_boundary"}:
+                result_status = "failed"
+                compactor = getattr(self.runner, "compactor", None)
+                reason = (
+                    None
+                    if compactor is None
+                    else compactor.state.last_failure_reason
+                ) or operation_status
+            else:
+                raise RuntimeError(
+                    f"Unexpected manual Compact status: {operation_status}."
+                )
+            after = _context_status(
+                context,
+                context_window_tokens=self.runner.context_budget.context_window_tokens,
+                reserved_output_tokens=self.runner.context_budget.reserved_output_tokens,
+                safety_margin_tokens=self.runner.context_budget.safety_margin_tokens,
+                last_provider_prompt_tokens=(
+                    None
+                    if self.runner.last_token_usage is None
+                    else self.runner.last_token_usage.prompt_tokens
+                ),
+            )
+            return CompactResult(
+                status=result_status,
+                reason=reason,
+                before=before,
+                after=after,
+            )
+        except Exception as error:  # noqa: BLE001 - application command boundary
+            return CompactResult(
+                status="failed",
+                reason=error_summary(error),
+                before=before,
+                after=(
+                    self._safe_context_status(before)
+                    if before is not None
+                    else None
+                ),
+            )
+
+    def _ensure_active(self) -> None:
+        if self._cleaned_up:
+            raise RuntimeError(
+                "AgentApplicationSession is already closed or interrupted."
+            )
+
+    def _safe_context_status(self, fallback: ContextStatus) -> ContextStatus:
+        try:
+            return self.get_context_status()
+        except Exception:
+            return fallback
+
+    def startup_events(self) -> Iterator[RuntimeEvent]:
+        yield RuntimeEvent(
+            type="runtime_ready",
+            session_id=self.active_project_session.record.id,
+            session_title=self.active_project_session.record.title,
+            session_created=self.active_project_session.created,
+            compact_state_recovered=self.compact_state_recovered,
+            instruction_sources=tuple(
+                getattr(self.runner, "instruction_sources", ())
+            ),
+            instruction_warnings=tuple(
+                getattr(self.runner, "instruction_warnings", ())
+            ),
+            skill_warnings=tuple(getattr(self.runner, "skill_warnings", ())),
+        )
+        for status in self.mcp_statuses:
+            yield RuntimeEvent(type="mcp_status", mcp_status=status)
+
+    def run_turn(
+        self,
+        content: str,
+        *,
+        turn_id: str | None = None,
+        event_handler: RuntimeEventHandler | None = None,
+    ) -> AgentRunOutcome:
+        if self._cleaned_up:
+            raise RuntimeError(
+                "AgentApplicationSession is already closed or interrupted."
+            )
+
+        def handle_agent_event(agent_event: AgentEvent) -> None:
+            if event_handler is not None:
+                event_handler(
+                    RuntimeEvent(
+                        type="agent",
+                        turn_id=turn_id,
+                        agent_event=agent_event,
+                    )
+                )
+
+        outcome = run_agent_turn(
+            self.runner,
+            content,
+            event_handler=handle_agent_event,
+        )
+        if event_handler is not None:
+            event_handler(
+                RuntimeEvent(
+                    type="turn_finished",
+                    turn_id=turn_id,
+                    outcome=outcome,
+                )
+            )
+        return outcome
+
+    def close(self) -> None:
+        self._cleanup("closed")
+
+    def interrupt(self) -> None:
+        """Finalize this session as interrupted and release its resources.
+
+        This does not asynchronously cancel a currently running Agent turn.
+        """
+        self._cleanup("interrupted")
+
+    def _cleanup(self, status: Literal["closed", "interrupted"]) -> None:
+        if self._cleaned_up:
+            return
+        try:
+            if status == "closed":
+                self.active_project_session.close()
+            else:
+                self.active_project_session.interrupt()
+        finally:
+            try:
+                self.mcp_manager.close()
+            finally:
+                self._cleaned_up = True
+
+
+def start_agent_application_session(
+    store: SessionStore,
+    project: ProjectIdentity,
+    *,
+    request: SessionStartRequest,
+    mcp_config: MCPConfig | None = None,
+    confirmer: Confirmer | None = None,
+    external_observer: SubAgentObserver | None = None,
+    llm_config: LLMConfig | None = None,
+    observability_sink: ObservationSink | None = None,
+) -> AgentApplicationSession:
+    active_session = start_project_session(store, project, request=request)
+    mcp_manager: MCPManager | None = None
+    try:
+        conversation_history = active_session.load_history()
+        compact_state = active_session.load_compact_state()
+        mcp_manager = MCPManager(
+            MCPConfig() if mcp_config is None else mcp_config,
+            observability_sink=observability_sink,
+        )
+        mcp_manager.start()
+        session_observer = SessionSubAgentObserver(session=active_session.writer)
+        subagent_observer: SubAgentObserver = session_observer
+        if external_observer is not None:
+            subagent_observer = CompositeSubAgentObserver(
+                observers=(session_observer, external_observer),
+            )
+        runner = build_agent_runner(
+            workspace_path=project.workspace_root,
+            confirmer=confirmer,
+            conversation_history=conversation_history,
+            on_message_added=active_session.persist_message,
+            compact_state=compact_state,
+            on_compact_state_changed=active_session.persist_compact_state,
+            artifact_directory=active_session.artifact_directory,
+            subagent_observer=subagent_observer,
+            llm_config=llm_config,
+            llm_session_id=active_session.record.id,
+            observability_sink=observability_sink,
+        )
+        for tool in mcp_manager.tools:
+            runner.tool_registry.register(tool)
+        return AgentApplicationSession(
+            runner=runner,
+            active_project_session=active_session,
+            mcp_manager=mcp_manager,
+        )
+    except BaseException:
+        if mcp_manager is not None:
+            try:
+                mcp_manager.close()
+            except BaseException:
+                pass
+        try:
+            active_session.interrupt()
+        except BaseException:
+            pass
+        raise

mycode/application/events.py

@@ -0,0 +1,59 @@
+"""Application-facing runtime events."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from mycode.agent.events import AgentEvent
+from mycode.agent.outcome import AgentRunOutcome
+from mycode.mcp.models import MCPServerStatus
+
+
+RuntimeEventType = Literal[
+    "runtime_ready",
+    "mcp_status",
+    "agent",
+    "turn_finished",
+]
+
+
+@dataclass(frozen=True)
+class RuntimeEvent:
+    """Small application boundary wrapper around existing domain events."""
+
+    type: RuntimeEventType
+    turn_id: str | None = None
+    agent_event: AgentEvent | None = None
+    outcome: AgentRunOutcome | None = None
+    mcp_status: MCPServerStatus | None = None
+    session_id: str | None = None
+    session_title: str | None = None
+    session_created: bool | None = None
+    compact_state_recovered: bool | None = None
+    instruction_sources: tuple[str, ...] = ()
+    instruction_warnings: tuple[str, ...] = ()
+    skill_warnings: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.type not in {
+            "runtime_ready",
+            "mcp_status",
+            "agent",
+            "turn_finished",
+        }:
+            raise ValueError(f"Unsupported runtime event type: {self.type}")
+        object.__setattr__(self, "instruction_sources", tuple(self.instruction_sources))
+        object.__setattr__(self, "instruction_warnings", tuple(self.instruction_warnings))
+        object.__setattr__(self, "skill_warnings", tuple(self.skill_warnings))
+
+        if self.type == "agent" and not isinstance(self.agent_event, AgentEvent):
+            raise ValueError("agent runtime events require agent_event")
+        if self.type == "mcp_status" and not isinstance(
+            self.mcp_status, MCPServerStatus
+        ):
+            raise ValueError("mcp_status runtime events require mcp_status")
+        if self.type == "turn_finished" and not isinstance(
+            self.outcome, AgentRunOutcome
+        ):
+            raise ValueError("turn_finished runtime events require outcome")

mycode/application/runtime.py

@@ -0,0 +1,211 @@
+"""Application-layer use cases shared by interactive and automated frontends."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from uuid import uuid4
+
+from mycode.agent.events import AgentEvent, AgentStopReason
+from mycode.context.artifacts import (
+    ReadArtifactTool,
+    ToolResultArtifactStore,
+)
+from mycode.config import LLMConfig, load_llm_config
+from mycode.context.budget import ContextBudget
+from mycode.context.compact import CompactState, ConversationCompactor
+from mycode.conversation import Conversation
+from mycode.instructions import load_instruction_bundle
+from mycode.llm import OpenAICompatibleLLMClient
+from mycode.memory import MemoryStore
+from mycode.memory_context import MemoryContextSelector, MemoryRecallPolicy
+from mycode.messages import Message
+from mycode.observability import ObservationSink
+from mycode.permissions import Confirmer
+from mycode.project import ProjectIdentity
+from mycode.prompts import build_agent_system_prompt
+from mycode.agent.outcome import AgentRunOutcome
+from mycode.agent.runner import AgentRunner
+from mycode.skills import ActiveSkillState, SkillRegistry
+from mycode.subagents.delegate import DelegateTaskTool
+from mycode.subagents.delegation import DelegationToolBatchHandler
+from mycode.subagents.observability import SubAgentObserver
+from mycode.subagents.runtime import SubAgentRuntime
+from mycode.tools import (
+    LoadSkillTool,
+    ReadSkillResourceTool,
+    RunSkillScriptTool,
+    Workspace,
+    create_default_tool_registry,
+)
+
+
+AgentEventHandler = Callable[[AgentEvent], None]
+
+
+def build_agent_runner(
+    workspace_path: Path | None = None,
+    *,
+    confirmer: Confirmer | None = None,
+    conversation_history: Conversation | None = None,
+    on_message_added: Callable[[Message], None] | None = None,
+    compact_state: CompactState | None = None,
+    on_compact_state_changed: Callable[[CompactState], None] | None = None,
+    artifact_directory: Path | None = None,
+    memory_store: MemoryStore | None = None,
+    subagent_observer: SubAgentObserver | None = None,
+    llm_config: LLMConfig | None = None,
+    llm_session_id: str | None = None,
+    observability_sink: ObservationSink | None = None,
+) -> AgentRunner:
+    """Assemble one Agent runtime without coupling it to a presentation layer."""
+    workspace_root = Path.cwd() if workspace_path is None else workspace_path
+    workspace = Workspace(workspace_root)
+    project = ProjectIdentity.from_workspace(workspace.root)
+    effective_memory_store = (
+        MemoryStore(project) if memory_store is None else memory_store
+    )
+    instruction_bundle = load_instruction_bundle(workspace.root)
+    skill_registry = SkillRegistry.discover(workspace.root)
+    active_skill_state = ActiveSkillState()
+    config = (
+        load_llm_config(workspace_root=workspace.root)
+        if llm_config is None
+        else llm_config
+    )
+    effective_llm_session_id = llm_session_id or uuid4().hex
+    client = OpenAICompatibleLLMClient(
+        config=config,
+        session_id=effective_llm_session_id,
+    )
+    summary_client = OpenAICompatibleLLMClient(
+        config=config,
+        model=config.compact_model,
+        thinking_enabled=False,
+        session_id=effective_llm_session_id,
+    )
+    context_budget = context_budget_from_config(config)
+    memory_recall_policy = MemoryRecallPolicy(
+        max_tokens=config.memory_context_tokens,
+    )
+    subagent_runtime = SubAgentRuntime(
+        workspace=workspace,
+        llm_client_factory=lambda: OpenAICompatibleLLMClient(
+            config=config,
+            model=config.subagent_model,
+            session_id=effective_llm_session_id,
+        ),
+        confirmer=confirmer,
+        memory_store=effective_memory_store,
+        memory_recall_policy=memory_recall_policy,
+        context_budget=context_budget,
+        observability_sink=observability_sink,
+    )
+    history_messages = (
+        [] if conversation_history is None else conversation_history.get_messages()
+    )
+    if any(message.role == "system" for message in history_messages):
+        raise ValueError("conversation_history must not contain system messages.")
+    conversation = Conversation.from_messages(
+        [
+            Message(
+                role="system",
+                content=build_agent_system_prompt(
+                    instruction_bundle.to_prompt_text(),
+                    memory_enabled=True,
+                    delegation_enabled=True,
+                    skill_catalog=skill_registry.get_catalog(),
+                ),
+            ),
+            *history_messages,
+        ],
+        on_message_added=on_message_added,
+    )
+    artifact_store = (
+        None
+        if artifact_directory is None
+        else ToolResultArtifactStore(
+            root=artifact_directory,
+            threshold_chars=context_budget.tool_result_compression_threshold_chars,
+        )
+    )
+    extra_tools = []
+    if artifact_store is not None:
+        extra_tools.append(ReadArtifactTool(artifact_store.root))
+    extra_tools.append(
+        DelegateTaskTool(
+            subagent_runtime,
+            observer=subagent_observer,
+        )
+    )
+    if skill_registry.list_skills():
+        extra_tools.extend(
+            [
+                LoadSkillTool(skill_registry, active_skill_state),
+                ReadSkillResourceTool(skill_registry, active_skill_state),
+                RunSkillScriptTool(workspace, skill_registry, active_skill_state),
+            ]
+        )
+    tool_registry = create_default_tool_registry(
+        workspace,
+        confirmer=confirmer,
+        memory_store=effective_memory_store,
+        extra_tools=extra_tools,
+    )
+
+    return AgentRunner(
+        llm_client=client,
+        tool_registry=tool_registry,
+        conversation=conversation,
+        context_budget=context_budget,
+        instruction_sources=tuple(
+            source.label for source in instruction_bundle.sources
+        ),
+        instruction_warnings=tuple(
+            issue.display for issue in instruction_bundle.issues
+        ),
+        skill_warnings=tuple(warning.display for warning in skill_registry.warnings),
+        active_skill_state=active_skill_state,
+        memory_context_selector=MemoryContextSelector(
+            effective_memory_store,
+            policy=memory_recall_policy,
+        ),
+        tool_batch_handler=DelegationToolBatchHandler(),
+        compactor=ConversationCompactor(
+            llm_client=summary_client,
+            state=CompactState() if compact_state is None else compact_state,
+            on_state_changed=on_compact_state_changed,
+            observability_sink=observability_sink,
+            observability_scope="compact",
+        ),
+        tool_result_artifact_store=artifact_store,
+        observability_sink=observability_sink,
+        observability_scope="main",
+    )
+
+
+def run_agent_turn(
+    runner: AgentRunner,
+    content: str,
+    *,
+    event_handler: AgentEventHandler | None = None,
+) -> AgentRunOutcome:
+    """Run one user request, optionally forwarding events to its caller."""
+    stop_reasons: list[AgentStopReason] = []
+    for event in runner.run(content):
+        if event.type == "stop" and event.stop_reason is not None:
+            stop_reasons.append(event.stop_reason)
+        if event_handler is not None:
+            event_handler(event)
+
+    if len(stop_reasons) != 1:
+        return AgentRunOutcome.from_stop_reason(None)
+    return AgentRunOutcome.from_stop_reason(stop_reasons[0])
+
+
+def context_budget_from_config(config: LLMConfig) -> ContextBudget:
+    return ContextBudget(
+        context_window_tokens=config.context_window_tokens,
+        reserved_output_tokens=config.reserved_output_tokens,
+        safety_margin_tokens=config.context_safety_margin_tokens,
+    )