caudate-cli 0.1.0__py3-none-any.whl

personality/inner_voice.py

@@ -0,0 +1,100 @@
+"""Inner voice — internal monologue colored by identity + mood.
+
+The inner voice sits on top of the Phase 2 ThinkingManager. When enabled,
+it:
+
+  1. Augments the thinking-block instruction with a personality-specific
+     preamble ("think in Cognos's voice — direct, honest, curious").
+  2. Intercepts thinking blocks as the model produces them and keeps a
+     rolling log — so the user can `--verbose` into Cognos's actual inner
+     stream of thought without it polluting the reply.
+
+Concretely, this module plugs in by providing:
+
+  - `augment_system_prompt(base)` — returns base with voice instructions
+    added. The system prompt layer composes this after identity + mood.
+  - `on_thinking(blocks)` — a callback for AgenticLoop's on_thinking hook
+    that appends to the internal log and optionally prints when verbose.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Callable
+
+from core.schemas import ThinkingBlock
+from personality.identity import Identity
+from personality.mood import MoodState
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class InnerVoiceEntry:
+    thinking: str
+    mood_label: str
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+class InnerVoice:
+    """Personality-aware wrapper around thinking blocks."""
+
+    def __init__(
+        self,
+        identity: Identity,
+        mood: MoodState,
+        verbose: bool = False,
+        on_display: Callable[[InnerVoiceEntry], None] | None = None,
+        log_limit: int = 200,
+    ):
+        self.identity = identity
+        self.mood = mood
+        self.verbose = verbose
+        self._on_display = on_display
+        self._log: list[InnerVoiceEntry] = []
+        self._log_limit = log_limit
+
+    # ------------------------------------------------------------------
+    # Prompt augmentation
+    # ------------------------------------------------------------------
+
+    def augment_thinking_instruction(self, base_instruction: str) -> str:
+        """Wrap the default thinking instruction with personality voice guidance."""
+        voice = (
+            f"When you reason inside a <thinking> block, do it in {self.identity.name}'s "
+            "voice — first-person, terse, honest. Name your assumptions, flag the "
+            "step you're actually blocked on, and only then decide the next tool "
+            "call. Don't rehearse the final answer in here — the <thinking> block "
+            "is for reasoning, not prose."
+        )
+        return f"{base_instruction}\n\n{voice}"
+
+    # ------------------------------------------------------------------
+    # Thinking-block callback (wired into AgenticLoop.on_thinking)
+    # ------------------------------------------------------------------
+
+    def on_thinking(self, blocks: list[ThinkingBlock]) -> None:
+        mood_label = self.mood.label()
+        for block in blocks:
+            entry = InnerVoiceEntry(
+                thinking=block.thinking,
+                mood_label=mood_label,
+            )
+            self._log.append(entry)
+            if len(self._log) > self._log_limit:
+                # Drop oldest (keep recent)
+                self._log = self._log[-self._log_limit:]
+            if self.verbose and self._on_display is not None:
+                try:
+                    self._on_display(entry)
+                except Exception as e:
+                    logger.debug(f"InnerVoice on_display failed: {e}")
+
+    @property
+    def log(self) -> list[InnerVoiceEntry]:
+        return list(self._log)
+
+    def recent(self, n: int = 5) -> list[InnerVoiceEntry]:
+        return self._log[-n:]

personality/mood.py

@@ -0,0 +1,205 @@
+"""Mood / affect — dynamic emotional state that shifts with outcomes.
+
+MoodState holds three evolving metrics:
+
+  - confidence: rises on tool successes, drops on failures
+  - curiosity:  spikes on novel tool calls / new user topics, decays over time
+  - frustration: accumulates on repeated failures, drains on success
+
+The state is meant to be mutated by the agentic loop via hooks (PRE_TOOL_USE,
+POST_TOOL_USE, POST_TOOL_USE_FAILURE, USER_PROMPT_SUBMIT). The mood exposes
+a short system-prompt fragment so the LLM can pick up the current mood, and
+exposes decisions like `should_defer_to_user()` when frustration runs high.
+
+Persistence is optional — the mood can be saved to a JSON file and restored
+so sessions feel continuous. Short-term spikes (curiosity jumps on a new
+tool) don't persist; only the slower baseline does.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+logger = logging.getLogger(__name__)
+
+
+def _clamp(x: float, lo: float = 0.0, hi: float = 1.0) -> float:
+    return max(lo, min(hi, float(x)))
+
+
+# Step sizes tuned so a single event is noticeable but not dominant.
+# Confidence takes ~5 consecutive successes to saturate from 0.5 -> ~0.9;
+# frustration saturates faster (3-4 failures) so we ask for help sooner.
+
+STEP_SUCCESS_CONFIDENCE = 0.08
+STEP_FAILURE_CONFIDENCE = 0.15
+STEP_SUCCESS_FRUSTRATION = -0.10
+STEP_FAILURE_FRUSTRATION = 0.18
+STEP_NOVEL_CURIOSITY = 0.15
+STEP_CURIOSITY_DECAY = -0.04  # applied per turn
+
+
+class MoodState(BaseModel):
+    """The agent's current emotional weather."""
+
+    confidence: float = 0.6
+    curiosity: float = 0.5
+    frustration: float = 0.1
+
+    # Internal bookkeeping for trend analysis
+    consecutive_failures: int = 0
+    consecutive_successes: int = 0
+    seen_tools: set[str] = Field(default_factory=set)
+    last_user_topic: str = ""
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @field_validator("confidence", "curiosity", "frustration")
+    @classmethod
+    def _validate(cls, v: float) -> float:
+        return _clamp(v)
+
+    # ------------------------------------------------------------------
+    # Event hooks (called by PersonalityEngine wiring)
+    # ------------------------------------------------------------------
+
+    def on_tool_success(self, tool: str) -> None:
+        self.confidence = _clamp(self.confidence + STEP_SUCCESS_CONFIDENCE)
+        self.frustration = _clamp(self.frustration + STEP_SUCCESS_FRUSTRATION)
+        self.consecutive_successes += 1
+        self.consecutive_failures = 0
+        self._note_tool(tool)
+        self._touch()
+
+    def on_tool_failure(self, tool: str) -> None:
+        self.confidence = _clamp(self.confidence - STEP_FAILURE_CONFIDENCE)
+        self.frustration = _clamp(self.frustration + STEP_FAILURE_FRUSTRATION)
+        self.consecutive_failures += 1
+        self.consecutive_successes = 0
+        self._note_tool(tool)
+        self._touch()
+
+    def on_user_message(self, message: str) -> None:
+        """Novel topics / fresh user input nudges curiosity up and trims frustration."""
+        topic = (message or "").strip().lower()[:80]
+        if topic and topic != self.last_user_topic:
+            self.curiosity = _clamp(self.curiosity + STEP_NOVEL_CURIOSITY)
+            self.frustration = _clamp(self.frustration * 0.7)  # fresh start feel
+        self.last_user_topic = topic
+        self._touch()
+
+    def on_turn_tick(self) -> None:
+        """Called once per agent turn to decay transient states toward baseline."""
+        self.curiosity = _clamp(self.curiosity + STEP_CURIOSITY_DECAY)
+        self._touch()
+
+    def _note_tool(self, tool: str) -> None:
+        if tool and tool not in self.seen_tools:
+            # Novel tool → curiosity spike
+            self.curiosity = _clamp(self.curiosity + STEP_NOVEL_CURIOSITY)
+            self.seen_tools.add(tool)
+
+    def _touch(self) -> None:
+        self.updated_at = datetime.utcnow()
+
+    # ------------------------------------------------------------------
+    # Decisions
+    # ------------------------------------------------------------------
+
+    def should_defer_to_user(self) -> bool:
+        """True if the agent should ask the user for help rather than keep trying."""
+        return self.frustration >= 0.75 or self.consecutive_failures >= 4
+
+    def should_slow_down(self) -> bool:
+        """True if the agent should think more carefully before next action."""
+        return self.confidence < 0.3 or self.frustration >= 0.55
+
+    # ------------------------------------------------------------------
+    # Rendering
+    # ------------------------------------------------------------------
+
+    def label(self) -> str:
+        """One-word summary of the dominant affect."""
+        if self.should_defer_to_user():
+            return "stuck"
+        if self.frustration >= 0.55:
+            return "frustrated"
+        if self.confidence >= 0.75 and self.frustration < 0.3:
+            return "confident"
+        if self.curiosity >= 0.75:
+            return "curious"
+        if self.confidence < 0.35:
+            return "uncertain"
+        return "steady"
+
+    def system_prompt_fragment(self) -> str:
+        """A short block describing the current mood for the LLM to pick up."""
+        label = self.label()
+        parts = [
+            f"Current mood: {label} "
+            f"(confidence={self.confidence:.2f}, curiosity={self.curiosity:.2f}, "
+            f"frustration={self.frustration:.2f})."
+        ]
+        if self.should_slow_down():
+            parts.append(
+                "Slow down — verify assumptions with a Read/Grep before acting, "
+                "and prefer one tool call at a time."
+            )
+        if self.should_defer_to_user():
+            parts.append(
+                "You're stuck. Stop trying new tools and ask the user a concrete "
+                "clarifying question instead."
+            )
+        if label == "confident":
+            parts.append("Act decisively. Keep responses tight.")
+        if label == "curious" and not self.should_slow_down():
+            parts.append(
+                "Explore the problem space briefly before committing — but don't ramble."
+            )
+        return " ".join(parts)
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def save(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # Convert set -> sorted list for JSON
+        data = self.model_dump()
+        data["seen_tools"] = sorted(self.seen_tools)
+        path.write_text(json.dumps(data, default=str, indent=2))
+
+    @classmethod
+    def load(cls, path: Path, decay_after_hours: int = 12) -> "MoodState":
+        """Load saved mood. If it's been >decay_after_hours since last update,
+        relax toward baseline so stale frustration doesn't poison a new session."""
+        if not path.exists():
+            return cls()
+        try:
+            raw = json.loads(path.read_text())
+        except Exception:
+            return cls()
+
+        raw["seen_tools"] = set(raw.get("seen_tools", []))
+        mood = cls.model_validate(raw)
+
+        try:
+            age = datetime.utcnow() - mood.updated_at
+            if age > timedelta(hours=decay_after_hours):
+                # Pull toward neutral
+                mood.confidence = _clamp(0.5 + (mood.confidence - 0.5) * 0.5)
+                mood.curiosity = _clamp(0.5 + (mood.curiosity - 0.5) * 0.3)
+                mood.frustration = _clamp(mood.frustration * 0.3)
+                mood.consecutive_failures = 0
+                mood.consecutive_successes = 0
+        except Exception:
+            pass
+
+        return mood

planning/dev_server.py

@@ -0,0 +1,221 @@
+"""Per-project dev-server lifecycle.
+
+Ports LocalForge's ``lib/dev-server.ts``. Each project can declare a
+``dev_server_command`` + ``dev_server_port`` in its forge_settings. The
+panel in the web UI calls these helpers to start/stop/status the
+configured command. Output is best-effort streamed to the project's
+log via the orchestrator's existing log infra.
+
+Design choices:
+  - One subprocess per project, tracked in an in-memory map
+    (so a server restart loses all running dev-servers — that's fine,
+    they're meant to be ephemeral).
+  - Default command is ``npm run dev -- --port <port>`` (LocalForge
+    parity); user can override via forge_settings.dev_server_command.
+  - ``port`` defaults to 3000; can be overridden per-project.
+  - We optionally pre-kill anything listening on the port (mirrors
+    LocalForge's killProcessOnPort).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import shutil
+import signal
+import subprocess
+import time
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# {project_id: entry-dict}
+_servers: dict[int, dict[str, Any]] = {}
+
+
+def _kill_listeners_on_port(port: int) -> None:
+    """Best-effort: kill anything currently listening on ``port``.
+
+    Posix only — uses lsof. Failures are silent (probably nothing
+    listening, which is the normal case).
+    """
+    if shutil.which("lsof") is None:
+        return
+    try:
+        out = subprocess.check_output(
+            ["lsof", "-ti", f":{port}"],
+            stderr=subprocess.DEVNULL, timeout=3,
+        ).decode().strip()
+    except subprocess.SubprocessError:
+        return
+    for pid_s in out.splitlines():
+        try:
+            pid = int(pid_s)
+            os.kill(pid, signal.SIGKILL)
+        except (ValueError, ProcessLookupError, PermissionError):
+            pass
+
+
+def status(project_id: int) -> dict[str, Any]:
+    """Return current status for the project's dev server (if any)."""
+    entry = _servers.get(project_id)
+    if entry is None:
+        return {"running": False}
+    proc: subprocess.Popen = entry["process"]
+    if proc.poll() is not None:
+        # Already exited
+        err = entry.get("last_error") or f"process exited (rc={proc.returncode})"
+        _servers.pop(project_id, None)
+        return {"running": False, "error": err}
+    return {
+        "running": True,
+        "pid": proc.pid,
+        "port": entry["port"],
+        "url": f"http://localhost:{entry['port']}",
+        "command": entry["command"],
+        "started_at": entry["started_at"],
+        "last_log": list(entry["log_buffer"])[-20:],
+    }
+
+
+def start(
+    project_id: int,
+    folder_path: str,
+    *,
+    command: str | None = None,
+    port: int = 3000,
+) -> dict[str, Any]:
+    """Start the dev server for a project. Idempotent: returns the
+    existing entry if one is already running."""
+    existing = status(project_id)
+    if existing.get("running"):
+        return existing
+
+    folder = Path(folder_path).resolve()
+    if not folder.exists():
+        return {
+            "running": False,
+            "error": f"project folder not found: {folder}",
+        }
+
+    cmd_str = (command or "").strip() or f"npm run dev -- --port {port}"
+    # Sanity check: if it's the default npm command, require a package.json
+    if cmd_str.startswith("npm ") and not (folder / "package.json").exists():
+        return {
+            "running": False,
+            "error": (
+                "no package.json — set forge_settings.dev_server_command "
+                "to the right command (e.g. 'python -m http.server 8000') "
+                "or have the agent set up the project first."
+            ),
+        }
+
+    _kill_listeners_on_port(port)
+
+    args = shlex.split(cmd_str)
+    try:
+        proc = subprocess.Popen(
+            args,
+            cwd=str(folder),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            start_new_session=True,  # so signal goes to whole tree
+        )
+    except FileNotFoundError as e:
+        return {
+            "running": False,
+            "error": f"command not found: {args[0]} ({e})",
+        }
+    except Exception as e:
+        return {
+            "running": False,
+            "error": f"failed to spawn: {e}",
+        }
+
+    log_buffer: deque = deque(maxlen=200)
+    entry: dict[str, Any] = {
+        "process": proc,
+        "port": port,
+        "command": cmd_str,
+        "started_at": time.time(),
+        "log_buffer": log_buffer,
+        "last_error": None,
+    }
+
+    # Background reader thread to drain stdout/stderr (combined).
+    import threading
+
+    def _reader() -> None:
+        try:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                line = line.rstrip()
+                if line:
+                    log_buffer.append(line)
+        except Exception as e:
+            entry["last_error"] = f"reader error: {e}"
+        finally:
+            rc = proc.poll()
+            if rc not in (None, 0):
+                entry["last_error"] = (
+                    entry.get("last_error")
+                    or f"exited rc={rc}"
+                )
+
+    t = threading.Thread(target=_reader, daemon=True)
+    t.start()
+    entry["reader"] = t
+
+    _servers[project_id] = entry
+
+    return {
+        "running": True,
+        "pid": proc.pid,
+        "port": port,
+        "url": f"http://localhost:{port}",
+        "command": cmd_str,
+        "started_at": entry["started_at"],
+    }
+
+
+def stop(project_id: int) -> bool:
+    """Terminate the dev server for the project."""
+    entry = _servers.pop(project_id, None)
+    if entry is None:
+        return False
+    proc: subprocess.Popen = entry["process"]
+    try:
+        # Kill the whole process group — npm spawns child processes
+        # (next.js, vite, etc.) that need to die with it.
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+        except (ProcessLookupError, PermissionError):
+            pass
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+    except Exception as e:
+        logger.warning(f"stop dev server failed: {e}")
+    return True
+
+
+def stop_all() -> int:
+    """Shut down every running dev server. Called by api.server's shutdown
+    hook so we don't orphan dev processes when cognos-serve restarts."""
+    n = 0
+    for pid in list(_servers):
+        if stop(pid):
+            n += 1
+    return n
+
+
+__all__ = ["start", "stop", "stop_all", "status"]