sgar 0.1.3__py3-none-any.whl

core/__init__.py

@@ -0,0 +1,7 @@
+def str_to_obj(*args, **kwargs):
+    from .utils.common import str_to_obj as _str_to_obj
+
+    return _str_to_obj(*args, **kwargs)
+
+
+__all__ = ["str_to_obj"]

core/cc/__init__.py

@@ -0,0 +1,119 @@
+# ---------------------------------------------------------------------------
+# Public API (stable, recommended for external integrations)
+# ---------------------------------------------------------------------------
+from .audit import (
+    RuntimeAuditQuery,
+    RuntimeAuditSnapshot,
+    RuntimeAuditSummary,
+    query_runtime_audit,
+    read_runtime_audit,
+    summarize_runtime_audit,
+)
+from .api import (
+    AgentRunRequest,
+    AgentRunResult,
+    CodeAgent,
+    CodeBuildRequest,
+    build_code_with_agent,
+    run_code_agent,
+)
+from .config import CCConfig, load_cc_config
+
+# ---------------------------------------------------------------------------
+# Advanced API (stable but lower-level; for fine-grained session control)
+# ---------------------------------------------------------------------------
+from .llm import DefaultLLMClientProvider, LLMClientProvider
+from .runtime import build_default_query_engine
+from .conversation.query_engine import QueryEngine
+from .conversation.session import QuerySession, SessionFactory
+from .conversation.models import SessionEvent, SessionMessage
+
+# ---------------------------------------------------------------------------
+# Middleware pipeline (composable cross-cutting concerns)
+# ---------------------------------------------------------------------------
+from .conversation.middleware import (
+    RetryPolicy,
+    TurnHooks,
+    TurnMiddleware,
+    TurnRunner,
+    apply as apply_middleware,
+    pipe as pipe_middleware,
+    with_compaction,
+    with_hooks,
+    with_persistence,
+    with_retry,
+    with_turn_tracking,
+)
+
+# ---------------------------------------------------------------------------
+# Environment providers (injectable filesystem / shell abstractions)
+# ---------------------------------------------------------------------------
+from .providers import (
+    CommandProvider,
+    Environment,
+    FileSystemProvider,
+    LocalCommandProvider,
+    LocalFileSystemProvider,
+    default_environment,
+)
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+from .errors import (
+    CCError,
+    ConfigError,
+    ToolExecutionError,
+    ToolValidationError,
+)
+
+__all__ = [
+    # -- Public API --
+    "AgentRunRequest",
+    "AgentRunResult",
+    "CCConfig",
+    "CodeAgent",
+    "CodeBuildRequest",
+    "RuntimeAuditQuery",
+    "RuntimeAuditSnapshot",
+    "RuntimeAuditSummary",
+    "build_code_with_agent",
+    "load_cc_config",
+    "query_runtime_audit",
+    "read_runtime_audit",
+    "run_code_agent",
+    "summarize_runtime_audit",
+    # -- Advanced API --
+    "DefaultLLMClientProvider",
+    "LLMClientProvider",
+    "QueryEngine",
+    "QuerySession",
+    "SessionEvent",
+    "SessionFactory",
+    "SessionMessage",
+    "build_default_query_engine",
+    # -- Middleware pipeline --
+    "RetryPolicy",
+    "TurnHooks",
+    "TurnMiddleware",
+    "TurnRunner",
+    "apply_middleware",
+    "pipe_middleware",
+    "with_compaction",
+    "with_hooks",
+    "with_persistence",
+    "with_retry",
+    "with_turn_tracking",
+    # -- Environment providers --
+    "CommandProvider",
+    "Environment",
+    "FileSystemProvider",
+    "LocalCommandProvider",
+    "LocalFileSystemProvider",
+    "default_environment",
+    # -- Errors --
+    "CCError",
+    "ConfigError",
+    "ToolExecutionError",
+    "ToolValidationError",
+]

core/cc/agents/__init__.py

@@ -0,0 +1,10 @@
+from .definitions import AgentDefinition
+from .task_manager import TaskManager
+from .task_model import AgentTask, AgentTaskStatus
+
+__all__ = [
+    "AgentDefinition",
+    "AgentTask",
+    "AgentTaskStatus",
+    "TaskManager",
+]

