geode-agent 0.99.330__py3-none-any.whl

core/__init__.py

@@ -0,0 +1,50 @@
+"""GEODE — 범용 자율 실행 에이전트."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Declare ``__version__`` for mypy / IDEs.  The runtime value is produced
+    # lazily by ``__getattr__`` below so module import does not pull
+    # ``importlib.metadata`` (~70 ms cumulative including ``email.message`` /
+    # ``email.utils``) into the cold-start path.
+    __version__: str
+
+_VERSION_CACHE: str | None = None
+
+
+def _resolve_version() -> str:
+    """Resolve the package version from importlib.metadata, with a
+    pyproject.toml fallback for non-installed dev environments."""
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _pkg_version
+
+    try:
+        return _pkg_version("geode-agent")
+    except PackageNotFoundError:
+        # Fallback: read from pyproject.toml directly (dev / non-installed env)
+        from pathlib import Path as _Path
+
+        _pyproject = _Path(__file__).resolve().parent.parent / "pyproject.toml"
+        if _pyproject.exists():
+            import re as _re
+
+            _match = _re.search(r'version\s*=\s*"([^"]+)"', _pyproject.read_text())
+            return _match.group(1) if _match else "0.0.0-dev"
+        return "0.0.0-dev"
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 lazy ``__version__`` resolver.
+
+    Cold-start paths that never reference ``core.__version__`` (e.g. the
+    serve daemon's ``import core.runtime`` bootstrap) avoid loading
+    ``importlib.metadata`` entirely.
+    """
+    if name == "__version__":
+        global _VERSION_CACHE
+        if _VERSION_CACHE is None:
+            _VERSION_CACHE = _resolve_version()
+        return _VERSION_CACHE
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

core/agent/activity_channel.py

