core-runtime 0.1.1__py3-none-any.whl

shared/workers/loop_hold_telemetry.py

@@ -0,0 +1,210 @@
+# src/shared/workers/loop_hold_telemetry.py
+"""
+ADR-081 Step 3a-telemetry — structured sink for asyncio slow-callback warnings.
+
+When the daemon enables `loop.set_debug(True)` (ADR-081 Step 0), the asyncio
+event loop emits a `logger.warning` on the "asyncio" logger every time a
+single handle executes for longer than `slow_callback_duration`. The
+warning's repr carries the running task's `name='<stem>_worker'` attribute,
+which the daemon assigns at task-creation time.
+
+This module restructures that emission stream into machine-readable
+`loop_hold.sample::<stem>` blackboard entries — the data source the
+Step 3b drift detector consumes.
+
+Two collaborators:
+
+- `SlowCallbackBlackboardHandler` — a `logging.Handler` subclass installed
+  on the "asyncio" logger. `emit()` runs synchronously on the asyncio hot
+  path, so it MUST NOT block and MUST NOT raise. It parses the slow-callback
+  message into a structured sample and pushes it (non-blocking) onto an
+  asyncio queue.
+
+- `drain_loop_hold_samples()` — a long-running coroutine spawned as a
+  daemon task. It awaits samples from the queue and posts each to the
+  blackboard via the matching worker's `post_observation()`. Decoupling
+  the post from `emit()` keeps the measurement channel from blocking the
+  loop it measures.
+
+The queue is bounded — backpressure manifests as silent sample drops in
+`emit()` rather than back-pressuring the loop. Acceptable: slow-callback
+warnings are sparse compared to general loop activity, and a missed
+sample is cheaper than a measurement-induced perf regression.
+
+LAYER: shared.workers — telemetry infrastructure. No file writes, no
+direct DB access — posts via Worker.post_observation which routes
+through the standard blackboard path. Imported by cli.commands.daemon.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from shared.logger import getLogger
+
+
+if TYPE_CHECKING:
+    from shared.workers.base import Worker
+
+
+logger = getLogger(__name__)
+
+
+# The slow-callback warning's handle repr embeds `name='<task name>'` for
+# task-wrapping handles. Workers are named `<stem>_worker` by the daemon at
+# create_task time (see cli.commands.daemon._run_daemon_locked), so the
+# captured group gives us the task name; the `_worker` suffix is stripped
+# downstream to recover the YAML stem.
+_TASK_NAME_RE = re.compile(r"name='([^']+)'")
+
+# Queue cap — drop samples beyond this rather than blocking emit(). The
+# heaviest realistic flux is ~1 slow callback per cycle * ~10 workers per
+# process * 1 cycle/second worst case = ~10/s. 1024 buys ~2 minutes of
+# headroom before drop; the drain coroutine empties it as fast as the
+# blackboard accepts inserts.
+_QUEUE_MAXSIZE = 1024
+
+
+# ID: 5e5f1c2a-3b4d-4c5e-9f8a-0b1c2d3e4f50
+class SlowCallbackBlackboardHandler(logging.Handler):
+    """Subscribes asyncio slow-callback warnings to a queued blackboard sink.
+
+    Installed on the ``asyncio`` logger by the daemon at startup when
+    ``loop.set_debug(True)`` is enabled (per ADR-081 Step 0). ``emit()`` is
+    on the asyncio hot path — it MUST NOT block and MUST NOT raise.
+
+    The handler parses each warning record into a structured sample and
+    pushes it (non-blocking) onto the queue. A separate drain coroutine
+    posts samples to the blackboard. If the queue is full, samples are
+    dropped silently — preferable to blocking the loop with backpressure
+    from the measurement channel.
+    """
+
+    # ID: 8c2d4f6a-9e1b-4a3c-bf5d-2e7f0a1b3c4d
+    def __init__(self, sample_queue: asyncio.Queue[dict[str, Any]]) -> None:
+        super().__init__()
+        self._queue = sample_queue
+
+    # ID: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            # The slow-callback warning logs with `record.args = (handle, duration)`
+            # via `logger.warning("Executing %s took %.3f seconds", handle, dur)`
+            # (CPython asyncio/base_events.py). Anything else on the asyncio
+            # logger gets ignored.
+            args = record.args
+            if not args or not isinstance(args, tuple) or len(args) < 2:
+                return
+            try:
+                duration_sec = float(args[1])
+            except (TypeError, ValueError):
+                return
+            handle_repr = str(args[0])
+            m = _TASK_NAME_RE.search(handle_repr)
+            if not m:
+                # Slow callback wasn't a named task — could be an internal
+                # asyncio handle (e.g. a timer). Skip silently; this is not
+                # a worker-attributable sample.
+                return
+            task_name = m.group(1)
+            stem = task_name.removesuffix("_worker")
+            sample = {
+                "stem": stem,
+                "duration_sec": duration_sec,
+                "handle_repr": handle_repr,
+                "ts": datetime.now(UTC).isoformat(),
+            }
+            try:
+                self._queue.put_nowait(sample)
+            except asyncio.QueueFull:
+                # Drop the sample silently. The drain coroutine will catch
+                # up on the next free slot; we never block emit() on the
+                # hot path waiting for blackboard capacity.
+                pass
+        except Exception:
+            # Last-ditch safety net. A logging handler exception on the
+            # asyncio hot path would inject latency back into the loop it's
+            # measuring — never propagate.
+            pass
+
+
+# ID: c0d1e2f3-a4b5-c6d7-e8f9-0a1b2c3d4e5f
+def make_sample_queue() -> asyncio.Queue[dict[str, Any]]:
+    """Construct the bounded queue the handler pushes into.
+
+    Kept as a factory so the daemon can construct it in the same coroutine
+    that owns the drain task — `asyncio.Queue` binds to the current event
+    loop at construction time.
+    """
+    return asyncio.Queue(maxsize=_QUEUE_MAXSIZE)
+
+
+# ID: d1e2f3a4-b5c6-d7e8-f9a0-b1c2d3e4f5a6
+async def drain_loop_hold_samples(
+    sample_queue: asyncio.Queue[dict[str, Any]],
+    workers_by_stem: dict[str, Worker],
+) -> None:
+    """Drain the slow-callback sample queue to the blackboard.
+
+    Posts each sample as a ``loop_hold.sample::<stem>`` observability entry
+    under the matching worker's UUID, status ``abandoned`` — the terminal
+    status the Worker.post_observation contract reserves for per-event
+    records that recur on the next detection (the same shape the
+    ``*.yield.receipt`` pattern uses; ADR-069 / observability-TTL recon).
+
+    Cancellation-safe: an outer ``asyncio.CancelledError`` exits the loop
+    cleanly without losing buffered samples. Per-sample errors are logged
+    but never propagate — telemetry failure must not bring down the daemon.
+    """
+    logger.info(
+        "loop_hold telemetry: drain coroutine started "
+        "(%d worker(s) registered for attribution)",
+        len(workers_by_stem),
+    )
+    posted = 0
+    skipped_unknown_stem = 0
+    while True:
+        try:
+            sample = await sample_queue.get()
+        except asyncio.CancelledError:
+            logger.info(
+                "loop_hold telemetry: drain coroutine cancelled "
+                "(posted=%d, skipped_unknown_stem=%d)",
+                posted,
+                skipped_unknown_stem,
+            )
+            raise
+        stem = sample["stem"]
+        worker = workers_by_stem.get(stem)
+        if worker is None:
+            # Task name didn't map to a registered worker. Could be the
+            # _run_one_shot_loop wrapper task (its name carries the stem
+            # but the wrapper itself isn't the Worker instance), or an
+            # internal asyncio task. Either way, no UUID to attribute to —
+            # drop the sample.
+            skipped_unknown_stem += 1
+            continue
+        try:
+            await worker.post_observation(
+                subject=f"loop_hold.sample::{stem}",
+                payload={
+                    "duration_sec": sample["duration_sec"],
+                    "handle_repr": sample["handle_repr"],
+                    "ts": sample["ts"],
+                },
+                status="abandoned",
+            )
+            posted += 1
+        except Exception as e:
+            # Telemetry post failure must not bring down the daemon or the
+            # drain loop. Log and continue — the next sample is more
+            # important than this one's persistence.
+            logger.warning(
+                "loop_hold telemetry: post failed for stem=%s: %s",
+                stem,
+                e,
+            )

shared/workers/schedule.py

@@ -0,0 +1,123 @@
+# src/shared/workers/schedule.py
+"""
+WorkerScheduleState - single source of per-worker liveness inputs.
+
+Per ADR-041 D4: the YAML-scanning logic that produces
+``(thresholds, active_uuids)`` is centralised here so all readers
+(WorkerShopManager, dashboard runtime health, health_log_service)
+consume the same construction. This prevents drift at the YAML-reading
+layer between the supervisor and downstream readers.
+
+LAYER: shared/workers — pure function over .intent/workers/*.yaml,
+routed through IntentRepository (the canonical gateway for .intent/).
+No DB access, no file writes, no Worker dependency. Safe to import
+from CLI, body services, and will/workers alike.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from shared.infrastructure.intent.intent_repository import (
+    IntentRepository,
+    get_intent_repository,
+)
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG = load_operational_config().workers.worker_shop
+
+
+@dataclass(frozen=True)
+# ID: f406d128-ea33-49d4-8095-9639089c6201
+class WorkerScheduleState:
+    """Per-worker liveness inputs derived from .intent/workers/*.yaml.
+
+    thresholds: maps worker_uuid (string form) → max_interval + glide_off
+                in seconds. Workers without a declared ``schedule`` block
+                do not appear here; callers apply *fallback_sec* instead.
+
+    active_uuids: the set of worker_uuids declared with ``status: active``.
+                  Workers with any other status (paused, missing) are
+                  absent. Callers use this for orphan-skip: registry rows
+                  whose UUID is not in this set are excluded from
+                  liveness reads (ADR-041 D3).
+
+    fallback_sec: canonical liveness threshold for active workers that
+                  declare no ``schedule`` block. Sourced from
+                  ``operational_config.workers.worker_shop.fallback_threshold_sec``
+                  so the producer (WorkerShopManager) and all readers
+                  (dashboard, health_log_service) apply the same fallback.
+    """
+
+    thresholds: dict[str, int]
+    active_uuids: frozenset[str]
+    fallback_sec: int
+
+
+# ID: f2d9b5b3-4a8e-4c7f-9d0a-2b3c4d5e6f7a
+def load_worker_schedule_state(
+    intent_repo: IntentRepository | None = None,
+) -> WorkerScheduleState:
+    """Read every declared worker via IntentRepository and return per-worker
+    liveness inputs.
+
+    Only YAMLs with ``metadata.status: active`` contribute. Workers with
+    ``status: paused`` (or any other non-active status) yield neither
+    a threshold nor an active-uuid entry — their registry rows, if
+    present, are orphans by D3 and excluded from liveness reads.
+
+    Failures reading individual worker declarations are logged and
+    skipped; the function never raises on per-worker errors. A missing
+    .intent/workers/ directory yields an empty state rather than an
+    error.
+
+    Per-worker threshold formula matches WorkerShopManager's pre-ADR-041
+    computation: ``max_interval + glide_off`` from the worker's
+    ``mandate.schedule`` block, with ``glide_off`` defaulting to
+    ``max(max_interval * glide_off_multiplier, 10)`` from
+    operational_config.
+
+    The ``intent_repo`` parameter exists so callers on the hot path
+    (WorkerShopManager runs this every cycle) and tests can pass a
+    pre-constructed gateway and avoid repeating ``validate_intent_tree``.
+    When omitted, the process-wide singleton from
+    ``get_intent_repository()`` is used.
+    """
+    repo = intent_repo if intent_repo is not None else get_intent_repository()
+
+    thresholds: dict[str, int] = {}
+    active_uuids: set[str] = set()
+
+    for worker_id in repo.list_workers():
+        try:
+            data = repo.load_worker(worker_id)
+            if data.get("metadata", {}).get("status") != "active":
+                continue
+            uuid = (data.get("identity") or {}).get("uuid", "")
+            if not uuid:
+                continue
+            active_uuids.add(uuid)
+            schedule = data.get("mandate", {}).get("schedule")
+            if schedule:
+                max_interval = schedule.get("max_interval", _CFG.fallback_threshold_sec)
+                glide_off = schedule.get(
+                    "glide_off",
+                    max(int(max_interval * _CFG.glide_off_multiplier), 10),
+                )
+                thresholds[uuid] = max_interval + glide_off
+        except Exception as exc:
+            logger.warning(
+                "load_worker_schedule_state: could not read %s: %s",
+                worker_id,
+                exc,
+            )
+
+    return WorkerScheduleState(
+        thresholds=thresholds,
+        active_uuids=frozenset(active_uuids),
+        fallback_sec=_CFG.fallback_threshold_sec,
+    )

will/__init__.py

@@ -0,0 +1,4 @@
+# src/will/__init__.py
+"""Provides functionality for the __init__ module."""
+
+from __future__ import annotations

will/agents/__init__.py

@@ -0,0 +1,4 @@
+# src/will/agents/__init__.py
+"""Provides functionality for the __init__ module."""
+
+from __future__ import annotations

will/agents/base_planner.py

@@ -0,0 +1,133 @@
+# src/will/agents/base_planner.py
+"""
+Base planning utilities - Strategic Action Filter.
+
+CONSTITUTIONAL ENHANCEMENT (V2.3):
+- Enforces planning.mutation_only: plans must not contain Read/Analyze steps.
+- Validates that ExecutionTask.params.code is None.
+- Enforces valid file_path formats.
+- Ensures separation between PLANNING and CODE_GENERATION phases.
+"""
+
+from __future__ import annotations
+
+from pydantic import ValidationError
+
+from shared.logger import getLogger
+from shared.models import ExecutionTask, PlanExecutionError
+from shared.path_resolver import PathResolver
+from shared.utils.parsing import extract_json_from_response
+from will.orchestration.prompt_pipeline import PromptPipeline
+
+
+logger = getLogger(__name__)
+
+
+# ID: c2df9e04-5177-44a0-bbcc-abbe0e1f7dde
+def build_planning_prompt(
+    path_resolver: PathResolver,
+    goal: str,
+    action_descriptions_str: str,
+    reconnaissance_report: str,
+    prompt_template: str,
+) -> str:
+    """
+    Builds the final planning prompt with explicit Mutation-Only instructions.
+    """
+    if not isinstance(path_resolver, PathResolver):
+        raise TypeError("path_resolver must be a PathResolver instance")
+
+    prompt_pipeline = PromptPipeline(path_resolver.repo_root)
+
+    # Pillar III: Explicitly instruct the Planner to be action-oriented.
+    directive = """
+STRATEGIC DIRECTIVE: MUTATION-ONLY PLANNING
+
+Your execution plan MUST only contain MUTATING ACTIONS
+(Create, Edit, Delete, Sync).
+
+DO NOT include 'Read', 'Analyze', 'Inspect', or 'Understand' steps.
+The CoderAgent has its own sensation layer and will read files automatically.
+
+Keep the plan lean. Focus exclusively on the final state of the code.
+"""
+
+    base_prompt = prompt_template.format(
+        goal=goal,
+        action_descriptions=action_descriptions_str,
+        reconnaissance_report=reconnaissance_report,
+    )
+
+    final_prompt = base_prompt + directive
+    return prompt_pipeline.process(final_prompt)
+
+
+# ID: 53af1563-669b-4cd0-b636-671bdd46570d
+def parse_and_validate_plan(response_text: str) -> list[ExecutionTask]:
+    """
+    Parses and validates the execution plan against the Mutation-Only Law.
+    """
+    try:
+        parsed_json = extract_json_from_response(response_text)
+        if not isinstance(parsed_json, list):
+            raise ValueError("LLM did not return a valid JSON list for the plan.")
+
+        validated_plan: list[ExecutionTask] = []
+
+        # Forbidden actions in an Execution Plan (belong to Reconnaissance)
+        forbidden_actions = {"file.read", "inspect", "analyze", "check.audit"}
+
+        for i, task_dict in enumerate(parsed_json, 1):
+            if not isinstance(task_dict, dict):
+                continue
+
+            action = str(task_dict.get("action", "")).lower()
+            step_desc = str(task_dict.get("step", "")).lower()
+
+            # Constitutional check: mutation only
+            if action in forbidden_actions or "read " in step_desc:
+                logger.warning(
+                    "Planner attempted to include Read/Analyze step (filtered)."
+                )
+                continue
+
+            # Constitutional check: no code generation during planning
+            params = task_dict.get("params") or {}
+            if isinstance(params, dict) and "code" in params:
+                if params.get("code"):
+                    raise PlanExecutionError(
+                        f"Step {i} violates planning.no_code_generation. "
+                        "Code belongs in the Code Generation phase."
+                    )
+
+            # Constitutional check: valid file_path format
+            if isinstance(params, dict) and "file_path" in params:
+                file_path = params.get("file_path")
+                if file_path and ("/ " in file_path or chr(92) in file_path):
+                    raise PlanExecutionError(
+                        f"Step {i} has invalid file_path format: {file_path}"
+                    )
+
+            # Validate via Pydantic model
+            try:
+                validated_plan.append(ExecutionTask(**task_dict))
+            except ValidationError as e:
+                logger.debug("Step %d failed Pydantic validation: %s", i, e)
+                continue
+
+        if not validated_plan:
+            raise PlanExecutionError(
+                "Planner failed to produce any valid mutation steps."
+            )
+
+        logger.info(
+            "PlannerAgent formed action-oriented plan with %d mutations.",
+            len(validated_plan),
+        )
+        return validated_plan
+
+    except Exception as e:
+        if isinstance(e, PlanExecutionError):
+            raise
+        logger.warning("Plan parsing failed: %s", e)
+        raise PlanExecutionError("Failed to create a valid mutation-only plan.") from e

will/agents/code_generation/__init__.py

@@ -0,0 +1,15 @@
+# src/will/agents/code_generation/__init__.py
+"""Code generation subsystem for CoderAgent."""
+
+from __future__ import annotations
+
+from .code_generator import CodeGenerator
+from .correction_engine import CorrectionEngine
+from .pattern_validator import PatternValidator
+
+
+__all__ = [
+    "CodeGenerator",
+    "CorrectionEngine",
+    "PatternValidator",
+]