core/cc/agents/agent_tool.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+import os
+from typing import Any
+import asyncio
+
+from ..agents.backends import InProcessBackend, LocalSubprocessBackend, RuntimeBackend
+from ..config import CCConfig
+from ..conversation.session import QuerySession, SessionFactory
+from ..llm import DefaultLLMClientProvider, LLMClientProvider
+from ..observability import EventRecord, JsonlAuditLogger
+from ..tools.base import BaseTool, ToolCall, ToolResult, ToolSpec, ValidationResult
+from ..tools.context import ToolUseContext
+from .definitions import AgentDefinition
+from .runtime import AgentRuntime
+from .runtime_registry import InProcessRuntimeRegistry, get_in_process_runtime_registry
+from .task_manager import TaskManager
+from .task_model import AgentTask, AgentTaskStatus
+
+
+logger = logging.getLogger(__name__)
+
+
+# Maximum recursion depth for the ``agent`` tool. With cc_query_loop as the
+# default ccx runner kind, every agent node can call ``agent`` to spawn a
+# child runtime, which itself can call ``agent``, and so on. Each level
+# multiplies the cost by the per-node fan-out, so an unconstrained recursion
+# of depth 4 with fan-out 3 is already 81 leaves. The cap here is the only
+# mechanical (non-prompt) backstop — LLMs can't reliably stay within a
+# nominal budget via prompt instructions, but the runtime can refuse the
+# call.
+#
+# Depth 0 = the top-level cc engine driven by ccx's CcAgentRunner; depth 1
+# = its first helper; depth 2 = a helper-of-helper. The default of 3 keeps
+# room for a real "lead → researcher → reviewer" pattern without permitting
+# unbounded chains. Override via the ``CC_MAX_AGENT_RECURSION_DEPTH``
+# environment variable for unusual workloads.
+_DEFAULT_MAX_AGENT_RECURSION_DEPTH = 3
+_RECURSION_DEPTH_STATE_KEY = "agent_recursion_depth"
+_AGENT_SPAWN_REFUSED_ERROR_CODE = "AT1100"
+
+
+def _resolve_max_recursion_depth() -> int:
+    raw = os.environ.get("CC_MAX_AGENT_RECURSION_DEPTH")
+    if not raw:
+        return _DEFAULT_MAX_AGENT_RECURSION_DEPTH
+    try:
+        value = int(raw)
+    except ValueError:
+        logger.warning(
+            "CC_MAX_AGENT_RECURSION_DEPTH=%r is not an int; using default %d",
+            raw, _DEFAULT_MAX_AGENT_RECURSION_DEPTH,
+        )
+        return _DEFAULT_MAX_AGENT_RECURSION_DEPTH
+    if value < 0:
+        logger.warning(
+            "CC_MAX_AGENT_RECURSION_DEPTH=%d is negative; using default %d",
+            value, _DEFAULT_MAX_AGENT_RECURSION_DEPTH,
+        )
+        return _DEFAULT_MAX_AGENT_RECURSION_DEPTH
+    return value
+
+
+@dataclass(slots=True)
+class AgentToolRequest:
+    description: str
+    prompt: str
+    subagent_type: str | None = None
+    backend: str | None = None
+    model: str | None = None
+    run_in_background: bool = False
+    name: str | None = None
+    team_name: str | None = None
+    mode: str | None = None
+    isolation: str | None = None
+    cwd: str | None = None
+
+
+class AgentTool(BaseTool):
+    def __init__(
+        self,
+        llm_client_provider: LLMClientProvider | None = None,
+        runtime_registry: InProcessRuntimeRegistry | None = None,
+    ) -> None:
+        super().__init__(
+            ToolSpec(
+                name="agent",
+                description="Spawn a child agent to work on a sub-task and return its result.",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "description": {"type": "string"},
+                        "prompt": {"type": "string"},
+                        "subagent_type": {"type": "string"},
+                        "backend": {"type": "string"},
+                        "run_in_background": {"type": "boolean"},
+                        "cwd": {"type": "string"},
+                    },
+                    "required": ["description", "prompt"],
+                },
+            )
+        )
+        self.llm_client_provider = llm_client_provider or DefaultLLMClientProvider()
+        self.runtime_registry = runtime_registry
+
+    def validate_input(self, arguments: dict[str, Any]) -> ValidationResult:
+        if not arguments.get("description"):
+            return ValidationResult(ok=False, message="description is required.")
+        if not arguments.get("prompt"):
+            return ValidationResult(ok=False, message="prompt is required.")
+        backend = arguments.get("backend")
+        if backend and str(backend) not in {"in_process", "local_subprocess"}:
+            return ValidationResult(ok=False, message=f"Unsupported backend: {backend}")
+        return ValidationResult(ok=True)
+
+    async def execute(self, tool_call: ToolCall, ctx: ToolUseContext) -> ToolResult:
+        request = AgentToolRequest(
+            description=str(tool_call.arguments["description"]),
+            prompt=str(tool_call.arguments["prompt"]),
+            subagent_type=tool_call.arguments.get("subagent_type"),
+            backend=tool_call.arguments.get("backend"),
+            run_in_background=bool(tool_call.arguments.get("run_in_background", False)),
+            cwd=tool_call.arguments.get("cwd"),
+        )
+        # Recursion depth check (Tier 1 backstop against runaway sub-agent
+        # spawning when cc_query_loop is the default ccx runner). Read the
+        # parent's depth from session metadata.state, refuse if we'd exceed
+        # the cap, and emit an audit event either way so deep chains are
+        # debuggable post-hoc.
+        parent_session = ctx.metadata.get("session")
+        parent_depth = 0
+        if parent_session is not None:
+            parent_depth = int(
+                (parent_session.metadata.state or {}).get(
+                    _RECURSION_DEPTH_STATE_KEY, 0,
+                ) or 0
+            )
+        max_depth = _resolve_max_recursion_depth()
+        runtime_root_for_audit = ctx.config.runtime_root_path(ctx.cwd)
+        agent_audit_logger = JsonlAuditLogger(
+            runtime_root_for_audit / "audit" / "agent_events.jsonl"
+        )
+        prospective_child_depth = parent_depth + 1
+        if prospective_child_depth > max_depth:
+            agent_audit_logger.append(EventRecord(
+                event_type="agent_spawn_refused_recursion_cap",
+                session_id=getattr(parent_session, "session_id", None),
+                tool_name="agent",
+                success=False,
+                error_code=_AGENT_SPAWN_REFUSED_ERROR_CODE,
+                details={
+                    "parent_depth": parent_depth,
+                    "prospective_child_depth": prospective_child_depth,
+                    "max_depth": max_depth,
+                    "description": (request.description or "")[:200],
+                    "tool_use_id": tool_call.tool_use_id,
+                },
+            ))
+            logger.warning(
+                "agent tool refused: parent_depth=%d would exceed max_depth=%d "
+                "(description=%r). Set CC_MAX_AGENT_RECURSION_DEPTH to raise the cap.",
+                parent_depth, max_depth, (request.description or "")[:120],
+            )
+            return ToolResult(
+                tool_use_id=tool_call.tool_use_id,
+                tool_name=tool_call.tool_name,
+                success=False,
+                content=(
+                    f"agent spawn refused: recursion depth {prospective_child_depth} "
+                    f"would exceed cap {max_depth}. Complete this task with the "
+                    f"context you already have, or finalize and return."
+                ),
+                error_code=_AGENT_SPAWN_REFUSED_ERROR_CODE,
+                data={
+                    "parent_depth": parent_depth,
+                    "max_depth": max_depth,
+                    "refused": True,
+                },
+            )
+        # Approaching-cap warning (one less than max). Distinct event type
+        # so dashboards can flag chains that get close without firing on
+        # every spawn.
+        if prospective_child_depth == max_depth:
+            agent_audit_logger.append(EventRecord(
+                event_type="agent_collaboration_depth_warning",
+                session_id=getattr(parent_session, "session_id", None),
+                tool_name="agent",
+                success=None,
+                details={
+                    "parent_depth": parent_depth,
+                    "child_depth": prospective_child_depth,
+                    "max_depth": max_depth,
+                    "description": (request.description or "")[:200],
+                    "tool_use_id": tool_call.tool_use_id,
+                },
+            ))
+
+        definition = self.resolve_agent_definition(request)
+        backend_name = self.resolve_backend_name(request, ctx)
+        backend = self.resolve_backend(backend_name)
+        runtime_root = ctx.config.runtime_root_path(ctx.cwd)
+        runtime_registry = self.runtime_registry or get_in_process_runtime_registry(runtime_root)
+        task_manager = TaskManager(runtime_root / "tasks")
+        task = task_manager.create_task(
+            AgentTask.create(
+                agent_type=definition.agent_id,
+                backend=backend_name,
+                prompt_language=ctx.prompt_language,
+                title=request.description,
+                input_payload={
+                    "description": request.description,
+                    "prompt": request.prompt,
+                },
+            )
+        )
+        child_session = self.build_child_session(
+            parent_session=ctx.metadata["session"],
+            task=task,
+            agent_definition=definition,
+            cwd=request.cwd or ctx.cwd,
+        )
+        # Stamp the child's depth so its own ``agent`` tool calls see a
+        # bumped value and the cap composes across levels.
+        child_session.metadata.state[_RECURSION_DEPTH_STATE_KEY] = prospective_child_depth
+        from ..runtime import build_default_query_engine
+
+        runtime = AgentRuntime(
+            definition=definition,
+            task=task,
+            query_engine=build_default_query_engine(
+                cwd=child_session.cwd,
+                config=child_session.config,
+                llm_client_provider=self.llm_client_provider,
+                session=child_session,
+            ),
+            task_manager=task_manager,
+        )
+        controller = await backend.create_controller(
+            runtime=runtime,
+            run_in_background=request.run_in_background,
+            runtime_root=runtime_root,
+        )
+        runtime_registry.register(controller)
+        if request.run_in_background:
+            if backend_name == "in_process":
+                task_manager.update_task_status(task.task_id, AgentTaskStatus.RUNNING)
+                background_task = asyncio.create_task(controller.start(request.prompt))
+                runtime_registry.register_background_task(task.runtime_id, background_task)
+                launch_result = {
+                    "task_id": task.task_id,
+                    "runtime_id": task.runtime_id,
+                    "status": task.status.value,
+                    "background": True,
+                    "backend": backend_name,
+                }
+            else:
+                launch_result = await controller.start(request.prompt)
+            return ToolResult(
+                tool_use_id=tool_call.tool_use_id,
+                tool_name=tool_call.tool_name,
+                success=True,
+                content="Agent launched in background mode.",
+                data=launch_result,
+            )
+        result = await controller.start(request.prompt)
+        return ToolResult(
+            tool_use_id=tool_call.tool_use_id,
+            tool_name=tool_call.tool_name,
+            success=True,
+            content=result["final_text"],
+            data=result,
+        )
+
+    def resolve_backend_name(self, request: AgentToolRequest, ctx: ToolUseContext) -> str:
+        return str(request.backend or request.mode or ctx.config.default_backend or "in_process")
+
+    def resolve_backend(self, backend_name: str) -> RuntimeBackend:
+        if backend_name == "in_process":
+            return InProcessBackend()
+        if backend_name == "local_subprocess":
+            return LocalSubprocessBackend()
+        raise ValueError(f"Unsupported backend: {backend_name}")
+
+    def resolve_agent_definition(self, request: AgentToolRequest) -> AgentDefinition:
+        agent_id = request.subagent_type or "worker"
+        return AgentDefinition(
+            agent_id=agent_id,
+            name=request.name or agent_id,
+            description=request.description,
+            prompt_key="agents.worker",
+        )
+
+    def build_child_session(
+        self,
+        *,
+        parent_session: QuerySession,
+        task: AgentTask,
+        agent_definition: AgentDefinition,
+        cwd: str,
+    ) -> QuerySession:
+        child_config = CCConfig.from_mapping(
+            {
+                **parent_session.config.to_dict(),
+                "agent_mode": "",
+            }
+        )
+        child_factory = SessionFactory(child_config)
+        child_session = child_factory.create(
+            cwd=cwd,
+            model_name=parent_session.model_name,
+            agent_id=agent_definition.agent_id,
+            parent_task_id=task.task_id,
+        )
+        child_session.prompt_language = parent_session.prompt_language
+        child_session.permission_mode = parent_session.permission_mode
+        child_session.agent_mode = ""
+        child_session.metadata.state["spawned_by_agent_mode"] = parent_session.agent_mode
+        return child_session

