sgar 0.1.3__tar.gz

sgar-0.1.3/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 wxy2ab. All rights reserved.
+
+This software is distributed as a proprietary, internal package ("sgar").
+No license to use, copy, modify, or distribute is granted except by explicit
+written permission of the copyright holder. Replace this file with the license
+of your choice before any external distribution.

sgar-0.1.3/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include requirements.txt
+include setting.ini.template
+recursive-include core *.md *.toml *.j2 *.typed *.ini *.json *.html *.txt *.yaml *.yml
+global-exclude *.py[cod]
+global-exclude __pycache__/*

sgar-0.1.3/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: sgar
+Version: 0.1.3
+Summary: SGAR — ccx 治理化 agent 运行时（自 llm_dealer 导出的独立分发）
+Author: wxy2ab
+License: Proprietary
+Keywords: ccx,sgar,agent,llm,governance
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic
+Requires-Dist: azure-ai-inference
+Requires-Dist: boto3
+Requires-Dist: colorlog
+Requires-Dist: dashscope
+Requires-Dist: google-generativeai
+Requires-Dist: grep-ast
+Requires-Dist: httpx
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: openai
+Requires-Dist: pandas
+Requires-Dist: pillow
+Requires-Dist: rank-bm25
+Requires-Dist: ratelimit
+Requires-Dist: regex
+Requires-Dist: requests
+Requires-Dist: tenacity
+Requires-Dist: tencentcloud-sdk-python
+Requires-Dist: tree-sitter
+Requires-Dist: tree-sitter-python
+Requires-Dist: volcengine-python-sdk[ark]
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# sgar
+
+`ccx` 治理化 agent 运行时，从 `llm_dealer` 仓库中按 `core/ccx` 的依赖闭包自动导出的
+独立、可 pip 安装项目。
+
+本目录由 `task/copy/ccx_out.py` 生成：包含 321 个源文件、61 个运行期资源文件，
+覆盖子包 `core.cc`, `core.ccx`, `core.deepstack_v5`, `core.llms`, `core.utils`。
+
+> 注意：分发名是 `sgar`，但可导入的顶层包是 `core`（保留原命名空间以免改写大量
+> `import core.*`）。
+
+## 安装
+
+```bash
+pip install -e .
+# 或
+pip install .
+```
+
+需要 Python >=3.12。
+
+## 配置
+
+复制配置模板并填入你的密钥：
+
+```bash
+cp setting.ini.template setting.ini
+$EDITOR setting.ini
+```
+
+所有键也可以用同名大写的环境变量提供（见 `core/utils/config_setting.py`）。
+`setting.ini` 含密钥，已在 `.gitignore` 中忽略，请勿提交。
+
+## 使用
+
+```bash
+sgar --help                 # 安装后提供的命令行入口
+python -m sgar --help
+python -m core.ccx.sgar --help
+```
+
+```python
+from core.ccx.api import AgentRunRequest  # 程序化入口
+```
+
+## 自动发布
+
+- 每次 push 到 `main` 后，GitHub Actions 会自动将 `pyproject.toml` 的 patch 版本加 `1`。
+- 版本 bump 成功后，会自动构建并发布到 PyPI。
+- 如需手动发布，可在 GitHub Actions 里运行 `Publish sgar to PyPI`，并选择 `pypi` 或 `testpypi`。
+- 正式发布使用 GitHub Repository Secret `PYPI_API_TOKEN`。
+- 如需手动发布到 TestPyPI，请额外配置 `TEST_PYPI_API_TOKEN`。

sgar-0.1.3/README.md

@@ -0,0 +1,52 @@
+# sgar
+
+`ccx` 治理化 agent 运行时，从 `llm_dealer` 仓库中按 `core/ccx` 的依赖闭包自动导出的
+独立、可 pip 安装项目。
+
+本目录由 `task/copy/ccx_out.py` 生成：包含 321 个源文件、61 个运行期资源文件，
+覆盖子包 `core.cc`, `core.ccx`, `core.deepstack_v5`, `core.llms`, `core.utils`。
+
+> 注意：分发名是 `sgar`，但可导入的顶层包是 `core`（保留原命名空间以免改写大量
+> `import core.*`）。
+
+## 安装
+
+```bash
+pip install -e .
+# 或
+pip install .
+```
+
+需要 Python >=3.12。
+
+## 配置
+
+复制配置模板并填入你的密钥：
+
+```bash
+cp setting.ini.template setting.ini
+$EDITOR setting.ini
+```
+
+所有键也可以用同名大写的环境变量提供（见 `core/utils/config_setting.py`）。
+`setting.ini` 含密钥，已在 `.gitignore` 中忽略，请勿提交。
+
+## 使用
+
+```bash
+sgar --help                 # 安装后提供的命令行入口
+python -m sgar --help
+python -m core.ccx.sgar --help
+```
+
+```python
+from core.ccx.api import AgentRunRequest  # 程序化入口
+```
+
+## 自动发布
+
+- 每次 push 到 `main` 后，GitHub Actions 会自动将 `pyproject.toml` 的 patch 版本加 `1`。
+- 版本 bump 成功后，会自动构建并发布到 PyPI。
+- 如需手动发布，可在 GitHub Actions 里运行 `Publish sgar to PyPI`，并选择 `pypi` 或 `testpypi`。
+- 正式发布使用 GitHub Repository Secret `PYPI_API_TOKEN`。
+- 如需手动发布到 TestPyPI，请额外配置 `TEST_PYPI_API_TOKEN`。

sgar-0.1.3/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"]

sgar-0.1.3/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",
+]

sgar-0.1.3/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",
+]

sgar-0.1.3/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

sgar-0.1.3/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",
+]

sgar-0.1.3/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:
+        ...