@@ -0,0 +1,89 @@
+"""Child->parent live-activity side-channel for the fleet view (Stage 1.5).
+
+Design SOT: ``docs/plans/2026-07-03-fleet-view.md``.
+
+Sub-agents run as ``python -m core.agent.worker`` subprocesses with the child
+:class:`~core.agent.loop.AgenticLoop` in ``quiet=True`` mode, so the child emits
+no per-tool IPC back to the parent's renderer — the parent learns a task's state
+only from the single final ``WorkerResult`` line at exit. Stage 1 left
+``FleetAgent.current_activity`` as ``""`` for exactly this reason.
+
+Stage 1.5 closes the gap with a **process-local activity sink**. The worker
+subprocess installs a sink (:func:`set_activity_sink`) that serialises a
+``{"type":"activity", ...}`` JSON line to its own stdout *before* the final
+result line. The child's :class:`ToolExecutor` calls :func:`emit_tool_activity`
+at the single per-tool dispatch boundary; when a sink is installed the current
+tool name + best-effort cumulative token count are forwarded to it.
+
+Fail-safe by construction:
+
+- The sink is a plain module global, **only ever set inside the worker
+  subprocess** (:mod:`core.agent.worker`). The parent process and every test
+  never call :func:`set_activity_sink`, so :func:`emit_tool_activity` is a
+  cheap no-op everywhere except a worker that opted in via
+  ``WorkerRequest.emit_activity``.
+- No sink installed → no emission → ``current_activity`` stays ``""`` (the
+  Stage 1 honest default). Nothing is faked.
+- Token count is read from the process token tracker (fresh per subprocess, so
+  its cumulative total *is* this task's total). Subscription / CLI-routed calls
+  expose no usage, so the count is honestly ``0`` for those — never fabricated.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+log = logging.getLogger(__name__)
+
+# ``(tool_name, cumulative_tokens) -> None``. Installed only by the worker
+# subprocess; ``None`` everywhere else (parent process, tests) → no-op emit.
+ActivitySink = Callable[[str, int], None]
+
+_activity_sink: ActivitySink | None = None
+
+
+def set_activity_sink(sink: ActivitySink) -> None:
+    """Install the process-local activity sink (worker subprocess only)."""
+    global _activity_sink
+    _activity_sink = sink
+
+
+def clear_activity_sink() -> None:
+    """Remove the installed sink (test hygiene; the worker process just exits)."""
+    global _activity_sink
+    _activity_sink = None
+
+
+def get_activity_sink() -> ActivitySink | None:
+    """Return the installed sink, or ``None`` when the feature is inactive."""
+    return _activity_sink
+
+
+def emit_tool_activity(tool: str) -> None:
+    """Forward the child's *current* tool + cumulative tokens to the sink.
+
+    A cheap no-op unless a sink was installed (i.e. unless this is a worker
+    subprocess that opted in via ``WorkerRequest.emit_activity``). The token
+    count is best-effort: read from the process token tracker, which is fresh
+    per worker subprocess so its cumulative total is this task's total, and is
+    ``0`` for subscription / CLI-routed calls that expose no usage.
+    """
+    sink = _activity_sink
+    if sink is None:
+        return
+    tokens = 0
+    try:
+        from core.llm.token_tracker import get_tracker
+
+        snap = get_tracker().snapshot()
+        tokens = int(snap.total_input_tokens) + int(snap.total_output_tokens)
+    except Exception:
+        # Best-effort — a missing/unbound tracker must never break tool dispatch.
+        tokens = 0
+    try:
+        sink(tool, tokens)
+    except Exception:
+        # A misbehaving sink (e.g. a broken stdout pipe) must never propagate
+        # into the child's tool-execution path.
+        log.debug("activity sink raised for tool=%s", tool, exc_info=True)

core/agent/agent_contracts_policy.py

@@ -0,0 +1,185 @@
+"""Agent contracts SoT reader — ADR-012 M2, JSON mutation surface.
+
+Mutator overrides per-agent ``role`` / ``system_prompt`` / ``tools`` on
+:class:`core.skills.agents.AgentDefinition` instances. ``model`` field
+는 Tier 2 (안전성 invariants 의 root) 이므로 본 surface 에서 명시적
+제외 — mutator 가 provider 를 임의로 바꿔 safety guardrail 을 우회하지
+못하도록 설계.
+
+**SoT schema** (모든 agent entry optional, 모든 field optional):
+
+.. code-block:: json
+
+    {
+      "research_assistant": {
+        "role": "Research Specialist (v2)",
+        "system_prompt": "...evolved prompt...",
+        "tools": ["web_search", "web_fetch", "read_document"]
+      },
+      "data_analyst": {
+        "system_prompt": "...evolved prompt..."
+      }
+    }
+
+Unknown agent name / 부적합 schema → graceful drop (forward-compat).
+
+**Resolution order** (PR-BACKFILL-SOT 2026-05-21 shared chain):
+
+1. ``GEODE_AGENT_CONTRACTS_OVERRIDE`` env var — explicit override.
+   - With ``GEODE_AGENT_CONTRACTS_STRICT=1``: strict.
+   - Without strict flag: graceful (no fall-through).
+2. ``~/.geode/autoresearch/handoff/agent-contracts.json`` — operator-local.
+3. ``core/self_improving/state/policies/agent-contracts.json`` — in-repo.
+4. ``None`` — no-op.
+
+**Frontier**: Claude Code 의 ``.claude/agents/*.md`` agent definitions
+이 사용자 hand-edit 만 받지만 — mutator 가 자동 진화시키는 것이 M2 의
+가치. ``model`` 은 사용자 explicit 선택만 허용 (Tier 2).
+"""
+
+from __future__ import annotations
+
+import copy
+import logging
+from pathlib import Path
+from typing import Any
+
+from core.agent.policy_sot import load_policy_sot
+from core.paths import (
+    AUTORESEARCH_AGENT_CONTRACTS_PATH,
+    OPERATOR_LOCAL_AGENT_CONTRACTS_PATH,
+)
+
+log = logging.getLogger(__name__)
+
+_AGENT_CONTRACTS_OVERRIDE_ENV = "GEODE_AGENT_CONTRACTS_OVERRIDE"
+
+_AGENT_CONTRACTS_SOT_PATH = AUTORESEARCH_AGENT_CONTRACTS_PATH
+"""Cross-process in-repo SoT path (M2, 2026-05-21). Module-local alias."""
+
+_OPERATOR_LOCAL_AGENT_CONTRACTS_PATH = OPERATOR_LOCAL_AGENT_CONTRACTS_PATH
+"""Operator-local SoT path. Module-local alias for monkey-patch."""
+
+
+# Mutable field set — ``model`` is intentionally absent (Tier 2 guardrail).
+_FIELD_ROLE = "role"
+_FIELD_SYSTEM_PROMPT = "system_prompt"
+_FIELD_TOOLS = "tools"
+_MUTABLE_FIELDS = frozenset({_FIELD_ROLE, _FIELD_SYSTEM_PROMPT, _FIELD_TOOLS})
+
+
+def _load_agent_contracts_override() -> dict[str, dict[str, Any]] | None:
+    """Return the active agent-contracts dict, or ``None`` if no SoT applies."""
+    return load_policy_sot(
+        env_var=_AGENT_CONTRACTS_OVERRIDE_ENV,
+        operator_local=_OPERATOR_LOCAL_AGENT_CONTRACTS_PATH,
+        in_repo=_AGENT_CONTRACTS_SOT_PATH,
+        label="agent-contracts",
+        validate_strict=_validate_schema,
+        validate_graceful=_validate_schema,
+        coerce=_coerce,
+    )
+
+
+def _validate_schema(data: Any, path: Path) -> None:
+    """Top-level ``dict[str, dict[field, value]]``. role/system_prompt = str;
+    tools = list[str]. Unknown field 무시 (forward-compat).
+    """
+    if not isinstance(data, dict):
+        raise RuntimeError(f"agent-contracts at {path} must be a dict")
+    for agent_name, entry in data.items():
+        if not isinstance(agent_name, str):
+            type_name = type(agent_name).__name__
+            raise RuntimeError(f"agent-contracts at {path} key must be str, got {type_name}")
+        if not isinstance(entry, dict):
+            type_name = type(entry).__name__
+            raise RuntimeError(
+                f"agent-contracts at {path}[{agent_name!r}] must be dict, got {type_name}"
+            )
+        for field in (_FIELD_ROLE, _FIELD_SYSTEM_PROMPT):
+            if field in entry and not isinstance(entry[field], str):
+                raise RuntimeError(f"agent-contracts at {path}[{agent_name!r}].{field} must be str")
+        if _FIELD_TOOLS in entry:
+            tools = entry[_FIELD_TOOLS]
+            if not isinstance(tools, list) or not all(isinstance(t, str) for t in tools):
+                raise RuntimeError(
+                    f"agent-contracts at {path}[{agent_name!r}].tools must be list[str]"
+                )
+
+
+def _coerce(data: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Extract known mutable fields per agent. ``model`` etc. dropped
+    (Tier 2 guardrail)."""
+    result: dict[str, dict[str, Any]] = {}
+    for agent_name, entry in data.items():
+        if not isinstance(entry, dict):
+            continue
+        kept: dict[str, Any] = {}
+        for field in _MUTABLE_FIELDS:
+            if field in entry:
+                value = entry[field]
+                if field == _FIELD_TOOLS and isinstance(value, list):
+                    kept[field] = [t for t in value if isinstance(t, str)]
+                elif isinstance(value, str):
+                    kept[field] = value
+        if kept:
+            result[agent_name] = kept
+    return result
+
+
+def apply_agent_contracts_policy(
+    agent_def: Any,
+    policy: dict[str, dict[str, Any]] | None,
+) -> Any:
+    """Return a (possibly modified) copy of ``agent_def`` with policy
+    overrides applied — role / system_prompt / tools only. ``model``
+    field is never touched (Tier 2 guardrail).
+
+    ``policy is None`` or agent name absent from policy → original
+    ``agent_def`` returned unchanged (no behavior change).
+    """
+    if not policy:
+        return agent_def
+    name = getattr(agent_def, "name", None)
+    if not isinstance(name, str) or name not in policy:
+        return agent_def
+    entry = policy[name]
+    if not entry:
+        return agent_def
+    # Pydantic BaseModel.model_copy(update=...) returns a new instance.
+    # Filter overrides to mutable fields only — defensive even though
+    # ``_coerce`` already drops everything else.
+    overrides = {k: v for k, v in entry.items() if k in _MUTABLE_FIELDS}
+    if not overrides:
+        return agent_def
+    # CSP-1 fix-up (Codex MCP MEDIUM #1) — an agent that declares a
+    # ``toolkit:`` will have its ``tools`` field shadowed by the
+    # toolkit's resolved set inside ``filter_handlers``. A policy entry
+    # that mutates ``tools`` on a toolkit-declaring agent therefore
+    # silently does nothing. Warn so operators notice rather than
+    # debugging a no-op override later.
+    agent_toolkit: str = str(getattr(agent_def, "toolkit", "") or "")
+    if _FIELD_TOOLS in overrides and agent_toolkit:
+        log.warning(
+            "agent_contracts_policy: agent %r declares toolkit=%r; "
+            "the policy's ``tools`` override is shadowed at spawn time "
+            "(toolkit takes precedence in filter_handlers). Either "
+            "remove the ``tools`` override or add a ``toolkit`` field "
+            "to the policy entry.",
+            name,
+            agent_toolkit,
+        )
+    if hasattr(agent_def, "model_copy"):
+        return agent_def.model_copy(update=overrides)
+    # Fallback for non-BaseModel doubles (test stubs, dicts) —
+    # deep-copy + setattr / item-set.
+    new_def = copy.deepcopy(agent_def)
+    for k, v in overrides.items():
+        if isinstance(new_def, dict):
+            new_def[k] = v
+        else:
+            setattr(new_def, k, v)
+    return new_def
+
+
+__all__ = ["apply_agent_contracts_policy"]