core/cc/agents/backends/__init__.py

@@ -0,0 +1,11 @@
+from .base import BackendHandle, RuntimeBackend, RuntimeController
+from .in_process import InProcessBackend
+from .local_subprocess import LocalSubprocessBackend
+
+__all__ = [
+    "BackendHandle",
+    "InProcessBackend",
+    "LocalSubprocessBackend",
+    "RuntimeBackend",
+    "RuntimeController",
+]

core/cc/agents/backends/base.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..runtime import AgentMessage, AgentRuntime
+    from ..task_model import AgentTask
+
+
+@dataclass(slots=True)
+class BackendHandle:
+    runtime_id: str
+    backend_name: str
+    process_id: int | None = None
+    endpoint: str | None = None
+    output_path: str | None = None
+
+
+class RuntimeController(Protocol):
+    task: "AgentTask"
+    handle: BackendHandle
+
+    async def start(self, prompt: str) -> dict[str, Any]:
+        ...
+
+    async def send_message(
+        self,
+        message: "AgentMessage",
+        *,
+        timeout_seconds: float | None = None,
+    ) -> dict[str, Any]:
+        ...
+
+    async def stop(self, reason: str) -> None:
+        ...
+
+    async def collect_status(self) -> dict[str, Any]:
+        ...
+
+    async def apply_shared_state(
+        self,
+        *,
+        shared_context: dict[str, Any],
+        shared_allowed_paths: list[str],
+        timeout_seconds: float | None = None,
+    ) -> dict[str, Any]:
+        ...
+
+
+class RuntimeBackend(Protocol):
+    name: str
+
+    async def create_controller(
+        self,
+        *,
+        runtime: "AgentRuntime",
+        run_in_background: bool,
+        runtime_root: Path,
+    ) -> RuntimeController:
+        ...

