specsmith 0.4.0.dev221__tar.gz → 0.4.0.dev223__tar.gz

{specsmith-0.4.0.dev221/src/specsmith.egg-info → specsmith-0.4.0.dev223}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.4.0.dev221
+Version: 0.4.0.dev223
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.4.0.dev221 → specsmith-0.4.0.dev223}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.4.0.dev221"
+version = "0.4.0.dev223"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"
@@ -107,6 +107,11 @@ select = ["E", "F", "W", "I", "UP", "B", "SIM"]
 # Long rule text and install command strings in documentation modules
 "src/specsmith/toolrules.py" = ["E501"]
 "src/specsmith/tool_installer.py" = ["E501"]
+# One-shot rebuild scripts contain literal REQ description strings that are
+# intentionally long; wrapping them would damage readability of the source
+# of truth they reconstruct.
+"scripts/rebuild_requirements_json.py" = ["E501"]
+"scripts/rebuild_requirements_md.py" = ["E501"]
 
 [tool.mypy]
 python_version = "3.10"
@@ -141,9 +146,11 @@ ignore_missing_imports = true
 module = ["epistemic", "epistemic.*"]
 ignore_errors = true
 
-# New modules that use dynamic typing patterns incompatible with strict mypy.
+# Modules that use dynamic typing patterns incompatible with strict mypy.
 # These are correct at runtime; the Any-heavy urllib, json.loads, etc. patterns
 # are the source of most errors here. Exclude from strict type checking.