core/cc/agents/backends/in_process.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+import time
+
+from ..swarm.mailbox import MailboxEnvelope, MailboxStore
+from .base import BackendHandle, RuntimeBackend, RuntimeController
+
+
+class InProcessController:
+    def __init__(self, runtime, runtime_root: Path, *, keep_alive: bool) -> None:
+        self.runtime = runtime
+        self.task = runtime.task
+        self.task_manager = runtime.task_manager
+        self.keep_alive = keep_alive
+        session = runtime.query_engine.session
+        team_id = session.metadata.team_id
+        lead_runtime_id = session.metadata.state.get("team_lead_runtime_id")
+        self.team_mailbox = (
+            MailboxStore(runtime_root / "teams" / str(team_id) / "mailbox")
+            if team_id is not None and lead_runtime_id
+            else None
+        )
+        self.lead_runtime_id = str(lead_runtime_id) if lead_runtime_id else None
+        self.handle = BackendHandle(
+            runtime_id=runtime.task.runtime_id,
+            backend_name="in_process",
+            process_id=None,
+            output_path=None,
+        )
+
+    async def start(self, prompt: str) -> dict[str, object]:
+        return await self.runtime.start(prompt, keep_alive=self.keep_alive)
+
+    async def send_message(self, message, *, timeout_seconds: float | None = None) -> dict[str, object]:
+        del timeout_seconds
+        self._publish_team_event(
+            "status_update",
+            {
+                "message_id": message.message_id,
+                "status": "running",
+                "description": message.metadata.get("description"),
+            },
+        )
+        self._publish_team_event(
+            "partial_result",
+            {
+                "message_id": message.message_id,
+                "partial_text": f"Worker {self.task.runtime_id} started task {message.message_id}",
+                "description": message.metadata.get("description"),
+            },
+        )
+        result = await self.runtime.send_message(message)
+        self._publish_team_event(
+            "final_result",
+            {
+                "message_id": message.message_id,
+                "description": message.metadata.get("description"),
+                "final_text": result.get("final_text", ""),
+                "status": result.get("status"),
+            },
+        )
+        self._publish_team_event(
+            "assignment_completed",
+            {
+                "message_id": message.message_id,
+                "description": message.metadata.get("description"),
+                "final_text": result.get("final_text", ""),
+                "status": result.get("status"),
+            },
+        )
+        return result
+
+    async def stop(self, reason: str) -> None:
+        await self.runtime.stop(reason)
+
+    async def collect_status(self) -> dict[str, object]:
+        return await self.runtime.collect_status()
+
+    async def apply_shared_state(
+        self,
+        *,
+        shared_context: dict[str, object],
+        shared_allowed_paths: list[str],
+        timeout_seconds: float | None = None,
+    ) -> dict[str, object]:
+        del timeout_seconds
+        session = self.runtime.query_engine.session
+        session.metadata.state["team_shared_context"] = dict(shared_context)
+        session.metadata.state["team_shared_allowed_paths"] = list(shared_allowed_paths)
+        session.metadata.state["allowed_paths"] = list(shared_allowed_paths)
+        return {
+            "runtime_id": self.task.runtime_id,
+            "backend": self.handle.backend_name,
+            "shared_context": dict(shared_context),
+            "shared_allowed_paths": list(shared_allowed_paths),
+        }
+
+    def _publish_team_event(self, message_type: str, payload: dict[str, object]) -> None:
+        if self.team_mailbox is None or self.lead_runtime_id is None:
+            return
+        message_token = str(payload.get("message_id") or "evt")
+        self.team_mailbox.enqueue(
+            MailboxEnvelope(
+                envelope_id=f"env_{message_type}_{self.task.runtime_id}_{message_token}_{int(time.time() * 1000)}",
+                team_id=self.runtime.query_engine.session.metadata.team_id,
+                from_runtime_id=self.task.runtime_id,
+                to_runtime_id=self.lead_runtime_id,
+                message_type=message_type,
+                payload=dict(payload),
+            )
+        )
+
+
+class InProcessBackend(RuntimeBackend):
+    name = "in_process"
+
+    async def create_controller(
+        self,
+        *,
+        runtime,
+        run_in_background: bool,
+        runtime_root: Path,
+    ) -> RuntimeController:
+        return InProcessController(runtime, runtime_root, keep_alive=run_in_background)