+# REQ-111: shrunk this list as part of the pre-1.0 cleanup; broker, safety,
+# console_utils, and indexer have been graduated to strict mypy.
 [[tool.mypy.overrides]]
 module = [
     "specsmith.ollama_cmds",
@@ -153,14 +160,10 @@ module = [
     "specsmith.importer",
     "specsmith.agent.providers.gemini",
     "specsmith.agent.runner",
-    "specsmith.agent.broker",
     "specsmith.agent.cleanup",
-    "specsmith.agent.indexer",
     "specsmith.agent.orchestrator",
     "specsmith.agent.repl",
-    "specsmith.agent.safety",
     "specsmith.agent.tools",
-    "specsmith.console_utils",
     "specsmith.profiles",
     "specsmith.serve",
     "specsmith.toolrules",

{specsmith-0.4.0.dev221 → specsmith-0.4.0.dev223}/src/specsmith/agent/broker.py

@@ -40,6 +40,7 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
+from typing import Any
 
 # ---------------------------------------------------------------------------
 # Intent classification
@@ -285,7 +286,7 @@ def infer_scope(
 class PreflightDecision:
     """Wrapped Specsmith preflight outcome."""
 
-    raw: dict
+    raw: dict[str, Any]
     decision: str = "unknown"
     work_item_id: str = ""
     requirement_ids: list[str] = field(default_factory=list)
@@ -294,7 +295,7 @@ class PreflightDecision:
     instruction: str = ""
 
     @classmethod
-    def from_json(cls, payload: dict) -> PreflightDecision:
+    def from_json(cls, payload: dict[str, Any]) -> PreflightDecision:
         return cls(
             raw=payload,
             decision=str(payload.get("decision", "unknown")),
@@ -476,7 +477,7 @@ RETRY_STRATEGIES = (
 )
 
 
-def classify_retry_strategy(report: dict, decision: PreflightDecision) -> str:
+def classify_retry_strategy(report: dict[str, Any], decision: PreflightDecision) -> str:
     """Map an executor failure report to one of the canonical retry strategies.
 
     The classification is deterministic and inspects:
@@ -529,7 +530,7 @@ def classify_retry_strategy(report: dict, decision: PreflightDecision) -> str:
 def execute_with_governance(
     decision: PreflightDecision,
     *,
-    executor: Callable[[PreflightDecision, int], dict],
+    executor: Callable[[PreflightDecision, int], dict[str, Any]],
     retry_budget: int = DEFAULT_RETRY_BUDGET,
 ) -> RunResult:
     """Run the work with Specsmith governance and a hard retry budget.
@@ -546,7 +547,7 @@ def execute_with_governance(
 
     last_summary = ""
     last_confidence = 0.0
-    last_report: dict = {}
+    last_report: dict[str, Any] = {}
     for attempt in range(1, retry_budget + 1):
         report = executor(decision, attempt) or {}
         last_report = report

specsmith-0.4.0.dev223/src/specsmith/agent/events.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Block-based JSONL event protocol for `specsmith chat` (REQ-112, REQ-113, REQ-114).
+
+The protocol is the contract between the Specsmith chat backend and any
+client (the Nexus REPL itself, the VS Code extension, or future TUIs).
+Every event is a single JSON object on its own line with a ``type`` key.
+
+Event kinds
+-----------
+* ``block_start``      - begins a new block (kinds: ``plan``, ``message``,
+                         ``tool_call``, ``tool_result``, ``diff``,
+                         ``test_results``, ``verdict``).
+* ``block_complete``   - closes the block opened by ``block_start``.
+* ``token``            - incremental LLM token within a ``message`` block.
+* ``tool_call``        - the LLM has decided to invoke a tool.
+* ``tool_request``     - safe-mode permission request (REQ-115).
+* ``tool_result``      - completed tool execution.
+* ``plan_step``        - status transition for a step in the active plan
+                         block (REQ-114).
+* ``task_complete``    - final block; carries final summary + profile.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import IO, Any
+
+
+def _now_iso() -> str:
+    """Return a UTC ISO-8601 timestamp (second precision)."""
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _new_block_id() -> str:
+    return f"blk_{uuid.uuid4().hex[:12]}"
+
+
+@dataclass
+class EventEmitter:
+    """Writes JSONL events to a stream (default stdout).
+
+    Used by the `specsmith chat` CLI and by the test suite. Each event is
+    flushed immediately so consumers can react in real time.
+    """
+
+    stream: IO[str] = field(default_factory=lambda: sys.stdout)
+
+    def emit(self, event: dict[str, Any]) -> None:
+        line = json.dumps(event, ensure_ascii=False)
+        self.stream.write(line + "\n")
+        # Some test buffers (e.g. capsys) don't support flush; ignore.
+        with contextlib.suppress(Exception):
+            self.stream.flush()
+
+    # ── Block helpers ────────────────────────────────────────────────────
+
+    def block_start(self, kind: str, *, agent: str = "nexus", **payload: Any) -> str:
+        """Open a new block of ``kind`` and return its id."""
+        block_id = _new_block_id()
+        self.emit(
+            {
+                "type": "block_start",
+                "block_id": block_id,
+                "kind": kind,
+                "agent": agent,
+                "timestamp": _now_iso(),
+                "payload": payload,
+            }
+        )
+        return block_id
+
+    def block_complete(self, block_id: str, **payload: Any) -> None:
+        self.emit(
+            {
+                "type": "block_complete",
+                "block_id": block_id,
+                "timestamp": _now_iso(),
+                "payload": payload,
+            }
+        )
+
+    def token(self, block_id: str, text: str) -> None:
+        self.emit(
+            {
+                "type": "token",
+                "block_id": block_id,
+                "text": text,
+            }
+        )
+
+    def tool_call(self, block_id: str, name: str, args: dict[str, Any]) -> None:
+        self.emit(
+            {
+                "type": "tool_call",
+                "block_id": block_id,
+                "name": name,
+                "args": args,
+            }
+        )
+
+    def tool_request(self, block_id: str, name: str, args: dict[str, Any]) -> None:
+        self.emit(
+            {
+                "type": "tool_request",
+                "block_id": block_id,
+                "name": name,
+                "args": args,
+            }
+        )
+
+    def tool_result(self, block_id: str, name: str, ok: bool, output: str) -> None:
+        self.emit(
+            {
+                "type": "tool_result",
+                "block_id": block_id,
+                "name": name,
+                "ok": ok,
+                "output": output,
+            }
+        )
+
+    def plan(self, steps: list[dict[str, Any]]) -> str:
+        return self.block_start("plan", steps=steps)
+
+    def plan_step(
+        self,
+        block_id: str,
+        step_id: str,
+        status: str,
+        **payload: Any,
+    ) -> None:
+        self.emit(
+            {
+                "type": "plan_step",
+                "block_id": block_id,
+                "step_id": step_id,
+                "status": status,
+                "timestamp": _now_iso(),
+                "payload": payload,
+            }
+        )
+
+    def diff(self, path: str, body: str) -> str:
+        return self.block_start("diff", path=path, body=body)
+
+    def task_complete(
+        self,
+        *,
+        success: bool,
+        confidence: float,
+        summary: str,
+        profile: str,
+        comments: list[dict[str, Any]] | None = None,
+        **extra: Any,
+    ) -> None:
+        self.emit(
+            {
+                "type": "task_complete",
+                "timestamp": _now_iso(),
+                "success": success,
+                "confidence": confidence,
+                "summary": summary,
+                "profile": profile,
+                "comments": comments or [],
+                **extra,
+            }
+        )
+
+
+__all__ = ["EventEmitter"]

{specsmith-0.4.0.dev221 → specsmith-0.4.0.dev223}/src/specsmith/agent/indexer.py

@@ -5,7 +5,7 @@ import subprocess
 from pathlib import Path
 
 
-def generate_index(cwd: str = None):
+def generate_index(cwd: str | None = None) -> None:
     """Generate repository index into .repo-index/"""
     if cwd is None:
         cwd = os.getcwd()

specsmith-0.4.0.dev223/src/specsmith/agent/mcp.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""MCP (Model Context Protocol) tool consumption for Nexus (REQ-121).
+
+Reads ``.specsmith/mcp.yml`` (a list of server configs) and returns a list
+of tool wrappers that Nexus can register alongside its built-in tool set.
+The wrappers are invoked over stdio per the MCP spec (subprocess +
+JSON-RPC framing). For 1.0 we ship the loader and the wrapper interface;
+the actual stdio JSON-RPC client is implemented but kept narrow so the
+Specsmith safety middleware fully wraps every call.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class MCPServerSpec:
+    """Static configuration for an MCP server.
+
+    Mirrors `.specsmith/mcp.yml` entries; the YAML parser turns each
+    entry into one of these.
+    """
+
+    name: str
+    command: str
+    args: list[str]
+    env: dict[str, str]
+
+
+@dataclass
+class MCPTool:
+    """A Nexus-side handle to an MCP server.
+
+    Calling ``invoke(payload)`` opens a subprocess, sends the payload as
+    a JSON-RPC ``tools/call`` request, and returns the response. Errors
+    surface as plain strings; the orchestrator wraps the call with the
+    standard Specsmith safety middleware so destructive payloads are
+    blocked exactly the same way as native Nexus tools.
+    """
+
+    spec: MCPServerSpec
+
+    @property
+    def name(self) -> str:
+        return self.spec.name
+
+    def invoke(self, payload: dict[str, Any]) -> str:
+        request = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": payload,
+        }
+        body = json.dumps(request) + "\n"
+        try:
+            proc = subprocess.run(  # noqa: S603 - argv is configured by user
+                [self.spec.command, *self.spec.args],
+                input=body,
+                capture_output=True,
+                text=True,
+                timeout=30,
+                env={**self.spec.env},
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            return f"mcp error: {exc}"
+        if proc.returncode != 0:
+            return f"mcp error: {proc.stderr.strip() or 'non-zero exit'}"
+        return proc.stdout.strip() or "(empty mcp response)"
+
+
+def load_mcp_tools(project_dir: Path) -> list[MCPTool]:
+    """Read ``.specsmith/mcp.yml`` and return a list of :class:`MCPTool`.
+
+    Returns an empty list when the file is absent or unparseable so the
+    rest of the orchestrator continues to function with zero MCP servers
+    configured (the default).
+    """
+    cfg_path = Path(project_dir) / ".specsmith" / "mcp.yml"
+    if not cfg_path.is_file():
+        return []
+    try:
+        import yaml
+
+        raw = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or []
+    except Exception:  # noqa: BLE001
+        return []
+    if not isinstance(raw, list):
+        return []
+
+    out: list[MCPTool] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            continue
+        name = str(entry.get("name", "")).strip()
+        command = str(entry.get("command", "")).strip()
+        if not name or not command:
+            continue
+        args_raw = entry.get("args", []) or []
+        env_raw = entry.get("env", {}) or {}
+        spec = MCPServerSpec(
+            name=name,
+            command=command,
+            args=[str(a) for a in args_raw if isinstance(a, (str, int, float))],
+            env={str(k): str(v) for k, v in env_raw.items()},
+        )
+        out.append(MCPTool(spec=spec))
+    return out
+
+
+__all__ = ["MCPServerSpec", "MCPTool", "load_mcp_tools"]

specsmith-0.4.0.dev223/src/specsmith/agent/memory.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Persistent session memory for the Nexus chat surface (REQ-120, REQ-125).
+
+Every chat turn (user utterance, broker decision, task result, tool calls)
+is appended as JSONL to ``.specsmith/sessions/<session_id>/turns.jsonl``.
+The orchestrator prepends the most-recent turns (capped by character
+budget) to its first message so the LLM has continuity across runs.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _session_dir(project_dir: Path, session_id: str) -> Path:
+    return Path(project_dir) / ".specsmith" / "sessions" / session_id
+
+
+def _turns_path(project_dir: Path, session_id: str) -> Path:
+    return _session_dir(project_dir, session_id) / "turns.jsonl"
+
+
+def append_turn(
+    project_dir: Path,
+    session_id: str,
+    turn: dict[str, Any],
+) -> None:
+    """Append ``turn`` to the session log. Adds a UTC timestamp if missing."""
+    path = _turns_path(project_dir, session_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    record = dict(turn)
+    record.setdefault("timestamp", time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()))
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def all_turns(project_dir: Path, session_id: str) -> list[dict[str, Any]]:
+    """Return every recorded turn for ``session_id`` (oldest-first)."""
+    path = _turns_path(project_dir, session_id)
+    if not path.is_file():
+        return []
+    out: list[dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            out.append(json.loads(line))
+        except ValueError:
+            continue
+    return out
+
+
+def recent_turns(
+    project_dir: Path,
+    session_id: str,
+    *,
+    max_chars: int = 20_000,
+) -> list[dict[str, Any]]:
+    """Return the most recent turns whose serialized size fits ``max_chars``.
+
+    Truncates oldest-first so the prompt always carries the latest context.
+    """
+    turns = all_turns(project_dir, session_id)
+    out: list[dict[str, Any]] = []
+    used = 0
+    for turn in reversed(turns):
+        size = len(json.dumps(turn, ensure_ascii=False))
+        if used + size > max_chars:
+            break
+        out.append(turn)
+        used += size
+    out.reverse()
+    return out
+
+
+__all__ = ["append_turn", "all_turns", "recent_turns"]

{specsmith-0.4.0.dev221 → specsmith-0.4.0.dev223}/src/specsmith/agent/orchestrator.py

@@ -207,13 +207,15 @@ Next action:
 
         AG2's ``initiate_chat`` returns a ``ChatResult`` whose ``summary`` is
         the last assistant message and whose ``chat_history`` lists every
-        turn. We treat reaching a non-empty summary that includes the
-        ``Next action:`` section as equilibrium per REQ-073, and parse
-        ``Files changed:`` and ``Test results:`` if present. The confidence
-        is conservative (0.85 for a complete contract response, 0.4 for a
-        partial one) and is meant to be replaced by a real verifier signal
-        once one is wired in.
+        turn. We parse the Nexus output contract out of the summary and feed
+        the structured signal through :func:`specsmith.agent.verifier.score`
+        (REQ-108) so ``equilibrium`` and ``confidence`` reflect real test /
+        ruff / mypy state instead of a hardcoded heuristic. When the LLM
+        returns no contract sections at all we fall back to the previous
+        conservative defaults so behaviour stays the same on degraded runs.
         """
+        from specsmith.agent.verifier import report_from_chat_sections, score
+
         summary = ""
         if chat_result is not None:
             summary = getattr(chat_result, "summary", "") or ""
@@ -221,8 +223,6 @@ Next action:
                 summary = str(summary)
 
         sections = self._parse_output_contract(summary)
-        equilibrium = bool(sections) and "next_action" in sections
-        confidence = 0.85 if equilibrium else (0.4 if summary else 0.0)
 
         files_changed: list[str] = []
         files_section = sections.get("files_changed", "")
@@ -236,6 +236,22 @@ Next action:
         if tests_section:
             test_results["raw"] = tests_section
 
+        # REQ-108: derive confidence and equilibrium from the real verifier
+        # signal rather than guessing from the presence of contract sections.
+        if sections:
+            report = report_from_chat_sections(sections, files_changed=files_changed)
+            verdict = score(report, confidence_target=0.7)
+            confidence = verdict.confidence
+            # Treat "reached the next_action section" as a soft floor for
+            # equilibrium so the harness still distinguishes a structurally
+            # complete contract from a totally empty one.
+            equilibrium = verdict.equilibrium or (
+                "next_action" in sections and report.has_changes and report.test_failed == 0
+            )
+        else:
+            equilibrium = False
+            confidence = 0.4 if summary else 0.0
+
         return TaskResult(
             equilibrium=equilibrium,
             confidence=confidence,

specsmith-0.4.0.dev223/src/specsmith/agent/router.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Dynamic agent / model routing for the Nexus orchestrator (REQ-122).
+
+The orchestrator asks ``choose_tier`` which model tier should run a given
+task. Three tiers are recognized:
+
+* ``coder``  - the local `l1-nexus` Qwen-Coder server (default).
+* ``heavy``  - a larger reasoning model for governance / architecture work.
+* ``fast``   - a quick lightweight model for read-only asks and summaries.
+
+The default mapping is overridable per project via
+``.specsmith/config.yml``::
+
+    routing:
+      change: coder
+      release: heavy
+      destructive: heavy
+      read_only_ask: fast
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+Tier = Literal["coder", "heavy", "fast"]
+
+DEFAULT_MAPPING: dict[str, Tier] = {
+    "read_only_ask": "fast",
+    "change": "coder",
+    "release": "heavy",
+    "destructive": "heavy",
+}
+
+
+def choose_tier(
+    intent: str,
+    *,
+    project_dir: Path | None = None,
+    retry_count: int = 0,
+) -> Tier:
+    """Pick a model tier for ``intent``.
+
+    Repeated retries escalate from ``coder`` to ``heavy`` so a stuck task
+    gets a more capable model on the next try (Phase-3 behaviour from the
+    plan).
+    """
+    mapping = dict(DEFAULT_MAPPING)
+    if project_dir is not None:
+        mapping.update(_load_routing_overrides(project_dir))
+    tier: Tier = mapping.get(intent, "coder")
+    if retry_count >= 2 and tier == "coder":
+        tier = "heavy"
+    return tier
+
+
+def _load_routing_overrides(project_dir: Path) -> dict[str, Tier]:
+    cfg = Path(project_dir) / ".specsmith" / "config.yml"
+    if not cfg.is_file():
+        return {}
+    try:
+        import yaml
+
+        raw = yaml.safe_load(cfg.read_text(encoding="utf-8")) or {}
+    except Exception:  # noqa: BLE001
+        return {}
+    section = raw.get("routing") if isinstance(raw, dict) else None
+    if not isinstance(section, dict):
+        return {}
+    out: dict[str, Tier] = {}
+    for key, val in section.items():
+        if isinstance(val, str) and val in ("coder", "heavy", "fast"):
+            out[str(key)] = val  # type: ignore[assignment]
+    return out
+
+
+__all__ = ["DEFAULT_MAPPING", "Tier", "choose_tier"]

specsmith-0.4.0.dev223/src/specsmith/agent/rules.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Project rules auto-injection for the Nexus orchestrator (REQ-119).
+
+Combines `docs/governance/*_RULES.md` files and the H-rules from
+`AGENTS.md` into a single deterministic system-prompt prefix that the
+orchestrator prepends to every AG2 agent's `system_message`.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+def load_rules(project_dir: Path) -> str:
+    """Return the combined rules prefix for ``project_dir``.
+
+    The returned string is empty when no governance rule files are present
+    (so older projects keep working unchanged). When rules exist, they are
+    rendered as a single compact block so AG2 token costs stay reasonable.
+    """
+    project_dir = Path(project_dir)
+    sections: list[str] = []
+
+    governance_dir = project_dir / "docs" / "governance"
+    if governance_dir.is_dir():
+        for path in sorted(governance_dir.glob("*_RULES.md")):
+            try:
+                text = path.read_text(encoding="utf-8").strip()
+            except OSError:
+                continue
+            if text:
+                sections.append(f"# {path.stem}\n{text}")
+
+    agents_md = project_dir / "AGENTS.md"
+    if agents_md.is_file():
+        try:
+            agents_text = agents_md.read_text(encoding="utf-8")
+        except OSError:
+            agents_text = ""
+        h_rules = _extract_h_rules(agents_text)
+        if h_rules:
+            sections.append("# AGENTS.md hard rules\n" + h_rules)
+
+    if not sections:
+        return ""
+
+    return "## Project Governance Rules (auto-loaded)\n" + "\n\n".join(sections) + "\n"
+
+
+def _extract_h_rules(text: str) -> str:
+    """Extract numbered hard-rules (`H1`, `H2`, ...) from AGENTS.md."""
+    lines: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if re.match(r"^[*\-]?\s*\*?\*?H\d+\b", stripped):
+            lines.append(stripped.lstrip("*-").lstrip())
+    return "\n".join(lines)
+
+
+__all__ = ["load_rules"]